Package micycle.pgs

Class PGS_Processing

java.lang.Object

micycle.pgs.PGS_Processing

public final class PGS_Processing
extends Object

Methods that process shape geometry: partitioning, slicing, cleaning, etc.

Author:

Michael Carleton

Method Summary

Modifier and Type	Method	Description
static processing.core.PShape	apply(processing.core.PShape shape, Consumer<processing.core.PShape> applyFunction)	Applies a specified function to each child of the given PShape.
static processing.core.PShape	applyWithIndex(processing.core.PShape shape, BiConsumer<Integer,processing.core.PShape> applyFunction)	Applies a specified function to each child of the given PShape, providing the index of each child.
static processing.core.PShape	centroidSplit(processing.core.PShape shape)	Splits the input shape into multiple wedge-shaped regions by connecting the centroid to each vertex.
static processing.core.PShape	centroidSplit(processing.core.PShape shape, int n, double offset)	Splits the input shape into n wedge-shaped regions by connecting the centroid to points along the perimeter.
static processing.core.PShape	convexPartition(processing.core.PShape shape)	Partitions shape(s) into convex (simple) polygons.
static processing.core.PShape	densify(processing.core.PShape shape, double distanceTolerance)	Densifies a shape by inserting additional vertices along its line segments.
static processing.core.PShape	dissolve(processing.core.PShape shape)	Dissolves the linear components of a shape (or group of shapes) into a set of maximal-length lines in which each unique segment appears once.
static processing.core.PShape	eliminateSlivers(processing.core.PShape shape, double threshold)	Removes narrow areas ("slivers") from a shape while preserving the geometry of the remaining parts.
static processing.core.PShape	equalPartition(processing.core.PShape shape, int parts)	Randomly partitions a shape into N approximately equal-area polygonal cells.
static processing.core.PShape	equalPartition(processing.core.PShape shape, int parts, long seed)	Randomly (with a given seed) partitions a shape into N approximately equal-area polygonal cells.
static processing.core.PShape	extractHoles(processing.core.PShape shape)	Extracts all the holes from a shape, returning them as if they are polygons.
static processing.core.PShape	extractPerimeter(processing.core.PShape shape, double from, double to)	Extracts a portion/subline of the perimeter of a shape between two locations on the perimeter.
static processing.core.PShape	filterChildren(processing.core.PShape shape, Predicate<processing.core.PShape> filterFunction)	Filters out the children of a given PShape object based on a given Predicate function.
static processing.core.PShape	fix(processing.core.PShape shape)	Attempts to fix shapes with invalid geometry, while preserving its original form and location as much as possible.
static <T> List<T>	forEachShape(processing.core.PShape shape, Function<processing.core.PShape,T> function)	Applies a specified transformation function to each child of the given PShape and returns a list of results produced by the function.
static <T> List<T>	forEachShapeWithIndex(processing.core.PShape shape, BiFunction<Integer,processing.core.PShape,T> function)	Applies a specified transformation function to each child of the given PShape along with its index and returns a list of results produced by the function.
static List<processing.core.PVector>	generateRandomGridPoints(processing.core.PShape shape, int maxPoints, boolean constrainedToCircle, double gutterFraction)	Generates up to maxPoints number of random points that are contained within the shape region.
static List<processing.core.PVector>	generateRandomGridPoints(processing.core.PShape shape, int maxPoints, boolean constrainedToCircle, double gutterFraction, long randomSeed)	Generates up to maxPoints number of random points that are contained within the shape region.
static List<processing.core.PVector>	generateRandomPoints(processing.core.PShape shape, int points)	Generates N random points that lie within the shape region.
static List<processing.core.PVector>	generateRandomPoints(processing.core.PShape shape, int points, long seed)	Generates N random points that are contained within the shape region.
static List<processing.core.PVector>	lineSegmentsIntersection(List<processing.core.PVector> lineSegments)	Computes all points of intersection between segments in a set of line segments.
static processing.core.PShape	nest(processing.core.PShape shape, int n, double r)	Creates a nested shape having n levels of inner polygons; each inner polygon is obtained by joining the points at some fractional distance r along each side of the previous polygon.
static processing.core.PShape	normalise(processing.core.PShape shape)	Normalises a shape by standardising its vertex ordering and orientation: The outer shell (exterior contour) is oriented clockwise (CW). All holes (interior contours) are oriented counterclockwise (CCW). Each contour (shell or hole) is rotated so its sequence starts at the vertex with the minimum coordinate (lexicographically by x, then y).
static processing.core.PVector	pointOnExterior(processing.core.PShape shape, double perimeterPosition, double offsetDistance)	Extracts a point from the perimeter (exterior) of the given shape at a specific position along its perimeter.
static processing.core.PVector	pointOnExteriorByDistance(processing.core.PShape shape, double perimeterDistance, double offsetDistance)	Extracts a point from the perimeter (exterior) of the given shape at some distance along its perimeter.
static List<processing.core.PVector>	pointsOnExterior(processing.core.PShape shape, double interPointDistance, double offsetDistance)	Sample points along every linear component of a shape.
static List<processing.core.PVector>	pointsOnExterior(processing.core.PShape shape, int points, double offsetDistance)	Extracts multiple points evenly distributed along the boundary of individual rings within a shape, including both exterior and interior rings (i.e., holes).
static List<processing.core.PVector>	pointsOnExterior(processing.core.PShape shape, int points, double offsetDistance, double startOffset)	Extract a fixed number of evenly spaced samples from every linear component.
static processing.core.PShape	polygonizeLines(List<processing.core.PVector> lineSegmentVertices)	Finds the polygonal faces formed by a set of intersecting line segments.
static processing.core.PShape	removeHiddenLines(processing.core.PShape shape)	Removes overlap between polygons contained in a GROUP shape, preserving only visible line segments suitable for pen plotting and similar applications.
static processing.core.PShape	removeSmallHoles(processing.core.PShape shape, double areaThreshold)	Returns a copy of the shape where holes having an area less than the specified threshold are removed.
static processing.core.PShape	segmentsOnExterior(processing.core.PShape shape, double lineLength, double interLineDistance, double offset)	Extracts evenly spaced dashed line segments along every boundary of a shape.
static List<processing.core.PVector>	shapeIntersection(processing.core.PShape a, processing.core.PShape b)	Computes all points of intersection between the linework of two shapes.
static processing.core.PShape	slice(processing.core.PShape shape, processing.core.PVector p1, processing.core.PVector p2)	Slices a shape using a line given by its start and endpoints.
static processing.core.PShape	split(processing.core.PShape shape)	Splits a shape into four equal quadrants (based on the envelope of the shape).
static processing.core.PShape	split(processing.core.PShape shape, int splitDepth)	Splits a shape into 4^(1+recursions) rectangular partitions.
static double	tangentAngle(processing.core.PShape shape, double perimeterRatio)	Calculates the angle of the line tangent to the shape at a specific point on its perimeter.
static processing.core.PShape	transform(processing.core.PShape shape, UnaryOperator<processing.core.PShape> function)	Applies a specified transformation function to each child of the given PShape and returns a new PShape containing the transformed children.
static processing.core.PShape	transformWithIndex(processing.core.PShape shape, BiFunction<Integer,processing.core.PShape,processing.core.PShape> function)	Applies a specified transformation function to each child of the given PShape, providing the index of each child, and returns a new PShape containing the transformed children.
static processing.core.PShape	trapezoidPartition(processing.core.PShape shape)	Decomposes/partitions a shape into axis-aligned (stip-like) trazepoids.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

