Documentation
SFCGAL is a wrapper around CGAL library that intents to implement 2D and 3D operations on OGC standards models (Simple Feature Access, CityGML,...)
Introduction
SFCGAL relies on a single CGAL Kernel : The Exact Predicate Exact Construction Kernel (Epeck). SFCGAL::Kernel is a typedef on Epeck on this Kernel.
SFCGAL::Coordinate class provides a type erasure on CGAL points in order to fit the dynamic is3D() world. SFCGAL::Coordinate hides either a dummy empty entity, either a CGAL::Point_2, or a CGAL::Point_3 in the Epeck kernel.
Furthermore, conversions to double that would break constructive robustness are avoided.
Geometric model
The Geometric Model is an extension of OGC Simple Feature Access providing solids (SFCGAL::Solid) defined in the ISO 19107 and implemented in CityGML.
Primitives
- SFCGAL::Point is a Point defined by SFCGAL::Coordinate
- SFCGAL::LineString is a defined by an ordered list of SFCGAL::Point
- SFCGAL::Polygon is a polygon with optional holes, defined by an exterior ring and interior rings
- SFCGAL::Triangle is a Triangle defined by 3 points (*)
- SFCGAL::Solid is a solid with optional holes (**), defined by an exterior shell and interior shells
Geometry collections
- SFCGAL::GeometryCollection is a list of geometries that might mix types
- SFCGAL::MultiPoint is GeometryCollection restricted to SFCGAL::Point
- SFCGAL::MultiLineString is GeometryCollection restricted to SFCGAL::LineString
- SFCGAL::MultiPolygon is GeometryCollection restricted to SFCGAL::Polygon
Geometries with shared coordinates
- SFCGAL::TriangulatedSurface is a triangle set with shared components
- SFCGAL::PolyhedralSurface is a polygon set with shared components
(*) SFCGAL doesn't respect the standard on this point. SFCGAL::Triangle doesn't inherit SFCGAL::Polygon for different reasons
- Library is not query-only, geometries can be edited. We should expose triangle.addInteriorRing and throws exceptions on it.
- Inherits Polygon would brought useless structure to handle exterior and interior rings
- CGAL model relies on 3 points
On the other hand, it leads to convert between Triangle and Polygon and to duplicate some codes (area for example) so that it could to change that and conform.
(**) A solid may be represented with holes, but no algorithm supports them for now.
Note on orientations: geometries (surfaces in 2D and volumes in 3D) are oriented. The orientation is used with geometries that have 'holes'. for instance, interior rings of a 2D polygon have an orientation that is reversed to the exterior ring's orientation. The same would apply on solid' shells. However, there is no enforcement for a particular orientation on exterior rings / shells. This behaviour on solids is subject to changes since OGC standards on Solids are not yet stabilized. Exceptions to this rule are stated in the reference manual (example ).
Geometry validation policy
Every processing algorithm takes valid geometries as input parameters (no self intersection, etc.). Validity of geometries is tested with the algorithm::isValid() function and corresponds to validity preconditions asked for by OGC standards.
Since validation can be slow, a validity flag may be force-set to bypass these checks.
API
Two sets of functionalities are exposed and will be maintained as a stable API :
Some other elements of the documentation are tagged as 'details' which means they are for internal use only and are subject to changes within future releases.