/*$************************************************************************************************
 **
 ** $Id: MathTransform.java 831 2006-05-01 00:27:23Z Desruisseaux $
 **
 ** $URL: http://svn.code.sf.net/p/geoapi/code/branches/2.0.x/geoapi/src/main/java/org/opengis/referencing/operation/MathTransform.java $
 **
 ** Copyright (C) 2003-2005 Open GIS Consortium, Inc.
 ** All Rights Reserved. http://www.opengis.org/legal/
 **
 *************************************************************************************************/
package org.opengis.referencing.operation;

// OpenGIS direct dependencies
import org.opengis.spatialschema.geometry.DirectPosition;
import org.opengis.spatialschema.geometry.MismatchedDimensionException;

// Annotations
import org.opengis.annotation.UML;
import static org.opengis.annotation.Obligation.*;
import static org.opengis.annotation.Specification.*;


/**
 * Transforms multi-dimensional coordinate points. This interface transforms coordinate
 * value for a point given in the {@linkplain CoordinateOperation#getSourceCRS source
 * coordinate reference system} to coordinate value for the same point in the
 * {@linkplain CoordinateOperation#getTargetCRS target coordinate reference system}.
 *
 * In a {@linkplain Conversion conversion}, the transformation is accurate to within the
 * limitations of the computer making the calculations. In a {@linkplain Transformation
 * transformation}, where some of the operational parameters are derived from observations,
 * the transformation is accurate to within the limitations of those observations.
 *
 * If a client application wishes to query the source and target
 * {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference systems}
 * of an operation, then it should keep hold of the {@link CoordinateOperation} interface,
 * and use the contained math transform object whenever it wishes to perform a transform.
 *
 * @version Implementation specification 1.0
 * @author Open Geospatial Consortium
 * @author Martin Desruisseaux (IRD)
 * @since GeoAPI 1.0
 *
 * @see java.awt.geom.AffineTransform
 * @see javax.media.jai.PerspectiveTransform
 * @see javax.media.j3d.Transform3D
 * @see MathTransformFactory
 * @see CoordinateOperation#getMathTransform
 */
@UML(identifier="CT_MathTransform", specification=OGC_01009)
public interface MathTransform {
    /**
     * Gets the dimension of input points.
     */
    @UML(identifier="getDimSource", specification=OGC_01009)
    int getSourceDimensions();
    
    /**
     * Gets the dimension of output points.
     */
    @UML(identifier="getDimTarget", specification=OGC_01009)
    int getTargetDimensions();
    
    /**
     * Transforms the specified {@code ptSrc} and stores the result in
     * {@code ptDst}. If {@code ptDst} is {@code null}, a new
     * {@link DirectPosition} object is allocated and then the result of the
     * transformation is stored in this object. In either case, {@code ptDst},
     * which contains the transformed point, is returned for convenience.
     * If {@code ptSrc} and {@code ptDst} are the same object,
     * the input point is correctly overwritten with the transformed point.
     *
     * @param ptSrc the specified coordinate point to be transformed.
     * @param ptDst the specified coordinate point that stores the
     *              result of transforming {@code ptSrc}, or
     *              {@code null}.
     * @return the coordinate point after transforming {@code ptSrc}
     *         and storing the result in {@code ptDst}, or a newly
     *         created point if {@code ptDst} was null.
     * @throws MismatchedDimensionException if {@code ptSrc} or
     *         {@code ptDst} doesn't have the expected dimension.
     * @throws TransformException if the point can't be transformed.
     */
    @UML(identifier="transform", specification=OGC_01009)
    DirectPosition transform(DirectPosition ptSrc, DirectPosition ptDst)
            throws MismatchedDimensionException, TransformException;
    
    /**
     * Transforms a list of coordinate point ordinal values.
     * This method is provided for efficiently transforming many points.
     * The supplied array of ordinal values will contain packed ordinal
     * values. For example, if the source dimension is 3, then the ordinals
     * will be packed in this order:
     *
     * (x0,y0,z0,
     *  x1,y1,z1 ...).
     *
     * @param srcPts the array containing the source point coordinates.
     * @param srcOff the offset to the first point to be transformed
     *               in the source array.
     * @param dstPts the array into which the transformed point
     *               coordinates are returned. May be the same
     *               than {@code srcPts}.
     * @param dstOff the offset to the location of the first
     *               transformed point that is stored in the
     *               destination array.
     * @param numPts the number of point objects to be transformed.
     * @throws TransformException if a point can't be transformed.
     */
    @UML(identifier="transformList", specification=OGC_01009)
    void transform(double[] srcPts, int srcOff,
                   double[] dstPts, int dstOff,
                   int numPts) throws TransformException;
    
