geos::geom::Envelope Class Reference

An Envelope defines a rectangulare region of the 2D coordinate plane. More...

`#include <geos.h>`

## Public Types

typedef std::unique_ptr< Envelope > | Ptr

## Public Member Functions

| Envelope ()
| Creates a null Envelope.
| Envelope (double x1, double x2, double y1, double y2)
| Creates an Envelope for a region defined by maximum and minimum values.
| Envelope (const CoordinateXY &p1, const CoordinateXY &p2)
| Creates an Envelope for a region defined by two Coordinates.
| Envelope (const CoordinateXY &p)
| Creates an Envelope for a region defined by a single Coordinate.
| Envelope (const std::string &str)
| Create an Envelope from an Envelope string representation produced by Envelope::toString().
bool | intersects (const CoordinateXY &a, const CoordinateXY &b) const
| Check if the extent defined by two extremal points intersects the extent of this Envelope.
void | init ()
| Initialize to a null Envelope.
void | init (double x1, double x2, double y1, double y2)
| Initialize an Envelope for a region defined by maximum and minimum values.
void | init (const CoordinateXY &p1, const CoordinateXY &p2)
| Initialize an Envelope to a region defined by two Coordinates.
void | init (const CoordinateXY &p)
| Initialize an Envelope to a region defined by a single Coordinate.
void | setToNull ()
| Makes this Envelope a "null" envelope, that is, the envelope of the empty geometry.
bool | isNull (void) const
| Returns true if this Envelope is a "null" envelope.
double | getWidth () const
| Returns the difference between the maximum and minimum x values.
double | getHeight () const
| Returns the difference between the maximum and minimum y values.
double | getArea () const
| Gets the area of this envelope.
double | getPerimeter () const
| Gets the perimeter of this envelope.
bool | isFinite () const
| Returns true if this Envelope covers a finite region.
double | getMaxY () const
| Returns the Envelope maximum y-value. Null envelopes do not have maximum values.
double | getMaxX () const
| Returns the Envelope maximum x-value. Null envelopes do not have maximum values.
double | getMinY () const
| Returns the Envelope minimum y-value. Null envelopes do not have maximum values.
double | getMinX () const
| Returns the Envelope minimum x-value. Null envelopes do not have maximum values.
double | getDiameter () const
bool | centre (CoordinateXY &centre) const
| Computes the coordinate of the centre of this envelope (as long as it is non-null).
bool | intersection (const Envelope &env, Envelope &result) const
| Computes the intersection of two Envelopes.
Envelope | intersection (const Envelope &env) const
| Computes the intersection of two Envelopes.
void | translate (double transX, double transY)
| Translates this envelope by given amounts in the X and Y direction.
void | expandBy (double deltaX, double deltaY)
| Expands this envelope by a given distance in all directions. Both positive and negative distances are supported.
void | expandBy (double p_distance)
| Expands this envelope by a given distance in all directions.
void | expandToInclude (const CoordinateXY &p)
| Enlarges the boundary of the Envelope so that it contains p. Does nothing if p is already on or within the boundaries.
void | expandToInclude (double x, double y)
| Enlarges the boundary of the Envelope so that it contains (x,y).
void | expandToInclude (const Envelope *other)
| Enlarges the boundary of the Envelope so that it contains other.
void | expandToInclude (const Envelope &other)
bool | contains (const Envelope &other) const
| Tests if the Envelope other lies wholly inside this Envelope (inclusive of the boundary).
bool | contains (const Envelope *other) const
bool | contains (const CoordinateXY &p) const
| Returns true if the given point lies in or on the envelope.
bool | contains (double x, double y) const
| Returns true if the given point lies in or on the envelope.
bool | intersects (const CoordinateXY &other) const
| Check if the point p intersects (lies inside) the region of this Envelope.
bool | intersects (double x, double y) const
| Check if the point (x, y) intersects (lies inside) the region of this Envelope.
bool | intersects (const Envelope *other) const
| Check if the region defined by other Envelope intersects the region of this Envelope.
bool | intersects (const Envelope &other) const
bool | disjoint (const Envelope &other) const
bool | disjoint (const Envelope *other) const
bool | covers (double x, double y) const
| Tests if the given point lies in or on the envelope.
bool | covers (const CoordinateXY *p) const
| Tests if the given point lies in or on the envelope.
bool | covers (const Envelope &other) const
| Tests if the Envelope other lies wholly inside this Envelope (inclusive of the boundary).
bool | covers (const Envelope *other) const
bool | equals (const Envelope *other) const
| Returns true if the Envelope other spatially equals this Envelope.
bool | isfinite () const
std::string | toString () const
| Returns a string of the form Env[minx:maxx,miny:maxy].
double | distance (const Envelope &env) const
| Computes the distance between this and another Envelope.
double | maxDistance (const Envelope &other) const
| Computes the maximum distance between points in this and another Envelope.
double | distanceSquared (const Envelope &env) const
| Computes the square of the distance between this and another Envelope.
std::size_t | hashCode () const

