001 //$HeadURL: svn+ssh://rbezema@svn.wald.intevation.org/deegree/base/tags/2.1/src/org/deegree/model/csct/ct/MathTransform.java $
002 /*---------------- FILE HEADER ------------------------------------------
003
004 This file is part of deegree.
005 Copyright (C) 2001 by:
006 EXSE, Department of Geography, University of Bonn
007 http://www.giub.uni-bonn.de/exse/
008 lat/lon GmbH
009 http://www.lat-lon.de
010
011 It has been implemented within SEAGIS - An OpenSource implementation of OpenGIS specification
012 (C) 2001, Institut de Recherche pour le D�veloppement (http://sourceforge.net/projects/seagis/)
013 SEAGIS Contacts: Surveillance de l'Environnement Assist�e par Satellite
014 Institut de Recherche pour le D�veloppement / US-Espace
015 mailto:seasnet@teledetection.fr
016
017
018 This library is free software; you can redistribute it and/or
019 modify it under the terms of the GNU Lesser General Public
020 License as published by the Free Software Foundation; either
021 version 2.1 of the License, or (at your option) any later version.
022
023 This library is distributed in the hope that it will be useful,
024 but WITHOUT ANY WARRANTY; without even the implied warranty of
025 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
026 Lesser General Public License for more details.
027
028 You should have received a copy of the GNU Lesser General Public
029 License along with this library; if not, write to the Free Software
030 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
031
032 Contact:
033
034 Andreas Poth
035 lat/lon GmbH
036 Aennchenstr. 19
037 53115 Bonn
038 Germany
039 E-Mail: poth@lat-lon.de
040
041 Klaus Greve
042 Department of Geography
043 University of Bonn
044 Meckenheimer Allee 166
045 53115 Bonn
046 Germany
047 E-Mail: klaus.greve@uni-bonn.de
048
049
050 ---------------------------------------------------------------------------*/
051 package org.deegree.model.csct.ct;
052
053 // OpenGIS dependencies
054 import org.deegree.model.csct.pt.CoordinatePoint;
055 import org.deegree.model.csct.pt.Matrix;
056
057 /**
058 * Transforms multi-dimensional coordinate points. This interface transforms coordinate value for a
059 * point given in the source coordinate system to coordinate value for the same point in the target
060 * coordinate system. In an ISO conversion, the transformation is accurate to within the limitations
061 * of the computer making the calculations. In an ISO transformation, where some of the operational
062 * parameters are derived from observations, the transformation is accurate to within the
063 * limitations of those observations.
064 *
065 * @version 1.00
066 * @author OpenGIS (www.opengis.org)
067 * @author Martin Desruisseaux
068 *
069 * @author last edited by: $Author: bezema $
070 *
071 * @version $Revision: 6259 $, $Date: 2007-03-20 10:15:15 +0100 (Di, 20 Mär 2007) $
072 *
073 * @see "org.opengis.ct.CT_MathTransform"
074 */
075 public interface MathTransform {
076 /**
077 * Gets the dimension of input points.
078 *
079 * @return the dimension of input points.
080 *
081 * @see "org.opengis.ct.CT_MathTransform#getDimSource()"
082 */
083 public abstract int getDimSource();
084
085 /**
086 * Gets the dimension of output points.
087 *
088 * @return the dimension of output points.
089 *
090 * @see "org.opengis.ct.CT_MathTransform#getDimTarget()"
091 */
092 public abstract int getDimTarget();
093
094 /*
095 * Gets flags classifying domain points within a convex hull. Conceptually, each of the (usually
096 * infinite) points inside the convex hull is tested against the source domain. The flags of all
097 * these tests are then combined. In practice, implementations of different transforms will use
098 * different short-cuts to avoid doing an infinite number of tests. <br><br> Convex hull are
099 * not yet implemented in the <code>org.deegree.model</code> package. Consequently, the
100 * default implementation for this method always throws a {@link UnsupportedOperationException}.
101 *
102 * @param hull The convex hull. @return flags classifying domain points within the convex hull.
103 *
104 * @see org.opengis.ct.CT_MathTransform#getDomainFlags
105 */
106 // public DomainFlags getDomainFlags(final ConvexHull hull)
107 // {throw new UnsupportedOperationException("Not implemented");}
108 /**
109 * Transforms the specified <code>ptSrc</code> and stores the result in <code>ptDst</code>.
110 * If <code>ptDst</code> is <code>null</code>, a new {@link CoordinatePoint} object is
111 * allocated and then the result of the transformation is stored in this object. In either case,
112 * <code>ptDst</code>, which contains the transformed point, is returned for convenience. If
113 * <code>ptSrc</code> and <code>ptDst</code> are the same object, the input point is
114 * correctly overwritten with the transformed point.
115 *
116 * @param ptSrc
117 * the specified coordinate point to be transformed.
118 * @param ptDst
119 * the specified coordinate point that stores the result of transforming
120 * <code>ptSrc</code>, or <code>null</code>.
121 * @return the coordinate point after transforming <code>ptSrc</code> and storing the result
122 * in <code>ptDst</code>, or a newly created point if <code>ptDst</code> was null.
123 * @throws TransformException
124 * if the point can't be transformed.
125 *
126 */
127 public abstract CoordinatePoint transform( CoordinatePoint ptSrc, CoordinatePoint ptDst )
128 throws TransformException;
129
130 /**
131 * Transforms a list of coordinate point ordinal values. This method is provided for efficiently
132 * transforming many points. The supplied array of ordinal values will contain packed ordinal
133 * values. For example, if the source dimension is 3, then the ordinals will be packed in this
134 * order:
135 * (<var>x<sub>0</sub></var>,<var>y<sub>0</sub></var>,<var>z<sub>0</sub></var>,
136 * <var>x<sub>1</sub></var>,<var>y<sub>1</sub></var>,<var>z<sub>1</sub></var> ...).
137 *
138 * The size of the passed array must be an integer multiple of {@link #getDimSource}.
139 *
140 * @param srcPts
141 * the array containing the source point coordinates.
142 * @param srcOff
143 * the offset to the first point to be transformed in the source array.
144 * @param dstPts
145 * the array into which the transformed point coordinates are returned. May be the
146 * same than <code>srcPts</code>.
147 * @param dstOff
148 * the offset to the location of the first transformed point that is stored in the
149 * destination array.
150 * @param numPts
151 * the number of point objects to be transformed.
152 * @throws TransformException
153 * if a point can't be transformed.
154 *
155 */
156 public abstract void transform( double[] srcPts, int srcOff, double[] dstPts, int dstOff,
157 int numPts )
158 throws TransformException;
159
160 /**
161 * Transforms a list of coordinate point ordinal values. This method is provided for efficiently
162 * transforming many points. The supplied array of ordinal values will contain packed ordinal
163 * values. For example, if the source dimension is 3, then the ordinals will be packed in this
164 * order:
165 * (<var>x<sub>0</sub></var>,<var>y<sub>0</sub></var>,<var>z<sub>0</sub></var>,
166 * <var>x<sub>1</sub></var>,<var>y<sub>1</sub></var>,<var>z<sub>1</sub></var> ...).
167 *
168 * The size of the passed array must be an integer multiple of {@link #getDimSource}.
169 *
170 * @param srcPts
171 * the array containing the source point coordinates.
172 * @param srcOff
173 * the offset to the first point to be transformed in the source array.
174 * @param dstPts
175 * the array into which the transformed point coordinates are returned. May be the
176 * same than <code>srcPts</code>.
177 * @param dstOff
178 * the offset to the location of the first transformed point that is stored in the
179 * destination array.
180 * @param numPts
181 * the number of point objects to be transformed.
182 * @throws TransformException
183 * if a point can't be transformed.
184 */
185 public abstract void transform( float[] srcPts, int srcOff, float[] dstPts, int dstOff,
186 int numPts )
187 throws TransformException;
188
189 /**
190 * Gets the derivative of this transform at a point. The derivative is the matrix of the
191 * non-translating portion of the approximate affine map at the point. The matrix will have
192 * dimensions corresponding to the source and target coordinate systems. If the input dimension
193 * is <var>M</var>, and the output dimension is <var>N</var>, then the matrix will have size
194 * <code>N×M</code>. The elements of the matrix
195 * <code>{e<sub>n,m</sub> : n=0..(N-1)}</code> form a vector in the output space which is
196 * parallel to the displacement caused by a small change in the <var>m</var>'th ordinate in the
197 * input space. <br>
198 * <br>
199 * For example, if the input dimension is 4 and the output dimension is 3, then a small
200 * displacement
201 * <code>(x<sub>0</sub>, x<sub>1</sub>, x<sub>2</sub>, x<sub>3</sub>)</code>
202 * in the input space will result in a displacement
203 * <code>(y<sub>0</sub>, y<sub>1</sub>, y<sub>2</sub>)</code> in the output
204 * space computed as below (<code>e<sub>n,m</sub></code> are the matrix's elements):
205 *
206 * <pre>
207 * [ y<sub>0</sub> ] [ e<sub>00</sub> e<sub>01</sub> e<sub>02</sub> e<sub>03</sub> ] [ x<sub>0</sub> ]
208 * [ y<sub>1</sub> ] = [ e<sub>10</sub> e<sub>11</sub> e<sub>12</sub> e<sub>13</sub> ] [ x<sub>1</sub> ]
209 * [ y<sub>2</sub> ] [ e<sub>20</sub> e<sub>21</sub> e<sub>22</sub> e<sub>23</sub> ] [ x<sub>2</sub> ]
210 * <sub> </sub> <sub> </sub> <sub> </sub> <sub> </sub> <sub> </sub> [ x<sub>3</sub> ]
211 * </pre>
212 *
213 * @param point
214 * The coordinate point where to evaluate the derivative. Null value is accepted only
215 * if the derivative is the same everywhere. For example affine transform accept null
216 * value since they produces identical derivative no matter the coordinate value. But
217 * most map projection will requires a non-null value.
218 * @return The derivative at the specified point (never <code>null</code>). This method never
219 * returns an internal object: changing the matrix will not change the state of this
220 * math transform.
221 * @throws NullPointerException
222 * if the derivative dependents on coordinate and <code>point</code> is
223 * <code>null</code>.
224 * @throws TransformException
225 * if the derivative can't be evaluated at the specified point.
226 *
227 */
228 public abstract Matrix derivative( final CoordinatePoint point )
229 throws TransformException;
230
231 /**
232 * Creates the inverse transform of this object. The target of the inverse transform is the
233 * source of the original. The source of the inverse transform is the target of the original.
234 * Using the original transform followed by the inverse's transform will result in an identity
235 * map on the source coordinate space, when allowances for error are made. This method may fail
236 * if the transform is not one to one. However, all cartographic projections should succeed.
237 *
238 * @return The inverse transform.
239 * @throws NoninvertibleTransformException
240 * if the transform can't be inversed.
241 *
242 */
243 public abstract MathTransform inverse()
244 throws NoninvertibleTransformException;
245
246 /**
247 * Tests whether this transform does not move any points.
248 *
249 * @return <code>true</code> if this <code>MathTransform</code> is an identity transform;
250 * <code>false</code> otherwise.
251 *
252 */
253 public abstract boolean isIdentity();
254 }