TerraLib and TerraView Wiki Page

This is an old revision of the document!


Geometry Module

The TerraLib Geometry module is compliant with spatial standards from ISO (International Organization for Standardization) and OGC (Open Geospatial Consortium). The latest OGC Simple Feature Specification, version 1.2, is closely related to ISO SQL/MM Spatial and readers of this section should be familiar with OGC Simple Feature Specification - Part 1: Common Architecture at least.

It is important to notice that this module refers to a geometry model to be used in main memory and it doesn't assume any kind of persistence or data storage management. This section explains the basic concepts, design behind this module ad how to use it.

All the types offered by Geometry module are in the namespace te::gm. Check the DOxygen documentation of this module, where these and other classes are documented in details.

General Concepts

This module relies on some basic definitions from the OGC and ISO specifications:

  • Object dimension:
    • From Wikipedia: “in mathematics, the dimension of an object is an intrinsic property, independent of the space in which the object may happen to be embedded”.
    • A 0-dimensional geometry is one with a geometric dimension of 0 (zero). Points are 0-dimensional objects.
    • A 1-dimensional geometry is one with a geometric dimension of 1 (one). Curves (lines) are 1-dimensional objects.
    • A 2-dimensional geometry is one with a geometric dimension of 2 (two). Surfaces (polygons) are 2-dimensional objects.
  • We can have geometries in ℜ2, ℜ3 or ℜ4 coordinate spaces.
    • The z coordinate value not necessarely represents altitude.
    • The m coordinate value represents arbitrary measurement.
  • The term ring is applied to a closed curve (the first and last points are coincident).

Geometry Class Hierarchy

The following class diagram shows the geometric classes provided in TerraLib1):

Geometry Classes

This model implements the classes defined in OGC SFS and ISO SQL/MM Spatial. Following, each class from the above diagram is discussed in detail.

Geometry

Geometry is the base class for all geometry types. It is an abstract class and though not instantiable.

As one can see, every geometry has an associated Spatial Reference System identifier or srid. This identifier can be used when converting between Spatial Reference Systems 2).

Another important information associated to a geometry is its minimum bounding rectangle (mar) or envelope (according to OGC definition). Actually, the mbr is not automatically computed for a geometry. Instead the mbr is computed just when an mbr accessor method is first called. If a client of a geometry class changes its coordinates the mbr will not be automatically adjusted. The method computeMBR() can be used to control when the MBR should be computed.

For an in depth explanation, see Doxygen documentation of this class.

Point

Pictorial Representation of a Point

A Point has at least a x and y coordinate values. It is possible to represent points with a z coordinate value (class PointZ) or points with an associated measure m (class PointM) or with z and m values (class PointZM).

std::unique_ptr<te::gm::Point> p = std::make_unique<te::gm::Point>(-54.0, -12.0, 4326);

Due to optimization issues, we have subclassified the class Point in: PointM, PointZ and PointZM. This doesn't violate any standard principle.

Another class introduced by TerraLib is PointKd, that can be used to represent more than 4-dimensions.

For an in depth explanation, see Doxygen documentation of this class.

Curve

The OGC SFS specification defines only one subclass of Curve which uses linear interpolation between Points: LineString, Line, LinearRing. The ISO SQL/MM specifies CircularString and CompoundCurve.

For an in depth explanation, see Doxygen documentation of this class.

LineString

Pictorial Representation of a LineString

The class LineString can be used to represent curves with linear interpolation between points. A LineString can have M or Z coordinates.

In a LineString each consecutive pair of points defines a line segment.

std::unique_ptr<te::gm::LineString> l = std::make_unique<te::gm:: LineString>(2, te::gm::LineStringType);
 
l->setPoint(0, -54.0, -12.0);
l->setPoint(1, -55.0, -13.0);

Internally, we store an array of coordinates and separate arrays for points with z and m.

All OGC interface is supported based on points through the method getPointN. But the extended methods, for coordinates, will be faster than the same versions of OGC methods because they work with less complex structures (coordinates) than points.

For an in depth explanation, see Doxygen documentation of this class.

Line

A Line is a LineString restricted to 2 points.

For an in depth explanation, see Doxygen documentation of this class.

LinearRing

Pictorial Representation of a LinearRing

A LinearRing is a LineString that is both closed and simple.

std::unique_ptr<te::gm::LinearRing> s = std::make_unique<te::gm::LinearRing>(5, te::gm::LineStringType);
 
double xc = -54.0;
double yc = -12.0;
duble halfSize = size * 0.5;
 
s->setPoint(0, xc - halfSize, yc - halfSize); // lower left 
s->setPoint(1, xc - halfSize, yc + halfSize); // upper left
s->setPoint(2, xc + halfSize, yc + halfSize); // upper right
s->setPoint(3, xc + halfSize, yc - halfSize); // lower right
s->setPoint(4, xc - halfSize, yc - halfSize); // closing