## Static Public Member Functions

static bool | intersects (const CoordinateXY &p1, const CoordinateXY &p2, const CoordinateXY &q)
| Test the point q to see whether it intersects the Envelope defined by p1-p2.
static bool | intersects (const CoordinateXY &p1, const CoordinateXY &p2, const CoordinateXY &q1, const CoordinateXY &q2)
| Test the envelope defined by p1-p2 for intersection with the envelope defined by q1-q2.
static double | distanceToCoordinate (const CoordinateXY &c, const CoordinateXY &p0, const CoordinateXY &p1)
| Computes the distance between one Coordinate and an Envelope defined by two other Coordinates. The order of the Coordinates used to define the envelope is not significant.
static double | distanceSquaredToCoordinate (const CoordinateXY &c, const CoordinateXY &p0, const CoordinateXY &p1)
| Computes the squared distance between one Coordinate and an Envelope defined by two other Coordinates. The order of the Coordinates used to define the envelope is not significant.

## Friends

std::ostream & | operator<< (std::ostream &os, const Envelope &o)
| Output operator.
bool | operator== (const Envelope &a, const Envelope &b)
| Checks if two Envelopes are equal (2D only check).
bool | operator!= (const Envelope &a, const Envelope &b)
bool | operator< (const Envelope &a, const Envelope &b)

## Detailed Description

An Envelope defines a rectangulare region of the 2D coordinate plane.

It is often used to represent the bounding box of a Geometry, e.g. the minimum and maximum x and y values of the Coordinates.

Envelopes allow null values, which are represented with NaN values for ordinates. Envelopes support infinite or half-infinite regions, by using the values of Double_POSITIVE_INFINITY and Double_NEGATIVE_INFINITY.

When Envelope objects are created or initialized, the supplies extent values are automatically sorted into the correct order.

## Constructor & Destructor Documentation

## Envelope() [1/3]

geos::geom::Envelope::Envelope | ( | double | x1,
|  | double | x2,
|  | double | y1,
|  | double | y2 )

inline

Creates an Envelope for a region defined by maximum and minimum values.

Parameters

  x1 | the first x-value
  x2 | the second x-value
  y1 | the first y-value
  y2 | the second y-value

References init().

## Envelope() [2/3]

geos::geom::Envelope::Envelope | ( | const CoordinateXY & | p1,
|  | const CoordinateXY & | p2 )

inline

Creates an Envelope for a region defined by two Coordinates.

Parameters

  p1 | the first Coordinate
  p2 | the second Coordinate

References init().

## Envelope() [3/3]

geos::geom::Envelope::Envelope | ( | const CoordinateXY & | p | ) |

inline explicit

Creates an Envelope for a region defined by a single Coordinate.

Parameters

  p | the Coordinate

## Member Function Documentation

## centre()

bool geos::geom::Envelope::centre | ( | CoordinateXY & | centre | ) | const

Computes the coordinate of the centre of this envelope (as long as it is non-null).

Parameters

  centre | The coordinate to write results into

Returns
  false if the center could not be found (null envelope).

References centre().

Referenced by centre().

## contains() [1/3]

bool geos::geom::Envelope::contains | ( | const CoordinateXY & | p | ) | const

inline

Returns true if the given point lies in or on the envelope.

Parameters

  p | the point which this Envelope is being checked for containing

Returns
  true if the point lies in the interior or on the boundary of this Envelope.

References covers().

## contains() [2/3]

bool geos::geom::Envelope::contains | ( | const Envelope & | other | ) | const

inline

