Class PGS_Morphology
- Author:
- Michael Carleton
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptionstatic processing.core.PShape
buffer
(processing.core.PShape shape, double buffer) Returns a rounded buffer region of the given shape at the specified distance.static processing.core.PShape
buffer
(processing.core.PShape shape, double buffer, PGS_Contour.OffsetStyle bufferStyle) Returns a buffer region of the given shape using the specified join style.static processing.core.PShape
buffer
(processing.core.PShape shape, double buffer, PGS_Contour.OffsetStyle bufferStyle, PGS_Morphology.CapStyle capStyle) Returns a buffer region of the given shape using the specified join and cap styles.static processing.core.PShape
chaikinCut
(processing.core.PShape shape, double ratio, int iterations) Smoothes a shape by recursively cutting its corners, a technique introduced by George Chaikin in 1974.static processing.core.PShape
dilationErosion
(processing.core.PShape shape, double buffer) Applies a positive followed by a negative buffer (in a single operation), the effect of which is small holes and gaps are filled in, while the general structure of the shape is preserved.static processing.core.PShape
erosionDilation
(processing.core.PShape shape, double buffer) Applies a negative followed by a positive buffer (in a single operation), the effect of which is small edges/islands are removed, while the general structure of the shape is preserved.static processing.core.PShape
fieldWarp
(processing.core.PShape shape, double magnitude, double noiseScale, boolean densify) Warps/perturbs a shape by displacing vertices according to a 2D noise vector field.static processing.core.PShape
fieldWarp
(processing.core.PShape shape, double magnitude, double noiseScale, double time, boolean densify, long noiseSeed) Warps/perturbs a shape by displacing vertices according to a 2D noise vector field.static processing.core.PShape
interpolate
(processing.core.PShape from, processing.core.PShape to, double interpolationFactor) Generates an intermediate shape between two shapes by interpolating between them.static processing.core.PShape
interpolate
(processing.core.PShape from, processing.core.PShape to, int frames) Generates intermediate shapes (frames) between two shapes by interpolating between them.static processing.core.PShape
minkDifference
(processing.core.PShape source, processing.core.PShape subtract) Computes a Minkowski difference (a.k.a erosion) of the two source shapes.static processing.core.PShape
minkSum
(processing.core.PShape source, processing.core.PShape addition) Computes a Minkowski sum (a.k.a dilation) of the two source shapes.static processing.core.PShape
pinchWarp
(processing.core.PShape shape, processing.core.PVector pinchPoint, double weight) Applies a pinch warping effect to a shape, distorting vertices towards a specified point.static processing.core.PShape
radialWarp
(processing.core.PShape shape, double magnitude, double warpOffset, boolean densify) Distorts a polygonal shape by radially displacing its vertices along the line connecting each vertex with the shape's centroid, creating a warping or perturbing effect.static processing.core.PShape
reducePrecision
(processing.core.PShape shape, double precision) Reduces the precision of a shape, whilst ensuring the output shape is valid.static processing.core.PShape
round
(processing.core.PShape shape, double radius) Rounds polygon corners by replacing each corner with a circular arc.static processing.core.PShape
simplify
(processing.core.PShape shape, double distanceTolerance) Simplifies a shape using the Douglas-Peucker algorithm, reducing the complexity and number of vertices of the shape.static processing.core.PShape
simplifyDCE
(processing.core.PShape shape, double relevanceThreshold) Simplify the shape using DCE, removing vertices with relevance < r.static processing.core.PShape
simplifyDCE
(processing.core.PShape shape, micycle.pgs.commons.DiscreteCurveEvolution.DCETerminationCallback terminationCallback) Simplifies a shape via Discrete Curve Evolution.static processing.core.PShape
simplifyHobby
(processing.core.PShape shape, double tension) Creates a Hobby Curve from the vertices of the shape.static processing.core.PShape
simplifyTopology
(processing.core.PShape shape, double distanceTolerance) Simplifies a shape, whilst preserving the topological structure of the shape (holes, etc.).static processing.core.PShape
simplifyVW
(processing.core.PShape shape, double distanceTolerance) Simplifies a shape using the Visvalingam-Whyatt area-based algorithm, reducing the complexity and number of vertices of the shape.static processing.core.PShape
sineWarp
(processing.core.PShape shape, double magnitude, double frequency, double phase) Warps/perturbs a shape by displacing vertices (both positively and negatively) according to the magnitude of a sine wave which follows the shape perimeter at some frequency.static processing.core.PShape
smooth
(processing.core.PShape shape, double alpha) Smoothes a shape.static processing.core.PShape
smoothEllipticFourier
(processing.core.PShape shape, int descriptors) Calculates the Elliptic Fourier Descriptors (EFD) of a specified shape, yielding a simplified/smoothed shape representation based on the specified number of descriptors.static processing.core.PShape
smoothGaussian
(processing.core.PShape shape, double sigma) Smoothes a shape by applying a gaussian filter to vertex coordinates.static processing.core.PShape
smoothLaneRiesenfeld
(processing.core.PShape shape, int degree, int subdivisions, double antiContractionFactor) Smooths a shape using Lane-Riesenfeld curve subdivision with 4-point refinement to reduce contraction.static processing.core.PShape
variableBuffer
(processing.core.PShape shape, double startDistance, double endDistance) Buffers a shape with a varying buffer distance (interpolated between a start distance and an end distance) along the shape's perimeter.static processing.core.PShape
variableBuffer
(processing.core.PShape shape, BiFunction<org.locationtech.jts.geom.Coordinate, Double, Double> bufferCallback) Applies a variable buffer to a shape.
-
Method Details
-
buffer
public static processing.core.PShape buffer(processing.core.PShape shape, double buffer) Returns a rounded buffer region of the given shape at the specified distance.The distance is in the same coordinate units as the shape: positive values expand the shape, negative values contract it. The returned shape is a polygonal PShape and may be empty. The input shape is not modified.
- Parameters:
shape
- the source shape to bufferbuffer
- distance (extent/width) of the buffer; may be positive or negative- Returns:
- a polygonal PShape representing the buffer region (may be empty)
- See Also:
-
buffer
public static processing.core.PShape buffer(processing.core.PShape shape, double buffer, PGS_Contour.OffsetStyle bufferStyle) Returns a buffer region of the given shape using the specified join style.The distance is in the same coordinate units as the shape: positive values expand the shape, negative values contract it. The bufferStyle controls how corners are joined (e.g. ROUND, MITER, BEVEL). The returned shape is a polygonal PShape and may be empty. The input shape is not modified.
- Parameters:
shape
- the source shape to bufferbuffer
- distance (extent/width) of the buffer; may be positive or negativebufferStyle
- how to join offset segments (ROUND, MITER, BEVEL)- Returns:
- a polygonal PShape representing the buffer region (may be empty)
- Since:
- 1.3.0
- See Also:
-
buffer
public static processing.core.PShape buffer(processing.core.PShape shape, double buffer, PGS_Contour.OffsetStyle bufferStyle, PGS_Morphology.CapStyle capStyle) Returns a buffer region of the given shape using the specified join and cap styles.The distance is in the same coordinate units as the shape: positive values expand the shape, negative values contract it. bufferStyle controls how corners are joined; capStyle controls the end-cap style used for open geometries. The input shape is not modified; the returned PShape preserves the user data from the original geometry. The result is a polygonal PShape and may be empty.
- Parameters:
shape
- the source shape to bufferbuffer
- distance (extent/width) of the buffer; may be positive or negativebufferStyle
- how to join offset segments (ROUND, MITER, BEVEL)capStyle
- how to draw end caps for open geometries (e.g. ROUND, FLAT)- Returns:
- a polygonal PShape representing the buffer region (may be empty)
- Since:
- 2.1
-
variableBuffer
public static processing.core.PShape variableBuffer(processing.core.PShape shape, double startDistance, double endDistance) Buffers a shape with a varying buffer distance (interpolated between a start distance and an end distance) along the shape's perimeter.- Parameters:
shape
- a single polygon or lineal shapestartDistance
- the starting buffer amountendDistance
- the terminating buffer amount- Returns:
- a polygonal shape representing the variable buffer region (which may be empty)
- Since:
- 1.3.0
-
variableBuffer
public static processing.core.PShape variableBuffer(processing.core.PShape shape, BiFunction<org.locationtech.jts.geom.Coordinate, Double, Double> bufferCallback) Applies a variable buffer to a shape. The buffer width at each vertex is determined by a callback function that considers the vertex's properties and its relative position along the shape's boundary.Example usage:
PShape bufferedShape = bufferWithCallback(inputShape, (coordinate, fraction) -> { // Example logic: buffer width decreases linearly from 10 units at the // start to 1 unit at the end return 10 - (fraction * (10 - 1)); });
- Parameters:
shape
- A single polygon or lineal shapebufferCallback
- A callback function that receives the vertex coordinate and a double representing tractional distance (0...1) of the vertex along the shape's boundary. The function may use properties of the vertex, or its position, to determine the buffer width at that point.- Returns:
- A new shape representing the original shape buffered with variable widths as specified by the callback function. The width at each vertex is calculated independently.
- Since:
- 2.0
-
erosionDilation
public static processing.core.PShape erosionDilation(processing.core.PShape shape, double buffer) Applies a negative followed by a positive buffer (in a single operation), the effect of which is small edges/islands are removed, while the general structure of the shape is preserved.This operation is known as "opening" in computer vision.
- Parameters:
shape
- polygonal shapebuffer
- a positive number- Returns:
- See Also:
-
dilationErosion
public static processing.core.PShape dilationErosion(processing.core.PShape shape, double buffer) Applies a positive followed by a negative buffer (in a single operation), the effect of which is small holes and gaps are filled in, while the general structure of the shape is preserved.This operation is known as "closing" in computer vision.
- Parameters:
shape
- polygonal shapebuffer
- a positive number- Since:
- 1.3.0
- See Also:
-
simplify
public static processing.core.PShape simplify(processing.core.PShape shape, double distanceTolerance) Simplifies a shape using the Douglas-Peucker algorithm, reducing the complexity and number of vertices of the shape.During the process shapes can be split, collapse to lines or disappear. Holes can be created or disappear.
- Parameters:
shape
-distanceTolerance
- the tolerance to use- Returns:
- simplifed copy of the shape
- See Also:
-
simplifyVW
public static processing.core.PShape simplifyVW(processing.core.PShape shape, double distanceTolerance) Simplifies a shape using the Visvalingam-Whyatt area-based algorithm, reducing the complexity and number of vertices of the shape.- Parameters:
shape
-distanceTolerance
- The simplification tolerance is specified as a distance.This is converted to an area tolerance by squaring it.- Returns:
- simplifed copy of the shape
- See Also:
-
simplifyTopology
public static processing.core.PShape simplifyTopology(processing.core.PShape shape, double distanceTolerance) Simplifies a shape, whilst preserving the topological structure of the shape (holes, etc.).- Parameters:
shape
-distanceTolerance
- the tolerance to use- Returns:
- simplifed copy of the shape
- See Also:
-
simplifyDCE
public static processing.core.PShape simplifyDCE(processing.core.PShape shape, micycle.pgs.commons.DiscreteCurveEvolution.DCETerminationCallback terminationCallback) Simplifies a shape via Discrete Curve Evolution.This algorithm simplifies a shape by iteratively removing kinks from the shape, starting with those having the least shape-relevance.
The simplification process terminates according to a user-specified
callback
that decides whether the DCE algorithm should terminate based on the current kink (having a candidate vertex), using its: coordinate, relevance score, and the number of vertices remaining in the simplified geometry. Implementations can use this method to provide custom termination logic which may depend on various factors, such as a threshold relevance score, a specific number of vertices to preserve, or other criteria.Note: the termination callback is applied per ring (boundary, hole, line, etc) in the input.
- Parameters:
shape
- The input shape to be simplified, which can be a polygonal (inclusive of holes) or a lineal shape. GROUP shapes are supported.terminationCallback
- The callback used to determine when the simplification process should terminate.true
if the DCE process should terminate;false
otherwise.- Returns:
- A new, simplified copy of the input shape, with the least significant kinks or vertices removed according to the provided fraction.
- Since:
- 2.0
-
simplifyDCE
public static processing.core.PShape simplifyDCE(processing.core.PShape shape, double relevanceThreshold) Simplify the shape using DCE, removing vertices with relevance < r.- Parameters:
shape
- the input shaperelevanceThreshold
- the relevance threshold; only vertices with relevance >= the threshold will be kept- Returns:
- the simplified PShape
- Since:
- 2.1
-
simplifyHobby
public static processing.core.PShape simplifyHobby(processing.core.PShape shape, double tension) Creates a Hobby Curve from the vertices of the shape. This tends to simplify/round the geometry of shape, but may actually increase the number of vertices due to increased curvature.You may want to consider simplifying a shape (reducing vertex count) with other methods before applying Hobby simplification.
- Parameters:
shape
- vertices to use as basis for the Hobby Curvetension
- a parameter that controls the tension of the curve (how tightly it is "pulled" towards underlying vertices). Suitable domain is [0.666...3].- Returns:
- a Hobby Curve
- Since:
- 1.4.0
-
minkSum
public static processing.core.PShape minkSum(processing.core.PShape source, processing.core.PShape addition) Computes a Minkowski sum (a.k.a dilation) of the two source shapes. Theaddition
shape should probably be centered on (0,0) for best results.To instill you with intuition of what a Minkowski sum looks like, here are a few examples:
- The sum of any shape and a point is that shape translated by that point.
- The sum of any shape and two points is two translated (possibly overlapping) copies of that shape.
- The sum of two circles is a larger circle (sum the radii) with its centre at the sum of the centres of the smaller circles.
- The sum of any shape and a line is that shape swept through that line. Think of placing your shape in sand, and dragging it along the line.
- Similarly, the sum of a shape and any curve is what you’d get by sweeping the shape through the curve.
- The sum of two parallel lines is a longer line.
- For perpendicular lines, you get a square.
- Returns:
- shape representing the Minkowski sum of source+addition
- See Also:
-
minkDifference
public static processing.core.PShape minkDifference(processing.core.PShape source, processing.core.PShape subtract) Computes a Minkowski difference (a.k.a erosion) of the two source shapes. Thesubtract
shape should probably be centered on (0,0) for best results.- Returns:
- shape representing the Minkowski difference of source-subtract
- See Also:
-
smooth
public static processing.core.PShape smooth(processing.core.PShape shape, double alpha) Smoothes a shape. The smoothing algorithm inserts new vertices which are positioned using Bezier splines. The output shape tends to be a little larger than the input.- Parameters:
shape
- shape to smoothalpha
- curvedness parameter (0 is linear, 1 is round, >1 is increasingly curved)- Returns:
- smoothed copy of the shape
- See Also:
-
smoothGaussian
public static processing.core.PShape smoothGaussian(processing.core.PShape shape, double sigma) Smoothes a shape by applying a gaussian filter to vertex coordinates. At larger values, this morphs the input shape much more visually thansmooth()
.- Parameters:
shape
- the shape to smoothsigma
- The standard deviation of the gaussian kernel. Larger values provide more smoothing.- Returns:
- smoothed copy of the shape
- See Also:
-
smoothEllipticFourier
public static processing.core.PShape smoothEllipticFourier(processing.core.PShape shape, int descriptors) Calculates the Elliptic Fourier Descriptors (EFD) of a specified shape, yielding a simplified/smoothed shape representation based on the specified number of descriptors.The EFD technique is an approach for shape analysis and simplification that decomposes a shape into a sequence of elliptic harmonic components. These components encapsulate the contour details of the shape: lower-order harmonics capture the broad geometry of the shape, while higher-order harmonics register the detailed, high-frequency contour characteristics, analogous to Principal Component Analysis (PCA). This technique is particularly effective for generating condensed or smoother versions of complex shapes.
- Parameters:
shape
- A polygonal shape to be transformed using the EFD.descriptors
- The desired level of the EFD, denoting the quantity of harmonics to be retained in the output. The maximum value is half the total number of vertices in the shape, while the minimum allowable value is 2. As the number of harmonics is increased, the output tends towards the input shape.- Returns:
- A new PShape, simplified through the application of the Elliptic Fourier Descriptors up to the indicated order. This shape will always have the same number of vertices as the original.
- Since:
- 1.4.0
-
smoothLaneRiesenfeld
public static processing.core.PShape smoothLaneRiesenfeld(processing.core.PShape shape, int degree, int subdivisions, double antiContractionFactor) Smooths a shape using Lane-Riesenfeld curve subdivision with 4-point refinement to reduce contraction.- Parameters:
shape
- A shape having lineal geometries (polygons or linestrings). Can be a GROUP shape consisting of these.degree
- The degree of the LR algorithm. Higher degrees influence the placement of vertices and the overall shape of the curve, but only slightly increase the number of vertices generated. Increasing the degree also increases the contraction of the curve toward its control points. The degree does not directly control the smoothness of the curve. A value of 3 or 4 is usually sufficient for most applications.subdivisions
- The number of times the subdivision process is applied. More subdivisions result in finer refinement and visually smoother curves between vertices. A value of 3 or 4 is usually sufficient for most applications.antiContractionFactor
- The weight parameter for the 4-point refinement. Controls the interpolation strength. A value of 0 effectively disables the contraction reduction. Generally suitable values are in [0...0.1]. Larger values may create self-intersecting geometry.- Returns:
- A Shape having same structure as the input, whose geometries are now smooth.
- Since:
- 2.1
-
round
public static processing.core.PShape round(processing.core.PShape shape, double radius) Rounds polygon corners by replacing each corner with a circular arc.This processes only the linear content of the input
PShape
- the contour paths (closed contours for polygon exteriors and interior contours/holes, and open polylines). Non‑linear or unsupported children are ignored.The
radius
is nominal; it is clamped so it cannot exceed what adjacent edges can support (this prevents overlapping or invalid contours).- Parameters:
shape
- a polygonalPShape
or aGROUP
PShape
containing polygonal children; holes (interior contours) are supportedradius
- nominal radius used to round corners; clamped by adjacent edge lengths- Returns:
- a non-null
PShape
with rounded corners; possibly an emptyGROUP
when nothing remains
-
chaikinCut
public static processing.core.PShape chaikinCut(processing.core.PShape shape, double ratio, int iterations) Smoothes a shape by recursively cutting its corners, a technique introduced by George Chaikin in 1974.This method can be used to generate smooth-looking curves from a limited number of points. More iterations result in more smoothing.
- Parameters:
shape
- The shape to be smoothedratio
- A ratio (between 0 and 1) determining how far along each edge to perform the two cuts. For example, a ratio of 0.5 will cut the underlying edge twice, at 0.25x and 0.75x along its length. A value of 1 will cut each edge once, directly at its midpoint. It is recommended to use a value of 0.5 for this parameter.iterations
- The number of cutting iterations/recursions to perform. A value of 1 will simply cut the corners once, higher values will effectively smooth the cut. Values greater than ~10 generally have no additional visual effect.- Returns:
- A copy of the input shape with corners cut.
- Since:
- 1.1.0
-
radialWarp
public static processing.core.PShape radialWarp(processing.core.PShape shape, double magnitude, double warpOffset, boolean densify) Distorts a polygonal shape by radially displacing its vertices along the line connecting each vertex with the shape's centroid, creating a warping or perturbing effect.The shape's input vertices can optionally be densified prior to the warping operation.
- Parameters:
shape
- A polygonal PShape object to be distorted.magnitude
- The degree of the displacement, which determines the maximum Euclidean distance a vertex will be moved in relation to the shape's centroid.warpOffset
- An offset angle, which establishes the starting angle for the displacement process.densify
- A boolean parameter determining whether the shape should be densified (by inserting additional vertices at a distance of 1) before warping. If true, shapes with long edges will experience warping along their entire length, not just at the original vertices.- Returns:
- A new PShape object that has been radially warped according to the specified parameters.
-
sineWarp
public static processing.core.PShape sineWarp(processing.core.PShape shape, double magnitude, double frequency, double phase) Warps/perturbs a shape by displacing vertices (both positively and negatively) according to the magnitude of a sine wave which follows the shape perimeter at some frequency.- Parameters:
shape
- single polygonal shapemagnitude
- maximum perpendicular displacement along the shape perimeterfrequency
- sine wave frequency. Values less than 1 will result in an offset that does not smoothly join up.phase
- sine wave phase. corresponds to the fraction (0...1) around the shape perimeter where the wave starts (0 displacement).- Returns:
- warped polygonal shape
- Since:
- 1.3.0
-
fieldWarp
public static processing.core.PShape fieldWarp(processing.core.PShape shape, double magnitude, double noiseScale, boolean densify) Warps/perturbs a shape by displacing vertices according to a 2D noise vector field.Inputs may be densified before warping.
- Parameters:
shape
- a polygonal shapemagnitude
- magnitude of the displacement (acting as noise value multiplier). The value defines the maximum displacement of a vertex in the both x and y axes.noiseScale
- the scale of the 2D noise vector field. This affects how of the coarseness of warping. Smaller values (~0.2) lead to more fine warping (at edges), whereas larger values (~2) affect the shape geometry at a larger scale.densify
- whether to densify the shape (using distance=1) before warping. When true, shapes with long edges will undergo warping along the whole edge (rather than only at the original vertices).- Returns:
- warped polygonal shape
- See Also:
-
fieldWarp
public static processing.core.PShape fieldWarp(processing.core.PShape shape, double magnitude, double noiseScale, double time, boolean densify, long noiseSeed) Warps/perturbs a shape by displacing vertices according to a 2D noise vector field.Inputs may be densified before warping for more finely-grained warping.
- Parameters:
shape
- a polygonal shapemagnitude
- magnitude of the displacement (acting as noise value multiplier). The value defines the maximum displacement of a vertex in the both x and y axes.noiseScale
- the scale of the 2D noise vector field. This affects how of the coarseness of warping. Smaller values (~0.2) lead to more fine warping (at edges), whereas larger values (~2) affect the shape geometry at a larger scale.time
- used to offset the underlying noise field and hence animate the warping over timedensify
- whether to densify the shape (using distance=1) before warping. When true, shapes with long edges will undergo warping along the whole edge (rather than only at the original vertices).noiseSeed
- a seed to pass to the underlying noise generator- Returns:
- warped polygonal shape
- See Also:
-
pinchWarp
public static processing.core.PShape pinchWarp(processing.core.PShape shape, processing.core.PVector pinchPoint, double weight) Applies a pinch warping effect to a shape, distorting vertices towards a specified point. The strength of the pinch effect decreases with distance from the pinch point, creating a localized warping effect.- Parameters:
shape
- The shape. The original shape is not modified; instead, a new warped shape is returned.pinchPoint
- The point in 2D space towards which the shape will be pinched. Vertices closer to this point will be affected more strongly.weight
- The strength of the pinching effect. Higher values create stronger distortion.- Returns:
- A new PShape object comprising the warped geometry.
- Since:
- 2.0
-
interpolate
public static processing.core.PShape interpolate(processing.core.PShape from, processing.core.PShape to, double interpolationFactor) Generates an intermediate shape between two shapes by interpolating between them. This process has many names: shape morphing / blending / averaging / tweening / interpolation.The underlying technique rotates one of the shapes to minimise the total distance between each shape's vertices, then performs linear interpolation between vertices. This performs well in practice but the outcome worsens as shapes become more concave; more sophisticated techniques would employ some level of rigidity preservation.
- Parameters:
from
- a single polygon; the shape we want to morph fromto
- a single polygon; the shape we want to morphfrom
intointerpolationFactor
- between 0...1- Returns:
- a polygonal PShape
- Since:
- 1.2.0
- See Also:
-
interpolate
public static processing.core.PShape interpolate(processing.core.PShape from, processing.core.PShape to, int frames) Generates intermediate shapes (frames) between two shapes by interpolating between them. This process has many names: shape morphing / blending / averaging / tweening / interpolation.This method is faster than calling
interpolate()
repeatedly for different interpolation factors.- Parameters:
from
- a single polygon; the shape we want to morph fromto
- a single polygon; the shape we want to morphfrom
intoframes
- the number of frames (including first and last) to generate. >= 2- Returns:
- a GROUP PShape, where each child shape is a frame from the interpolation
- Since:
- 1.3.0
- See Also:
-
reducePrecision
public static processing.core.PShape reducePrecision(processing.core.PShape shape, double precision) Reduces the precision of a shape, whilst ensuring the output shape is valid.This method effectively rounds vertices to the nearest value given by
precision
.- Parameters:
shape
- shape to reduceprecision
- the exact grid size with which to round shape vertices. should be non-zero and positive- Returns:
- reduced copy of input
- Since:
- 1.3.0
-