org.opengis.referencing.operation.MathTransform Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of geoapi Show documentation
Show all versions of geoapi Show documentation
The development community in building GIS solutions is sustaining an enormous level
of effort. The GeoAPI project aims to reduce duplication and increase interoperability
by providing neutral, interface-only APIs derived from OGC/ISO Standards.
/*
* GeoAPI - Java interfaces for OGC/ISO standards
* http://www.geoapi.org
*
* Copyright (C) 2004-2011 Open Geospatial Consortium, Inc.
* All Rights Reserved. http://www.opengeospatial.org/ogc/legal
*
* Permission to use, copy, and modify this software and its documentation, with
* or without modification, for any purpose and without fee or royalty is hereby
* granted, provided that you include the following on ALL copies of the software
* and documentation or portions thereof, including modifications, that you make:
*
* 1. The full text of this NOTICE in a location viewable to users of the
* redistributed or derivative work.
* 2. Notice of any changes or modifications to the OGC files, including the
* date changes were made.
*
* THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
* NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
* TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
* THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
* PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
*
* COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
* CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
*
* The name and trademarks of copyright holders may NOT be used in advertising or
* publicity pertaining to the software without specific, written prior permission.
* Title to copyright in this software and any associated documentation will at all
* times remain with copyright holders.
*/
package org.opengis.referencing.operation;
import org.opengis.geometry.DirectPosition;
import org.opengis.geometry.MismatchedDimensionException;
import org.opengis.annotation.UML;
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.
*
* @author Martin Desruisseaux (IRD)
* @version 3.0
* @since 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.
*
* @return The dimension of input points.
*/
@UML(identifier="getDimSource", specification=OGC_01009)
int getSourceDimensions();
/**
* Gets the dimension of output points.
*
* @return 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. Some implementations will stop
* at the first failure, wile some other implementations will fill the untransformable
* points with {@linkplain Double#NaN NaN} values, continue and throw the exception
* only at end. Implementations that fall in the later case should set the {@linkplain
* TransformException#getLastCompletedTransform last completed transform} to {@code this}.
*/
@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. Some implementations will stop
* at the first failure, wile some other implementations will fill the untransformable
* points with {@linkplain Double#NaN NaN} values, continue and throw the exception
* only at end. Implementations that fall in the later case should set the {@linkplain
* TransformException#getLastCompletedTransform last completed transform} to {@code this}.
*/
void transform(float[] srcPts, int srcOff,
float[] 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.
* @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. Some implementations will stop
* at the first failure, wile some other implementations will fill the untransformable
* points with {@linkplain Double#NaN NaN} values, continue and throw the exception
* only at end. Implementations that fall in the later case should set the {@linkplain
* TransformException#getLastCompletedTransform last completed transform} to {@code this}.
*
* @since 2.2
*/
void transform(float [] 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.
* @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. Some implementations will stop
* at the first failure, wile some other implementations will fill the untransformable
* points with {@linkplain Double#NaN NaN} values, continue and throw the exception
* only at end. Implementations that fall in the later case should set the {@linkplain
* TransformException#getLastCompletedTransform last completed transform} to {@code this}.
*
* @since 2.2
*/
void transform(double[] 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
*
* (x₀, x₁, x₂, x₃)
*
* in the input space will result in a displacement
*
* (y₀, y₁, y₂)
*
* in the output space computed as below (en,m
* are the matrix elements):
*
*
* ┌ ┐ ┌ ┐ ┌ ┐
* │ y₀ │ │ e₀₀ e₀₁ e₀₂ e₀₃ │ │ x₀ │
* │ y₁ │ = │ e₁₀ e₁₁ e₁₂ e₁₃ │ │ x₁ │
* │ y₂ │ │ e₂₀ e₂₁ e₂₂ e₂₃ │ │ x₂ │
* └ ┘ └ ┘ │ x₃ │
* └ ┘
*
*
* @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 inverted.
*/
@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;
}