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.coverage;
033
034 import javax.measure.unit.Unit;
035 import org.opengis.util.InternationalString;
036 import org.opengis.referencing.operation.MathTransform1D;
037 import org.opengis.annotation.Extension;
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 * Contains information for an individual sample dimension of {@linkplain Coverage coverage}.
046 * This interface is applicable to any coverage type.
047 * For {@linkplain org.opengis.coverage.grid.GridCoverage grid coverages},
048 * the sample dimension refers to an individual band.
049 *
050 * <P> </P>
051 * <TABLE WIDTH="80%" ALIGN="center" CELLPADDING="18" BORDER="4" BGCOLOR="#FFE0B0">
052 * <TR><TD>
053 * <P align="justify"><STRONG>WARNING: THIS CLASS WILL CHANGE.</STRONG> Current API is derived from OGC
054 * <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverages Implementation specification 1.0</A>.
055 * We plan to replace it by new interfaces derived from ISO 19123 (<CITE>Schema for coverage geometry
056 * and functions</CITE>). Current interfaces should be considered as legacy and are included in this
057 * distribution only because they were part of GeoAPI 1.0 release. We will try to preserve as much
058 * compatibility as possible, but no migration plan has been determined yet.</P>
059 * </TD></TR>
060 * </TABLE>
061 *
062 * @version <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverage specification 1.0</A>
063 * @author Martin Desruisseaux (IRD)
064 * @since GeoAPI 1.0
065 */
066 @UML(identifier="CV_SampleDimension", specification=OGC_01004)
067 public interface SampleDimension {
068 /**
069 * Sample dimension title or description.
070 * This string may be null or empty if no description is present.
071 *
072 * @return A description for this sample dimension.
073 */
074 @UML(identifier="description", obligation=MANDATORY, specification=OGC_01004)
075 InternationalString getDescription();
076
077 /**
078 * A code value indicating grid value data type.
079 * This will also indicate the number of bits for the data type.
080 *
081 * @return A code value indicating grid value data type.
082 */
083 @UML(identifier="sampleDimensionType", obligation=MANDATORY, specification=OGC_01004)
084 SampleDimensionType getSampleDimensionType();
085
086 /**
087 * Sequence of category names for the values contained in a sample dimension.
088 * This allows for names to be assigned to numerical values.
089 * The first entry in the sequence relates to a cell value of zero.
090 * For grid coverages, category names are only valid for a classified grid data.
091 *
092 * For example:<br>
093 * <UL>
094 * <li>0 Background</li>
095 * <li>1 Water</li>
096 * <li>2 Forest</li>
097 * <li>3 Urban</li>
098 * </UL>
099 * Note: If no category names exist, an empty sequence is returned.
100 *
101 * @return The category names.
102 */
103 @UML(identifier="categoryNames", obligation=MANDATORY, specification=OGC_01004)
104 InternationalString[] getCategoryNames();
105
106 /**
107 * Color interpretation of the sample dimension.
108 * A sample dimension can be an index into a color palette or be a color model
109 * component. If the sample dimension is not assigned a color interpretation the
110 * value is {@link ColorInterpretation#UNDEFINED UNDEFINED}.
111 *
112 * @return The color interpretation of the sample dimension.
113 *
114 * @deprecated No replacement.
115 */
116 @UML(identifier="colorInterpretation", obligation=MANDATORY, specification=OGC_01004)
117 ColorInterpretation getColorInterpretation();
118
119 /**
120 * Indicates the type of color palette entry for sample dimensions which have a
121 * palette. If a sample dimension has a palette, the color interpretation must
122 * be {@link ColorInterpretation#GRAY_INDEX GRAY_INDEX}
123 * or {@link ColorInterpretation#PALETTE_INDEX PALETTE_INDEX}.
124 * A palette entry type can be Gray, RGB, CMYK or HLS.
125 *
126 * @return The type of color palette entry for sample dimensions which have a palette.
127 *
128 * @deprecated No replacement.
129 */
130 @UML(identifier="paletteInterpretation", obligation=MANDATORY, specification=OGC_01004)
131 PaletteInterpretation getPaletteInterpretation();
132
133 /**
134 * Color palette associated with the sample dimension.
135 * A color palette can have any number of colors.
136 * See palette interpretation for meaning of the palette entries.
137 * If the grid coverage has no color palette, {@code null} will be returned.
138 *
139 * @return The color palette associated with the sample dimension.
140 *
141 * @see #getPaletteInterpretation
142 * @see #getColorInterpretation
143 * @see java.awt.image.IndexColorModel
144 *
145 * @deprecated No replacement.
146 */
147 @UML(identifier="palette", obligation=MANDATORY, specification=OGC_01004)
148 int[][] getPalette();
149
150 /**
151 * Values to indicate no data values for the sample dimension.
152 * For low precision sample dimensions, this will often be no data values.
153 *
154 * @return The values to indicate no data values for the sample dimension.
155 *
156 * @see #getMinimumValue
157 * @see #getMaximumValue
158 */
159 @UML(identifier="noDataValue", obligation=MANDATORY, specification=OGC_01004)
160 double[] getNoDataValues();
161
162 /**
163 * The minimum value occurring in the sample dimension.
164 * If this value is not available, this value can be determined from the
165 * {@link org.opengis.coverage.processing.GridAnalysis#getMinValue} operation.
166 * This value can be empty if this value is not provided by the implementation.
167 *
168 * @return The minimum value occurring in the sample dimension.
169 *
170 * @see #getMaximumValue
171 * @see #getNoDataValues
172 */
173 @UML(identifier="minimumValue", obligation=MANDATORY, specification=OGC_01004)
174 double getMinimumValue();
175
176 /**
177 * The maximum value occurring in the sample dimension.
178 * If this value is not available, this value can be determined from the
179 * {@link org.opengis.coverage.processing.GridAnalysis#getMaxValue} operation.
180 * This value can be empty if this value is not provided by the implementation.
181 *
182 * @return The maximum value occurring in the sample dimension.
183 *
184 * @see #getMinimumValue
185 * @see #getNoDataValues
186 */
187 @UML(identifier="maximumValue", obligation=MANDATORY, specification=OGC_01004)
188 double getMaximumValue();
189
190 /**
191 * The unit information for this sample dimension.
192 * This interface typically is provided with grid coverages which represent
193 * digital elevation data.
194 * This value will be {@code null} if no unit information is available.
195 *
196 * @return The unit information for this sample dimension.
197 */
198 @UML(identifier="units", obligation=MANDATORY, specification=OGC_01004)
199 Unit<?> getUnits();
200
201 /**
202 * Offset is the value to add to grid values for this sample dimension.
203 * This attribute is typically used when the sample dimension represents
204 * elevation data. The default for this value is 0.
205 *
206 * @return The offset.
207 *
208 * @see #getScale
209 */
210 @UML(identifier="offset", obligation=MANDATORY, specification=OGC_01004)
211 double getOffset();
212
213 /**
214 * Scale is the value which is multiplied to grid values for this sample dimension.
215 * This attribute is typically used when the sample dimension represents elevation
216 * data. The default for this value is 1.
217 *
218 * @return The scale factor.
219 *
220 * @see #getOffset
221 */
222 @UML(identifier="scale", obligation=MANDATORY, specification=OGC_01004)
223 double getScale();
224
225 /**
226 * The transform which is applied to grid values for this sample dimension.
227 * This transform is often defined as
228 * <var>y</var> = {@linkplain #getOffset offset} + {@link #getScale scale}×<var>x</var> where
229 * <var>x</var> is the grid value and <var>y</var> is the geophysics value.
230 * However, this transform may also defines more complex relationship, for
231 * example a logarithmic one. In order words, this transform is a generalization of
232 * {@link #getScale}, {@link #getOffset} and {@link #getNoDataValues} methods.
233 *
234 * @departure generalization
235 * Added this optional method as a generalization of <code>scale</code> and <code>offset</code>
236 * attributes. Note that ISO 19115-2 refers to a similar function as "<cite>the transfert function</cite>".
237 *
238 * @return The transform from sample to geophysics values, or {@code null} if
239 * it doesn't apply.
240 *
241 * @see #getScale
242 * @see #getOffset
243 * @see #getNoDataValues
244 */
245 @Extension
246 MathTransform1D getSampleToGeophysics();
247 }