Tests if the Envelope other lies wholly inside this Envelope (inclusive of the boundary).

Note that this is not the same definition as the SFS contains, which would exclude the envelope boundary.

Parameters

  other | the Envelope to check

Returns
  true if other is contained in this Envelope

See also
  covers(Envelope)

References covers(), and Envelope().

## contains() [3/3]

bool geos::geom::Envelope::contains | ( | double | x,
|  | double | y ) const

inline

Returns true if the given point lies in or on the envelope.

Parameters

  x | the x-coordinate of the point which this Envelope is being checked for containing
  y | the y-coordinate of the point which this Envelope is being checked for containing

Returns
  true if (x, y) lies in the interior or on the boundary of this Envelope.

References covers().

## covers() [1/3]

bool geos::geom::Envelope::covers | ( | const CoordinateXY * | p | ) | const

inline

Tests if the given point lies in or on the envelope.

Parameters

  p | the point which this Envelope is being checked for containing

Returns
  true if the point lies in the interior or on the boundary of this Envelope.

References covers().

## covers() [2/3]

bool geos::geom::Envelope::covers | ( | const Envelope & | other | ) | const

Tests if the Envelope other lies wholly inside this Envelope (inclusive of the boundary).

Parameters

  other | the Envelope to check

Returns
  true if this Envelope covers the other

References covers(), and Envelope().

## covers() [3/3]

bool geos::geom::Envelope::covers | ( | double | x,
|  | double | y ) const

inline

Tests if the given point lies in or on the envelope.

Parameters

  x | the x-coordinate of the point which this Envelope is being checked for containing
  y | the y-coordinate of the point which this Envelope is being checked for containing

Returns
  true if (x, y) lies in the interior or on the boundary of this Envelope.

Referenced by contains(), contains(), contains(), covers(), and covers().

## disjoint()

bool geos::geom::Envelope::disjoint | ( | const Envelope & | other | ) | const

inline

Tests if the region defined by other is disjoint from the region of this Envelope

Parameters

  other | the Envelope being checked for disjointedness

Returns
  true if the Envelopes are disjoint

References Envelope(), and intersects().

## distance()

double geos::geom::Envelope::distance | ( | const Envelope & | env | ) | const

inline

Computes the distance between this and another Envelope.

The distance between overlapping Envelopes is 0. Otherwise, the distance is the Euclidean distance between the closest points.

References distanceSquared(), and Envelope().

Referenced by operator<.

## distanceSquared()

double geos::geom::Envelope::distanceSquared | ( | const Envelope & | env | ) | const

inline

Computes the square of the distance between this and another Envelope.

The distance between overlapping Envelopes is 0. Otherwise, the distance is the Euclidean distance between the closest points.

References Envelope().

Referenced by distance(), and geos::operation::cluster::EnvelopeDistanceClusterFinder::shouldJoin().

## distanceSquaredToCoordinate()

double geos::geom::Envelope::distanceSquaredToCoordinate | ( | const CoordinateXY & | c,
|  | const CoordinateXY & | p0,
|  | const CoordinateXY & | p1 )

inline static

Computes the squared distance between one Coordinate and an Envelope defined by two other Coordinates. The order of the Coordinates used to define the envelope is not significant.

Parameters

  c | the coordinate to from which distance should be found
  p0 | first coordinate defining an envelope
  p1 | second coordinate defining an envelope.

Referenced by distanceToCoordinate().

## distanceToCoordinate()

double geos::geom::Envelope::distanceToCoordinate | ( | const CoordinateXY & | c,
|  | const CoordinateXY & | p0,
|  | const CoordinateXY & | p1 )

inline static

Computes the distance between one Coordinate and an Envelope defined by two other Coordinates. The order of the Coordinates used to define the envelope is not significant.

Parameters

  c | the coordinate to from which distance should be found
  p0 | first coordinate defining an envelope
  p1 | second coordinate defining an envelope.

References distanceSquaredToCoordinate().

## equals()

bool geos::geom::Envelope::equals | ( | const Envelope * | other | ) | const

Returns true if the Envelope other spatially equals this Envelope.

Parameters

  other | the Envelope which this Envelope is being checked for equality

Returns
  true if this and other Envelope objects are spatially equal

References Envelope().

Referenced by operator==.

## expandBy() [1/2]

