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}