    /**
     * Transforms a list of coordinate point ordinal values.
     * This method is provided for efficiently transforming many points.
     * The supplied array of ordinal values will contain packed ordinal
     * values.  For example, if the source dimension is 3, then the ordinals
     * will be packed in this order:
     *
     * (x0,y0,z0,
     *  x1,y1,z1 ...).
     *
     * @param srcPts the array containing the source point coordinates.
     * @param srcOff the offset to the first point to be transformed
     *               in the source array.
     * @param dstPts the array into which the transformed point
     *               coordinates are returned. May be the same
     *               than {@code srcPts}.
     * @param dstOff the offset to the location of the first
     *               transformed point that is stored in the
     *               destination array.
     * @param numPts the number of point objects to be transformed.
     * @throws TransformException if a point can't be transformed.
     */
    void transform(float[] srcPts, int srcOff,
                   float[] dstPts, int dstOff,
                   int numPts) throws TransformException;

    /**
     * Gets the derivative of this transform at a point. The derivative is the
     * matrix of the non-translating portion of the approximate affine map at
     * the point. The matrix will have dimensions corresponding to the source
     * and target coordinate systems. If the input dimension is M,
     * and the output dimension is N, then the matrix will have size
     * N×M. The elements of the matrix
     *
     *              {en,m : n=0..(N-1)}
     *
     * form a vector in the output space which is parallel to the displacement
     * caused by a small change in the m'th ordinate in the input space.
     * 

* For example, if the input dimension is 4 and the * output dimension is 3, then a small displacement * * (x0, x1, x2, x3) * * in the input space will result in a displacement * * (y0, y1, y2) * * in the output space computed as below (en,m * are the matrix's elements): * *

     * [ y0 ]     [ e00  e01  e02  e03 ] [ x0 ]
     * [ y1 ]  =  [ e10  e11  e12  e13 ] [ x1 ]
     * [ y2 ]     [ e20  e21  e22  e23 ] [ x2 ]
     *                                   [ x3 ]
     * 
* * @param point The coordinate point where to evaluate the derivative. Null * value is accepted only if the derivative is the same everywhere. * For example affine transform accept null value since they produces * identical derivative no matter the coordinate value. But most map * projection will requires a non-null value. * @return The derivative at the specified point (never {@code null}). * This method never returns an internal object: changing the matrix * will not change the state of this math transform. * @throws NullPointerException if the derivative dependents on coordinate * and {@code point} is {@code null}. * @throws MismatchedDimensionException if {@code point} doesn't have * the expected dimension. * @throws TransformException if the derivative can't be evaluated at the * specified point. */ @UML(identifier="derivative", specification=OGC_01009) Matrix derivative(final DirectPosition point) throws MismatchedDimensionException, TransformException; /** * Creates the inverse transform of this object. The target of the inverse transform * is the source of the original. The source of the inverse transform is the target * of the original. Using the original transform followed by the inverse's transform * will result in an identity map on the source coordinate space, when allowances for * error are made. This method may fail if the transform is not one to one. However, * all cartographic projections should succeed. * * @return The inverse transform. * @throws NoninvertibleTransformException if the transform can't be inversed. */ @UML(identifier="inverse", specification=OGC_01009) MathTransform inverse() throws NoninvertibleTransformException; /** * Tests whether this transform does not move any points. * * @return {@code true} if this {@code MathTransform} is * an identity transform; {@code false} otherwise. */ @UML(identifier="isIdentity", specification=OGC_01009) boolean isIdentity(); /** * Returns a Well Known Text (WKT) for this object. Well know text are * defined in extended Backus Naur form. * This operation may fails if an object is too complex for the WKT format capability. * * @return The Well Known Text (WKT) for this object. * @throws UnsupportedOperationException If this object can't be formatted as WKT. */ @UML(identifier="getWKT", specification=OGC_01009) String toWKT() throws UnsupportedOperationException; }

Ads help maintain this website.