The boundary of a linear ring is empty.

This class is the basic building block of class Polygon.

For an in depth explanation, see Doxygen documentation of this class.

CircularString

CircularString is a curve with circular interpolation between points and it must have an odd number of points greater than 1. When representing more than one arc the last point of the previous arc becomes the first point of the next arc.

For an in depth explanation, see Doxygen documentation of this class.

CompoundCurve

A CompoundCurve is a curve that may have circular and linear segments.

For an in depth explanation, see Doxygen documentation of this class.

Surface

Surface is an abstract class that represents a 2-dimensional geometric object.

For an in depth explanation, see Doxygen documentation of this class.

CurvePolygon

CurvePolygon is a planar surface defined by 1 exterior boundary and 0 or more interior boundaries. The boundary of each ring can be any closed and simple curve.

For an in depth explanation, see Doxygen documentation of this class.

Polygon

Pictorial Representation of a Polygon with an outer boundary and one hole

Polygon is a subclass of CurvePolygon whose rings are defined by linear rings.

std::unique_ptr<te::gm::Polygon> p = std::make_unique<te::gm::Polygon>(0, te::gm::PolygonType);
 
p->push_back(createSquare(5, 5, 10)); // external square
p->push_back(createSquare(5, 5, 5));  // internal square (the hole!)

For an in depth explanation, see Doxygen documentation of this class.

Triangle

Triangle is a polygon with 3 distinct, non-collinear vertices and no interior boundary.

For an in depth explanation, see Doxygen documentation of this class.

PolyhedralSurface

PolyhedralSurface is a contiguous collection of polygons, which share common boundary segments.

For an in depth explanation, see Doxygen documentation of this class.

TIN

TIN (triangulated irregular network) is a PolyhedralSurface consisting only of Triangle patches.

For an in depth explanation, see Doxygen documentation of this class.

GeometryCollection

Pictorial Representation of a GeometryCollection

A GeometryCollection is a collection of other geometric objects.

It can contains any combination of geometric elements. Thus its is a heterogeneous collection of geometries.

In the above picture we have one GeometryCollection that contains one MultiPolygon, one Point and one LineString.

te::gm::GeometryCollection* gColl = new te::gm::GeometryCollection(0, te::gm::GeometryCollectionType); 	
 
gColl->add(createPoint(0.0, 0.0));
gColl->add(createLineString(0.0, 0.0, 10.0, 10.0));
gColl->add(createLineString(0.0, 10.0, 10.0, 0.0));
gColl->add(createPolygon());
gColl->add(createPolygonWithHole());

For an in depth explanation, see Doxygen documentation of this class.

MultiPoint

Pictorial Representation of a MultiPoint

MultiPoint is a GeometryCollection whose elements are restricted to points. In other words, it is a homogeneous collection of points.

For an in depth explanation, see Doxygen documentation of this class.

MultiCurve

MultiCurve is a class that represents a 1-dimensional GeometryCollection whose elements are curves.

For an in depth explanation, see Doxygen documentation of this class.

MultiLineString

Pictorial Representation of a MultiLineString

MultiLineString is a MultiCurve whose elements are LineStrings. In other words, it is a homogeneous collection of lines.

For an in depth explanation, see Doxygen documentation of this class.

MultiSurface

MultiSurface is a class that represents a 2-dimensional GeometryCollection whose elements are surfaces.

For an in depth explanation, see Doxygen documentation of this class.

MultiPolygon

Pictorial Representation of a MultiPolygon

MultiPolygon is a MultiSurface whose elements are Polygons. In other words, it is a homogeneous collection of polygons.

For an in depth explanation, see Doxygen documentation of this class.

Auxiliary Classes

Coord2D

A Coord2D is an utility struct for representing 2D coordinates.

Envelope

An Envelope defines a 2D rectangular region that is useful for representing objects bounding box (or minimum bouding rectangles).

Spatial Relationships

std::unique_ptr<te::gm::Geometry> g1(0);
std::unique_ptr<te::gm::Geometry> g2(0);
 
std::cout << g1->contains(g2);
 
std::cout << g1->coveredBy(g2);
 
std::cout << g1->covers(g2);
 
std::cout << return g1->crosses(g2);
 
std::cout << return g1->disjoint(g2);
 
std::cout << return g1->equals(g2);
 
std::cout << g1->intersects(g2);
 
std::cout << g1->overlaps(g2);
 
std::cout << g1->touches(g2);
 
std::cout << g1->within(g2);

Set Operations

Buffer

Metric Operators

1) This diagram follows OGC Simple Feature Specification
2) See the SRS module for more detail on this