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 org.opengis.util.CodeList;
021import org.opengis.annotation.UML;
022import org.opengis.geoapi.internal.Vocabulary;
023
024import static org.opengis.annotation.Obligation.*;
025import static org.opengis.annotation.Specification.*;
026
027
028/**
029 * Specification of the way the image grid is associated with the image data attributes.
030 * This code list is similar to {@link org.opengis.metadata.spatial.PixelOrientation}
031 * except that the latter is more clearly restricted to the two-dimensional case.
032 *
033 * @author  OGC Topic 2 (for abstract model and documentation)
034 * @author  Martin Desruisseaux (IRD, Geomatys)
035 * @version 3.1
036 * @since   1.0
037 *
038 * @see org.opengis.metadata.spatial.PixelOrientation
039 *
040 * @deprecated This code list has been removed from ISO 19111:2019 together with {@code ImageDatum}.
041 * The "pixel in corner" versus "pixel in center" problematic will be handled by ISO 19123 instead.
042 */
043@Deprecated(since = "3.1")
044@Vocabulary(capacity=2)
045@UML(identifier="CD_PixelInCell", specification=ISO_19111, version=2007)
046public final class PixelInCell extends CodeList<PixelInCell> {
047    /**
048     * Serial number for compatibility with different versions.
049     */
050    private static final long serialVersionUID = 2857889370030758462L;
051
052    /**
053     * The origin of the image coordinate system is the centre of a grid cell or image pixel.
054     *
055     * @see org.opengis.metadata.spatial.PixelOrientation#CENTER
056     */
057    @UML(identifier="cell center", obligation=CONDITIONAL, specification=ISO_19111)
058    public static final PixelInCell CELL_CENTER = new PixelInCell("CELL_CENTER");
059
060    /**
061     * The origin of the image coordinate system is the corner of a grid cell,
062     * or half-way between the centres of adjacent image pixels.
063     *
064     * @see org.opengis.metadata.spatial.PixelOrientation#LOWER_LEFT
065     */
066    @UML(identifier="cell corner", obligation=CONDITIONAL, specification=ISO_19111)
067    public static final PixelInCell CELL_CORNER = new PixelInCell("CELL_CORNER");
068
069    /**
070     * Constructs an element of the given name.
071     *
072     * @param name  the name of the new element. This name shall not be in use by another element of this type.
073     */
074    private PixelInCell(final String name) {
075        super(name);
076    }
077
078    /**
079     * Returns the programmatic name and the UML identifier of this code, together with alternative UML identifier
080     * if any. In particular, {@link #CELL_CENTER} is known as both {@code "cell center"} (from ISO 19111:2007) and
081     * {@code "cell centre"} (derived from ISO 19162:2015).
082     *
083     * @return Names of this code, including alternative names if any.
084     */
085    @Override
086    public String[] names() {
087        if (this == CELL_CENTER) {
088            return new String[] {name(), "cell center", "cell centre"};
089        }
090        return super.names();
091    }
092
093    /**
094     * Returns the list of {@code PixelInCell}s.
095     *
096     * @return the list of codes declared in the current JVM.
097     */
098    public static PixelInCell[] values() {
099        return values(PixelInCell.class);
100    }
101
102    /**
103     * Returns the list of codes of the same kind as this code list element.
104     * Invoking this method is equivalent to invoking {@link #values()}, except that
105     * this method can be invoked on an instance of the parent {@code CodeList} class.
106     *
107     * @return all code {@linkplain #values() values} for this code list.
108     */
109    @Override
110    public PixelInCell[] family() {
111        return values();
112    }
113
114    /**
115     * Returns the pixel in cell that matches the given string, or returns a new one if none match it.
116     * This methods returns the first instance (in declaration order) for which the {@linkplain #name() name}
117     * is {@linkplain String#equalsIgnoreCase(String) equals, ignoring case}, to the given name.
118     * If no existing instance is found, then a new one is created for the given name.
119     *
120     * @param  code  the name of the code to fetch or to create.
121     * @return a code matching the given name.
122     */
123    public static PixelInCell valueOf(String code) {
124        return valueOf(PixelInCell.class, code, PixelInCell::new).get();
125    }
126}