View on GitHub

SFCGAL

About | Authors | Documentation | Development | Screencast | Installation
Download this project as a .zip file Download this project as a tar.gz file

Documentation

SFCGAL reference manual

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

Geometry collections

Geometries with shared coordinates

(*) SFCGAL doesn't respect the standard on this point. SFCGAL::Triangle doesn't inherit SFCGAL::Polygon for different reasons

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 these validity checkings may be slow, each algorithm comes with a variant where no actual check is made (taking a NoValidityCheck tag as additional parameter).

Validity checking could also be bypassed at a global level, by setting to 'OFF' the 'SFCGAL_CHECK_VALIDITY' CMake option.

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.