org.opengis.geometry.Envelope Maven / Gradle / Ivy

/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2011, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2003-2005, Open Geospatial Consortium Inc.
 *
 *    All Rights Reserved. http://www.opengis.org/legal/
 */
package org.opengis.geometry;

import static org.opengis.annotation.Obligation.*;
import static org.opengis.annotation.Specification.*;

import java.awt.geom.Rectangle2D; // Used in @see javadoc tags
import org.opengis.annotation.Extension;
import org.opengis.annotation.UML;
import org.opengis.referencing.crs.CoordinateReferenceSystem;

/**
 * A minimum bounding box or rectangle. Regardless of dimension, an {@code Envelope} can be
 * represented without ambiguity as two direct positions (coordinate points). To encode an {@code
 * Envelope}, it is sufficient to encode these two points. This is consistent with all of the data
 * types in this specification, their state is represented by their publicly accessible attributes.
 *
 * @version ISO 19107
 * @author Martin Desruisseaux (IRD)
 * @since GeoAPI 1.0
 * @see org.opengis.coverage.grid.GridEnvelope
 */
@UML(identifier = "GM_Envelope", specification = ISO_19107)
public interface Envelope {
    /**
     * Returns the envelope coordinate reference system, or {@code null} if unknown. If non-null, it
     * shall be the same as {@linkplain #getLowerCorner lower corner} and {@linkplain
     * #getUpperCorner upper corner} CRS.
     *
     * @return The envelope CRS, or {@code null} if unknown.
     * @since GeoAPI 2.1
     */
    @Extension
    CoordinateReferenceSystem getCoordinateReferenceSystem();

    /**
     * The length of coordinate sequence (the number of entries) in this envelope. Mandatory even
     * when the {@linkplain #getCoordinateReferenceSystem coordinate reference system} is unknown.
     *
     * @return The dimensionality of this envelope.
     * @since GeoAPI 2.0
     */
    @Extension
    int getDimension();

    /**
     * A coordinate position consisting of all the minimal ordinates for each dimension for all
     * points within the {@code Envelope}.
     *
     * @return The lower corner.
     */
    @UML(identifier = "lowerCorner", obligation = MANDATORY, specification = ISO_19107)
    DirectPosition getLowerCorner();

    /**
     * A coordinate position consisting of all the maximal ordinates for each dimension for all
     * points within the {@code Envelope}.
     *
     * @return The upper corner.
     */
    @UML(identifier = "upperCorner", obligation = MANDATORY, specification = ISO_19107)
    DirectPosition getUpperCorner();

    /**
     * Returns the minimal ordinate along the specified dimension. This is a shortcut for the
     * following without the cost of creating a temporary {@link DirectPosition} object:
     *
     * 
     *
     * 
     * {@linkplain #getLowerCorner}.{@linkplain DirectPosition#getOrdinate getOrdinate}(dimension)
     * 
     *
     * 
     *
     * @param dimension The dimension for which to obtain the ordinate value.
     * @return The minimal ordinate at the given dimension.
     * @throws IndexOutOfBoundsException If the given index is negative or is equals or greater than
     *     the {@linkplain #getDimension envelope dimension}.
     * @see Rectangle2D#getMinX
     * @see Rectangle2D#getMinY
     * @since GeoAPI 2.0
     */
    @Extension
    double getMinimum(int dimension) throws IndexOutOfBoundsException;

    /**
     * Returns the maximal ordinate along the specified dimension. This is a shortcut for the
     * following without the cost of creating a temporary {@link DirectPosition} object:
     *
     * 
     *
     * 
     * {@linkplain #getUpperCorner}.{@linkplain DirectPosition#getOrdinate getOrdinate}(dimension)
     * 
     *
     * 
     *
     * @param dimension The dimension for which to obtain the ordinate value.
     * @return The maximal ordinate at the given dimension.
     * @throws IndexOutOfBoundsException If the given index is negative or is equals or greater than
     *     the {@linkplain #getDimension envelope dimension}.
     * @see Rectangle2D#getMaxX
     * @see Rectangle2D#getMaxY
     * @since GeoAPI 2.0
     */
    @Extension
    double getMaximum(int dimension) throws IndexOutOfBoundsException;

    /**
     * Returns the median ordinate along the specified dimension. The result should be equals (minus
     * rounding error) to:
     *
     * 
     *
     * 
     * ({@linkplain #getMinimum getMinimum}(dimension) + {@linkplain #getMaximum getMaximum}(dimension)) / 2
     * 
     *
     * 
     *
     * @param dimension The dimension for which to obtain the ordinate value.
     * @return The median ordinate at the given dimension.
     * @throws IndexOutOfBoundsException If the given index is negative or is equals or greater than
     *     the {@linkplain #getDimension envelope dimension}.
     * @see Rectangle2D#getCenterX
     * @see Rectangle2D#getCenterY
     * @since GeoAPI 2.2
     */
    @Extension
    double getMedian(int dimension) throws IndexOutOfBoundsException;

    /**
     * Returns the envelope span (typically width or height) along the specified dimension. The
     * result should be equals (minus rounding error) to:
     *
     * 
     *
     * 
     * {@linkplain #getMaximum getMaximum}(dimension) - {@linkplain #getMinimum getMinimum}(dimension)
     * 
     *
     * 
     *
     * @param dimension The dimension for which to obtain the ordinate value.
     * @return The span (typically width or height) at the given dimension.
     * @throws IndexOutOfBoundsException If the given index is negative or is equals or greater than
     *     the {@linkplain #getDimension envelope dimension}.
     * @see Rectangle2D#getWidth
     * @see Rectangle2D#getHeight
     * @since GeoAPI 2.2
     */
    @Extension
    double getSpan(int dimension) throws IndexOutOfBoundsException;
}