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