001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2005-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.coverage.grid;
033
034 import java.util.List;
035 import org.opengis.geometry.DirectPosition;
036 import org.opengis.referencing.crs.CoordinateReferenceSystem;
037 import org.opengis.referencing.datum.Datum;
038 import org.opengis.annotation.UML;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * Grid for which there is an affine transformation between the grid coordinates and the coordinates of
046 * an external {@linkplain CoordinateReferenceSystem coordinate reference system}. A rectified grid is
047 * defined by an origin in an external {@linkplain CoordinateReferenceSystem coordinate reference system},
048 * and a set of offset vectors that specify the direction and distance between grid lines within
049 * that external CRS.
050 * <p>
051 * <b>NOTE:</b> If the coordinate reference system is related to the earth by a
052 * {@linkplain Datum datum}, the grid is a georectified grid.
053 * <p>
054 * <b>Constraints:</b>
055 * <ul>
056 * <li>The {@linkplain Grid#getDimension dimension of the grid} shall be less than or equal to the
057 * dimension of the {@linkplain DirectPosition#getCoordinateReferenceSystem coordinate
058 * reference system of the point} that is the {@linkplain #getOrigin origin}.</li>
059 * <li>The number of {@linkplain #getOffsetVectors offset vectors} shall equal the
060 * {@linkplain Grid#getDimension dimension of the grid}.</li>
061 * <li>The dimension of all offset vectors shall equal the dimension of the coordinate reference
062 * system, even if an offset vector is aligned with an axis of the external coordinate system.</li>
063 * </ul>
064 *
065 * @departure constraint
066 * ISO 19123 defines <code>RectifiedGrid</code> as a direct sub-type of <code>Grid</code>.
067 * In GeoAPI, <code>RectifiedGrid</code> extends <code>Grid</code> indirectly, through
068 * <code>ReferenceableGrid</code>. In the GeoAPI hierarchy, <code>RectifiedGrid</code>
069 * is considered as a special case of <code>ReferenceableGrid</code> where the <cite>grid
070 * to CRS</cite> coordinate operation is affine. This hierarchy make easier to leverage
071 * the same code for both the affine and non-affine cases when the code does not require
072 * a strictly affine operation.
073 *
074 * @version ISO 19123:2004
075 * @author Wim Koolhoven
076 * @author Martin Schouwenburg
077 * @author Martin Desruisseaux (IRD)
078 * @since GeoAPI 2.1
079 */
080 @UML(identifier="CV_RectifiedGrid", specification=ISO_19123)
081 public interface RectifiedGrid extends ReferenceableGrid {
082 /**
083 * Returns the origin of the rectified grid in an external coordinate reference system.
084 *
085 * @return The origin of the rectified grid.
086 */
087 @UML(identifier="origin", obligation=MANDATORY, specification=ISO_19123)
088 DirectPosition getOrigin();
089
090 /**
091 * Returns the offset vectors that determine the grid spacing in each direction.
092 * The vectors are defined in terms of the external coordinate reference system.
093 *
094 * @return The offset vectors that determine the grid spacing in each direction.
095 */
096 @UML(identifier="offsetVectors", obligation=MANDATORY, specification=ISO_19123)
097 List<double[]> getOffsetVectors();
098
099 /**
100 * Converts through an affine transform grid coordinates to a direct position.
101 *
102 * @param g The grid coordinates to convert.
103 * @return The "real world" coordinates.
104 *
105 * @departure rename
106 * A <code>"convertCoordinates"</code> method name would match better the ISO identifier.
107 * However since <code>RectifiedGrid</code> extends <code>ReferenceableGrid</code> in GeoAPI,
108 * we have to use the same method names than the later. Here, <cite>transform</cite> is to be
109 * understood as a term encompassing both <cite>transformation</cite> and <cite>conversion</cite>.
110 * This is similar to the <code>MathTransform</code> name policy.
111 */
112 @UML(identifier="coordConv", obligation=MANDATORY, specification=ISO_19123)
113 DirectPosition transformCoordinates(GridCoordinates g);
114
115 /**
116 * @deprecated Renamed as {@link #transformCoordinates}.
117 *
118 * @param g The grid coordinates to convert.
119 * @return The "real world" coordinates.
120 */
121 @Deprecated
122 DirectPosition convertCoordinates(GridCoordinates g);
123
124 /**
125 * Converts through an affine transform a direct position to the grid coordinates of
126 * the nearest grid point.
127 *
128 * @param p The "real world" coordinates to convert.
129 * @return The grid coordinates.
130 *
131 * @departure rename
132 * A <code>"inverseConvertCoordinates"</code> method name would match better the ISO identifier.
133 * However since <code>RectifiedGrid</code> extends <code>ReferenceableGrid</code> in GeoAPI,
134 * we have to use the same method names than the later. Here, <cite>transform</cite> is to be
135 * understood as a term encompassing both <cite>transformation</cite> and <cite>conversion</cite>.
136 * This is similar to the <code>MathTransform</code> name policy.
137 */
138 @UML(identifier="invCoordConv", obligation=MANDATORY, specification=ISO_19123)
139 GridCoordinates inverseTransformCoordinates(DirectPosition p);
140
141 /**
142 * @deprecated Renamed as {@link #inverseTransformCoordinates}.
143 *
144 * @param p The "real world" coordinates to convert.
145 * @return The grid coordinates.
146 */
147 @Deprecated
148 GridCoordinates inverseConvertCoordinates(DirectPosition p);
149 }