densify

public static processing.core.PShape densify(processing.core.PShape shape,
 double distanceTolerance)

Densifies a shape by inserting additional vertices along its line segments. This results in a more detailed representation of the shape, affecting its structure without altering its geometry.

Parameters:

shape - The shape to be densified. It should be a lineal or polygonal shape.

distanceTolerance - The densification tolerance used. All line segments in the densified geometry will have lengths no longer than the specified distance tolerance. The distance tolerance must be a positive value.

Returns:

A new PShape object representing the densified geometry.

pointOnExterior

public static processing.core.PVector pointOnExterior(processing.core.PShape shape,
 double perimeterPosition,
 double offsetDistance)

Extracts a point from the perimeter (exterior) of the given shape at a specific position along its perimeter.

Parameters:

shape - A lineal or polygonal shape. If the input is a GROUP shape, a single point will be extracted from its first child shape.

perimeterPosition - A normalised position along the perimeter of a shape [0...1]. 0 corresponds to the starting point of the shape's perimeter, and 1 corresponds to the ending point of the perimeter; any value between 0 and 1 represents a proportional distance along the shape's boundary.

offsetDistance - A perpendicular offset distance from the shape's perimeter. A value of 0 corresponds to exactly on the shape's exterior/ Positive values offset the point away from the shape (outwards); negative values offset the point inwards towards its interior.

See Also:

• pointsOnExterior(PShape, int, double)

pointOnExteriorByDistance

public static processing.core.PVector pointOnExteriorByDistance(processing.core.PShape shape,
 double perimeterDistance,
 double offsetDistance)