void geos::geom::Envelope::expandBy | ( | double | deltaX,
|  | double | deltaY )

Expands this envelope by a given distance in all directions. Both positive and negative distances are supported.

Parameters

  deltaX | the distance to expand the envelope along the X axis
  deltaY | the distance to expand the envelope along the Y axis

Referenced by expandBy(), geos::operation::cluster::DBSCANClusterFinder::queryEnvelope(), geos::operation::cluster::EnvelopeDistanceClusterFinder::queryEnvelope(), and geos::operation::cluster::GeometryDistanceClusterFinder::queryEnvelope().

## expandBy() [2/2]

void geos::geom::Envelope::expandBy | ( | double | p_distance | ) |

inline

Expands this envelope by a given distance in all directions.

Both positive and negative distances are supported.

Parameters

  p_distance | the distance to expand the envelope

References expandBy().

## expandToInclude() [1/3]

void geos::geom::Envelope::expandToInclude | ( | const CoordinateXY & | p | ) |

inline

Enlarges the boundary of the Envelope so that it contains p. Does nothing if p is already on or within the boundaries.

Parameters

  p | the Coordinate to include

References expandToInclude().

Referenced by expandToInclude().

## expandToInclude() [2/3]

void geos::geom::Envelope::expandToInclude | ( | const Envelope * | other | ) |

inline

Enlarges the boundary of the Envelope so that it contains other.

Does nothing if other is wholly on or within the boundaries.

Parameters

  other | the Envelope to merge with

References Envelope(), and isNull().

## expandToInclude() [3/3]

void geos::geom::Envelope::expandToInclude | ( | double | x,
|  | double | y )

inline

Enlarges the boundary of the Envelope so that it contains (x,y).

Does nothing if (x,y) is already on or within the boundaries.

Parameters

  x | the value to lower the minimum x to or to raise the maximum x to
  y | the value to lower the minimum y to or to raise the maximum y to

References isNull().

## getArea()

double geos::geom::Envelope::getArea | ( |  | ) | const

inline

Gets the area of this envelope.

Returns
  the area of the envelope
  0.0 if the envelope is null

References getHeight(), and getWidth().

Referenced by isFinite().

## getDiameter()

double geos::geom::Envelope::getDiameter | ( |  | ) | const

inline

Gets the length of the diameter (diagonal) of the envelope.

Returns
  the diameter length

References getHeight(), getWidth(), and isNull().

## getHeight()

double geos::geom::Envelope::getHeight | ( |  | ) | const

inline

Returns the difference between the maximum and minimum y values.

Returns
  max y - min y, or 0 if this is a null Envelope

References isNull().

Referenced by getArea(), getDiameter(), and getPerimeter().

## getPerimeter()

double geos::geom::Envelope::getPerimeter | ( |  | ) | const

inline

Gets the perimeter of this envelope.

Returns
  the perimeter of the envelope
  0.0 if the envelope is null

References getHeight(), and getWidth().

## getWidth()

double geos::geom::Envelope::getWidth | ( |  | ) | const

inline

Returns the difference between the maximum and minimum x values.

Returns
  max x - min x, or 0 if this is a null Envelope

References isNull().

Referenced by getArea(), getDiameter(), and getPerimeter().

## init() [1/3]

void geos::geom::Envelope::init | ( | const CoordinateXY & | p | ) |

inline

Initialize an Envelope to a region defined by a single Coordinate.

Parameters

  p | the Coordinate

References init().

## init() [2/3]

void geos::geom::Envelope::init | ( | const CoordinateXY & | p1,
|  | const CoordinateXY & | p2 )

inline

Initialize an Envelope to a region defined by two Coordinates.

Parameters

  p1 | the first Coordinate
  p2 | the second Coordinate

References init().

## init() [3/3]

void geos::geom::Envelope::init | ( | double | x1,
|  | double | x2,
|  | double | y1,
|  | double | y2 )

inline

Initialize an Envelope for a region defined by maximum and minimum values.

Parameters

  x1 | the first x-value
  x2 | the second x-value
  y1 | the first y-value
  y2 | the second y-value

## intersection() [1/2]

Envelope geos::geom::Envelope::intersection | ( | const Envelope & | env | ) | const

Computes the intersection of two Envelopes.

Parameters

  env | the envelope to intersect with

Returns
  the envelope representing the intersection of the envelopes (this will be the null envelope if either argument is null, or they do not intersect)

References Envelope().

## intersection() [2/2]

bool geos::geom::Envelope::intersection | ( | const Envelope & | env,
|  | Envelope & | result ) const

Computes the intersection of two Envelopes.

Parameters

  env | the envelope to intersect with
  result | the envelope representing the intersection of the envelopes (this will be the null envelope if either argument is null, or they do not intersect)

Returns
  false if no intersection is found

References Envelope().

## intersects() [1/6]

bool geos::geom::Envelope::intersects | ( | const CoordinateXY & | a,
|  | const CoordinateXY & | b ) const

Check if the extent defined by two extremal points intersects the extent of this Envelope.

Parameters

  a | a point
  b | another point

Returns
  true if the extents intersect

## intersects() [2/6]

bool geos::geom::Envelope::intersects | ( | const CoordinateXY & | other | ) | const

inline

Check if the point p intersects (lies inside) the region of this Envelope.

Parameters

  other | the Coordinate to be tested

Returns
  true if the point intersects this Envelope

## intersects() [3/6]

bool geos::geom::Envelope::intersects | ( | const CoordinateXY & | p1,
|  | const CoordinateXY & | p2,
|  | const CoordinateXY & | q )

static

Test the point q to see whether it intersects the Envelope defined by p1-p2.

Parameters

  p1 | one extremal point of the envelope
  p2 | another extremal point of the envelope
  q | the point to test for intersection

Returns
  true if q intersects the envelope p1-p2

Referenced by disjoint(), and geos::operation::cluster::EnvelopeIntersectsClusterFinder::shouldJoin().

## intersects() [4/6]

bool geos::geom::Envelope::intersects | ( | const CoordinateXY & | p1,
|  | const CoordinateXY & | p2,
|  | const CoordinateXY & | q1,
|  | const CoordinateXY & | q2 )

inline static

Test the envelope defined by p1-p2 for intersection with the envelope defined by q1-q2.

Parameters

  p1 | one extremal point of the envelope P
  p2 | another extremal point of the envelope P
  q1 | one extremal point of the envelope Q
  q2 | another extremal point of the envelope Q

Returns
  true if Q intersects P

## intersects() [5/6]

bool geos::geom::Envelope::intersects | ( | const Envelope * | other | ) | const

inline

Check if the region defined by other Envelope intersects the region of this Envelope.

Parameters

  other | the Envelope which this Envelope is being checked for intersection

Returns
  true if the Envelopes intersects

References Envelope().

## intersects() [6/6]

bool geos::geom::Envelope::intersects | ( | double | x,
|  | double | y ) const

inline

Check if the point (x, y) intersects (lies inside) the region of this Envelope.

Parameters

  x | the x-ordinate of the point
  y | the y-ordinate of the point

Returns
  true if the point intersects this Envelope

## isfinite()

bool geos::geom::Envelope::isfinite | ( |  | ) | const

Returns true if all the extents of the Envelope are finite and defined (not NaN)

Returns
  true if envelope has only finite/valid extents, false otherwise

## isNull()

bool geos::geom::Envelope::isNull | ( | void |  | ) | const

inline

Returns true if this Envelope is a "null" envelope.

Returns
  true if this Envelope is uninitialized or is the envelope of the empty geometry.

Referenced by expandToInclude(), expandToInclude(), getDiameter(), getHeight(), getMaxX(), getMaxY(), getMinX(), getMinY(), and getWidth().

## toString()

std::string geos::geom::Envelope::toString | ( |  | ) | const

Returns a string of the form Env[minx:maxx,miny:maxy].

Returns
  a string of the form Env[minx:maxx,miny:maxy]

## translate()

void geos::geom::Envelope::translate | ( | double | transX,
|  | double | transY )

Translates this envelope by given amounts in the X and Y direction.

Parameters

  transX | the amount to translate along the X axis
  transY | the amount to translate along the Y axis

## Friends And Related Symbol Documentation

## operator<

bool operator< | ( | const Envelope & | a,
|  | const Envelope & | b )

friend

Strict weak ordering operator for Envelope This is the C++ equivalent of JTS's compareTo

References distance(), and Envelope().

The documentation for this class was generated from the following file:

- Envelope.h