com.mapinfo.midev.geometry

## Class Envelope

- java.lang.Object
- - com.mapinfo.midev.geometry.Envelope

All Implemented Interfaces:
  Serializable

    public final class Envelope
    extends Object
    implements Serializable

Represents the x and y extents of a geometry.

The behavior of `Envelope` is to identify the minimum and maximum x,y coordinate values from all the `DirectPosition`s in a geometry. The extents of the `Envelope` are the difference in value between the minimum and maximum x,y values.

An empty `Envelope`, e.g. one that has been instantiated using `Envelope.Envelope(SpatialInfo)`, does not enclose any `DirectPosition`s and thus has all empty x,y extents. An empty extent has no value, in particular it is not 0 which is a valid extent value. The methods to get extents, `Envelope.getExtentX()` and `Envelope.getExtentY()` throw a `InvalidGeometryOperationException` when that extent is empty as there is no legitimate value to return.

If the methods `Envelope.getLowerLeft()` and `Envelope.getUpperRight()` are called on an empty `Envelope`, they return `DirectPosition`s with all x,y initialized to `Double.POSITIVE_INFINITY` and `Double.NEGATIVE_INFINITY` respectively.

See Also:
  Serialized Form

### Constructor Summary

Constructors
Constructor and Description
`Envelope(DirectPosition dp1, DirectPosition dp2, SpatialInfo spatialInfo)` Create an `Envelope` given two direct positions and a coordinate system.
`Envelope(double x1, double y1, double x2, double y2, SpatialInfo spatialInfo)` Create an `Envelope` given two x,y values and a coordinate system.
`Envelope(Envelope e)` Create an Envelope as a copy of another `Envelope`.
`Envelope(SpatialInfo spatialInfo)` Create an empty `Envelope`.

### Method Summary

All Methods Instance Methods Concrete Methods
`boolean` `contains(DirectPosition dp)` Returns `true` if this `Envelope` contains the location as represented in the specified `DirectPosition`; `false` if not.
`boolean` `contains(Envelope env)` Returns `true` if this `Envelope` contains the specified `Envelope`; `false` if not.
`boolean` `equals(Object obj)`
`void` `expand(double deltaX, double deltaY)` Move the x,y sides of this `Envelope` toward or away from each other.
`void` `extend(DirectPosition dp)` Enlarge this `Envelope`, if necessary, to include the specified position.
`void` `extend(double x, double y)` Enlarge this `Envelope`, if necessary, to include the specified x,y coordinates.
`void` `extend(Envelope e)` Enlarge this `Envelope`, if necessary, to include the specified `Envelope`.
`void` `extend(IDirectPositionList dpl)` Enlarge this `Envelope`, if necessary, to include the `DirectPosition`s in the given list.
`DirectPosition` `getCenter()` Returns the center of the `Envelope`.
`Envelope` `getCopy()` Returns a copy of this `Envelope`.
`Envelope` `getCopy(SpatialInfo spatialInfo)` Returns a copy of this `Envelope` but with the coordinates transformed into the specified `SpatialInfo`.
`double` `getExtentX()` Returns the span of this `Envelope` in the x direction.
`double` `getExtentY()` Returns the span of this `Envelope` in the y direction.
`Envelope` `getIntersection(Envelope e)` Returns an `Envelope` that represents the intersection of the specified `Envelope` with this `Envelope`.
`double` `getLLX()` Returns the x value of the lower left corner of this `Envelope`.
`double` `getLLY()` Returns the y value of the lower left corner of this `Envelope`.
`DirectPosition` `getLowerLeft()` Returns the lower-left corner of the `Envelope`.
`SpatialInfo` `getSpatialInfo()` Returns the `Envelope`'s spatial metadata.
`DirectPosition` `getUpperRight()` Returns the upper-right corner of the `Envelope`.
`double` `getURX()` Returns the x value of the upper right corner of this `Envelope`.
`double` `getURY()` Returns the y value of the upper right corner of this `Envelope`.
`int` `hashCode()`
`boolean` `intersects(Envelope e)` Returns `true` if the specified `Envelope` intersects this `Envelope`; `false` otherwise.
`boolean` `isEmpty()` Returns `true` if this `Envelope` is empty; `false` if not.
`void` `offset(double deltaX, double deltaY)` Translate this `Envelope` in the x and y directions by the given deltas.
`void` `scale(double scaleX, double scaleY)` Expand or contract the extents of the `Envelope` by the given scale factors.
`void` `set(DirectPosition dp1, DirectPosition dp2)` Reinitialize this `Envelope` with the two given `DirectPosition`s.
`void` `set(double x1, double y1, double x2, double y2)` Reinitialize this `Envelope` with the two given x,y values.
`void` `setEmpty()` Re-initialize this `Envelope` to be empty.
`void` `setEmpty(SpatialInfo spatialInfo)` Re-initialize this envelope to be empty and to have the given spatial metadata.
`String` `toString()`

