Class Envelope

  • All Implemented Interfaces:
    JsonSerializable

    public final class Envelope
    extends Geometry
    A geometry that represents a rectangular shape.

    An Envelope is an axis-aligned box described by the coordinates of the lower left corner and the coordinates of the upper right corner. They are commonly used to represent the spatial extent covered by layers or other geometries, or to define an area of interest. They can be used as the geometry for a graphic and as an input for many spatial operations. Although they both represent a geographic area, an Envelope is distinct from a Polygon, and they cannot always be used interchangeably.

    New instances of Envelope are defined by specifying minimum and maximum x coordinates and minimum and maximum y coordinates, and a SpatialReference. Optionally, a minimum and maximum z value can be specified to define the depth of the envelope.

    The sides of an Envelope align with the axes of its SpatialReference. If the SpatialReference is a geographic coordinate system, the x coordinates relate to lines of longitude and the y coordinates relate to lines of latitude.

    Envelope is immutable. Instead of changing the properties of an existing Envelope, create new Envelope instances, or use EnvelopeBuilder.

    Envelopes cannot be used as the Geometry of a Feature.

    If the Envelope is empty, then getXMin(), getXMax(), getYMin(), getYMax(), getZMin(), getZMax(), getMMin(), getMMax(), getWidth(), getHeight(), and getCenter() will all return NaN.

    Since:
    100.0.0
    See Also:
    EnvelopeBuilder, Geometry
    • Constructor Summary

      Constructors 
      Constructor Description
      Envelope​(double x1, double y1, double x2, double y2, double z1, double z2, SpatialReference spatialReference)
      Creates a new immutable Envelope with the given minimum and maximum x,y coordinates, z value and SpatialReference.
      Envelope​(double x1, double y1, double x2, double y2, SpatialReference spatialReference)
      Creates a new immutable Envelope with the given minimum and maximum x,y coordinates and SpatialReference.
      Envelope​(Point center, double width, double height)
      Creates a new immutable Envelope with the given center point, width and height.
      Envelope​(Point center, double width, double height, double depth)
      Creates a new immutable Envelope with the given center point, width, height and depth.
      Envelope​(Point point1, Point point2)
      Creates a new immutable Envelope with opposing corners at the given Points.
    • Constructor Detail

      • Envelope

        public Envelope​(Point point1,
                        Point point2)
        Creates a new immutable Envelope with opposing corners at the given Points. The new Envelope has the same SpatialReference as point2.

        The two points can represent either the upper-left and lower-right corner, or the upper-right and lower-left corners of the Envelope.

        Parameters:
        point1 - the first corner of the new Envelope
        point2 - the second corner of the new Envelope
        Throws:
        IllegalArgumentException - if either parameter is null
        Since:
        100.0.0
      • Envelope

        public Envelope​(Point center,
                        double width,
                        double height)
        Creates a new immutable Envelope with the given center point, width and height. The new Envelope has the same SpatialReference as the given center point.
        Parameters:
        center - the center point of the new Envelope
        width - the width of the new Envelope around the center point
        height - the height of the new Envelope around the center point
        Throws:
        IllegalArgumentException - if center is null
        Since:
        100.1.0
      • Envelope

        public Envelope​(Point center,
                        double width,
                        double height,
                        double depth)
        Creates a new immutable Envelope with the given center point, width, height and depth. The new Envelope has the same SpatialReference as the given center point.
        Parameters:
        center - the center point of the new Envelope
        width - the width of the new Envelope around the center point
        height - the height of the new Envelope around the center point
        depth - the depth of the new Envelope around the center point
        Throws:
        IllegalArgumentException - if center is null
        Since:
        100.1.0
      • Envelope

        public Envelope​(double x1,
                        double y1,
                        double x2,
                        double y2,
                        SpatialReference spatialReference)
        Creates a new immutable Envelope with the given minimum and maximum x,y coordinates and SpatialReference.

        If x1 is larger than x2, then it is used as the maximum x coordinate of the new Envelope, and vice versa. The same applies to the other parameter pairs.

        Parameters:
        x1 - the first x coordinate of the new Envelope
        y1 - the first y coordinate of the new Envelope
        x2 - the second x coordinate of the new Envelope
        y2 - the second y coordinate of the new Envelope
        spatialReference - the spatial reference of the new Envelope, and of the x1, y1, x2, and y2 coordinate values
        Since:
        100.0.0
      • Envelope

        public Envelope​(double x1,
                        double y1,
                        double x2,
                        double y2,
                        double z1,
                        double z2,
                        SpatialReference spatialReference)
        Creates a new immutable Envelope with the given minimum and maximum x,y coordinates, z value and SpatialReference.

        If x1 is larger than x2, then it is used as the maximum x coordinate of the new Envelope, and vice versa. The same applies to the other parameter pairs.

        Parameters:
        x1 - the first x coordinate of the new Envelope
        y1 - the first y coordinate of the new Envelope
        x2 - the second x coordinate of the new Envelope
        y2 - the second y coordinate of the new Envelope
        z1 - the first z value of the new Envelope
        z2 - the second z value of the new Envelope
        spatialReference - the spatial reference of the new Envelope, and of the x1, y1, x2, and y2 coordinate values
        Since:
        100.0.0
    • Method Detail

      • createWithM

        public static Envelope createWithM​(double x1,
                                           double y1,
                                           double x2,
                                           double y2,
                                           double m1,
                                           double m2)
        Creates a new immutable Envelope with the given minimum and maximum x,y coordinates and m value.

        If x1 is larger than x2, then it is used as the maximum x coordinate of the new Envelope, and vice versa. The same applies to the other parameter pairs.

        Parameters:
        x1 - the first x coordinate of the new Envelope
        y1 - the first y coordinate of the new Envelope
        x2 - the second x coordinate of the new Envelope
        y2 - the second y coordinate of the new Envelope
        m1 - the first m value of the new Envelope
        m2 - the second m value of the new Envelope
        Returns:
        new envelope
        Since:
        100.0.0
      • createWithM

        public static Envelope createWithM​(double x1,
                                           double y1,
                                           double x2,
                                           double y2,
                                           double m1,
                                           double m2,
                                           SpatialReference spatialReference)
        Creates a new immutable Envelope with the given minimum and maximum x,y coordinates, m value and SpatialReference.

        If x1 is larger than x2, then it is used as the maximum x coordinate of the new Envelope, and vice versa. The same applies to the other parameter pairs.

        Parameters:
        x1 - the first x coordinate of the new Envelope
        y1 - the first y coordinate of the new Envelope
        x2 - the second x coordinate of the new Envelope
        y2 - the second y coordinate of the new Envelope
        m1 - the first m value of the new Envelope
        m2 - the second m value of the new Envelope
        spatialReference - the spatial reference of the new Envelope, and of the x1, y1, x2, and y2 coordinate values
        Returns:
        new envelope
        Since:
        100.0.0
      • createWithM

        public static Envelope createWithM​(double x1,
                                           double y1,
                                           double x2,
                                           double y2,
                                           double z1,
                                           double z2,
                                           double m1,
                                           double m2)
        Creates a new immutable Envelope with the given minimum and maximum x,y coordinates, z value and m value.

        If x1 is larger than x2, then it is used as the maximum x coordinate of the new Envelope, and vice versa. The same applies to the other parameter pairs.

        Parameters:
        x1 - the first x coordinate of the new Envelope
        y1 - the first y coordinate of the new Envelope
        x2 - the second x coordinate of the new Envelope
        y2 - the second y coordinate of the new Envelope
        z1 - the first z value of the new Envelope
        z2 - the second z value of the new Envelope
        m1 - the first m value of the new Envelope
        m2 - the second m value of the new Envelope
        Returns:
        new envelope
        Since:
        100.0.0
      • createWithM

        public static Envelope createWithM​(double x1,
                                           double y1,
                                           double x2,
                                           double y2,
                                           double z1,
                                           double z2,
                                           double m1,
                                           double m2,
                                           SpatialReference spatialReference)
        Creates a new immutable Envelope with the given minimum and maximum x,y coordinates, z value, m value and SpatialReference.

        If x1 is larger than x2, then it is used as the maximum x coordinate of the new Envelope, and vice versa. The same applies to the other parameter pairs.

        Parameters:
        x1 - the first x coordinate of the new Envelope
        y1 - the first y coordinate of the new Envelope
        x2 - the second x coordinate of the new Envelope
        y2 - the second y coordinate of the new Envelope
        z1 - the first z value of the new Envelope
        z2 - the second z value of the new Envelope
        m1 - the first m value of the new Envelope
        m2 - the second m value of the new Envelope
        spatialReference - the spatial reference of the new Envelope, and of the x1, y1, x2, and y2 coordinate values
        Returns:
        new envelope
        Since:
        100.0.0
      • getXMin

        public double getXMin()
        Gets the minimum x coordinate of this Envelope. The SpatialReference determines the coordinate units.

        If the SpatialReference is a geographic coordinate system, the x coordinate defines longitude, and the units will be angular.

        Returns:
        the minimum x coordinate of this Envelope
        Since:
        100.0.0
        See Also:
        getXMax(), getWidth()
      • getXMax

        public double getXMax()
        Gets the maximum x coordinate of this Envelope. The SpatialReference determines the coordinate units.

        If the SpatialReference is a geographic coordinate system, the x coordinate defines longitude, and the units will be angular.

        Returns:
        the maximum x coordinate of this Envelope
        Since:
        100.0.0
        See Also:
        getXMin(), getWidth()
      • getYMin

        public double getYMin()
        Gets the minimum y coordinate of this Envelope. The SpatialReference determines the coordinate units.

        If the SpatialReference is a geographic coordinate system, the y coordinate defines latitude, and the units will be angular.

        Returns:
        the minimum y coordinate of this Envelope
        Since:
        100.0.0
        See Also:
        getYMax(), getHeight()
      • getYMax

        public double getYMax()
        Gets the maximum y coordinate of this Envelope. The SpatialReference determines the coordinate units.

        If the SpatialReference is a geographic coordinate system, the y coordinate defines latitude, and the units will be angular.

        Returns:
        the maximum y coordinate of this Envelope
        Since:
        100.0.0
        See Also:
        getYMin(), getHeight()
      • getZMin

        public double getZMin()
        Gets the minimum z value of this Envelope.

        z values are used as z coordinates when displayed in 3D. The vertical coordinate system component of the Geometry.getSpatialReference() determines the units in this case.

        Returns:
        the minimum z value of this Envelope
        Since:
        100.0.0
        See Also:
        getZMax()
      • getZMax

        public double getZMax()
        Gets the maximum z value of this Envelope.

        Z values are used as z coordinates when displayed in 3D. The vertical coordinate system component of the Geometry.getSpatialReference() determines the units in this case.

        Returns:
        the maximum z value of this Envelope
        Since:
        100.0.0
        See Also:
        getZMin()
      • getMMin

        public double getMMin()
        Gets the minimum m value of this Envelope. M values do not have specific units.

        M values are also known as measures, and are used in linear referencing functions.

        Returns:
        the minimum m value of this Envelope
        Since:
        100.0.0
        See Also:
        getMMax()
      • getMMax

        public double getMMax()
        Gets the maximum m value of this Envelope. M values do not have specific units.

        M values are also known as measures, and are used in linear referencing functions.

        Returns:
        the maximum m value of this Envelope
        Since:
        100.0.0
        See Also:
        getMMin()
      • getWidth

        public double getWidth()
        Gets the width of this Envelope.

        The width of an Envelope is the difference between the minimum and maximum x coordinates. The units of the width are the same as the units of the Geometry.getSpatialReference().

        Returns:
        the width of this Envelope
        Since:
        100.0.0
        See Also:
        getXMin(), getXMax()
      • getHeight

        public double getHeight()
        Gets the height of this Envelope.

        The height of an Envelope is the difference between the minimum and maximum y coordinates. The units of the height are the same as the units of the Geometry.getSpatialReference().

        Returns:
        the height of this Envelope
        Since:
        100.0.0
        See Also:
        getYMin(), getYMax()
      • getDepth

        public double getDepth()
        Gets the depth of this Envelope.

        The depth of an Envelope is the difference between the minimum and maximum z values.

        Returns:
        the depth of this Envelope
        Since:
        100.1.0
        See Also:
        getZMin(), getZMax()
      • getCenter

        public Point getCenter()
        Gets a Point located at the center of this Envelope.
        Returns:
        a Point representing the center of this Envelope
        Since:
        100.0.0
      • getDimension

        public GeometryDimension getDimension()
        Description copied from class: Geometry
        Gets the dimension of this Geometry, relating to the number of spatial dimensions in which the geometry may have a size.
        Overrides:
        getDimension in class Geometry
        Returns:
        the dimension of this Geometry
      • getGeometryType

        public GeometryType getGeometryType()
        Description copied from class: Geometry
        Gets the type of this Geometry, indicating the subclass, and the type of geometrical shape it can represent.
        Overrides:
        getGeometryType in class Geometry
        Returns:
        the type of this Geometry
      • toString

        public String toString()
        Returns a string representation of this Envelope instance. The format and content of this string is subject to change without notice.

        This value may be useful for debugging purposes, but cannot be relied upon for persistence purposes.

        Overrides:
        toString in class Object
        Since:
        100.0.0
        See Also:
        Geometry.toJson()