Package com.esri.arcgisruntime.geometry

Class EnvelopeBuilder

  • public final class EnvelopeBuilder
extends GeometryBuilder
    Helper class for building immutable Envelope geometries. Envelopes are straightforward geometries to define, and therefore Envelope class constructors provide very similar options as available on this builder. This builder class is provided mainly for consistency with other immutable geometries.

    Use the constructors to define minimum and maximum x,y coordinates, z- and m values, and a SpatialReference. Once set, the SpatialReference cannot be changed. Each other value can also be set individually or later modified by using the setter methods. Call the toGeometry() method to create a new immutable Envelope from the current values of this builder.

    Since:
    100.0.0
    See Also:
    GeometryBuilder, Envelope

    • Constructor Summary

      Constructors 
      Constructor Description
      EnvelopeBuilder​(Envelope envelope)
      Creates a new EnvelopeBuilder with values from the given Envelope.
      EnvelopeBuilder​(Point center, double width, double height)
      Creates a new EnvelopeBuilder with the given center point, width and height.
      EnvelopeBuilder​(Point center, double width, double height, double depth)
      Creates a new EnvelopeBuilder with the given center point, width, height and depth.
      EnvelopeBuilder​(SpatialReference spatialReference)
      Creates a new empty EnvelopeBuilder with the given SpatialReference.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void centerAt​(Point point)
      Re-centers the builder's Envelope geometry at the specified location.
      void changeAspectRatio​(double width, double height)
      Adjusts the Envelope's aspect ratio to match the ratio of the given width and height.
      void expand​(double factor)
      Expands the builder's Envelope geometry.
      void expand​(Point anchorPoint, double factor)
      Expands the builder's Envelope geometry at the given anchor point by the given factor.
      Point getCenter()
      Gets a Point at the center of the Envelope currently being constructed.
      double getDepth()
      Gets the current depth of the Envelope being constructed.
      double getHeight()
      Gets the current height of the Envelope being constructed, the difference between the minimum and maximum y coordinates.
      double getMMax()
      Gets the current maximum m value of the Envelope being constructed.
      double getMMin()
      Gets the current minimum m value of the Envelope being constructed.
      double getWidth()
      Gets the current width of the Envelope being constructed, the difference between the minimum and maximum x coordinates.
      double getXMax()
      Gets the current maximum x coordinate of the Envelope being constructed.
      double getXMin()
      Gets the current minimum x coordinate of the Envelope being constructed.
      double getYMax()
      Gets the current maximum y coordinate of the Envelope being constructed..
      double getYMin()
      Gets the current minimum y coordinate of the Envelope being constructed.
      double getZMax()
      Gets the current maximum z value of the Envelope being constructed.
      double getZMin()
      Gets the current minimum z value of the Envelope being constructed.
      void offsetBy​(double offsetX, double offsetY)
      Moves the builder's Envelope geometry by the given offsets.
      void setM​(double mMin, double mMax)
      Sets the new maximum and minimum m values of the Envelope currently being constructed.
      void setMMax​(double mMax)
      Sets a new maximum m value of the Envelope being constructed.
      void setMMin​(double mMin)
      Sets a new minimum m value of the Envelope being constructed.
      void setXMax​(double xMax)
      Sets a new maximum x coordinate of the Envelope being constructed.
      void setXMin​(double xMin)
      Sets a new minimum x coordinate of the Envelope being constructed.
      void setXY​(double xMin, double yMin, double xMax, double yMax)
      Sets new maximum and minimum x and y coordinates of the Envelope currently being constructed.
      void setYMax​(double yMax)
      Sets a new maximum y coordinate of the Envelope being constructed.
      void setYMin​(double yMin)
      Sets a new minimum y coordinate of the Envelope being constructed.
      void setZ​(double zMin, double zMax)
      Sets the new maximum and minimum z values of the Envelope currently being constructed.
      void setZMax​(double zMax)
      Sets a new maximum z value of the Envelope being constructed.
      void setZMin​(double zMin)
      Sets a new minimum z value of the Envelope being constructed.
      Envelope toGeometry()
      Returns a new Envelope based on the current state of this builder.
      void unionOf​(Envelope envelope)
      Finds the union of the builder's Envelope geometry and the given Envelope and updates the builder with the result.
      void unionOf​(Point point)
      Finds the union of the builder's Envelope geometry and the given point and updates the Envelope builder with the result.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • EnvelopeBuilder

        public EnvelopeBuilder​(SpatialReference spatialReference)
        Creates a new empty EnvelopeBuilder with the given SpatialReference.
        Parameters:
        spatialReference - the SpatialReference of the new builder
        Since:
        100.0.0

      • EnvelopeBuilder

        public EnvelopeBuilder​(Envelope envelope)
        Creates a new EnvelopeBuilder with values from the given Envelope. The SpatialReference of the new builder will match that of the given Envelope. Use this constructor in workflows that create a modified version of an existing geometry, for example feature or graphic editing workflows.
        Parameters:
        envelope - the envelope used to initialize this builder
        Since:
        100.0.0

      • EnvelopeBuilder

        public EnvelopeBuilder​(Point center,
                       double width,
                       double height)
        Creates a new EnvelopeBuilder with the given center point, width and height. The SpatialReference of the new builder will match that of the given center point.
        Parameters:
        center - the center point of the Envelope
        width - the width of the Envelope around the center point
        height - the height of the Envelope around the center point
        Throws:
        java.lang.IllegalArgumentException - if center is null
        Since:
        100.1.0

      • EnvelopeBuilder

        public EnvelopeBuilder​(Point center,
                       double width,
                       double height,
                       double depth)
        Creates a new EnvelopeBuilder with the given center point, width, height and depth. The SpatialReference of the new builder will match that of the given center point.
        Parameters:
        center - the center point of the Envelope
        width - the width of the Envelope around the center point
        height - the height of the Envelope around the center point
        depth - the depth of the Envelope around the center point
        Throws:
        java.lang.IllegalArgumentException - if center is null
        Since:
        100.1.0

    • Method Detail

      • getXMin

        public double getXMin()
        Gets the current minimum x coordinate of the Envelope being constructed.
        Returns:
        the current minimum x coordinate
        Since:
        100.0.0

      • setXMin

        public void setXMin​(double xMin)
        Sets a new minimum x coordinate of the Envelope being constructed.
        Parameters:
        xMin - the new minimum x coordinate
        Since:
        100.0.0

      • getYMin

        public double getYMin()
        Gets the current minimum y coordinate of the Envelope being constructed.
        Returns:
        the current minimum y coordinate
        Since:
        100.0.0

      • setYMin

        public void setYMin​(double yMin)
        Sets a new minimum y coordinate of the Envelope being constructed.
        Parameters:
        yMin - the new minimum y coordinate
        Since:
        100.0.0

      • getZMin

        public double getZMin()
        Gets the current minimum z value of the Envelope being constructed.
        Returns:
        the current minimum z value
        Since:
        100.0.0

      • setZMin

        public void setZMin​(double zMin)
        Sets a new minimum z value of the Envelope being constructed.
        Parameters:
        zMin - the new minimum z value
        Since:
        100.0.0

      • getMMin

        public double getMMin()
        Gets the current minimum m value of the Envelope being constructed. By default, m values are NaN.
        Returns:
        the current minimum m value
        Since:
        100.0.0

      • setMMin

        public void setMMin​(double mMin)
        Sets a new minimum m value of the Envelope being constructed. NaN is a valid m value.
        Parameters:
        mMin - the new minimum m value
        Since:
        100.0.0

      • getXMax

        public double getXMax()
        Gets the current maximum x coordinate of the Envelope being constructed.
        Returns:
        the current maximum x coordinate
        Since:
        100.0.0

      • setXMax

        public void setXMax​(double xMax)
        Sets a new maximum x coordinate of the Envelope being constructed.
        Parameters:
        xMax - the new maximum x coordinate
        Since:
        100.0.0

      • getYMax

        public double getYMax()
        Gets the current maximum y coordinate of the Envelope being constructed..
        Returns:
        the current maximum y coordinate
        Since:
        100.0.0

      • setYMax

        public void setYMax​(double yMax)
        Sets a new maximum y coordinate of the Envelope being constructed.
        Parameters:
        yMax - the new maximum y coordinate
        Since:
        100.0.0

      • getZMax

        public double getZMax()
        Gets the current maximum z value of the Envelope being constructed.
        Returns:
        the current maximum z value
        Since:
        100.0.0

      • setZMax

        public void setZMax​(double zMax)
        Sets a new maximum z value of the Envelope being constructed.
        Parameters:
        zMax - the new maximum z value
        Since:
        100.0.0

      • getMMax

        public double getMMax()
        Gets the current maximum m value of the Envelope being constructed. By default, m values are NaN.
        Returns:
        the current maximum m value
        Since:
        100.0.0

      • setMMax

        public void setMMax​(double mMax)
        Sets a new maximum m value of the Envelope being constructed. NaN is a valid m value.
        Parameters:
        mMax - the new maximum m value
        Since:
        100.0.0

      • getWidth

        public double getWidth()
        Gets the current width of the Envelope being constructed, the difference between the minimum and maximum x coordinates.
        Returns:
        the width of the Envelope
        Since:
        100.0.0

      • getHeight

        public double getHeight()
        Gets the current height of the Envelope being constructed, the difference between the minimum and maximum y coordinates.
        Returns:
        the height of the Envelope
        Since:
        100.0.0

      • getDepth

        public double getDepth()
        Gets the current depth of the Envelope being constructed.

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

        Returns:
        the depth of the Envelope
        Since:
        100.1.0

      • getCenter

        public Point getCenter()
        Gets a Point at the center of the Envelope currently being constructed.
        Returns:
        the center point
        Since:
        100.0.0

      • setXY

        public void setXY​(double xMin,
                  double yMin,
                  double xMax,
                  double yMax)
        Sets new maximum and minimum x and y coordinates of the Envelope currently being constructed. Note that the SpatialReference of a builder cannot be changed after it is initialized.
        Parameters:
        xMin - the new minimum x coordinate
        yMin - the new minimum y coordinate
        xMax - the new maximum x coordinate
        yMax - the new maximum y coordinate
        Since:
        100.0.0

      • setZ

        public void setZ​(double zMin,
                 double zMax)
        Sets the new maximum and minimum z values of the Envelope currently being constructed.
        Parameters:
        zMin - the new minimum z value
        zMax - the new maximum z value
        Since:
        100.0.0

      • setM

        public void setM​(double mMin,
                 double mMax)
        Sets the new maximum and minimum m values of the Envelope currently being constructed.
        Parameters:
        mMin - the new minimum m value
        mMax - the new maximum m value
        Since:
        100.0.0

      • toGeometry

        public Envelope toGeometry()
        Returns a new Envelope based on the current state of this builder. This method can be called as many times as required for any specific instance; it does not affect the state of the builder, and returns a new Envelope each time.
        Specified by:
        toGeometry in class GeometryBuilder
        Returns:
        a new Envelope based on the current state of this builder
        Since:
        100.0.0

      • centerAt

        public void centerAt​(Point point)
        Re-centers the builder's Envelope geometry at the specified location. The point's spatial reference must be the same as the builder's.
        Parameters:
        point - the point to center at
        Throws:
        java.lang.IllegalArgumentException - if point is null
        Since:
        100.5.0

      • changeAspectRatio

        public void changeAspectRatio​(double width,
                              double height)
        Adjusts the Envelope's aspect ratio to match the ratio of the given width and height. The operation preserves the center of the Envelope and will only increase either height or width, not both. If the new width would be greater than the old, the width will be changed and the height will remain the same. If the new width would be less than or equal to the old, the height will be changed and the width will remain the same. For example, for an EnvelopeBuilder who's current Envelope's width is 100 and height is 50, calling changeAspectRatio(2, 3) will result in an Envelope with a width of 100 and a height of 150.
        Parameters:
        width - a width
        height - a height
        Since:
        100.5.0

      • offsetBy

        public void offsetBy​(double offsetX,
                     double offsetY)
        Moves the builder's Envelope geometry by the given offsets.
        Parameters:
        offsetX - the number of units to move the envelope on the x-axis
        offsetY - the number of units to move the envelope on the y-axis
        Since:
        100.5.0

      • expand

        public void expand​(double factor)
        Expands the builder's Envelope geometry. A factor of less than 1.0 shrinks the envelope and greater than 1.0 expands it. The Envelope's center remains unchanged, but its corners change. This is the same as calling expand(Point, double) with the Envelope's center.
        Parameters:
        factor - the factor to scale the envelope by
        Since:
        100.5.0

      • expand

        public void expand​(Point anchorPoint,
                   double factor)
        Expands the builder's Envelope geometry at the given anchor point by the given factor. A factor of less than 1.0 shrinks the envelope and greater than 1.0 expands it.
        Parameters:
        anchorPoint - a point within the envelope to expand from
        factor - the factor to scale the envelope by
        Throws:
        java.lang.IllegalArgumentException - if anchorPoint is null
        Since:
        100.5.0

      • unionOf

        public void unionOf​(Envelope envelope)
        Finds the union of the builder's Envelope geometry and the given Envelope and updates the builder with the result.
        Parameters:
        envelope - another Envelope to union with
        Throws:
        java.lang.IllegalArgumentException - if envelope is null
        Since:
        100.5.0

      • unionOf

        public void unionOf​(Point point)
        Finds the union of the builder's Envelope geometry and the given point and updates the Envelope builder with the result.
        Parameters:
        point - a point to union with
        Throws:
        java.lang.IllegalArgumentException - if point is null
        Since:
        100.5.0