001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-2024 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.referencing.datum;
019
020import java.util.Collection;
021import org.opengis.metadata.quality.PositionalAccuracy;
022import org.opengis.referencing.IdentifiedObject;
023import org.opengis.annotation.UML;
024
025import static org.opengis.annotation.Specification.*;
026import static org.opengis.annotation.Obligation.MANDATORY;
027
028
029/**
030 * Collection of datums which for low accuracy requirements may be considered to be insignificantly different from each other.
031 * Every frame or datum within the datum ensemble must be a realization of the same reference system or datum.
032 * A datum ensemble is a construct to facilitate the merging of realizations of that common datum.
033 * For lower accuracy manipulation, datasets referenced to the various realizations may be merged without change of coordinates.
034 *
035 * <h2>Constraints</h2>
036 * If the datums specify a {@linkplain Datum#getConventionalRS() conventional reference system} (<abbr>RS</abbr>),
037 * then all datums in a datum ensemble shall have the same conventional <abbr>RS</abbr>.
038 *
039 * @author  OGC Topic 2 (for abstract model and documentation)
040 * @author  Martin Desruisseaux (IRD, Geomatys)
041 * @version 3.1
042 *
043 * @param <D> the type of datum contained in this ensemble.
044 *
045 * @since 3.1
046 */
047@UML(identifier="DatumEnsemble", specification=ISO_19111)
048public interface DatumEnsemble<D extends Datum> extends IdentifiedObject {
049    /**
050     * Datum or reference frames which are members of this datum ensemble.
051     * This collection shall contain at least 2 elements.
052     * All datum shall have the same {@linkplain Datum#getConventionalRS() conventional reference system} (if any).
053     *
054     * @return datum or reference frames which are members of this datum ensemble.
055     */
056    @UML(identifier="datum", obligation=MANDATORY, specification=ISO_19111)
057    Collection<D> getMembers();
058
059    /**
060     * Inaccuracy introduced through use of this collection of reference frames or datums.
061     * It is an indication of the differences in coordinate values at all points between
062     * the various realizations that have been grouped into this datum ensemble.
063     *
064     * @return inaccuracy introduced through use of this collection of datums.
065     */
066    @UML(identifier="ensembleAccuracy", obligation=MANDATORY, specification=ISO_19111)
067    PositionalAccuracy getEnsembleAccuracy();
068}