001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.referencing.operation;
033
034 import java.awt.Shape;
035 import java.awt.geom.Point2D;
036 import java.awt.geom.AffineTransform;
037
038
039 /**
040 * Transforms two-dimensional coordinate points. {@link CoordinateOperation#getMathTransform()} may
041 * returns instance of this interface when source and destination coordinate systems are both two
042 * dimensional. {@code MathTransform2D} extends {@link MathTransform} by adding some methods for
043 * easier inter-operability with <A HREF="http://java.sun.com/products/java-media/2D/">Java2D</A>.
044 *
045 * @departure integration
046 * This interface is not part of OGC specification. It has been added in GeoAPI for
047 * close integration with the <cite>Java2D</cite> library. The API defined in this
048 * interface matches the <code>java.awt.geom.AffineTransform</code> API.
049 *
050 * @author Martin Desruisseaux (IRD)
051 * @version 3.0
052 * @since 1.0
053 */
054 public interface MathTransform2D extends MathTransform {
055 /**
056 * Transforms the specified {@code ptSrc} and stores the result in {@code ptDst}.
057 * If {@code ptDst} is {@code null}, a new {@link Point2D} object is allocated
058 * and then the result of the transformation is stored in this object. In either case,
059 * {@code ptDst}, which contains the transformed point, is returned for convenience.
060 * If {@code ptSrc} and {@code ptDst} are the same object, the input point is
061 * correctly overwritten with the transformed point.
062 *
063 * @param ptSrc the coordinate point to be transformed.
064 * @param ptDst the coordinate point that stores the result of transforming {@code ptSrc},
065 * or {@code null} if a new point shall be created.
066 * @return the coordinate point after transforming {@code ptSrc} and storing the result
067 * in {@code ptDst} or in a new point if {@code ptDst} was null.
068 * @throws TransformException if the point can't be transformed.
069 *
070 * @see AffineTransform#transform(Point2D, Point2D)
071 */
072 Point2D transform(final Point2D ptSrc, final Point2D ptDst) throws TransformException;
073
074 /**
075 * Transforms the specified shape. This method may replace straight lines by quadratic curves
076 * when applicable. It may also do the opposite (replace curves by straight lines). The returned
077 * shape doesn't need to have the same number of points than the original shape.
078 *
079 * @param shape The Shape to transform.
080 * @return The transformed shape. Some implementations may returns
081 * {@code shape} unmodified if this transform is identity.
082 * @throws TransformException if a transform failed.
083 *
084 * @see AffineTransform#createTransformedShape(Shape)
085 */
086 Shape createTransformedShape(final Shape shape) throws TransformException;
087
088 /**
089 * Gets the derivative of this transform at a point. The derivative is the
090 * matrix of the non-translating portion of the approximate affine map at
091 * the point.
092 *
093 * @param point The coordinate point where to evaluate the derivative. Null value is
094 * accepted only if the derivative is the same everywhere. For example affine
095 * transform accept null value since they produces identical derivative no
096 * matter the coordinate value. But most map projection will requires a non-null
097 * value.
098 * @return The derivative at the specified point as a 2×2 matrix. This method
099 * never returns an internal object: changing the matrix will not change the
100 * state of this math transform.
101 * @throws NullPointerException if the derivative dependents on coordinate
102 * and {@code point} is {@code null}.
103 * @throws TransformException if the derivative can't be evaluated at the
104 * specified point.
105 */
106 Matrix derivative(final Point2D point) throws TransformException;
107
108 /**
109 * Creates the inverse transform of this object.
110 *
111 * @return The inverse transform.
112 * @throws NoninvertibleTransformException if the transform can not be inverted.
113 *
114 * @see AffineTransform#createInverse()
115 *
116 * @since 2.2
117 */
118 @Override
119 MathTransform2D inverse() throws NoninvertibleTransformException;
120 }