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.identification;
019
020import org.opengis.annotation.UML;
021import org.opengis.annotation.Profile;
022import org.opengis.annotation.Classifier;
023import org.opengis.annotation.Stereotype;
024import org.opengis.util.InternationalString;
025
026import static org.opengis.annotation.Obligation.*;
027import static org.opengis.annotation.Specification.*;
028import static org.opengis.annotation.ComplianceLevel.*;
029
030
031/**
032 * Level of detail expressed as a scale factor or a ground distance.
033 * Exactly one of the {@linkplain #getEquivalentScale() equivalent scale}, {@linkplain #getDistance() distance},
034 * {@linkplain #getVertical() vertical}, {@linkplain #getAngularDistance() angular distance} and
035 * {@linkplain #getLevelOfDetail() level of detail} properties shall be provided.
036 *
037 * @author  Martin Desruisseaux (IRD)
038 * @author  Cory Horner (Refractions Research)
039 * @version 3.1
040 * @since   2.0
041 *
042 * @see Identification#getSpatialResolutions()
043 */
044@Classifier(Stereotype.UNION)
045@UML(identifier="MD_Resolution", specification=ISO_19115)
046public interface Resolution {
047    /**
048     * Level of detail expressed as the scale of a comparable hardcopy map or chart.
049     *
050     * @return level of detail expressed as the scale of a comparable hardcopy, or {@code null}.
051     *
052     * @condition {@code distance}, {@code vertical}, {@code angularDistance} and {@code levelOfDetail} not provided.
053     */
054    @Profile(level=CORE)
055    @UML(identifier="equivalentScale", obligation=CONDITIONAL, specification=ISO_19115)
056    default RepresentativeFraction getEquivalentScale() {
057        return null;
058    }
059
060    /**
061     * Horizontal ground sample distance.
062     *
063     * <div class="warning"><b>Upcoming API change — units of measurement</b><br>
064     * The return type of this method may change in GeoAPI 4.0. It may be replaced by the
065     * {@link javax.measure.quantity.Length} type in order to provide unit of measurement
066     * together with the value.
067     * </div>
068     *
069     * @return the ground sample distance, or {@code null}.
070     * @unitof Distance
071     *
072     * @condition {@code equivalentScale}, {@code vertical}, {@code angularDistance} and {@code levelOfDetail} not provided.
073     */
074    @Profile(level=CORE)
075    @UML(identifier="distance", obligation=CONDITIONAL, specification=ISO_19115)
076    default Double getDistance() {
077        return null;
078    }
079
080    /**
081     * Vertical sampling distance.
082     *
083     * <div class="warning"><b>Upcoming API change — units of measurement</b><br>
084     * The return type of this method may change in GeoAPI 4.0. It may be replaced by the
085     * {@link javax.measure.quantity.Length} type in order to provide unit of measurement
086     * together with the value.
087     * </div>
088     *
089     * @return the vertical sampling distance, or {@code null}.
090     * @unitof Distance
091     *
092     * @condition {@code equivalentScale}, {@code distance}, {@code angularDistance} and {@code levelOfDetail} not provided.
093     *
094     * @since 3.1
095     */
096    @Profile(level=CORE)
097    @UML(identifier="vertical", obligation=CONDITIONAL, specification=ISO_19115)
098    default Double getVertical() {
099        return null;
100    }
101
102    /**
103     * Angular sampling measure.
104     *
105     * <div class="warning"><b>Upcoming API change — units of measurement</b><br>
106     * The return type of this method may change in GeoAPI 4.0. It may be replaced by the
107     * {@link javax.measure.quantity.Angle} type in order to provide unit of measurement
108     * together with the value.
109     * </div>
110     *
111     * @return the angular sampling measure, or {@code null}.
112     * @unitof Angle
113     *
114     * @condition {@code equivalentScale}, {@code distance}, {@code vertical} and {@code levelOfDetail} not provided.
115     *
116     * @since 3.1
117     */
118    @Profile(level=CORE)
119    @UML(identifier="angularDistance", obligation=CONDITIONAL, specification=ISO_19115)
120    default Double getAngularDistance() {
121        return null;
122    }
123
124    /**
125     * Brief textual description of the spatial resolution of the resource.
126     *
127     * @return textual description of the spatial resolution of the resource, or {@code null}.
128     *
129     * @condition {@code equivalentScale}, {@code distance}, {@code vertical} and {@code angularDistance} not provided.
130     *
131     * @since 3.1
132     */
133    @Profile(level=CORE)
134    @UML(identifier="levelOfDetail", obligation=CONDITIONAL, specification=ISO_19115)
135    default InternationalString getLevelOfDetail() {
136        return null;
137    }
138}