Extracts a point from the perimeter (exterior) of the given shape at some distance along its perimeter.

Parameters:

shape - A lineal or polygonal shape. If the input is a GROUP shape, a single point will be extracted from its first child shape.

perimeterDistance - Distance along shape perimeter to extract the point. 0 corresponds to the first vertex of the shape's perimeter.

offsetDistance - A perpendicular offset distance from the shape's perimeter. A value of 0 corresponds to exactly on the shape's exterior/ Positive values offset the point away from the shape (outwards); negative values offset the point inwards towards its interior.

Since:

1.4.0

pointsOnExterior

public static List<processing.core.PVector> pointsOnExterior(processing.core.PShape shape,
 int points,
 double offsetDistance)

Extracts multiple points evenly distributed along the boundary of individual rings within a shape, including both exterior and interior rings (i.e., holes).

This method enhances the performance of boundary sampling by directly extracting points from each linear ring of the shape's polygons. It is more efficient than multiple individual point extractions, and it supports sampling from holes (interior rings) as well.

Parameters:

shape - The shape from which to extract points. Should have polygonal members.

points - The number of points to extract per ring, evenly distributed around each ring's boundary.

offsetDistance - The offset distance measured perpendicular to each point on the ring's boundary. Positive values offset outwards, while negative values offset inwards.

Returns:

A list of PVector objects, each representing a point on the perimeter or interior rings of the shape.

Since:

1.3.0

See Also:

• pointOnExterior(PShape, double, double)
• pointsOnExterior(PShape, double, double)

pointsOnExterior

public static List<processing.core.PVector> pointsOnExterior(processing.core.PShape shape,
 int points,
 double offsetDistance,
 double startOffset)

Extract a fixed number of evenly spaced samples from every linear component.

Samples exactly points positions from each linear component (each LinearRing or LineString) found in shape. Sampling is done independently per component — i.e., points samples are produced for each ring or line. startOffset sets the fractional start position along each component (0..1). offsetDistance is applied perpendicular to the boundary when extracting each sample.

Orientation is normalized per component (reversed if necessary) so offsets are applied consistently. The method only collects points and does not modify the input geometry.

Parameters:

shape - the input PShape containing rings or LineStrings to sample

points - number of samples to take from each linear component

offsetDistance - perpendicular offset applied to each sampled point

startOffset - fractional start position along each component (0..1)

Returns:

a list of PVector points sampled from every linear component; empty if none produce samples

Since:

1.3.0

pointsOnExterior

public static List<processing.core.PVector> pointsOnExterior(processing.core.PShape shape,
 double interPointDistance,
 double offsetDistance)

Sample points along every linear component of a shape.

Samples points independently for each lineal component (polygon exterior rings, interior rings/holes, and standalone LineStrings) found in shape. Each component is sampled along its length with approximately interPointDistance spacing. offsetDistance is applied perpendicular to the component when extracting each point.

Orientation is normalised per component before sampling so offsets are applied consistently. Components with zero length (or that yield zero samples) are skipped. The method collects points only and does not modify the input geometry.

Parameters:

shape - the input PShape containing polygon rings or LineStrings to sample

interPointDistance - approximate spacing between consecutive samples on each linear component

offsetDistance - perpendicular offset applied to each sampled point

Returns:

a list of PVector points sampled from every linear component; empty if no samples are produced

Since:

1.3.0

See Also:

• #applyToLinealGeometries(PShape, java.util.function.UnaryOperator)

segmentsOnExterior

public static processing.core.PShape segmentsOnExterior(processing.core.PShape shape,
 double lineLength,
 double interLineDistance,
 double offset)

Extracts evenly spaced dashed line segments along every boundary of a shape.

For each linear component found in shape (each polygon perimeter or path) this method places repeated line segments along that component's length. Sampling is performed independently per component: exactly the same spacing/length rules are applied to each component, but counts and positions are computed from that component's own perimeter.

Parameters:

shape - input PShape containing polygons or paths (or a mix of both)

lineLength - desired length of each segment

interLineDistance - gap between consecutive segments along a component

