CGAL 6.2 - Boolean Operations on Meshes: Clipping and Splitting

CGAL 6.2 - Boolean Operations on Meshes

Loading...
Searching...
No Matches
Functions
Clipping and Splitting
Reference Manual

##

Functions to clip and split meshes using planes, boxes, or other meshes.

## Functions
template<class TriangleMesh , class NamedParameters1 = parameters::Default_named_parameters, class NamedParameters2 = parameters::Default_named_parameters>
bool | CGAL::Polygon_mesh_processing::clip (TriangleMesh &tm, TriangleMesh &clipper, const NamedParameters1 &np_tm=parameters::default_values(), const NamedParameters2 &np_c=parameters::default_values())
| clips `tm` by keeping the part that is inside the volume bounded by `clipper`.
template<class PolygonMesh , class NamedParameters = parameters::Default_named_parameters>
bool | CGAL::Polygon_mesh_processing::clip (PolygonMesh &pm, const Plane_3 &plane, const NamedParameters &np=parameters::default_values())
| clips `pm` by keeping the part that is on the negative side of `plane` (the side opposite to its normal vector).
template<class TriangleMesh , class NamedParameters = parameters::Default_named_parameters>
bool | CGAL::Polygon_mesh_processing::clip (TriangleMesh &tm, const Iso_cuboid_3 &iso_cuboid, const NamedParameters &np=parameters::default_values())
| clips `tm` by keeping the part that is inside `iso_cuboid`.
template<class TriangleMesh , class NamedParameters1 = parameters::Default_named_parameters, class NamedParameters2 = parameters::Default_named_parameters>
void | CGAL::Polygon_mesh_processing::split (TriangleMesh &tm, TriangleMesh &splitter, const NamedParameters1 &np_tm=parameters::default_values(), const NamedParameters2 &np_s=parameters::default_values())
| corefines `tm` and `splitter` and duplicates edges in `tm` that are on the intersection with `splitter`.
template<class PolygonMesh , class NamedParameters = parameters::Default_named_parameters>
void | CGAL::Polygon_mesh_processing::split (PolygonMesh &pm, const Plane_3 &plane, const NamedParameters &np=parameters::default_values())
| splits a polygon mesh with a plane.
template<class TriangleMesh , class NamedParameters = parameters::Default_named_parameters>
void | CGAL::Polygon_mesh_processing::split (TriangleMesh &tm, const Iso_cuboid_3 &iso_cuboid, const NamedParameters &np=parameters::default_values())
| adds intersection edges of `iso_cuboid` and `tm` in `tm` and duplicates those edges.

## Function Documentation

## ◆ clip() [1/3]

template<class PolygonMesh , class NamedParameters = parameters::Default_named_parameters>

bool CGAL::Polygon_mesh_processing::clip | ( | PolygonMesh & | pm,
|  | const Plane_3 & | plane,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |

`#include <CGAL/Polygon_mesh_processing/clip.h>`

clips `pm` by keeping the part that is on the negative side of `plane` (the side opposite to its normal vector).

If `pm` is closed, the clipped part can be kept closed by setting the named parameter `clip_volume`to `true`. See Subsection Clipping and Splitting Meshes for more details.

Template Parameters

  PolygonMesh | a model of `MutableFaceGraph`, `HalfedgeListGraph` and `FaceListGraph`. An internal property map for `CGAL::vertex_point_t` must be available.
  NamedParameters | a sequence of Named Parameters

Parameters

  pm | input surface mesh
  plane | plane whose negative side defines the halfspace to intersect `pm` with. `Plane_3` is the plane type for the same CGAL kernel as the point of the vertex point map of `pm`.
  np | an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a tag indicating if the task should be performed using one or several threads. Type: Either `CGAL::Sequential_tag`, or `CGAL::Parallel_tag`, or `CGAL::Parallel_if_available_tag` Default: `CGAL::Sequential_tag` |
  a property map associating points to the vertices of `pm` Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<PolygonMesh>::vertex_descriptor` as key type and `Point_3` as value type Default: `boost::get(CGAL::vertex_point, pm)` |
  a visitor used to track the creation of new faces, edges, and faces. Note that as there are no mesh associated with `plane`, `boost::graph_traits<PolygonMesh>::null_halfedge()` and `boost::graph_traits<PolygonMesh>::null_face()` will be used when calling functions of the visitor expecting a halfedge or a face from `plane`. Similarly, `pm` will be used as the mesh of `plane`. Type: a class model of `PMPCorefinementVisitor` Default: `Corefinement::Default_visitor<PolygonMesh>` |
  If `true`, the set of triangles close to the intersection of `pm` and `plane` will be checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` will be thrown if at least one self-intersection is found. This option is only taken into account if `pm` is a triangle mesh. Type: Boolean Default: `false` |
  If `true`, self-intersections in `pm` are accepted. Type: Boolean Default: `false` Extra: If this option is set to `true`, `pm` is no longer required to be without self-intersection. Setting this option to `true` will automatically set `throw_on_self_intersection` to `false` and `clip_volume` to `false` (overwriting any value provided) |
  If `true`, and if `pm` is closed, the clipping will be done on the volume bounded by `pm` rather than on its surface (i.e., `pm` will remain closed). Type: Boolean Default: `false` |
  If `false`, the parts of `pm` coplanar with `plane` will not be part of the output. Always `true` if `clip_volume` is `true`. Type: Boolean Default: `true` |
  If set to `true`, a faster implementation specialized for convex meshes is used. The input mesh must be convex to guarantee a correct execution and results. Type: Boolean Default: `false` |
  If the input mesh is triangulated and this parameter is set to `false`, the mesh will be kept triangulated. Always `true` if `pm` is not a triangle mesh. Type: Boolean Default: `false` |
  an instance of a geometric traits class Type: a class model of `Kernel` Default: a CGAL kernel deduced from the point type, using `CGAL::Kernel_traits` Extra: The geometric traits class must be compatible with the vertex point type. |

Returns
  `true`

See also
  `split()`

## ◆ clip() [2/3]

template<class TriangleMesh , class NamedParameters = parameters::Default_named_parameters>

bool CGAL::Polygon_mesh_processing::clip | ( | TriangleMesh & | tm,
|  | const Iso_cuboid_3 & | iso_cuboid,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |

`#include <CGAL/Polygon_mesh_processing/clip.h>`

clips `tm` by keeping the part that is inside `iso_cuboid`.

If `tm` is closed, the clipped part can be kept closed by setting the named parameter `clip_volume` to `true`. See Subsection Clipping and Splitting Meshes for more details.

Note
  `Iso_cuboid_3` must be from the same kernel as the point of the internal vertex point map of `TriangleMesh`.
  `Iso_cuboid_3` must be from the same kernel as the point of the vertex point map of `tm`.

Precondition
  `!CGAL::Polygon_mesh_processing::does_self_intersect(tm)`

Template Parameters

  TriangleMesh | a model of `MutableFaceGraph`, `HalfedgeListGraph` and `FaceListGraph`. An internal property map for `CGAL::vertex_point_t` must be available.
  NamedParameters | a sequence of Named Parameters

Parameters

  tm | input triangulated surface mesh
  iso_cuboid | iso-cuboid used to clip `tm`.
  np | an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a property map associating points to the vertices of `tm` Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<PolygonMesh>::vertex_descriptor` as key type and `Point_3` as value type Default: `boost::get(CGAL::vertex_point, tm)` |
  a visitor used to track the creation of new faces Type: a class model of `PMPCorefinementVisitor` Default: `Corefinement::Default_visitor<TriangleMesh>` |
  If `true`, and `tm` is closed, the clipping will be done on the volume bounded by `tm` rather than on its surface (i.e., `tm` will be kept closed). Type: Boolean Default: `false` |
  if `false` the parts of `tm` coplanar with `iso_cuboid` will not be part of the output Type: Boolean Default: `true` |
  If `true`, the set of triangles close to the intersection of `tm` and `iso_cuboid` will be checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` will be thrown if at least one self-intersection is found. Type: Boolean Default: `false` |
  If `true`, self-intersections in `tm` are accepted. Type: Boolean Default: `false` Extra: If this option is set to `true`, `tm` is no longer required to be without self-intersection. Setting this option to `true` will automatically set `throw_on_self_intersection` to `false` and `clip_volume` to `false`. |
  an instance of a geometric traits class Type: a class model of `Kernel` Default: a CGAL kernel deduced from the point type, using `CGAL::Kernel_traits` Extra: The geometric traits class must be compatible with the vertex point type. |

Returns
  `true` if the output surface mesh is manifold. If `false` is returned `tm` is only refined by the intersection with `iso_cuboid`.

See also
  `split()`

## ◆ clip() [3/3]

template<class TriangleMesh , class NamedParameters1 = parameters::Default_named_parameters, class NamedParameters2 = parameters::Default_named_parameters>

bool CGAL::Polygon_mesh_processing::clip | ( | TriangleMesh & | tm,
|  | TriangleMesh & | clipper,
|  | const NamedParameters1 & | np_tm = `parameters::default_values()`,
|  | const NamedParameters2 & | np_c = `parameters::default_values()`
| ) |  |

`#include <CGAL/Polygon_mesh_processing/clip.h>`

clips `tm` by keeping the part that is inside the volume bounded by `clipper`.

If `tm` is closed, the clipped part can be kept closed by setting the named parameter `clip_volume` to `true`. See Subsection Clipping and Splitting Meshes for more details.

Attention
  In the current implementation, `clipper` will be modified (refined with the intersection with `tm`) unless the named parameter `do_not_modify` is set to `true`.

Precondition
  `!CGAL::Polygon_mesh_processing::does_self_intersect(tm)`
  `!CGAL::Polygon_mesh_processing::does_self_intersect(clipper)`
  `CGAL::Polygon_mesh_processing::does_bound_a_volume(clipper)`

Template Parameters

  TriangleMesh | a model of `MutableFaceGraph`, `HalfedgeListGraph` and `FaceListGraph`.
  NamedParameters1 | a sequence of Named Parameters
  NamedParameters2 | a sequence of Named Parameters

Parameters

  tm | input triangulated surface mesh
  clipper | triangulated surface mesh used to clip `tm`
  np_tm | an optional sequence of Named Parameters among the ones listed below
  np_c | an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a property map associating points to the vertices of `tm` (resp. `clipper`) Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<TriangleMesh>::vertex_descriptor` as key type and `Point_3` as value type Default: `boost::get(CGAL::vertex_point, tm (resp. clipper))` Extra: If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` must be available in `TriangleMesh`. |
  a property map associating to each face of `tm` (`clipper`) a unique index between `0` and `num_faces(tm (resp. clipper)) - 1` Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<TriangleMesh>::face_descriptor` as key type and `std::size_t` as value type Default: an automatically indexed internal map Extra: if the property map is writable, the indices of the faces of `tm` and `clipper` will be set after refining `tm` with the intersection with `clipper` |
  a visitor used to track the creation of new faces Type: a class model of `PMPCorefinementVisitor` Default: `Corefinement::Default_visitor<TriangleMesh>` |
  If `true`, the set of triangles close to the intersection of `tm` and `clipper` will be checked for self-intersections and `Corefinement::Self_intersection_exception` will be thrown if at least one self-intersection is found. Type: Boolean Default: `false` |
  If `true`, and `tm` is closed, the clipping will be done on the volume bounded by `tm` rather than on its surface (i.e., `tm` will be kept closed). Type: Boolean Default: `false` |
  if `false`, the parts of `tm` coplanar with `clipper` will not be part of the output. Type: Boolean Default: `true` Extra: This option has an effect only if a surface and not a volume is clipped, (i.e., if `clip_volume` is `false` or if `tm` is open). |
  (`np_c` only) if `true`, `clipper` will not be modified. Type: Boolean Default: `false` Extra: If this option is set to `true`, `tm` is no longer required to be without self-intersection. Setting this option to `true` will automatically set `throw_on_self_intersection` to `false` and `clip_volume` to `false`. |

Returns
  `true` if the output surface mesh is manifold. If `false` is returned `tm` and `clipper` are only corefined.

See also
  `split()`

## ◆ split() [1/3]

template<class PolygonMesh , class NamedParameters = parameters::Default_named_parameters>

void CGAL::Polygon_mesh_processing::split | ( | PolygonMesh & | pm,
|  | const Plane_3 & | plane,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |

`#include <CGAL/Polygon_mesh_processing/clip.h>`

splits a polygon mesh with a plane.

The polygon mesh is refined with the intersection edges, and those edges are duplicated as to create a boundary, and thus separate connected components on either side of the plane.

Template Parameters

  PolygonMesh | a model of `MutableFaceGraph`, `HalfedgeListGraph`, and `FaceListGraph`. An internal property map for `CGAL::vertex_point_t` must be available.
  NamedParameters | a sequence of Named Parameters

Parameters

  pm | input surface mesh
  plane | the plane that will be used to split `pm`. `Plane_3` is the plane type for the same CGAL kernel as the point of the vertex point map of `pm`.
  np | an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a property map associating points to the vertices of `pm` Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<TriangleMesh>::vertex_descriptor` as key type and `Point_3` as value type Default: `boost::get(CGAL::vertex_point, pm)` |
  a visitor used to track the creation of new faces, edges, and vertices. Note that as there are no mesh associated with `plane`, `boost::graph_traits<PolygonMesh>::null_halfedge()` and `boost::graph_traits<PolygonMesh>::null_face()` will be used when calling functions of the visitor expecting a halfedge or a face from `plane`. Similarly, `pm` will be used as the mesh of `plane`.} Type: a class model of `PMPCorefinementVisitor` Default: `Corefinement::Default_visitor<TriangleMesh>` |
  If `true`, the set of triangles close to the intersection of `pm` and `plane` will be checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` will be thrown if at least one self-intersection is found. This option is only taken into account if `pm` is a triangle mesh. Type: Boolean Default: `false` |
  If the input mesh is triangulated and this parameter is set to `false`, the mesh will be kept triangulated. Always `true` if `pm` is not a triangle mesh. Type: Boolean Default: `false` |
  an instance of a geometric traits class Type: a class model of `Kernel` Default: a CGAL kernel deduced from the point type, using `CGAL::Kernel_traits` Extra: The geometric traits class must be compatible with the vertex point type. |

See also
  `clip()`

## ◆ split() [2/3]

template<class TriangleMesh , class NamedParameters = parameters::Default_named_parameters>

void CGAL::Polygon_mesh_processing::split | ( | TriangleMesh & | tm,
|  | const Iso_cuboid_3 & | iso_cuboid,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |

`#include <CGAL/Polygon_mesh_processing/clip.h>`

adds intersection edges of `iso_cuboid` and `tm` in `tm` and duplicates those edges.

Note
  `Iso_cuboid_3` must be from the same kernel as the point of the internal vertex point map of `TriangleMesh`.
  `Iso_cuboid_3` must be from the same kernel as the point of the vertex point map of `tm`.

Precondition
  `!CGAL::Polygon_mesh_processing::does_self_intersect(tm)`

Template Parameters

  TriangleMesh | a model of `MutableFaceGraph`, `HalfedgeListGraph`, and `FaceListGraph`. An internal property map for `CGAL::vertex_point_t` must be available.
  NamedParameters | a sequence of Named Parameters

Parameters

  tm | input triangulated surface mesh
  iso_cuboid | iso-cuboid used to split `tm`.
  np | an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a property map associating points to the vertices of `tm` Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<TriangleMesh>::vertex_descriptor` as key type and `Point_3` as value type Default: `boost::get(CGAL::vertex_point, tm)` |
  a visitor used to track the creation of new faces Type: a class model of `PMPCorefinementVisitor` Default: `Corefinement::Default_visitor<TriangleMesh>` |
  If `true`, and `tm` is closed, the clipping will be done on the volume bounded by `tm` rather than on its surface (i.e., `tm` will be kept closed). Type: Boolean Default: `false` |
  if `false`, the parts of `tm` coplanar with `iso_cuboid` will not be part of the output. Type: Boolean Default: `true` |
  If `true`, the set of triangles close to the intersection of `tm` and `iso_cuboid` will be checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` will be thrown if at least one self-intersection is found. Type: Boolean Default: `false` |
  If `true`, self-intersections in `tm` are accepted. Type: Boolean Default: `false` Extra: If this option is set to `true`, `tm` is no longer required to be without self-intersection. Setting this option to `true` will automatically set `throw_on_self_intersection` to `false` and `clip_volume` to `false`. |
  an instance of a geometric traits class Type: a class model of `Kernel` Default: a CGAL kernel deduced from the point type, using `CGAL::Kernel_traits` Extra: The geometric traits class must be compatible with the vertex point type. |

See also
  `clip()`

## ◆ split() [3/3]

template<class TriangleMesh , class NamedParameters1 = parameters::Default_named_parameters, class NamedParameters2 = parameters::Default_named_parameters>

void CGAL::Polygon_mesh_processing::split | ( | TriangleMesh & | tm,
|  | TriangleMesh & | splitter,
|  | const NamedParameters1 & | np_tm = `parameters::default_values()`,
|  | const NamedParameters2 & | np_s = `parameters::default_values()`
| ) |  |

`#include <CGAL/Polygon_mesh_processing/clip.h>`

corefines `tm` and `splitter` and duplicates edges in `tm` that are on the intersection with `splitter`.

Precondition
  `!CGAL::Polygon_mesh_processing::does_self_intersect(tm)`
  `!CGAL::Polygon_mesh_processing::does_self_intersect(splitter)`

Template Parameters

  TriangleMesh | a model of `MutableFaceGraph`, `HalfedgeListGraph`, and `FaceListGraph`.
  NamedParameters1 | a sequence of Named Parameters
  NamedParameters2 | a sequence of Named Parameters

Parameters

  tm | input triangulated surface mesh
  splitter | triangulated surface mesh used to split `tm`
  np_tm | an optional sequence of Named Parameters among the ones listed below
  np_s | an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a property map associating points to the vertices of `tm` (`splitter`) Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<TriangleMesh>::vertex_descriptor` as key type and `Point_3` as value type Default: `boost::get(CGAL::vertex_point, tm)` Default: If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` must be available in `TriangleMesh`. |
  (`np_tm` only) a visitor used to track a series of events such as the creation of new faces, edges... in both `tm` and `splitter`. Type: a class model of `PMPCorefinementVisitor` Default: `Corefinement::Default_visitor<TriangleMesh>` |
  If `true`, the set of triangles closed to the intersection of `tm` and `splitter` will be checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` will be thrown if at least one self-intersection is found. Type: Boolean Default: `false` |
  (`np_s` only) if `true`, `splitter` will not be modified. Type: Boolean Default: `false` Extra: If this option is set to `true`, `tm` is no longer required to be without self-intersection. Setting this option to `true` will automatically set `throw_on_self_intersection` to `false` and `clip_volume` to `false`. |

See also
  `clip()`