001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-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.metadata.content;
019
020import java.util.Collection;
021import java.util.Collections;
022import javax.measure.Unit;
023import org.opengis.util.Record;
024import org.opengis.util.RecordType;
025import org.opengis.annotation.UML;
026
027import static org.opengis.annotation.Obligation.*;
028import static org.opengis.annotation.Specification.ISO_19115;
029import static org.opengis.annotation.Specification.ISO_19115_2;
030
031
032/**
033 * The characteristics of each dimension (layer) included in the resource.
034 *
035 * <p><b>Conditional properties:</b></p>
036 * Following property has default method but shall nevertheless be implemented if the corresponding condition is met:
037 * <ul>
038 *   <li>{@linkplain #getUnits() Units} are mandatory if any of the {@linkplain #getMinValue() minimum},
039 *     {@linkplain #getMaxValue() maximum} or {@linkplain #getMeanValue() mean value} properties are provided.</li>
040 * </ul>
041 *
042 * @author  Rémi Maréchal (geomatys)
043 * @version 3.1
044 * @since   3.1
045 */
046@UML(identifier="MD_SampleDimension", specification=ISO_19115)
047public interface SampleDimension extends RangeDimension {
048    /**
049     * Minimum value of data values in each dimension included in the resource.
050     * May be {@code null} if unspecified.
051     *
052     * @return minimum value of data values in each dimension included in the resource, or {@code null} if none.
053     */
054    @UML(identifier="minValue", obligation=OPTIONAL, specification=ISO_19115)
055    default Double getMinValue() {
056        return null;
057    }
058
059    /**
060     * Maximum value of data values in each dimension included in the resource.
061     * May be {@code null} if unspecified.
062     *
063     * @return maximum value of data values in each dimension included in the resource, or {@code null} if none.
064     */
065    @UML(identifier="maxValue", obligation=OPTIONAL, specification=ISO_19115)
066    default Double getMaxValue() {
067        return null;
068    }
069
070    /**
071     * Mean value of data values in each dimension included in the resource.
072     * May be {@code null} if unspecified.
073     *
074     * @return the mean value of data values in each dimension included in the resource, or {@code null} if none.
075     */
076    @UML(identifier="meanValue", obligation=OPTIONAL, specification=ISO_19115)
077    default Double getMeanValue() {
078        return null;
079    }
080
081    /**
082     * Number of values used in a thematic classification resource.
083     * May be {@code null} if unspecified.
084     *
085     * <div class="note"><b>Example:</b> the number of classes in a Land Cover Type coverage
086     * or the number of cells with data in other types of coverages.</div>
087     *
088     * @return the number of values used in a thematic classification resource, or {@code null} if none.
089     */
090    @UML(identifier="numberOfValues", obligation=OPTIONAL, specification=ISO_19115)
091    default Integer getNumberOfValues() {
092        return null;
093    }
094
095    /**
096     * Standard deviation of data values in each dimension included in the resource.
097     * May be {@code null} if unspecified.
098     *
099     * @return standard deviation of data values in each dimension included in the resource, or {@code null} if none.
100     */
101    @UML(identifier="standardDeviation", obligation=OPTIONAL, specification=ISO_19115)
102    default Double getStandardDeviation() {
103        return null;
104    }
105
106    /**
107     * Units of data in each dimension included in the resource.
108     * May be {@code null} if unspecified.
109     *
110     * @return units of data in each dimension included in the resource, or {@code null} if none.
111     *
112     * @condition Mandatory if {@linkplain #getMinValue() minimum}, {@linkplain #getMaxValue() maximum}
113     *            or {@linkplain #getMeanValue() mean value} are provided.
114     */
115    @UML(identifier="units", obligation=CONDITIONAL, specification=ISO_19115)
116    default Unit<?> getUnits() {
117        return null;
118    }
119
120    /**
121     * Scale factor which has been applied to the cell value.
122     * May be {@code null} if unspecified.
123     *
124     * @return scale factor which has been applied to the cell value, or {@code null} if none.
125     */
126    @UML(identifier="scaleFactor", obligation=OPTIONAL, specification=ISO_19115)
127    default Double getScaleFactor() {
128        return null;
129    }
130
131    /**
132     * Physical value corresponding to a cell value of zero.
133     * May be {@code null} if unspecified.
134     *
135     * @return physical value corresponding to a cell value of zero, or {@code null} if none.
136     */
137    @UML(identifier="offset", obligation=OPTIONAL, specification=ISO_19115)
138    default Double getOffset() {
139        return null;
140    }
141
142    /**
143     * Type of transfer function to be used when scaling a physical value for a given element.
144     *
145     * @departure harmonization
146     *   ISO 19115-2 defines this property in the {@code MI_Band} type (a {@code MD_Band} subtype)
147     *   for historical reasons. GeoAPI moves this property up in the hierarchy to a more natural place
148     *   when not constrained by historical reasons, which is together with the offset and scale factor.
149     *
150     * @return type of transfer function.
151     */
152    @UML(identifier="transferFunctionType", obligation=OPTIONAL, specification=ISO_19115_2)
153    default TransferFunctionType getTransferFunctionType() {
154        return null;
155    }
156
157    /**
158     * Maximum number of significant bits in the uncompressed representation for the value in each band of each pixel.
159     * May be {@code null} if unspecified.
160     *
161     * @return maximum number of significant bits in the uncompressed representation
162     *         for the value in each band of each pixel, or {@code null} if none.
163     */
164    @UML(identifier="bitsPerValue", obligation=OPTIONAL, specification=ISO_19115)
165    default Integer getBitsPerValue() {
166        return null;
167    }
168
169    /**
170     * Provides the description and values of the specific range elements of a sample dimension.
171     * Example: missing data.
172     *
173     * @return description and values of the specific range elements.
174     */
175    @UML(identifier="rangeElementDescription", obligation=OPTIONAL, specification=ISO_19115, version=2018)
176    default Collection<? extends RangeElementDescription> getRangeElementDescriptions() {
177        return Collections.emptyList();
178    }
179
180    /**
181     * Smallest distance between which separate points can be distinguished, as specified in instrument design.
182     *
183     * <div class="warning"><b>Upcoming API change — units of measurement</b><br>
184     * The return type of this method may change in GeoAPI 4.0. It may be replaced by the
185     * {@link javax.measure.quantity.Length} type in order to provide unit of measurement
186     * together with the value.
187     * </div>
188     *
189     * @departure harmonization
190     *   ISO 19115-2 defines this property in the {@code MI_Band} type (a {@code MD_Band} subtype)
191     *   for historical reasons. GeoAPI moves this property up in the hierarchy since this property
192     *   can apply to any sample dimension, not only the measurements in the electromagnetic spectrum.
193     *
194     * @return smallest distance between which separate points can be distinguished.
195     * @unitof Distance
196     */
197    @UML(identifier="nominalSpatialResolution", obligation=OPTIONAL, specification=ISO_19115_2)
198    default Double getNominalSpatialResolution() {
199        return null;
200    }
201
202    /**
203     * Type of other attribute description.
204     * May be {@code null} if unspecified.
205     *
206     * @return type of other attribute description, or {@code null} if none.
207     */
208    @UML(identifier="otherPropertyType", obligation=OPTIONAL, specification=ISO_19115)
209    default RecordType getOtherPropertyType() {
210        return null;
211    }
212
213    /**
214     * Instance of other attribute type that defines attributes not explicitly included in {@link CoverageContentType}.
215     * May be {@code null} if unspecified.
216     *
217     * @return instance of other/attributeType that defines attributes, or {@code null} if none.
218     */
219    @UML(identifier="otherProperty", obligation=OPTIONAL, specification=ISO_19115)
220    default Record getOtherProperty() {
221        return null;
222    }
223}