offset - a fractional offset (a fraction of the component's perimeter) that sets where the first segment starts. Any real value is accepted and is normalised by modulo 1.0 (wrapped into [0,1)). Increasing offset values move the start point clockwise around the perimeter, while decreasing or negative values move it counter-clockwise. Varying offset over time will effectively "animate" the segments around the component.

Returns:

if the input contains only one linear element (i.e. a holeless polygon), a GROUP shape of segments; otherwise a GROUP PShape whose children are GROUPs of segment PShapes (one child group per linear component).

Since:

2.0

extractPerimeter

public static processing.core.PShape extractPerimeter(processing.core.PShape shape,
 double from,
 double to)

Extracts a portion/subline of the perimeter of a shape between two locations on the perimeter.

Parameters:

shape - the shape from which to extract a the perimeter

from - the starting location of the perimeter extract, given by a fraction (0...1) of the total perimeter length

to - the end location of the perimeter extract, given by a fraction (0...1) of the total perimeter length

Returns:

lineal shape

Since:

1.2.0

tangentAngle

public static double tangentAngle(processing.core.PShape shape,
 double perimeterRatio)

Calculates the angle of the line tangent to the shape at a specific point on its perimeter. The position of the point is determined by the normalized distance along the shape's perimeter.

Parameters:

shape - The shape for which to find the tangent angle.

perimeterRatio - A normalised position along the perimeter of a shape [0...1]. 0 corresponds to the starting point of the shape's perimeter, and 1 corresponds to the ending point of the perimeter; any value between 0 and 1 represents a proportional distance along the shape's boundary.

Returns:

the normalized angle (in radians) that the tangent line at the specified position makes with the positive x-axis (east), orientated clockwise.

Since:

1.3.0

shapeIntersection

public static List<processing.core.PVector> shapeIntersection(processing.core.PShape a,
 processing.core.PShape b)

Computes all points of intersection between the linework of two shapes.

NOTE: This method shouldn't be confused with PGS_ShapeBoolean.intersect(), which finds the shape made by the intersecting shape areas.

Parameters:

a - one shape

b - another shape

Returns:

list of all intersecting points (as PVectors)

lineSegmentsIntersection

public static List<processing.core.PVector> lineSegmentsIntersection(List<processing.core.PVector> lineSegments)

Computes all points of intersection between segments in a set of line segments. The input set is first processed to remove degenerate segments (does not mutate the input).

Parameters:

lineSegments - a list of PVectors where each pair (couplet) of PVectors represent the start and end point of one line segment

Returns:

A list of PVectors each representing the intersection point of a segment pair

generateRandomPoints

public static List<processing.core.PVector> generateRandomPoints(processing.core.PShape shape,
 int points)

Generates N random points that lie within the shape region.

This is a fast method but note that the underlying algorithm makes a minor trade-off for its speed: the resulting point set is slightly more uniformly distributed over the input shape compared to a purely random approach (this arises because the shape is first divided into triangles; each triangle is then sampled a fixed number of times according to its area relative to the whole).

Parameters:

shape - defines the region in which random points are generated

points - number of points to generate within the shape region

See Also:

• generateRandomPoints(PShape, int, long)
• generateRandomGridPoints(PShape, int, boolean, double)

generateRandomPoints

public static List<processing.core.PVector> generateRandomPoints(processing.core.PShape shape,
 int points,
 long seed)

Generates N random points that are contained within the shape region. Points are distributed completely randomly. This method accepts a seed for the RNG when identical sequences of random points are required.

This is a fast method but note that the underlying algorithm makes a minor trade-off for its speed: the resulting point set is slightly more uniformly distributed over the input shape compared to a purely random approach (this arises because the shape is first divided into triangles; each triangle is then sampled a fixed number of times according to its area relative to the whole).

Parameters:

shape - defines the region in which random points are generated

points - number of points to generate within the shape region

seed - number used to initialize the underlying pseudorandom number generator

Since:

1.1.0

See Also:

• generateRandomPoints(PShape, int)
• generateRandomGridPoints(PShape, int, boolean, double)

generateRandomGridPoints

public static List<processing.core.PVector> generateRandomGridPoints(processing.core.PShape shape,
 int maxPoints,
 boolean constrainedToCircle,
 double gutterFraction)

Generates up to maxPoints number of random points that are contained within the shape region. Points are distributed according to a grid of cells (one point randomly located in each cell), based on the envelope of the shape.

Parameters:

shape - defines the region in which random points are generated

maxPoints - maximum number of points, if this shape was its own envelope

constrainedToCircle - Sets whether generated points are constrained to lie within a circle contained within each grid cell. This provides greater separation between points in adjacent cells.

gutterFraction - Sets the fraction of the grid cell side which will be treated as a gutter, in which no points will be created. The provided value is clamped to the range [0.0, 1.0]. Higher values increase how "grid-like" the point distribution is.

Returns:

a list of random points, distributed according to a grid, contained within the given shape

See Also:

• generateRandomPoints(PShape, int)
• generateRandomGridPoints(PShape, int, boolean, double, long)

generateRandomGridPoints

public static List<processing.core.PVector> generateRandomGridPoints(processing.core.PShape shape,
 int maxPoints,
 boolean constrainedToCircle,
 double gutterFraction,
 long randomSeed)

Generates up to maxPoints number of random points that are contained within the shape region. Points are distributed according to a grid of cells (one point randomly located in each cell), based on the envelope of the shape.

This method accepts a seed for the RNG when identical sequences of random points are required.

Parameters:

shape - defines the region in which random points are generated

maxPoints - maximum number of points, if this shape was its own envelope

constrainedToCircle - Sets whether generated points are constrained to lie within a circle contained within each grid cell. This provides greater separation between points in adjacent cells.

gutterFraction - Sets the fraction of the grid cell side which will be treated as a gutter, in which no points will be created. The provided value is clamped to the range [0.0, 1.0]. Higher values increase how "grid-like" the point distribution is.

randomSeed -

Returns:

a list of random points, distributed according to a grid, contained within the given shape

See Also:

• generateRandomGridPoints(PShape, int, boolean, double)

nest

public static processing.core.PShape nest(processing.core.PShape shape,
 int n,
 double r)

Creates a nested shape having n levels of inner polygons; each inner polygon is obtained by joining the points at some fractional distance r along each side of the previous polygon.

This is also called a "derived polygon".

Parameters:

shape - a PShape representing the single input polygon for which the nested shape will be created. Although all polygon types are compatible, simpler/convex polygons make for a more effective result.

n - the number of nested levels to be created inside the input shape.

r - fractional distance between each nested level of polygons, where 0.5 produces maximal nesting.

Returns:

A PShape representing the nested shape, including the input shape and all the nested levels.

Since:

1.4.0

removeHiddenLines

public static processing.core.PShape removeHiddenLines(processing.core.PShape shape)

Removes overlap between polygons contained in a GROUP shape, preserving only visible line segments suitable for pen plotting and similar applications.

This method processes a GROUP shape consisting of lineal or polygonal child shapes, aiming to create linework that represents only the segments visible to a human, rather than a computer. The resulting linework is useful for pen plotters or other applications where only the visible paths are desired.

During the operation, any overlapping lines are also removed to ensure a clean and clear representation of the shapes. It's important to note that the order of shape layers in the input GROUP shape is significant. The method considers the last child shape of the input to be "on top" of all other shapes, as is the case visually.

Parameters:

shape - A GROUP shape containing lineal or polygonal child shapes.

Returns:

The resulting linework of the overlapping input as a LINES PShape, representing only visible line segments.

Since:

1.3.0

removeSmallHoles

public static processing.core.PShape removeSmallHoles(processing.core.PShape shape,
 double areaThreshold)

Returns a copy of the shape where holes having an area less than the specified threshold are removed.

Parameters:

shape - a single polygonal shape or GROUP polygonal shape

areaThreshold - removes any holes with an area smaller than this value

extractHoles

public static processing.core.PShape extractHoles(processing.core.PShape shape)

Extracts all the holes from a shape, returning them as if they are polygons.

Parameters:

shape - the PShape to extract holes from

Returns:

a new PShape that represents the holes extracted from the input shape. If the input had multiple holes, the output is a GROUP PShape where each child is polygon of one hole.

Since:

1.4.0

polygonizeLines

public static processing.core.PShape polygonizeLines(List<processing.core.PVector> lineSegmentVertices)

Finds the polygonal faces formed by a set of intersecting line segments.

Parameters:

lineSegmentVertices - a list of PVectors where each pair (couplet) of PVectors represent the start and end point of one line segment

Returns:

a GROUP PShape where each child shape is a face / enclosed area formed between intersecting lines

Since:

1.1.2

split

public static processing.core.PShape split(processing.core.PShape shape)

Splits a shape into four equal quadrants (based on the envelope of the shape).

Parameters:

shape - The shape to be split into quadrants.

Returns:

A GROUP PShape where each child shape represents one of the four quadrants partitioned from the original shape.

See Also:

• split(PShape, int)

split

public static processing.core.PShape split(processing.core.PShape shape,
 int splitDepth)

Splits a shape into 4^(1+recursions) rectangular partitions.

This method performs a recursive split operation on the given shape, dividing it into a finer grid of rectangular partitions. Each recursion further divides the envelopes of the parent shapes into four quadrants, resulting in a more refined partitioning of the original shape.

It's important to note that this operation differs from merely overlaying a regular square grid on the shape and then splitting it. The recursive process ensures that each subdivision is based on the envelope of the parent shape, which may be rectangular.

Parameters:

shape - The shape to be split into rectangular partitions.

splitDepth - The number of split recursions to perform, determining the level of partitioning and grid refinement.

Returns:

A GROUP PShape, where each child shape represents one of the quadrant partitions of the original shape.

See Also:

• split(PShape)

centroidSplit

public static processing.core.PShape centroidSplit(processing.core.PShape shape)

Splits the input shape into multiple wedge-shaped regions by connecting the centroid to each vertex.

This method computes the centroid of the given shape, and then draws a line from the centroid to every vertex on the shape’s exterior. The shape is then split along these lines, partitioning it into distinct regions—one for each side of the original shape. For polygons with n vertices, this typically creates n wedge-shaped regions. In the case of concave polygons, this operation may result in more than n regions due to the underlying geometry.

The returned shape is a GROUP PShape, whose children are the resulting partitioned regions.

Parameters:

shape - The shape to be partitioned. Typically a polygonal PShape.

Returns:

A GROUP PShape which contains one child for each wedge-shaped partition created by splitting from the centroid to each vertex.

Since:

2.1

See Also:

• centroidSplit(PShape, int, double)

centroidSplit

public static processing.core.PShape centroidSplit(processing.core.PShape shape,
 int n,
 double offset)

Splits the input shape into n wedge-shaped regions by connecting the centroid to points along the perimeter.

This method computes the centroid of the given shape, and then splits the shape by connecting the centroid to n points sampled evenly (with optional offset) around the outer ring (perimeter) of the shape. The split lines start at these points and end at the centroid. The operation results in approximately n regions for convex shapes, but may produce more than n partitions for highly concave input.

The offset parameter determines the rotation of the sampling around the perimeter.

The returned shape is a GROUP PShape, whose children are the resulting wedge-shaped partitions, radially sorted around the centroid.

Parameters:

shape - The shape to be split; typically a polygonal PShape.

n - The number of splits (rays) to create from the centroid; usually determines number of regions.

offset - The offset for the split lines, as a fraction of the perimeter, in [0, 1).

Returns:

A GROUP PShape, with child shapes being the regions created by the centroid splits, sorted radially.

See Also:

• centroidSplit(PShape)

convexPartition

public static processing.core.PShape convexPartition(processing.core.PShape shape)

Partitions shape(s) into convex (simple) polygons.

Parameters:

shape - the shape to partition. can be a single polygon or a GROUP of polygons

Returns:

a GROUP PShape, where each child shape is some convex partition of the original shape

equalPartition

public static processing.core.PShape equalPartition(processing.core.PShape shape,
 int parts)

Randomly partitions a shape into N approximately equal-area polygonal cells.

Parameters:

shape - a polygonal (non-group, no holes) shape to partition

parts - number of roughly equal area partitons to create

Returns:

a GROUP PShape, whose child shapes are partitions of the original

Since:

1.3.0

equalPartition

public static processing.core.PShape equalPartition(processing.core.PShape shape,
 int parts,
 long seed)

Randomly (with a given seed) partitions a shape into N approximately equal-area polygonal cells.

Parameters:

shape - a polygonal (non-group, no holes) shape to partition

parts - number of roughly equal area partitons to create

seed - number used to initialize the underlying pseudorandom number generator

Returns:

a GROUP PShape, whose child shapes are partitions of the original

Since:

1.4.0

trapezoidPartition

public static processing.core.PShape trapezoidPartition(processing.core.PShape shape)

Decomposes/partitions a shape into axis-aligned (stip-like) trazepoids.

The output can contain some "degenerate" trapezoids that do indeed have 4 vertices but look like triangles.

Parameters:

shape - a polygonal or a GROUP shape

Returns:

a GROUP PShape comprising of trapezoid child shapes

Since:

1.3.0

slice

public static processing.core.PShape slice(processing.core.PShape shape,
 processing.core.PVector p1,
 processing.core.PVector p2)

Slices a shape using a line given by its start and endpoints.

Parameters:

shape - PShape to slice into two shapes

p1 - must be outside shape

p2 - must be outside shape

Returns:

a GROUP PShape with two children, where each child shape is one of the slices

eliminateSlivers

public static processing.core.PShape eliminateSlivers(processing.core.PShape shape,
 double threshold)

Removes narrow areas ("slivers") from a shape while preserving the geometry of the remaining parts.

This operation is similar to erosionDilation(), but better preserves the original geometry of remaining parts.

If the input is a single polygon and if when removing slivers, a multipolygon is produced, further processing occurs within the method to repair it back into a single polygon.

Parameters:

shape - polygonal shape

threshold - width threshold (probably no more than 10); parts narrower than this are eliminated

Returns:

a copy of the input shape having narrow areas/parts removed

Since:

1.3.0

dissolve

public static processing.core.PShape dissolve(processing.core.PShape shape)

Dissolves the linear components of a shape (or group of shapes) into a set of maximal-length lines in which each unique segment appears once.

Example uses: avoid double-drawing shared polygon edges; merge contiguous segments for cleaner rendering/export; or extract non-redundant network edges for topology or routing.

This method does not node the input lines. Crossing segments without a vertex at the intersection remain crossing in the output.

Parameters:

shape - The PShape containing linear geometry.

Returns:

A GROUP PShape whose children are the dissolved maximal-length lines.

Since:

2.1

fix

public static processing.core.PShape fix(processing.core.PShape shape)

Attempts to fix shapes with invalid geometry, while preserving its original form and location as much as possible. See GeometryFixer for a full list of potential fixes.

Input shapes are always processed, so even valid inputs may have some minor alterations. The output is always a new geometry object.

Parameters:

shape - The shape to be corrected.

Returns:

A modified version of the input shape that aligns with valid shape geometry standards.

Since:

2.0

normalise

public static processing.core.PShape normalise(processing.core.PShape shape)

Normalises a shape by standardising its vertex ordering and orientation:

• The outer shell (exterior contour) is oriented clockwise (CW).
• All holes (interior contours) are oriented counterclockwise (CCW).
• Each contour (shell or hole) is rotated so its sequence starts at the vertex with the minimum coordinate (lexicographically by x, then y).

Parameters:

shape - the PShape to normalise

Returns:

a new PShape instance with standardised vertex winding and canonicalised vertex rotation

Since:

2.1

filterChildren

public static processing.core.PShape filterChildren(processing.core.PShape shape,
 Predicate<processing.core.PShape> filterFunction)

Filters out the children of a given PShape object based on a given Predicate function. Child shapes are filtered when the predicate is true: "remove if...".

Example Lambda Code:

 
 PGS_Processing.filterChildren(myShape, child -> PGS_ShapePredicates.area(child) < 50); // discard small child shapes
 
 

Parameters:

shape - The PShape whose children will be filtered.

filterFunction - A Predicate function that takes a PShape object as its argument and returns true if the child shape should be filtered out/removed from the shape. To retain child shapes, the Predicate function should return false. You can use a lambda expression or a method reference to implement the Predicate function.

Returns:

A new PShape that contains only the children shapes of the input shape that satisfy the given Predicate function (==false).

Since:

1.4.0

transform

public static processing.core.PShape transform(processing.core.PShape shape,
 UnaryOperator<processing.core.PShape> function)

Applies a specified transformation function to each child of the given PShape and returns a new PShape containing the transformed children.

This method processes each child of the input shape using the provided function, which can modify, replace, or filter out shapes. The resulting transformed shapes are flattened into a new PShape.

The transformation function can:

• Modify the shape in-place and return it
• Create and return a new shape
• Return null to remove the shape

Note: This method creates a new PShape and does not modify the original shape or its children. The hierarchical structure of the original shape is not preserved in the result.

Parameters:

shape - The PShape whose children will be transformed.

function - A UnaryOperator that takes a PShape as input and returns a transformed PShape. If the function returns null for a shape, that shape will be excluded from the result.

Returns:

A new PShape containing the transformed children, flattened into a single level.

Since:

2.0

See Also:

• transformWithIndex(PShape, BiFunction)

transformWithIndex

public static processing.core.PShape transformWithIndex(processing.core.PShape shape,
 BiFunction<Integer,processing.core.PShape,processing.core.PShape> function)

Applies a specified transformation function to each child of the given PShape, providing the index of each child, and returns a new PShape containing the transformed children.

This method processes each child of the input shape alongside its index using the provided BiFunction. The function can modify, replace, or filter out shapes. The resulting transformed shapes are flattened into a new PShape.

The transformation function can:

• Modify the shape in-place and return it
• Create and return a new shape
• Return null to exclude the shape from the final result

Note: This method creates a new PShape and does not modify the original shape or its children. The hierarchical structure of the original shape is not preserved in the result.

Example usage:

 PShape newShape = PGS_Processing.transformWithIndex(originalShape, (index, child) -> {
 	return (index % 2 == 0) ? child : null; // Include only even-indexed children
 });
 

Parameters:

shape - The PShape whose children will be transformed.

function - A BiFunction that takes an integer index and a PShape as input and returns a transformed PShape. If the function returns null for a shape, that shape will be excluded from the result.

Returns:

A new PShape containing the transformed children, flattened into a single level.

Since:

2.0

See Also:

• transform(PShape, UnaryOperator)

forEachShape

public static <T> List<T> forEachShape(processing.core.PShape shape,
 Function<processing.core.PShape,T> function)

Applies a specified transformation function to each child of the given PShape and returns a list of results produced by the function.

This method processes each child of the input shape using the provided function, which can transform the shape into any desired type T. The function can return null to exclude a shape from the result list.

Unlike the transform(PShape, UnaryOperator) method, this method does not flatten the results into a PShape. Instead, it returns a list of arbitrary objects (type T) produced by the transformation function. This makes it more flexible for use cases where the transformation does not necessarily produce PShape objects.

The transformation function can:

• Transform the shape into a new object of type T
• Return null to exclude the shape from the result list

Note: This method does not modify the original shape or its children. It only applies the transformation function to each child and collects the results.

Type Parameters:

T - The type of the objects produced by the transformation function.

Parameters:

shape - The PShape whose children will be transformed.

function - A Function that takes a PShape as input and returns an object of type T. If the function returns null for a shape, that shape will be excluded from the result list.

Returns:

A list of objects of type T produced by applying the transformation function to each child of the input shape.

Since:

2.1

See Also:

• transform(PShape, UnaryOperator)

forEachShapeWithIndex

public static <T> List<T> forEachShapeWithIndex(processing.core.PShape shape,
 BiFunction<Integer,processing.core.PShape,T> function)

Applies a specified transformation function to each child of the given PShape along with its index and returns a list of results produced by the function.

This method processes each child of the input shape using the provided function, which takes both the index of the child and the child itself as input. The function can transform the shape into any desired type T or return null to exclude the shape from the result list.

Unlike the transformWithIndex(PShape, BiFunction) method, this method does not flatten the results into a PShape. Instead, it returns a list of arbitrary objects (type T) produced by the transformation function. This makes it more flexible for use cases where the transformation does not necessarily produce PShape objects.

The transformation function can:

• Transform the shape into a new object of type T
• Return null to exclude the shape from the result list

Note: This method does not modify the original shape or its children. It only applies the transformation function to each child and collects the results.

Type Parameters:

T - The type of the objects produced by the transformation function.

Parameters:

shape - The PShape whose children will be transformed.

function - A BiFunction that takes an integer index and a PShape as input and returns an object of type T. If the function returns null for a shape, that shape will be excluded from the result list.

Returns:

A list of objects of type T produced by applying the transformation function to each child of the input shape along with its index.

Since:

2.1

See Also:

• transformWithIndex(PShape, BiFunction)
• forEachShape(PShape, Function)

apply

public static processing.core.PShape apply(processing.core.PShape shape,
 Consumer<processing.core.PShape> applyFunction)

Applies a specified function to each child of the given PShape.

This method iterates over each child of the input PShape, applying the provided Consumer function to each. The function can perform any operation on the shapes, such as modifying their properties or applying effects, but does not inherently alter the structure of the PShape or its hierarchy.

The changes are made in place; hence, the original PShape is modified, and the same reference is returned for convenience in chaining or further use.

Example usage:

 PShape shape = PGS_Processing.apply(shape, child -> child.setFill(false));
 

Parameters:

shape - The PShape whose children will be processed.

applyFunction - A Consumer that takes a PShape as input and performs operations on it.

Returns:

The original PShape with the function applied to each child.

Since:

2.0

See Also:

• applyWithIndex(PShape, BiConsumer)

applyWithIndex

public static processing.core.PShape applyWithIndex(processing.core.PShape shape,
 BiConsumer<Integer,processing.core.PShape> applyFunction)

Applies a specified function to each child of the given PShape, providing the index of each child.

This method iterates over each child of the input PShape and applies the provided BiConsumer function to each child along with its index. The function can perform any operation on the shapes such as modifying properties or applying effects. The index can be used for operations that depend on the position of the child within its parent.

The changes are made in place; hence, the original PShape is modified. The method returns the same PShape reference for convenience in chaining or further use.

Example usage:

 PShape shape = PGS_Processing.applyWithIndex(shape, (index, child) -> {
 	if (index % 2 == 0)
 		child.setFill(true);
 });
 

Parameters:

shape - The PShape whose children will be processed.

applyFunction - A BiConsumer that takes an integer index and a PShape as input and performs operations on it.

Returns:

The original PShape with the function applied to each indexed child.

Since:

2.0

See Also:

• apply(PShape, Consumer)