001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.referencing.datum;
019
020import java.util.Map;
021import org.opengis.annotation.UML;
022
023import static org.opengis.annotation.Obligation.*;
024import static org.opengis.annotation.Specification.*;
025
026
027/**
028 * Defines the origin of an image coordinate reference system. An image datum is used in a local context only.
029 * For an image datum, the anchor point is usually either the centre of the image or the corner of the image.
030 * The image datum definition applies regardless of whether or not the image is georeferenced.
031 * Georeferencing is performed through a transformation of image <abbr>CRS</abbr> to geodetic or projected <abbr>CRS</abbr>.
032 * The transformation plays no part in the image datum definition.
033 *
034 * <p>The image pixel grid is defined as the set of lines of constant integer coordinate values.
035 * The term "image grid" is often used in other standards to describe the concept of Image <abbr>CRS</abbr>.
036 * However, care must be taken to correctly interpret this term in the context in which it is used.
037 * The term "grid cell" is often used as a substitute for the term "pixel".</p>
038 *
039 * <p>The grid lines of the image may be associated in two ways with the data attributes of the pixel or grid cell.
040 * The data attributes of the image usually represent an average or integrated value that is associated with the entire pixel.
041 * An image grid can be associated with this data in such a way that the grid lines run through the centres of the pixels.
042 * The cell centres will thus have integer coordinate values.
043 * In that case the attribute "pixel in cell" will have the value "cell centre".
044 * Alternatively, the image grid may be defined such that the grid lines
045 * associate with the cell or pixel corners rather than the cell centres.
046 * The cell centres will thus have noninteger coordinate values, the fractional parts always being 0.5.
047 * The attribute "pixel in cell" will now have the value "cell corner".
048 * This difference in perspective has no effect on the image interpretation,
049 * but is important for coordinate transformations involving this defined image.</p>
050 *
051 * @author  OGC Topic 2 (for abstract model and documentation)
052 * @author  Martin Desruisseaux (IRD, Geomatys)
053 * @version 3.0
054 * @since   1.0
055 *
056 * @see DatumAuthorityFactory#createImageDatum(String)
057 * @see DatumFactory#createImageDatum(Map, PixelInCell)
058 *
059 * @deprecated Replaced by {@link EngineeringDatum} as of ISO 19111:2019.
060 */
061@Deprecated(since="3.1")
062@UML(identifier="CD_ImageDatum", specification=ISO_19111, version=2007)
063public interface ImageDatum extends Datum {
064    /**
065     * Specification of the way the image grid is associated with the image data attributes.
066     *
067     * @return the way image grid is associated with image data attributes.
068     */
069    @UML(identifier="pixelInCell", obligation=MANDATORY, specification=ISO_19111)
070    PixelInCell getPixelInCell();
071}