java.lang.Object
com.esri.arcgisruntime.geometry.Geometry
com.esri.arcgisruntime.geometry.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:
  • 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.
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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.
    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.
    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.
    Gets a Point located at the center of this Envelope.
    double
    Gets the depth of this Envelope.
    Gets the dimensionality of a Geometry, relating to the number of spatial dimensions in which the geometry may have a size.
    Gets the type of this Geometry, indicating the subclass, and the type of geometrical shape it can represent.
    double
    Gets the height of this Envelope.
    double
    Gets the maximum m value of this Envelope.
    double
    Gets the minimum m value of this Envelope.
    double
    Gets the width of this Envelope.
    double
    Gets the maximum x coordinate of this Envelope.
    double
    Gets the minimum x coordinate of this Envelope.
    double
    Gets the maximum y coordinate of this Envelope.
    double
    Gets the minimum y coordinate of this Envelope.
    double
    Gets the maximum z value of this Envelope.
    double
    Gets the minimum z value of this Envelope.
    Returns a string representation of this Envelope instance.

    Methods inherited from class com.esri.arcgisruntime.geometry.Geometry

    equals, equals, fromJson, fromJson, getExtent, getSpatialReference, getUnknownJson, getUnsupportedJson, hasCurves, hashCode, hasM, hasZ, isEmpty, toJson

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • 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 Details

    • 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:
      an envelope. This is passed to geometry or envelope functions.
      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:
      an envelope. This is passed to geometry or envelope functions.
      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:
      an envelope. This is passed to geometry or envelope functions.
      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:
      an envelope. This is passed to geometry or envelope functions.
      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

      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:
    • 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

      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:
    • 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

      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:
    • 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

      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:
    • 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:
    • 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:
    • 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:
    • 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 dimensionality of a Geometry, relating to the number of spatial dimensions in which the geometry may have a size.

      You can use Geometry.getDimension() to work out what kind of symbol can be applied to a specific type of geometry. For example, Point and Multipoint are both zero-dimensional point geometries, and both can be displayed using a type of MarkerSymbol. Polygon and Envelope are both 2-dimensional area geometries that can be displayed using a type of FillSymbol.

      Returns GeometryDimension.UNKNOWN if an error occurs.

      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: