CrossSection Class Reference

Two-dimensional cross sections guaranteed to be without self-intersections, or overlaps between polygons (from construction onwards). This class makes use of the Clipper2 library for polygon clipping (boolean) and offsetting operations. More...

#include <cross_section.h>

Public Types
enum class	FillRule { EvenOdd , NonZero , Positive , Negative }
enum class	JoinType { Square , Round , Miter }

Basics
Copy / move / assignment
	CrossSection ()
	CrossSection (const CrossSection &other)
CrossSection &	operator= (const CrossSection &other)
	CrossSection (CrossSection &&) noexcept
CrossSection &	operator= (CrossSection &&) noexcept

Input & Output
	CrossSection (const SimplePolygon &contour, FillRule fillrule=FillRule::Positive)
	CrossSection (const Polygons &contours, FillRule fillrule=FillRule::Positive)
	CrossSection (const Rect &rect)
Polygons	ToPolygons () const

Constructors
Topological ops and primitives
std::vector< CrossSection >	Decompose () const
static CrossSection	Compose (std::vector< CrossSection > &)
static CrossSection	Square (const vec2 dims, bool center=false)
static CrossSection	Circle (double radius, int circularSegments=0)

Information
Details of the cross-section
bool	IsEmpty () const
int	NumVert () const
int	NumContour () const
Rect	Bounds () const
double	Area () const

Transformation
CrossSection	Translate (const vec2 v) const
CrossSection	Rotate (double degrees) const
CrossSection	Scale (const vec2 s) const
CrossSection	Mirror (const vec2 ax) const
CrossSection	Transform (const mat2x3 &m) const
CrossSection	Warp (std::function< void(vec2 &)> warpFunc) const
CrossSection	WarpBatch (std::function< void(VecView< vec2 >)> warpFunc) const
CrossSection	Simplify (double epsilon=1e-6) const
CrossSection	Offset (double delta, JoinType jt, double miter_limit=2.0, int circularSegments=0) const

Boolean
Combine two manifolds
CrossSection	Boolean (const CrossSection &second, OpType op) const
CrossSection	operator+ (const CrossSection &) const
CrossSection &	operator+= (const CrossSection &)
CrossSection	operator- (const CrossSection &) const
CrossSection &	operator-= (const CrossSection &)
CrossSection	operator^ (const CrossSection &) const
CrossSection &	operator^= (const CrossSection &)
static CrossSection	BatchBoolean (const std::vector< CrossSection > &crossSections, OpType op)

Convex Hull
CrossSection	Hull () const
static CrossSection	Hull (const std::vector< CrossSection > &crossSections)
static CrossSection	Hull (const SimplePolygon pts)
static CrossSection	Hull (const Polygons polys)

Detailed Description

Two-dimensional cross sections guaranteed to be without self-intersections, or overlaps between polygons (from construction onwards). This class makes use of the Clipper2 library for polygon clipping (boolean) and offsetting operations.

Member Enumeration Documentation

FillRule

enum class FillRule

strong

Filling rules defining which polygon sub-regions are considered to be inside a given polygon, and which sub-regions will not (based on winding numbers). See the Clipper2 docs for a detailed explaination with illusrations.

Enumerator
EvenOdd	Only odd numbered sub-regions are filled.
NonZero	Only non-zero sub-regions are filled.
Positive	Only sub-regions with winding counts > 0 are filled.
Negative	Only sub-regions with winding counts < 0 are filled.

JoinType

enum class JoinType

strong

Specifies the treatment of path/contour joins (corners) when offseting CrossSections. See the Clipper2 doc for illustrations.

Enumerator
Square	Squaring is applied uniformly at all joins where the internal join angle is less that 90 degrees. The squared edge will be at exactly the offset distance from the join vertex.
Round	Rounding is applied to all joins that have convex external angles, and it maintains the exact offset distance from the join vertex.
Miter	There's a necessary limit to mitered joins (to avoid narrow angled joins producing excessively long and narrow spikes). So where mitered joins would exceed a given maximum miter distance (relative to the offset distance), these are 'squared' instead.

Constructor & Destructor Documentation

CrossSection() [1/5]

CrossSection

(

)

The default constructor is an empty cross-section (containing no contours).

CrossSection() [2/5]

CrossSection

(

const CrossSection &

other

)

The copy constructor avoids copying the underlying paths vector (sharing with its parent via shared_ptr), however subsequent transformations, and their application will not be shared. It is generally recommended to avoid this, opting instead to simply create CrossSections with the available const methods.

CrossSection() [3/5]

CrossSection	(	const SimplePolygon &	contour,
		FillRule	fillrule = FillRule::Positive )

Create a 2d cross-section from a single contour. A boolean union operation (with Positive filling rule by default) is performed to ensure the resulting CrossSection is free of self-intersections.

Parameters

contour	A closed path outlining the desired cross-section.
fillrule	The filling rule used to interpret polygon sub-regions created by self-intersections in contour.

CrossSection() [4/5]

CrossSection	(	const Polygons &	contours,
		FillRule	fillrule = FillRule::Positive )

Create a 2d cross-section from a set of contours (complex polygons). A boolean union operation (with Positive filling rule by default) is performed to combine overlapping polygons and ensure the resulting CrossSection is free of intersections.

Parameters

contours	A set of closed paths describing zero or more complex polygons.
fillrule	The filling rule used to interpret polygon sub-regions in contours.

CrossSection() [5/5]

CrossSection

(

const Rect &

rect

)

Create a 2d cross-section from an axis-aligned rectangle (bounding box).

Parameters

rect	An axis-aligned rectangular bounding box.

Member Function Documentation

ToPolygons()

Polygons ToPolygons

(

)

const

Return the contours of this CrossSection as a Polygons.

Decompose()

std::vector< CrossSection > Decompose

(

)

const

This operation returns a vector of CrossSections that are topologically disconnected, each containing one outline contour with zero or more holes.

Compose()

CrossSection Compose ( std::vector< CrossSection > & crossSections )

static

Construct a CrossSection from a vector of other CrossSections (batch boolean union).

Square()

CrossSection Square ( const vec2 size, bool center = false )

static

Constructs a square with the given XY dimensions. By default it is positioned in the first quadrant, touching the origin. If any dimensions in size are negative, or if all are zero, an empty Manifold will be returned.

Parameters

size	The X, and Y dimensions of the square.
center	Set to true to shift the center to the origin.

Circle()

CrossSection Circle ( double radius, int circularSegments = 0 )

static

Constructs a circle of a given radius.

Parameters

radius	Radius of the circle. Must be positive.
circularSegments	Number of segments along its diameter. Default is calculated by the static Quality defaults according to the radius.

IsEmpty()

bool IsEmpty

(

)

const

Does the CrossSection contain any contours?

NumVert()

int NumVert

(

)

const

Return the number of vertices in the CrossSection.

NumContour()

int NumContour

(

)

const

Return the number of contours (both outer and inner paths) in the CrossSection.

Bounds()

Rect Bounds

(

)

const

Returns the axis-aligned bounding rectangle of all the CrossSections' vertices.

Area()

double Area

(

)

const

Return the total area covered by complex polygons making up the CrossSection.

Translate()

CrossSection Translate

(

const vec2

v

)

const

Move this CrossSection in space. This operation can be chained. Transforms are combined and applied lazily.

Parameters

v	The vector to add to every vertex.

Rotate()

CrossSection Rotate

(

double

degrees

)

const

Applies a (Z-axis) rotation to the CrossSection, in degrees. This operation can be chained. Transforms are combined and applied lazily.

Parameters

degrees

degrees about the Z-axis to rotate.

Scale()

CrossSection Scale

(

const vec2

scale

)

const

Scale this CrossSection in space. This operation can be chained. Transforms are combined and applied lazily.

Parameters

scale

The vector to multiply every vertex by per component.

Mirror()

CrossSection Mirror

(

const vec2

ax

)

const

Mirror this CrossSection over the arbitrary axis described by the unit form of the given vector. If the length of the vector is zero, an empty CrossSection is returned. This operation can be chained. Transforms are combined and applied lazily.

Parameters

ax	the axis to be mirrored over

Transform()

CrossSection Transform

(

const mat2x3 &

m

)

const

Transform this CrossSection in space. The first two columns form a 2x2 matrix transform and the last is a translation vector. This operation can be chained. Transforms are combined and applied lazily.

Parameters

m	The affine transform matrix to apply to all the vertices.

Warp()

CrossSection Warp

(

std::function< void(vec2 &)>

warpFunc

)

const

Move the vertices of this CrossSection (creating a new one) according to any arbitrary input function, followed by a union operation (with a Positive fill rule) that ensures any introduced intersections are not included in the result.

Parameters

warpFunc

A function that modifies a given vertex position.

WarpBatch()

CrossSection WarpBatch

(

std::function< void(VecView< vec2 >)>

warpFunc

)

const

Same as CrossSection::Warp but calls warpFunc with a VecView which is roughly equivalent to std::span pointing to all vec2 elements to be modified in-place

Parameters

warpFunc

A function that modifies multiple vertex positions.

Simplify()

CrossSection Simplify

(

double

epsilon = 1e-6

)

const

Remove vertices from the contours in this CrossSection that are less than the specified distance epsilon from an imaginary line that passes through its two adjacent vertices. Near duplicate vertices and collinear points will be removed at lower epsilons, with elimination of line segments becoming increasingly aggressive with larger epsilons.

It is recommended to apply this function following Offset, in order to clean up any spurious tiny line segments introduced that do not improve quality in any meaningful way. This is particularly important if further offseting operations are to be performed, which would compound the issue.

Offset()

CrossSection Offset	(	double	delta,
		JoinType	jointype,
		double	miter_limit = 2.0,
		int	circularSegments = 0 ) const

Inflate the contours in CrossSection by the specified delta, handling corners according to the given JoinType.

Parameters

delta	Positive deltas will cause the expansion of outlining contours to expand, and retraction of inner (hole) contours. Negative deltas will have the opposite effect.
jointype	The join type specifying the treatment of contour joins (corners).
miter_limit	The maximum distance in multiples of delta that vertices can be offset from their original positions with before squaring is applied, when the join type is Miter (default is 2, which is the minimum allowed). See the Clipper2 MiterLimit page for a visual example.
circularSegments	Number of segments per 360 degrees of JoinType::Round corners (roughly, the number of vertices that will be added to each contour). Default is calculated by the static Quality defaults according to the radius.

Boolean()

CrossSection Boolean	(	const CrossSection &	second,
		OpType	op ) const

Perform the given boolean operation between this and another CrossSection.

BatchBoolean()

CrossSection BatchBoolean ( const std::vector< CrossSection > & crossSections, OpType op )

static

Perform the given boolean operation on a list of CrossSections. In case of Subtract, all CrossSections in the tail are differenced from the head.

operator+()

CrossSection operator+

(

const CrossSection &

Q

)

const

Compute the boolean union between two cross-sections.

operator+=()

CrossSection & operator+=

(

const CrossSection &

Q

)

Compute the boolean union between two cross-sections, assigning the result to the first.

operator-()

CrossSection operator-

(

const CrossSection &

Q

)

const

Compute the boolean difference of a (clip) cross-section from another (subject).

operator-=()

CrossSection & operator-=

(

const CrossSection &

Q

)

Compute the boolean difference of a (clip) cross-section from a another (subject), assigning the result to the subject.

operator^()

CrossSection operator^

(

const CrossSection &

Q

)

const

Compute the boolean intersection between two cross-sections.

operator^=()

CrossSection & operator^=

(

const CrossSection &

Q

)

Compute the boolean intersection between two cross-sections, assigning the result to the first.

Hull() [1/4]

CrossSection Hull

(

)

const

Compute the convex hull of this cross-section.

Hull() [2/4]

CrossSection Hull ( const std::vector< CrossSection > & crossSections )

static

Compute the convex hull enveloping a set of cross-sections.

Parameters

crossSections

A vector of cross-sections over which to compute a convex hull.

Hull() [3/4]

CrossSection Hull ( const SimplePolygon pts )

static

Compute the convex hull of a set of points. If the given points are fewer than 3, an empty CrossSection will be returned.

Parameters

pts	A vector of 2-dimensional points over which to compute a convex hull.

Hull() [4/4]

CrossSection Hull ( const Polygons polys )

static

Compute the convex hull of a set of points/polygons. If the given points are fewer than 3, an empty CrossSection will be returned.

Parameters

polys

A vector of vectors of 2-dimensional points over which to compute a convex hull.