### Methods inherited from class java.lang.Object

`getClass, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### Envelope

    public Envelope(SpatialInfo spatialInfo)

Create an empty `Envelope`.

Parameters:
  `spatialInfo` - spatial metadata of the extends represented by this envelope. Cannot be null.
Throws:
  `IllegalArgumentException` - if the specified spatialInfo is null.

#### Envelope

    public Envelope(Envelope e)

Create an Envelope as a copy of another `Envelope`.

Parameters:
  `e` - the envelope to copy.
Throws:
  `IllegalArgumentException` - if the specified `Envelope` is null.

#### Envelope

    public Envelope(DirectPosition dp1,
                    DirectPosition dp2,
                    SpatialInfo spatialInfo)

Create an `Envelope` given two direct positions and a coordinate system.

The individual x and y coordinates in dp1 and dp2 are analyzed to find the min and max x and y values that are used to define the lower left and upper right corners of the resulting envelope. This constructor has the same behavior as:

       Envelope e = new Envelope(csys);
       e.extend(dp1);
       e.extend(dp2);

Parameters:
  `dp1` - first direct position.
  `dp2` - second direct positions.
  `spatialInfo` - spatial metadata of the extends represented by this envelope. Cannot be null.
Throws:
  `IllegalArgumentException` - if the specified `SpatialInfo` is null.

#### Envelope

    public Envelope(double x1,
                    double y1,
                    double x2,
                    double y2,
                    SpatialInfo spatialInfo)

Create an `Envelope` given two x,y values and a coordinate system.

The individual x,y coordinates are analyzed to find the min and max x and y values that are used to define the lower left and upper right corners of the resulting envelope. This constructor has the same behavior as:

       Envelope e = new Envelope(csys);
       e.extend(x1, y1);
       e.extend(x2, y2);

Parameters:
  `x1` - first x value
  `y1` - first y value
  `x2` - second x value
  `y2` - second y value
  `spatialInfo` - spatial metadata of the extends represented by this envelope. Cannot be null.
Throws:
  `IllegalArgumentException` - if the specified `SpatialInfo` is null.

### Method Detail

#### set

    public void set(DirectPosition dp1,
                    DirectPosition dp2)

Reinitialize this `Envelope` with the two given `DirectPosition`s.

The individual x and y ordinates in dp1 and dp2 are analyzed to find the min and max x and y ordinate that are used to define the lower left and upper right corners of the resulting envelope. This method has the same behavior as:

       e.setEmpty();
       e.extend(dp1);
       e.extend(dp2);

Parameters:
  `dp1` - first DirectPosition.
  `dp2` - second DirectPosition.

#### set

    public void set(double x1,
                    double y1,
                    double x2,
                    double y2)

Reinitialize this `Envelope` with the two given x,y values.

The individual x,y coordinates are analyzed to find the min and max x and y values that are used to define the lower left and upper right corners of the resulting envelope. This method has the same behavior as:

       e.setEmpty();
       e.extend(x1,y1);
       e.extend(x2,y2);

Parameters:
  `x1` - first x value
  `y1` - first y value
  `x2` - second x value
  `y2` - second y value

#### offset

    public void offset(double deltaX,
                       double deltaY)

Translate this `Envelope` in the x and y directions by the given deltas.

Parameters:
  `deltaX` - +/- offset in the x direction
  `deltaY` - +/- offset in the y direction

#### expand

    public void expand(double deltaX,
                       double deltaY)
                throws InvalidGeometryOperationException

Move the x,y sides of this `Envelope` toward or away from each other.

The effect of this method is to subtract the deltas from the lower left (LL) and add the deltas to the upper right (UR).

       LLX = LLX - deltaX
       LLY = LLY - deltaY
       URX = URX + deltaX
       URY = URY + deltaY

Depending on the sign of the deltas, the sides of the `Envelope` will move away from each other or toward each other. For example, if both deltas are positive the sides move apart. If both deltas are negative the sides move together. The center of the `Envelope` does not change.

Throws `InvalidGeometryOperationException` if either delta is negative and its absolute value is greater than half the envelope extent for that delta direction. This condition would cause the opposite sides of the envelope to move "behind" each other.

Parameters:
  `deltaX` - +/- expansion in the x direction
  `deltaY` - +/- expansion in the y direction
Throws:
  `InvalidGeometryOperationException` - if either delta is negative and its absolute value is greater than half the envelope extend for that direction.
See Also:
  `Envelope.getExtentX()`, `Envelope.getExtentY()`, `Envelope.expand(double,double,double)`, `Envelope.scale(double,double)`

#### scale

    public void scale(double scaleX,
                      double scaleY)
               throws InvalidGeometryOperationException

Expand or contract the extents of the `Envelope` by the given scale factors.

The extents are changed as follows:

       newExtentX = extentX + extentX * scaleX;
       newExtentY = extentY + extentY * scaleY;

Scale factor > 0 causes that extent to expand equally in both directions.
Scale factor = 0 leaves that extent unchanged
Scale factor < 0 causes that extent to contract equally in both directions.

Throws `InvalidGeometryOperationException` if scaleX < -1.0 or scaleY < -1.0 as this condition would cause the resulting `Envelope` to have a negative extent.

Parameters:
  `scaleX` - the x scale factor, must be => -1.0
  `scaleY` - the y scale factor, must be => -1.0
Throws:
  `InvalidGeometryOperationException` - if scaleX < -1.0 or scaleY < -1.0
See Also:
  `Envelope.getExtentX()`, `Envelope.getExtentY()`, `Envelope.expand(double,double)`

#### equals

    public boolean equals(Object obj)

Overrides:
  `equals` in class `Object`

#### hashCode

    public int hashCode()

Overrides:
  `hashCode` in class `Object`

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

#### getCopy

    public Envelope getCopy()

Returns a copy of this `Envelope`. Changes to the copy are not reflected in this `Envelope` and vise-versa.

Returns:
  a copy of this `Envelope`.

#### getCopy

    public Envelope getCopy(SpatialInfo spatialInfo)

Returns a copy of this `Envelope` but with the coordinates transformed into the specified `SpatialInfo`. Changes to the copy are not reflected in this `Envelope` and vise-versa.

Returns:
  a copy of this `Envelope` but with the coordinates transformed into the specified `SpatialInfo`.

#### extend

    public void extend(Envelope e)

Enlarge this `Envelope`, if necessary, to include the specified `Envelope`. No change if e is empty.

Parameters:
  `e` - the `Envelope` to enlarge by.

#### extend

    public void extend(DirectPosition dp)

Enlarge this `Envelope`, if necessary, to include the specified position.

Parameters:
  `dp` - the `DirectPosition` to include.

#### extend

    public void extend(double x,
                       double y)

Enlarge this `Envelope`, if necessary, to include the specified x,y coordinates.

Parameters:
  `x` - x coordinate
  `y` - y coordinate
See Also:
  `Envelope.extend(DirectPosition)`

#### extend

    public void extend(IDirectPositionList dpl)

Enlarge this `Envelope`, if necessary, to include the `DirectPosition`s in the given list.

Parameters:
  `dpl` - IDirectPositionList

#### intersects

    public boolean intersects(Envelope e)

Returns `true` if the specified `Envelope` intersects this `Envelope`; `false` otherwise.

Parameters:
  `e` - envelope to test for overlap with.
Returns:
  Returns `true` if the specified `Envelope` intersects this `Envelope`; `false` otherwise.

#### getIntersection

    public Envelope getIntersection(Envelope e)

Returns an `Envelope` that represents the intersection of the specified `Envelope` with this `Envelope`. If the `Envelopes` do not intersect the result is an empty `Envelope`. If either `Envelope` is empty the result is an empty `Envelope`.

Parameters:
  `e` - the input `Envelope` to intersect with this one.
Returns:
  Returns an `Envelope` that represents the intersection of the specified `Envelope` with this `Envelope`.

#### contains

    public boolean contains(DirectPosition dp)

Returns `true` if this `Envelope` contains the location as represented in the specified `DirectPosition`; `false` if not.

Parameters:
  `dp` - a `DirectPosition`
Returns:
  `true` if this `Envelope` contains the location as represented in the specified `DirectPosition`; `false` if not.

#### contains

    public boolean contains(Envelope env)

Returns `true` if this `Envelope` contains the specified `Envelope`; `false` if not.

Parameters:
  `env` - the `Envelope` to check for containment.
Returns:
  Returns `true` if this `Envelope` contains the specified `Envelope`; `false` if not.

#### getCenter

    public DirectPosition getCenter()
                             throws InvalidGeometryException

Returns the center of the `Envelope`.

Returns:
  the center of the `Envelope`.
Throws:
  `InvalidGeometryException` - if this `Envelope` is empty

#### getUpperRight

    public DirectPosition getUpperRight()

Returns the upper-right corner of the `Envelope`.

Returns:
  the upper-right corner of the `Envelope`.

#### getLowerLeft

    public DirectPosition getLowerLeft()

Returns the lower-left corner of the `Envelope`.

Returns:
  the lower-left corner of the `Envelope`.

#### getExtentX

    public double getExtentX()
                      throws InvalidGeometryException

Returns the span of this `Envelope` in the x direction.

Returns:
  the span of this `Envelope` in the x direction.
Throws:
  `InvalidGeometryException` - if the `Envelope` is empty
See Also:
  `Envelope.isEmpty()`

#### getExtentY

    public double getExtentY()
                      throws InvalidGeometryException

Returns the span of this `Envelope` in the y direction.

Returns:
  the span of this `Envelope` in the y direction.
Throws:
  `InvalidGeometryException` - if the `Envelope` is empty
See Also:
  `Envelope.isEmpty()`

#### isEmpty

    public boolean isEmpty()

Returns `true` if this `Envelope` is empty; `false` if not.

Returns:
  `true` if this `Envelope` is empty; `false` if not.

#### setEmpty

    public void setEmpty()

Re-initialize this `Envelope` to be empty.

#### setEmpty

    public void setEmpty(SpatialInfo spatialInfo)

Re-initialize this envelope to be empty and to have the given spatial metadata.

Parameters:
  `spatialInfo` - the spatial metadata to have.

#### getSpatialInfo

    public SpatialInfo getSpatialInfo()

Returns the `Envelope`'s spatial metadata.

Returns:
  the `Envelope`'s spatial metadata.

#### getLLX

    public double getLLX()

Returns the x value of the lower left corner of this `Envelope`.

Returns:
  the x value of the lower left corner of this `Envelope`.

#### getLLY

    public double getLLY()

Returns the y value of the lower left corner of this `Envelope`.

Returns:
  the y value of the lower left corner of this `Envelope`.

#### getURX

    public double getURX()

Returns the x value of the upper right corner of this `Envelope`.

Returns:
  the x value of the upper right corner of this `Envelope`.

#### getURY

    public double getURY()

Returns the y value of the upper right corner of this `Envelope`.

Returns:
  the y value of the upper right corner of this `Envelope`.