3D Isosurfacing Reference

Julian Stahl and Daniel Zint

This package implements isosurfacing algorithms to generate a mesh from a scalar field. The algorithms provide different guarantees for the output and should be chosen depending on the use-case. The representations of input data is flexible and includes explicit and implicit formats.

Introduced in: CGAL 5.7
BibTeX: cgal:sz-mc-22b
License: GPL
Windows Demo: Polyhedron demo
Common Demo Dlls: dlls

This package provides algorithms to extract isosurfaces from different inputs. The input is represented as a domain and can be an implicit function, a cartesion grid, or an octree. The output is an indexed face set that stores an isosurface in the form of a surface mesh. Available algorithms include Marching Cubes, topologically correct Marching Cubes, and Dual Contouring.

Classified Reference Pages

Concepts

• IsosurfacingDomain
• IsosurfacingDomainWithGradient

Classes

• Cartesian_grid_3
• Zero_gradient
• Finite_difference_gradient
• Explicit_cartesian_grid_gradient

Free Functions

• CGAL::Isosurfacing::marching_cubes()
• CGAL::Isosurfacing::dual_contouring()
• CGAL::Isosurfacing::create_explicit_cartesian_grid_domain()
• CGAL::Isosurfacing::create_implicit_cartesian_grid_domain()

Modules
	Concepts

Classes
class	CGAL::Isosurfacing::Zero_gradient< GeomTraits >
	Template class for a gradient that is always zero. More...
class	CGAL::Isosurfacing::Finite_difference_gradient< GeomTraits, PointFunction >
	Template class for a gradient that is calculated using finite differences. More...
class	CGAL::Isosurfacing::Explicit_cartesian_grid_gradient< GeomTraits >
	Template class for a gradient that is stored in a Cartesian_grid_3. More...

Functions
template<typename Concurrency_tag = Sequential_tag, class Domain_ , class PointRange , class PolygonRange , class Positioning = internal::Positioning::QEM_SVD<true>>
void	CGAL::Isosurfacing::dual_contouring (const Domain_ &domain, const typename Domain_::FT iso_value, PointRange &points, PolygonRange &polygons, const Positioning &positioning=Positioning())
	Creates an indexed face set that represents an isosurface using the Dual Contouring algorithm. More...
template<class GeomTraits , typename Gradient_ = Zero_gradient<GeomTraits>>
Explicit_cartesian_grid_domain< GeomTraits, Gradient_ >	CGAL::Isosurfacing::create_explicit_cartesian_grid_domain (const std::shared_ptr< Cartesian_grid_3< GeomTraits >> grid, const Gradient_ &gradient=Gradient_())
	Creates a domain from a Cartesian_grid_3 that can be used as input for isosurfacing algorithms. More...
template<class GeomTraits , typename PointFunction , typename Gradient_ = Zero_gradient<GeomTraits>>
Implicit_cartesian_grid_domain< GeomTraits, PointFunction, Gradient_ >	CGAL::Isosurfacing::create_implicit_cartesian_grid_domain (const Bbox_3 &bbox, const typename GeomTraits::Vector_3 &spacing, const PointFunction &point_function, const Gradient_ &gradient=Gradient_())
	Creates a domain from a Cartesian_grid_3 that can be used as input for isosurfacing algorithms. More...
template<typename Concurrency_tag = Sequential_tag, class Domain_ , class PointRange , class TriangleRange >
void	CGAL::Isosurfacing::marching_cubes (const Domain_ &domain, const typename Domain_::FT iso_value, PointRange &points, TriangleRange &polygons, bool topologically_correct=true)
	Creates a polygon soup that represents an isosurface using the marching cubes algorithm. More...

Function Documentation

create_explicit_cartesian_grid_domain()

template<class GeomTraits , typename Gradient_ = Zero_gradient<GeomTraits>>

Explicit_cartesian_grid_domain<GeomTraits, Gradient_> CGAL::Isosurfacing::create_explicit_cartesian_grid_domain	(	const std::shared_ptr< Cartesian_grid_3< GeomTraits >>	grid,
		const Gradient_ &	gradient = Gradient_()
	)

#include <CGAL/Explicit_cartesian_grid_domain.h>

Creates a domain from a Cartesian_grid_3 that can be used as input for isosurfacing algorithms.

Template Parameters

GeomTraits

the traits type

Parameters

grid	the cartesian grid containing input data
gradient	a function that describes the gradient of the data

create_implicit_cartesian_grid_domain()

template<class GeomTraits , typename PointFunction , typename Gradient_ = Zero_gradient<GeomTraits>>

Implicit_cartesian_grid_domain<GeomTraits, PointFunction, Gradient_> CGAL::Isosurfacing::create_implicit_cartesian_grid_domain	(	const Bbox_3 &	bbox,
		const typename GeomTraits::Vector_3 &	spacing,
		const PointFunction &	point_function,
		const Gradient_ &	gradient = Gradient_()
	)

#include <CGAL/Implicit_cartesian_grid_domain.h>

Creates a domain from a Cartesian_grid_3 that can be used as input for isosurfacing algorithms.

Template Parameters

GeomTraits	the traits type
PointFunction	the type of the implicit function

Parameters

bbox	a bounding box that specifies the size of the functions domain
spacing	the distance between discretized points on the function
point_function	the function with a point as argument
gradient	a function that describes the gradient of the data

dual_contouring()

template<typename Concurrency_tag = Sequential_tag, class Domain_ , class PointRange , class PolygonRange , class Positioning = internal::Positioning::QEM_SVD<true>>

void CGAL::Isosurfacing::dual_contouring	(	const Domain_ &	domain,
		const typename Domain_::FT	iso_value,
		PointRange &	points,
		PolygonRange &	polygons,
		const Positioning &	positioning = Positioning()
	)

#include <CGAL/Dual_contouring_3.h>

Creates an indexed face set that represents an isosurface using the Dual Contouring algorithm.

Template Parameters

ConcurrencyTag	determines if the algorithm is executed sequentially or in parallel.
Domain_	must be a model of IsosurfacingDomain.
PointRange	is a model of the concept RandomAccessContainer and BackInsertionSequence whose value type can be constructed from the point type of the polygon mesh.
PolygonRange	a model of the concept RandomAccessContainer and BackInsertionSequence whose value type is itself a model of the concepts RandomAccessContainer and BackInsertionSequence whose value type is std::size_t.
Positioning	is a functor containing the operator() that takes domain, iso_value, cell, and position as input and returns a boolean that is true if the isosurface intersects the cell.

Parameters

domain	the domain providing input data and its topology
iso_value	value of the isosurface
points	points making the polygons of the indexed face set
polygons	each element in the vector describes a polygon using the indices of the points in points
positioning	the functor dealing with vertex positioning inside a voxel

Examples:

Isosurfacing_3/all_cartesian_cube.cpp, Isosurfacing_3/dual_contouring_cartesian_grid.cpp, Isosurfacing_3/dual_contouring_mesh_offset.cpp, and Isosurfacing_3/dual_contouring_octree.cpp.

marching_cubes()

template<typename Concurrency_tag = Sequential_tag, class Domain_ , class PointRange , class TriangleRange >

void CGAL::Isosurfacing::marching_cubes	(	const Domain_ &	domain,
		const typename Domain_::FT	iso_value,
		PointRange &	points,
		TriangleRange &	polygons,
		bool	topologically_correct = true
	)

#include <CGAL/Marching_cubes_3.h>

Creates a polygon soup that represents an isosurface using the marching cubes algorithm.

Template Parameters

ConcurrencyTag	determines if the algorithm is executed sequentially or in parallel.
Domain_	must be a model of IsosurfacingDomain.
PointRange	is a model of the concept RandomAccessContainer and BackInsertionSequence whose value type can be constructed from the point type of the polygon mesh.
PolygonRange	a model of the concept RandomAccessContainer and BackInsertionSequence whose value type is itself a model of the concepts RandomAccessContainer and BackInsertionSequence whose value type is std::size_t.

Parameters

domain	the domain providing input data and its topology
iso_value	value of the isosurface
points	points making the polygons of the soup
polygons	each element in the vector describes a polygon using the indices of the points in points
topologically_correct	decides whether the topologically correct variant of Marching Cubes should be used

Examples:

Isosurfacing_3/all_cartesian_cube.cpp, Isosurfacing_3/marching_cubes_cartesian_grid_sphere.cpp, Isosurfacing_3/marching_cubes_implicit_sphere.cpp, Isosurfacing_3/marching_cubes_inrimage.cpp, and Isosurfacing_3/marching_cubes_mesh_offset.cpp.