Package micycle.pgs

Class PGS_Morphology

java.lang.Object
micycle.pgs.PGS_Morphology
public final class PGS_Morphology extends Object
Morphological editing operations for PShape polygons.

This class hosts algorithms that reshape geometry, typically by offsetting, simplifying, smoothing, warping, or deforming outlines; often changing vertex count and sometimes changing topology (splitting/merging parts, creating/removing holes).

Author:
Michael Carleton

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    PGS_Morphology.CapStyle
    The end cap style to use.

  • Method Summary

    Modifier and Type
    Method
    Description
    static processing.core.PShape
    arapDeform(processing.core.PShape shape, List<processing.core.PVector> handles, List<processing.core.PVector> handleTargets)
    As-rigid-as-possible (ARAP) 2D deformation of a polygon PShape using point handles.
    static 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
    dilationMorph(processing.core.PShape from, processing.core.PShape to, double morphFactor)
    Interpolates ("morphs") between two shapes using a Hausdorff-distance based dilation approach.
    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(List<processing.core.PShape> shapes, double interpolationFactor)
    Generates an intermediate shape from a sequence of input shapes by interpolating (morphing) between their exterior rings.
    static processing.core.PShape
    interpolate(List<processing.core.PShape> shapes, int frames)
    Generates intermediate shapes (frames) by interpolating (morphing) through a sequence of shapes.
    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 their exterior rings.
    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
    normalisedErosion(processing.core.PShape shape, double amount)
    Erodes (a negative buffer) a shape by a normalised amount (scaled to shape size).
    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)
    Radially warps a polygon by moving each boundary vertex inward/outward along the ray from the polygon centroid to that vertex, 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
    regularise(processing.core.PShape shape, double maxOffset)
    Regularises (straightens) the contour of a lineal PShape by snapping edges toward a small set of principal directions and simplifying the result.
    static processing.core.PShape
    regularise(processing.core.PShape shape, double maxOffset, double axisOrientation)
    Regularises (straightens) the contour of a lineal PShape by snapping edges toward principal directions and simplifying the result.
    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
    smoothBezierFit(processing.core.PShape shape, double maxDeviation)
    Smoothes a shape by fitting one or more cubic Bezier curve segments to each lineal component (polylines and polygon rings), then resampling the fitted Beziers to produce a new vertex sequence.
    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
    smoothGaussianNormalised(processing.core.PShape shape, double amount)
    Applies Gaussian smoothing to each lineal geometry in a PShape using a normalised amount in [0..1], intended to be scale-invariant across children of different sizes.
    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.
    static processing.core.PShape
    voronoiMorph(processing.core.PShape from, processing.core.PShape to, double morphFactor)
    Computes the Voronoi-based Hausdorff morph between two shapes.
    static processing.core.PShape
    voronoiMorph(processing.core.PShape from, processing.core.PShape to, double morphFactor, double maxSegmentLength, boolean unionResult)
    Interpolates ("morphs") between two shapes using a Voronoi partition approach.

    Methods inherited from class java.lang.Object

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

  • 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 buffer
      buffer - 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 buffer
      buffer - distance (extent/width) of the buffer; may be positive or negative
      bufferStyle - 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 buffer
      buffer - distance (extent/width) of the buffer; may be positive or negative
      bufferStyle - 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.

      For polygons, only the exterior ring (perimeter) is buffered; interior rings (holes) are ignored.

      Parameters:
      shape - a polygon, lineal shape, or GROUP containing such shapes
      startDistance - the starting buffer amount
      endDistance - 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.

      For polygons, only the exterior ring (perimeter) is buffered; interior rings (holes) are ignored.

      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, lineal shape, or GROUP containing such shapes
      bufferCallback - A callback function that receives the vertex coordinate and a double representing fractional 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

    • normalisedErosion

      public static processing.core.PShape normalisedErosion(processing.core.PShape shape, double amount)
      Erodes (a negative buffer) a shape by a normalised amount (scaled to shape size).

      amount is dimensionless: amount == 1 corresponds to a full erosion (approximately to the maximum inscribed radius), often collapsing polygons to empty. shape may be a GROUP; each polygonal element is processed independently. The sign of amount is ignored (always erodes).

      Parameters:
      shape - the source shape (polygonal or GROUP)
      amount - normalised erosion amount (dimensionless)
      Returns:
      a polygonal PShape of the eroded geometry (may be empty)
      Since:
      2.2

    • 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 shape
      buffer - a positive number
      Returns:
      a polygonal PShape of the dilated geometry (may be empty)
      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 shape
      buffer - 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:
      simplified 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:
      simplified 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:
      simplified 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 shape
      relevanceThreshold - the relevance threshold; only vertices with relevance >= the threshold will be kept. 20 is a good starting value for generally imperceptible simplification.
      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 Curve
      tension - 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. The addition 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. The subtract 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.

      Note: this method effectively constructs a Bezier curve through the existing vertices. As a result, if the input geometry already has very dense / closely spaced vertices, the smoothing may have little or no perceptual effect. This differs from other smoothing approaches (e.g. Gaussian) that operate at a spatial scale and are therefore largely invariant to vertex density.

      Parameters:
      shape - shape to smooth
      alpha - curvedness parameter (0 is linear, 1 is round, >1 is increasingly curved)
      Returns:
      smoothed copy of the shape
      See Also:

    • smoothBezierFit

      public static processing.core.PShape smoothBezierFit(processing.core.PShape shape, double maxDeviation)
      Smoothes a shape by fitting one or more cubic Bezier curve segments to each lineal component (polylines and polygon rings), then resampling the fitted Beziers to produce a new vertex sequence.

      This method uses Philip J. Schneider’s curve fitting algorithm. Unlike smooth(), which constructs a Bezier curve through the existing vertices, this method approximates the input within a user-specified tolerance and can substantially simplify noisy or densely-vertexed input while producing a visually smoother result.

      The maxDeviation parameter controls how closely the fitted Bezier(s) must follow the original polyline/ring: smaller values preserve the original shape more strictly (often producing more Bezier segments and/or more output vertices), while larger values allow a smoother, more generalised result.

      Implementation note: the fitted Bezier segments are sampled at a fixed spacing (currently 2 units in the coordinate system of the input geometry) to create the returned JTS geometry, which is then converted back to a PShape.

      Parameters:
      shape - shape whose lineal geometry (LineStrings and polygon rings) will be Bezier-fit and resampled
      maxDeviation - maximum allowed deviation (error tolerance) between the input vertices and the fitted Bezier curve(s); must be > 0
      Returns:
      a smoothed copy of shape produced by piecewise cubic Bezier fitting and resampling
      Since:
      2.2
      See Also:
      • SchneiderBezierFitter

    • 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 than smooth().
      Parameters:
      shape - the shape to smooth
      sigma - The standard deviation of the gaussian kernel. Larger values provide more smoothing.
      Returns:
      smoothed copy of the shape
      See Also:

    • smoothGaussianNormalised

      public static processing.core.PShape smoothGaussianNormalised(processing.core.PShape shape, double amount)
      Applies Gaussian smoothing to each lineal geometry in a PShape using a normalised amount in [0..1], intended to be scale-invariant across children of different sizes. amount=0 leaves geometry unchanged; amount=1 collapses (per geometry) using the extreme-sigma fallback.
      Parameters:
      shape - input shape
      amount - normalised smoothing amount in [0..1]
      Returns:
      new shape with smoothed lineal components
      Since:
      2.2
      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 polygonal PShape or a GROUP PShape containing polygonal children; holes (interior contours) are supported
      radius - nominal radius used to round corners; clamped by adjacent edge lengths
      Returns:
      a non-null PShape with rounded corners; possibly an empty GROUP 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 smoothed
      ratio - 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)
      Radially warps a polygon by moving each boundary vertex inward/outward along the ray from the polygon centroid to that vertex, creating a warping or perturbing effect.

      Optionally, the input boundary can be densified before warping by inserting additional vertices at a spacing of ~1 unit. This causes long edges to warp smoothly along their full length rather than only at the original corner vertices.

      Parameters:
      shape - A polygonal PShape (or GROUP of polygons) to be distorted. The warp is applied to each polygon ring independently.
      magnitude - Controls the strength of the warp. Larger values produce larger radial displacements from the original boundary (i.e., larger inward/outward movement). A value of 0 produces an unchanged shape.
      warpOffset - An angular phase offset (in radians) added to each vertex's polar angle before sampling the noise field. Changing warpOffset does not change the warp magnitude; it rotates the noise pattern around the centroid (i.e., shifts where bulges/indentations occur along the boundary). This is useful for animation by incrementing warpOffset over time. The warp has a period of 2π. A typical/useful domain is [0, 2*Math.PI).
      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 shape
      magnitude - maximum perpendicular displacement along the shape perimeter
      frequency - 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 shape
      magnitude - 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 shape
      magnitude - 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 time
      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).
      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 their exterior rings. This process has many names: shape morphing / blending / averaging / tweening / interpolation.

      Note the interpolated shape may self-intersect (this implementation is not "rigid").

      Parameters:
      from - a single polygon; the shape we want to morph from
      to - a single polygon; the shape we want to morph from into
      interpolationFactor - between 0...1
      Returns:
      a polygonal PShape
      Since:
      1.2.0
      See Also:

    • interpolate

      public static processing.core.PShape interpolate(List<processing.core.PShape> shapes, double interpolationFactor)
      Generates an intermediate shape from a sequence of input shapes by interpolating (morphing) between their exterior rings.

      This is a generalisation of interpolate(PShape, PShape, double) to more than two shapes. The interpolation follows the order of shapes.

      Note the interpolated shape may self-intersect (this implementation is not "rigid").

      Parameters:
      shapes - a list of single-polygon PShapes; only the exterior ring is used.
      interpolationFactor - interpolation parameter in the range [0..1]
      Returns:
      a polygonal PShape representing the interpolated shape
      Since:
      2.2.0
      See Also:

    • interpolate

      public static processing.core.PShape interpolate(List<processing.core.PShape> shapes, int frames)
      Generates intermediate shapes (frames) by interpolating (morphing) through a sequence of shapes. This process has many names: shape morphing / blending / averaging / tweening / interpolation.

      The returned frames include both endpoints: the first frame corresponds to t = 0 (the first shape in shapes) and the last frame corresponds to t = 1 (the last shape in shapes). Intermediate frames are evenly spaced in [0..1] using t = i/(frames-1).

      This method is faster than calling interpolate(List, double) (or interpolate(PShape, PShape, double)) repeatedly for different interpolation factors.

      Parameters:
      shapes - a list of single-polygon PShapes, in the order they should be morphed through; only the exterior ring is used.
      frames - the number of frames (including first and last) to generate; must be >= 2
      Returns:
      a GROUP PShape whose children are the generated frames
      Since:
      2.2.0
      See Also:

    • dilationMorph

      public static processing.core.PShape dilationMorph(processing.core.PShape from, processing.core.PShape to, double morphFactor)
      Interpolates ("morphs") between two shapes using a Hausdorff-distance based dilation approach.

      The intermediate shape is computed by buffering each input by a complementary amount (based on the estimated Hausdorff distance between the shapes) and intersecting the two buffers. This provides a correspondence-free morph that works even when the inputs have different vertex counts, components, or holes.

      Parameters:
      from - the starting shape (α = 0)
      to - the ending shape (α = 1)
      morphFactor - the interpolation parameter α (in [0,1])
      Returns:
      a new PShape representing the Hausdorff morph between from and to
      Since:
      2.2

    • voronoiMorph

      public static processing.core.PShape voronoiMorph(processing.core.PShape from, processing.core.PShape to, double morphFactor)
      Computes the Voronoi-based Hausdorff morph between two shapes.

      Convenience overload for voronoiMorph(PShape, PShape, double, double, boolean) using default parameters.

      Uses maxSegmentLength = 0 (no boundary densification) and unionResult = true (returns a cleaned area geometry).

      Parameters:
      from - the starting shape (α = 0)
      to - the ending shape (α = 1)
      morphFactor - the morph parameter α, in [0,1]
      Returns:
      a new PShape representing the Voronoi Hausdorff morph between from and to
      Since:
      2.2
      See Also:

    • voronoiMorph

      public static processing.core.PShape voronoiMorph(processing.core.PShape from, processing.core.PShape to, double morphFactor, double maxSegmentLength, boolean unionResult)
      Interpolates ("morphs") between two shapes using a Voronoi partition approach.

      The non-overlapping parts of each input are partitioned by Voronoi cells induced by sampled boundary sites of the other shape; each partition piece is then moved toward its closest site:

      • closest vertex: uniform scaling toward that vertex,
      • closest edge: scaling perpendicular to the edge’s supporting line.
      The result is the union of transformed pieces from from using fraction α and transformed pieces from to using fraction 1-α, plus their overlap.

      This method supports polygons with holes and groups with disconnected components, and does not require any explicit correspondence between the inputs.

      Parameters:
      from - the starting shape (α = 0)
      to - the ending shape (α = 1)
      morphFactor - the morph parameter α, in [0,1]
      maxSegmentLength - maximum segment length used to densify boundaries when sampling Voronoi sites; <= 0 disables densification
      unionResult - if true, unions the result into a clean area geometry (slower); if false, returns a combined multi/collection geometry (faster) that may retain overlaps/seams
      Returns:
      a new PShape representing the Voronoi-partition morph between from and to
      Since:
      2.2
      See Also:

    • arapDeform

      public static processing.core.PShape arapDeform(processing.core.PShape shape, List<processing.core.PVector> handles, List<processing.core.PVector> handleTargets)
      As-rigid-as-possible (ARAP) 2D deformation of a polygon PShape using point handles.

      Handle semantics

      • handles are points in the rest (original) shape's coordinate space.
      • handleTargets are the desired positions for those same handles in the deformed shape.
      • Both lists must have the same size and matching order (i.e., index i in handles maps to index i in handleTargets).
      • ARAP typically requires at least 2 handles for a stable solve.

      Performance notes

      This method rebuilds and refines a triangulation on every call. For interactive dragging (re-solving every frame), prefer using Malleo directly: build the triangulation and call Malleo.prepareHandles(List) once, then repeatedly call Malleo.solve(Malleo.CompiledHandles, List) with updated targets.

      Output

      Returns the deformed polygon boundary. The result may self-intersect depending on handle motion and mesh quality.

      Parameters:
      shape - the rest shape to deform (expected to be a single polygon PShape)
      handles - handle locations in rest-space
      handleTargets - target locations for each handle, in the same order as handles
      Returns:
      a new PShape representing the deformed shape
      Since:
      2.2

    • 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 reduce
      precision - 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

    • regularise

      public static processing.core.PShape regularise(processing.core.PShape shape, double maxOffset)
      Regularises (straightens) the contour of a lineal PShape by snapping edges toward a small set of principal directions and simplifying the result. The prinicipal direction is derived from the shape's longest edge.
      Parameters:
      shape - a lineal PShape to regularise (or a group containing lineal children)
      maxOffset - maximum allowed offset. Used to constrain how far the regularised contour may deviate from the input; must be >= 0
      Returns:
      a new PShape whose linework has been regularised
      Since:
      2.2
      See Also:

    • regularise

      public static processing.core.PShape regularise(processing.core.PShape shape, double maxOffset, double axisOrientation)
      Regularises (straightens) the contour of a lineal PShape by snapping edges toward principal directions and simplifying the result.

      This overload lets you provide an explicit principal axis orientation (in degrees). Edges are snapped to be parallel to that axis or to its orthogonal (axis + 90°), subject to the maxOffset constraint.

      Parameters:
      shape - a lineal PShape to regularize (or a group containing lineal children)
      maxOffset - maximum allowed offset used to constrain how far the regularised contour may deviate from the input; must be >= 0
      axisOrientation - principal axis direction, in degrees, expected in the range [0,180) (values outside this range are normalised)
      Returns:
      a new PShape whose linework has been regularised
      Since:
      2.2
      See Also: