GEOS: geos::Geometry Class Reference

- Main Page
- Namespaces
- Classes
- Files
- Related Pages

- Class List
- Class Hierarchy
- Class Members

# geos::Geometry Class Reference

Basic implementation of Geometry, constructed and destructed by GeometryFactory. More...

`#include <geos.h>`

Inheritance diagram for geos::Geometry:

List of all members.

## Public Member Functions
| Geometry (const GeometryFactory *factory)
| Construct a geometry with the given GeometryFactory. Will keep a reference to the factory, so don't delete it until al Geometry objects referring to it are deleted.
virtual | ~Geometry ()
virtual Geometry * | clone () const =0
| Make a deep-copy of this Geometry.
const GeometryFactory * | getFactory () const
| Gets the factory which contains the context in which this geometry was created.
void | setUserData (void *newUserData)
| A simple scheme for applications to add their own custom data to a Geometry. An example use might be to add an object representing a Coordinate Reference System.
void * | getUserData ()
| Gets the user data object for this geometry, if any.
virtual const PrecisionModel * | getPrecisionModel () const
| Get the PrecisionModel used to create this Geometry.
virtual const Coordinate * | getCoordinate () const =0
| Returns a vertex of this Geometry.
virtual CoordinateSequence * | getCoordinates () const =0
| Returns this Geometry vertices. Caller takes ownership of the returned object.
virtual int | getNumPoints () const =0
| Returns the count of this Geometrys vertices.
virtual bool | isSimple () const =0
| Returns false if the Geometry not simple.
virtual string | getGeometryType () const =0
| Return a string representation of this Geometry type.
virtual GeometryTypeId | getGeometryTypeId () const =0
| Return an integer representation of this Geometry type.
virtual bool | isValid () const
| Tests the validity of this `Geometry`.
virtual bool | isEmpty () const =0
| Returns whether or not the set of points in this Geometry is empty.
virtual int | getDimension () const =0
| Returns the dimension of this Geometry (0=point, 1=line, 2=surface).
virtual Geometry * | getBoundary () const =0
| Returns the boundary, or the empty geometry if this Geometry is empty.
virtual int | getBoundaryDimension () const =0
| Returns the dimension of this Geometrys inherent boundary.
virtual Geometry * | getEnvelope () const
| Returns this Geometrys bounding box.
virtual const Envelope * | getEnvelopeInternal () const
| Returns the minimum and maximum x and y values in this Geometry, or a null Envelope if this Geometry is empty.
virtual bool | disjoint (const Geometry *other) const
| Returns true if the DE-9IM intersection matrix for the two Geometrys is FF*FF****.
virtual bool | touches (const Geometry *other) const
| Returns true if the DE-9IM intersection matrix for the two Geometrys is FT*******, F**T***** or F***T****.
virtual bool | intersects (const Geometry *g) const
| Returns true if disjoint returns false.
virtual bool | crosses (const Geometry *g) const
| Returns true if the DE-9IM intersection matrix for the two Geometrys is T*T****** (for a point and a curve, a point and an area or a line and an area) 0******** (for two curves).
virtual bool | within (const Geometry *g) const
| Returns true if the DE-9IM intersection matrix for the two Geometrys is T*F**F***.
virtual bool | contains (const Geometry *g) const
| Returns true if other.within(this) returns true.
virtual bool | overlaps (const Geometry *g) const
| Returns true if the DE-9IM intersection matrix for the two Geometrys is T*T***T** (for two points or two surfaces) 1*T***T** (for two curves).
virtual bool | relate (const Geometry *g, string intersectionPattern) const
| Returns true if the elements in the DE-9IM intersection matrix for the two Geometrys match the elements in intersectionPattern.
virtual IntersectionMatrix * | relate (const Geometry *g) const
| Returns the DE-9IM intersection matrix for the two Geometrys.
virtual bool | equals (const Geometry *g) const
| Returns true if the DE-9IM intersection matrix for the two Geometrys is T*F**FFF*.
virtual string | toString () const
| Returns the Well-known Text representation of this Geometry.
virtual Geometry * | buffer (double distance) const
| Returns a buffer region around this Geometry having the given width.
virtual Geometry * | buffer (double distance, int quadrantSegments) const
| Returns a buffer region around this Geometry having the given width and with a specified number of segments used to approximate curves.
virtual Geometry * | convexHull () const
| Returns the smallest convex Polygon that contains all the points in the Geometry.
virtual Geometry * | intersection (const Geometry *other) const
| Returns a Geometry representing the points shared by this Geometry and other.
virtual Geometry * | Union (const Geometry *other) const
| Returns a Geometry representing all the points in this Geometry and other.
virtual Geometry * | difference (const Geometry *other) const
| Returns a Geometry representing the points making up this Geometry that do not make up other.
virtual Geometry * | symDifference (const Geometry *other) const
| Returns a set combining the points in this Geometry not in other, and the points in other not in this Geometry.
virtual bool | equalsExact (const Geometry *other, double tolerance) const =0
| Returns true if the two Geometrys are exactly equal, up to a specified tolerance.
virtual void | normalize ()=0
| Converts this Geometry to normal form (or canonical form).
virtual double | distance (const Geometry *g) const
| Returns the minimum distance between this Geometry and the Geometry g.
virtual double | getArea () const
| Returns the area of this Geometry.
virtual double | getLength () const
| Returns the length of this Geometry.
virtual bool | isWithinDistance (const Geometry *geom, double cDistance)
| Tests whether the distance from this Geometry to another is less than or equal to a specified value.
virtual Point * | getCentroid () const
| Computes the centroid of this Geometry.
virtual Point * | getInteriorPoint ()
| Computes an interior point of this Geometry.
virtual void | geometryChanged ()
void | geometryChangedAction ()
## Protected Member Functions
virtual bool | isEquivalentClass (const Geometry *other) const
| Returns whether the two Geometrys are equal, from the point of view of the equalsExact method.
Geometry * | toInternalGeometry (const Geometry *g) const
## Static Protected Member Functions
static bool | hasNonEmptyElements (const vector< Geometry * > *geometries)
| Returns true if the array contains any non-empty Geometrys.
static bool | hasNullElements (const CoordinateSequence *list)
| Returns true if the CoordinateSequence contains any null elements.
static bool | hasNullElements (const vector< Geometry * > *lrs)
| Returns true if the vector contains any null elements.

## Detailed Description

Basic implementation of Geometry, constructed and destructed by GeometryFactory.

`clone` returns a deep copy of the object. Use GeometryFactory to construct.

### Binary Predicates

Because it is not clear at this time what semantics for spatial analysis methods involving `GeometryCollection`s would be useful, `GeometryCollection`s are not supported as arguments to binary predicates (other than `convexHull`) or the `relate` method.

### Set-Theoretic Methods

The spatial analysis methods will return the most specific class possible to represent the result. If the result is homogeneous, a `Point`, `LineString`, or `Polygon` will be returned if the result contains a single element; otherwise, a `MultiPoint`, `MultiLineString`, or `MultiPolygon` will be returned. If the result is heterogeneous a `GeometryCollection` will be returned.

Because it is not clear at this time what semantics for set-theoretic methods involving `GeometryCollection`s would be useful, `GeometryCollections` are not supported as arguments to the set-theoretic methods.

#### Representation of Computed Geometries

The SFS states that the result of a set-theoretic method is the "point-set" result of the usual set-theoretic definition of the operation (SFS 3.2.21.1). However, there are sometimes many ways of representing a point set as a `Geometry`.

The SFS does not specify an unambiguous representation of a given point set returned from a spatial analysis method. One goal of JTS is to make this specification precise and unambiguous. JTS will use a canonical form for `Geometry`s returned from spatial analysis methods. The canonical form is a `Geometry` which is simple and noded:

- Simple means that the Geometry returned will be simple according to the JTS definition of `isSimple`.
- Noded applies only to overlays involving `LineString`s. It means that all intersection points on `LineString`s will be present as endpoints of `LineString`s in the result.

This definition implies that non-simple geometries which are arguments to spatial analysis methods must be subjected to a line-dissolve process to ensure that the results are simple.

#### Constructed Points And The Precision Model

The results computed by the set-theoretic methods may contain constructed points which are not present in the input `Geometry` s. These new points arise from intersections between line segments in the edges of the input `Geometry`s. In the general case it is not possible to represent constructed points exactly. This is due to the fact that the coordinates of an intersection point may contain twice as many bits of precision as the coordinates of the input line segments. In order to represent these constructed points explicitly, JTS must truncate them to fit the `PrecisionModel`.

Unfortunately, truncating coordinates moves them slightly. Line segments which would not be coincident in the exact result may become coincident in the truncated representation. This in turn leads to "topology collapses" -- situations where a computed element has a lower dimension than it would in the exact result.

When JTS detects topology collapses during the computation of spatial analysis methods, it will throw an exception. If possible the exception will report the location of the collapse.

equals(Object) and hashCode are not overridden, so that when two topologically equal Geometries are added to HashMaps and HashSets, they remain distinct. This behaviour is desired in many cases.

## Constructor & Destructor Documentation

geos::Geometry::~Geometry | ( |  | ) | `[virtual]`

Destroy Geometry and all components

## Member Function Documentation

const GeometryFactory * geos::Geometry::getFactory | ( |  | ) | const

Gets the factory which contains the context in which this geometry was created.

Returns:
  the factory for this geometry

Gets the factory which contains the context in which this geometry was created.

Returns:
  the factory for this geometry

void geos::Geometry::setUserData | ( | void * | newUserData | ) |

A simple scheme for applications to add their own custom data to a Geometry. An example use might be to add an object representing a Coordinate Reference System.

Note that user data objects are not present in geometries created by construction methods.

Parameters:

  | newUserData | an object, the semantics for which are defined by the application using this Geometry

A simple scheme for applications to add their own custom data to a Geometry. An example use might be to add an object representing a Coordinate Reference System.

Note that user data objects are not present in geometries created by construction methods.

Parameters:

  | userData | an object, the semantics for which are defined by the application using this Geometry

void * geos::Geometry::getUserData | ( |  | ) |

Gets the user data object for this geometry, if any.

Returns:
  the user data object, or `null` if none set

Gets the user data object for this geometry, if any.

Returns:
  the user data object, or `null` if none set

bool geos::Geometry::isValid | ( |  | ) | const`[virtual]`

Tests the validity of this `Geometry`.

Subclasses provide their own definition of "valid".

Returns:
  `true` if this `Geometry` is valid

See also:
  IsValidOp

bool geos::Geometry::relate | ( | const Geometry * | g,
|  | string | intersectionPattern |
| ) |  |  | const`[virtual]`

Returns true if the elements in the DE-9IM intersection matrix for the two Geometrys match the elements in intersectionPattern.

IntersectionPattern elements may be: 0 1 2 T ( = 0, 1 or 2) F ( = -1) * ( = -1, 0, 1 or 2).

For more information on the DE-9IM, see the OpenGIS Simple Features Specification.

Geometry * geos::Geometry::buffer | ( | double | distance,
|  | int | quadrantSegments |
| ) |  |  | const`[virtual]`

Returns a buffer region around this Geometry having the given width and with a specified number of segments used to approximate curves.

Returns a buffer region around this `Geometry` having the given width and with a specified number of segments used to approximate curves. The buffer of a Geometry is the Minkowski sum of the Geometry with a disc of radius `distance`. Curves in the buffer polygon are approximated with line segments. This method allows specifying the accuracy of that approximation.

Parameters:

  | distance | the width of the buffer, interpreted according to the `PrecisionModel` of the `Geometry`
  | quadrantSegments | the number of segments to use to approximate a quadrant of a circle

Returns:
  all points whose distance from this `Geometry` are less than or equal to `distance`

double geos::Geometry::distance | ( | const Geometry * | other | ) | const`[virtual]`

Returns the minimum distance between this Geometry and the Geometry g.

Returns the minimum distance between this Geometry and the other Geometry

Parameters:

  | other | the Geometry from which to compute the distance

double geos::Geometry::getArea | ( |  | ) | const`[virtual]`

Returns the area of this Geometry.

Returns the area of this `Geometry`. Areal Geometries have a non-zero area. They override this function to compute the area. Others return 0.0

Returns:
  the area of the Geometry

Reimplemented in geos::GeometryCollection, and geos::Polygon.

double geos::Geometry::getLength | ( |  | ) | const`[virtual]`

Returns the length of this Geometry.

Returns the length of this `Geometry`. Linear geometries return their length. Areal geometries return their perimeter. They override this function to compute the area. Others return 0.0

Returns:
  the length of the Geometry

Reimplemented in geos::GeometryCollection, geos::LineString, and geos::Polygon.

bool geos::Geometry::isWithinDistance | ( | const Geometry * | geom,
|  | double | cDistance |
| ) |  |  | `[virtual]`

Tests whether the distance from this Geometry to another is less than or equal to a specified value.

Tests whether the distance from this `Geometry` to another is less than or equal to a specified value.

Parameters:

  | geom | the Geometry to check the distance to
  | cDistance | the distance value to compare

Returns:
  `true` if the geometries are less than `distance` apart.

Point * geos::Geometry::getCentroid | ( |  | ) | const`[virtual]`

Computes the centroid of this Geometry.

Computes the centroid of this `Geometry`. The centroid is equal to the centroid of the set of component Geometrys of highest dimension (since the lower-dimension geometries contribute zero "weight" to the centroid)

Returns:
  a Point which is the centroid of this Geometry

Point * geos::Geometry::getInteriorPoint | ( |  | ) | `[virtual]`

Computes an interior point of this Geometry.

Computes an interior point of this `Geometry`. An interior point is guaranteed to lie in the interior of the Geometry, if it possible to calculate such a point exactly. Otherwise, the point may lie on the boundary of the geometry.

Returns:
  a Point which is in the interior of this Geometry

void geos::Geometry::geometryChanged | ( |  | ) | `[virtual]`

Notifies this Geometry that its Coordinates have been changed by an external party (using a CoordinateFilter, for example). The Geometry will flush and/or update any information it has cached (such as its Envelope ).

void geos::Geometry::geometryChangedAction | ( |  | ) |

Notifies this Geometry that its Coordinates have been changed by an external party. When geometryChanged is called, this method will be called for this Geometry and its component Geometries.

See also:
  apply(GeometryComponentFilter *)

Geometry * geos::Geometry::toInternalGeometry | ( | const Geometry * | g | ) | const`[protected]`

The GEOS algorithms assume that Geometry::getCoordinate() and getCoordinates are fast, which may not be the case if the CoordinateSequence is not a DefaultCoordinateSequence (e.g. if it were implemented using separate arrays for the x- and y-values), in which case frequent construction of Coordinates takes up much space and time. To solve this performance problem, toInternalGeometry converts the Geometry to a DefaultCoordinateSequence implementation before sending it to the JTS algorithms.

The JTS algorithms assume that Geometry::getCoordinate and getCoordinates are fast, which may not be the case if the CoordinateSequence is not a DefaultCoordinateSequence (e.g. if it were implemented using separate arrays for the x- and y-values), in which case frequent construction of Coordinates takes up much space and time. To solve this performance problem, toInternalGeometry converts the Geometry to a DefaultCoordinateSequence implementation before sending it to the JTS algorithms.

Note: if the Geometry is already implemented with DefaultCoordinateSequence it is returned untouched, so you should check returned value before releasing memory associated with the one used as argument.

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

- geom.h
- Geometry.cpp