Package micycle.pgs

Class PGS_Contour

java.lang.Object
micycle.pgs.PGS_Contour
public final class PGS_Contour extends Object
Methods for producing interior contour structures from shapes.

The algorithms in this class extract derived linework—such as medial/chordal axes, straight skeletons, isolines, and field-derived curves—computed from within the interior of a polygonal PShape. These results describe the shape’s internal topology or scalar fields (e.g., distance-to-boundary), rather than directly editing the original boundary.

Note: Outputs are typically vector linework (polylines) and may be returned as GROUP PShapes. Depending on geometry complexity, some methods may produce branching networks, multiple disjoint components, or degenerate segments.

Author:
Michael Carleton

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    PGS_Contour.OffsetStyle
    Specifies the join style for offset curves.

  • Method Summary

    Modifier and Type
    Method
    Description
    static processing.core.PShape
    centerLine(processing.core.PShape shape)
    Calculates the longest center line passing through a given shape (using default straightness weighting and smoothing parameters).
    static processing.core.PShape
    centerLine(processing.core.PShape shape, double straightnessWeighting, double smoothing)
    Calculates the longest center line passing through a given shape.
    static processing.core.PShape
    chordalAxis(processing.core.PShape shape)
    Computes the chordal axis of a shape, which provides a characterization of the skeleton of a shape.
    static processing.core.PShape
    contrastField(processing.core.PShape shape, int intervals, processing.core.PVector reference)
    Generates vector contour lines representing a "contrast field" of a shape with respect to a given reference point.
    static processing.core.PShape
    distanceField(processing.core.PShape shape, double spacing)
    Generates interior contour lines (isolines) that radiate from a shape “center”.
    static processing.core.PShape
    distanceField(processing.core.PShape shape, double spacing, processing.core.PVector pole)
    Generates interior contour lines (isolines) that radiate from a specified pole point within a polygon.
    static processing.core.PShape
    distanceTree(processing.core.PShape mesh, processing.core.PVector source, boolean flatten)
    Generates a tree structure representing the shortest paths from a given start point to all other vertices in the provided mesh.
    static Map<processing.core.PShape,Float>
    isolines(Collection<processing.core.PVector> points, double intervalValueSpacing, double isolineMin, double isolineMax)
    Generates a topographic-like isoline contour map from the given points.
    static Map<processing.core.PShape,Float>
    isolines(Collection<processing.core.PVector> points, double intervalValueSpacing, double isolineMin, double isolineMax, int smoothing)
    Generates a topographic-like isoline contour map from the given points.
    static Map<processing.core.PShape,Float>
    isolines(Collection<processing.core.PVector> points, int intervals, int smoothing)
    Generates a topographic-like isoline contour map from the given points.
    static processing.core.PShape
    isolines(processing.core.PShape shape, processing.core.PVector highPoint, double intervalSpacing)
    Generates a topographic-like isoline contour map from the shape's vertices and a given "high point".
    static processing.core.PShape
    isolinesFromFunction(double[] bounds, double sampleSpacing, double contourInterval, DoubleBinaryOperator valueFunction)
    Extracts contour lines (isolines) from a user-defined 2D “height map” over a rectangular region.
    static processing.core.PShape
    isolinesFromFunction(double[] bounds, double sampleSpacing, double contourInterval, DoubleBinaryOperator valueFunction, double isolineMin, double isolineMax)
    Extracts contour lines (isolines) from a user-defined 2D “height map” over a rectangular region, within a specified value range.
    static processing.core.PShape
    isolineZeroFromFunction(double[] bounds, double sampleSpacing, DoubleBinaryOperator valueFunction)
    Extracts the zero contour (the 0-level set) from a user-defined 2D “height map” over a rectangular region.
    static processing.core.PShape
    medialAxis(processing.core.PShape shape, double axialThreshold, double distanceThreshold, double areaThreshold)
    Computes the medial axis of the given shape, providing a characterization of the skeleton of a shape.
    static processing.core.PShape
    offsetCurvesInward(processing.core.PShape shape, PGS_Contour.OffsetStyle style, double spacing)
    Generates inward-facing offset curves from a shape.
    static processing.core.PShape
    offsetCurvesInward(processing.core.PShape shape, PGS_Contour.OffsetStyle style, double spacing, int curves)
    Generates N inward-facing offset curves from a shape.
    static processing.core.PShape
    offsetCurvesOutward(processing.core.PShape shape, PGS_Contour.OffsetStyle style, double spacing, int curves)
    Generates N outward-facing offset curves from a shape.
    static processing.core.PShape
    straightSkeleton(processing.core.PShape shape)
    Computes the straight skeleton for a shape.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • medialAxis

      public static processing.core.PShape medialAxis(processing.core.PShape shape, double axialThreshold, double distanceThreshold, double areaThreshold)
      Computes the medial axis of the given shape, providing a characterization of the skeleton of a shape.

      The method employs three parameters to prune (simplify) the resulting medial axis according to distinct features.

      Parameters:
      shape - The PShape to calculate the medial axis for.
      axialThreshold - A value in the range of 0 to 1 that determines the level of pruning based on the axial gradient. The axial gradient evaluates the variation in the shape's width per unit length along the axis, measured per edge segment. A value of 0 results in no pruning, while a value of 1 leads to the maximum possible pruning.
      distanceThreshold - A value between 0 and 1 that determines the level of pruning based on the spatial distance from the root of the medial axis to the tail coordinate of each edge. A value of 0 results in no pruning, while a value of 1 results in maximum possible pruning.
      areaThreshold - A value between 0 and 1 that determines the level of pruning based on the aggregate feature area of each edge and its descendants in the medial axis. A value of 0 results in no pruning, while a value of 1 results in the maximum possible pruning.
      Returns:
      A GROUP PShape containing maximal-length lines representing the pruned edges of the medial axis.

    • chordalAxis

      public static processing.core.PShape chordalAxis(processing.core.PShape shape)
      Computes the chordal axis of a shape, which provides a characterization of the skeleton of a shape.

      In its primitive form, the chordal axis is constructed by joining the midpoints of the chords and the centroids of junction and terminal triangles of the delaunay triangulation of a shape.

      It can be considered a more useful alternative to the medial axis for obtaining skeletons of discrete shapes.

      Parameters:
      shape - polygonal shape
      Returns:
      a GROUP PShape, where each group is a single maximum-length line segment (possibly >2 vertices)
      Since:
      1.3.0

    • straightSkeleton

      public static processing.core.PShape straightSkeleton(processing.core.PShape shape)
      Computes the straight skeleton for a shape.

      A straight skeleton is a skeletal structure similar to the medial axis, consisting of straight-line segments only. Roughly, it is the geometric graph whose edges are the traces of vertices of shrinking mitered offset curves of the polygon.

      For a single polygon, this method returns a GROUP PShape containing three children:

      • Child 0: GROUP PShape consisting of skeleton faces.
      • Child 1: LINES PShape representing branches, which are lines connecting the skeleton to the polygon's edge.
      • Child 2: LINES PShape composed of bones, depicting the pure straight skeleton of the polygon.

      For multi-polygons, the method returns a master GROUP PShape. This master shape includes multiple skeleton GROUP shapes, each corresponding to a single polygon and structured as described above.

      Parameters:
      shape - a single polygon (that can contain holes), or a multi polygon (whose polygons can contain holes)
      Returns:
      PShape based on the input polygon structure, either as a single or multi-polygon skeleton representation.

    • isolines

      public static processing.core.PShape isolines(processing.core.PShape shape, processing.core.PVector highPoint, double intervalSpacing)
      Generates a topographic-like isoline contour map from the shape's vertices and a given "high point". Isolines represent the "elevation", or euclidean distance, between a location in the shape and the "high point".

      Assigns each point feature a number equal to the distance between geometry's centroid and the point.

      Parameters:
      shape - the bounds in which to draw isolines
      highPoint - position of "high" point within the shape
      intervalSpacing - distance between successive isolines
      Returns:
      PShape containing isolines linework

    • isolines

      public static Map<processing.core.PShape,Float> isolines(Collection<processing.core.PVector> points, int intervals, int smoothing)
      Generates a topographic-like isoline contour map from the given points. This method uses the Z value of each PVector point as the "elevation" of that location in the map, and uses a specified number of contour intervals. The function finds the minimum and maximum Z values in the given points, divides the Z range into the specified number of intervals, and generates isolines or contour curves at corresponding heights. Smoothing can be applied to the isolines for better visual results.
      Parameters:
      points - Collection of PVectors representing sample locations. The z coordinate of each PVector defines the elevation at that point.
      intervals - The number of contour levels (isolines) to generate between the minimum and maximum Z values in the input points. Must be greater than zero.
      smoothing - The amount of smoothing to apply to the generated isolines. The smoothing algorithm and valid range depend on implementation.
      Returns:
      A Map where the keys are PShape objects representing the isolines, and the values are Float numbers giving the Z value (height) for each isoline.
      Since:
      2.1
      See Also:

    • isolines

      public static Map<processing.core.PShape,Float> isolines(Collection<processing.core.PVector> points, double intervalValueSpacing, double isolineMin, double isolineMax)
      Generates a topographic-like isoline contour map from the given points. This method uses the Z value of each PVector point as the "elevation" of that location in the map.
      Parameters:
      points - List of PVectors: the z coordinate for each PVector defines the contour height at that location
      intervalValueSpacing - contour height distance represented by successive isolines (e.g. a value of 1 will generate isolines at each 1 unit of height)
      isolineMin - minimum value represented by isolines
      isolineMax - maximum value represented by isolines
      Returns:
      a map of {isoline -> height of the isoline}

    • isolines

      public static Map<processing.core.PShape,Float> isolines(Collection<processing.core.PVector> points, double intervalValueSpacing, double isolineMin, double isolineMax, int smoothing)
      Generates a topographic-like isoline contour map from the given points. This method uses the Z value of each PVector point as the "elevation" of that location in the map.
      Parameters:
      points - List of PVectors: the z coordinate for each PVector defines the contour height at that location
      intervalValueSpacing - contour height distance represented by successive isolines (e.g. a value of 1 will generate isolines at each 1 unit of height)
      isolineMin - minimum value represented by isolines
      isolineMax - maximum value represented by isolines
      smoothing - Number of contour smoothing passes to perform. The best choice for this value depends on the requirements of the application. Values in the range 5 to 40 are good candidates for investigation.
      Returns:
      a map of {isoline (path) -> height of the isoline}

    • isolinesFromFunction

      public static processing.core.PShape isolinesFromFunction(double[] bounds, double sampleSpacing, double contourInterval, DoubleBinaryOperator valueFunction)
      Extracts contour lines (isolines) from a user-defined 2D “height map” over a rectangular region.

      You provide a function f(x,y) that returns a numeric value for every point. This method samples that function on a regular grid over bounds, then traces contour lines that connect points with the same value (like elevation contours on a map) using the Marching Squares algorithm.

      This is a very versatile way to turn simple math functions into computational patterns—ripples, bands, interference fields, cellular textures, etc.—without manually constructing geometry. The contour value range is determined automatically from the sampled minimum/maximum values.

      Parameters:
      bounds - Sampling bounds as [xmin, ymin, xmax, ymax].
      sampleSpacing - Grid spacing in coordinate units (smaller yields finer detail but is slower). 5 is sufficient for very high quality.
      contourInterval - The value step between successive contour lines.
      valueFunction - Function that returns the value at (x,y).
      Returns:
      A map of isoline shapes to their corresponding contour (height) value.
      Since:
      2.2

    • isolinesFromFunction

      public static processing.core.PShape isolinesFromFunction(double[] bounds, double sampleSpacing, double contourInterval, DoubleBinaryOperator valueFunction, double isolineMin, double isolineMax)
      Extracts contour lines (isolines) from a user-defined 2D “height map” over a rectangular region, within a specified value range.

      You provide a function f(x,y) that returns a numeric value for every point. This method samples that function on a regular grid over bounds, then traces contour lines that connect points with the same value (like elevation contours on a map) using the Marching Squares algorithm.

      This is a very versatile way to turn simple math functions into computational patterns. Only contour lines with values in [isolineMin, isolineMax] are produced.

      Parameters:
      bounds - Sampling bounds as [xmin, ymin, xmax, ymax].
      sampleSpacing - Grid spacing in coordinate units (smaller yields finer detail but is slower). 5 is sufficient for very high quality.
      contourInterval - The value step between successive contour lines.
      valueFunction - Function that returns the value at (x,y).
      isolineMin - Minimum contour value (inclusive).
      isolineMax - Maximum contour value (inclusive).
      Returns:
      A map of isoline shapes to their corresponding contour (height) value.
      Since:
      2.2

    • isolineZeroFromFunction

      public static processing.core.PShape isolineZeroFromFunction(double[] bounds, double sampleSpacing, DoubleBinaryOperator valueFunction)
      Extracts the zero contour (the 0-level set) from a user-defined 2D “height map” over a rectangular region.

      You provide a function f(x,y) that returns a numeric value for every point. This method samples that function on a regular grid over bounds, then traces the isoline where f(x,y) = 0 using the Marching Squares algorithm.

      The resulting contour follows the boundary between positive and negative values of f (i.e., where the function crosses zero). This is useful for extracting implicit curves such as circles, signed-distance fields, and other zero-crossing patterns.

      Parameters:
      bounds - Sampling bounds as [xmin, ymin, xmax, ymax].
      sampleSpacing - Grid spacing in coordinate units (smaller yields finer detail but is slower). 5 is sufficient for very high quality.
      valueFunction - Function that returns the value at (x,y).
      Returns:
      A PShape containing all extracted zero-value isoline polylines within bounds.
      Since:
      2.2

    • distanceField

      public static processing.core.PShape distanceField(processing.core.PShape shape, double spacing)
      Generates interior contour lines (isolines) that radiate from a shape “center”.

      The result resembles offset curves (inward parallels), but the underlying metric is not a pure boundary offset. Instead, contours are derived from a distance-like field that balances distance to the boundary with distance to an interior pole (chosen automatically), producing characteristic rings/levels emanating from the shape’s interior.

      Parameters:
      shape - A polygonal PShape to generate contours for.
      spacing - The contour interval between successive lines.
      Returns:
      A GROUP PShape whose children form the contour set inside shape.
      Since:
      1.3.0
      See Also:

    • distanceField

      public static processing.core.PShape distanceField(processing.core.PShape shape, double spacing, processing.core.PVector pole)
      Generates interior contour lines (isolines) that radiate from a specified pole point within a polygon.

      The result is similar in spirit to inward offset curves, but governed by a distance-like field that blends proximity to the boundary with proximity to the given pole. This tends to produce characteristic “rings”/levels centred on pole, clipped to the shape interior.

      Parameters:
      shape - A polygonal PShape to generate contours for.
      spacing - The contour interval between successive lines.
      pole - The point that the contours are oriented around (need not lie inside shape).
      Returns:
      A GROUP PShape whose children form the contour set inside shape.
      Since:
      2.2

    • contrastField

      public static processing.core.PShape contrastField(processing.core.PShape shape, int intervals, processing.core.PVector reference)
      Generates vector contour lines representing a "contrast field" of a shape with respect to a given reference point.

      For each interior point of the shape, this field is defined as the absolute difference between (a) its shortest Euclidean distance to the shape's boundary, and (b) its distance to a specified reference point. Contour lines (isolines) are drawn at regular value intervals, connecting points where this difference is equal. This effectively visualises "ridges" and balance zones between the reference point and the shape boundary.

      Parameters:
      shape - A polygonal shape for which to calculate the distance field contours.
      intervals - The number of successive contour lines.
      reference - The reference point used for distance comparison.
      seed - Random seed for Poisson-disc sampling of interior points.
      Returns:
      A GROUP PShape where each child is a closed contour line or a contour segment, together forming the contrast field visualisation as a vector contour map.
      Since:
      2.1

    • distanceTree

      public static processing.core.PShape distanceTree(processing.core.PShape mesh, processing.core.PVector source, boolean flatten)
      Generates a tree structure representing the shortest paths from a given start point to all other vertices in the provided mesh. The paths are computed using the existing connectivity of the mesh edges, ensuring that the shortest-path tree respects the original mesh structure. The tree is constructed using a Breadth-First Search (BFS) algorithm.

      The shortest-path tree represents the minimal set of mesh edges required to connect the start point to all other vertices in the mesh, following the mesh's inherent connectivity. This ensures that the paths are constrained by the mesh's topology rather than creating arbitrary connections between vertices.

      If the provided start point does not exactly match a vertex in the mesh, the closest vertex in the mesh to the start point is used as the actual starting point for the shortest-path computation.

      Parameters:
      mesh - A GROUP shape representing a mesh from which the graph is constructed. The mesh defines the connectivity between vertices via its edges.
      source - The starting point from which the shortest paths are calculated. If this point does not exactly match a vertex in the mesh, the closest vertex in the mesh will be used as the starting point.
      flatten - Determines the format of the output shortest-path tree.

      If true, the method returns a flattened representation of the shortest-path tree as a single set of edges. This removes duplicate edges and combines all paths into a single structure.

      If false, the method returns a GROUP shape of individual paths, where each path is a separate line from the start point to each vertex in the mesh. This representation retains the structure of the shortest-path tree as a collection of distinct paths.

      Returns:
      A PShape object representing the tree of shortest paths from the start point to all other vertices in the mesh. The paths are constrained by the mesh's edge connectivity.
      Since:
      2.1

    • centerLine

      public static processing.core.PShape centerLine(processing.core.PShape shape)
      Calculates the longest center line passing through a given shape (using default straightness weighting and smoothing parameters).

      The center line is determined based on the medial axis of the shape; it endpoints are always leaf vertices of the medial axis, and the line will pass through the center coordinate of the shape's largest inscribed circle.

      Parameters:
      shape - The non-GROUP PShape representing the input shape for which the longest center line is to be calculated.
      Returns:
      A new PShape representing the smoothed longest center line of the input shape.
      Since:
      1.4.0
      See Also:

    • centerLine

      public static processing.core.PShape centerLine(processing.core.PShape shape, double straightnessWeighting, double smoothing)
      Calculates the longest center line passing through a given shape. Note that shapes with sparse vertices will need densified beforehand.

      The center line is determined based on the medial axis of the shape; it endpoints are always leaf vertices of the medial axis, and the line will pass through the center coordinate of the shape's largest inscribed circle.

      The method can promote paths that are straighter, even if they are somewhat shorter than the longest possible line, by weighting them according to straightnessWeighting.

      This method can be used to find the placement position for overlayed curved text label.

      Parameters:
      shape - The non-GROUP PShape representing the input shape for which the longest center line is to be calculated.
      straightnessWeighting - A value in [0...1] to determine how straighter paths should be weighted (preferred over the longest possible center line). 0 is no additional weighting - the longest path is chosen despite how concave it is - and 1 is maximum weighting. A good starting value to use is ~0.7.
      smoothing - Gaussian smoothing parameter. A good starting value to use is ~50.
      Returns:
      A new PShape representing the smoothed longest center line of the input shape.
      Since:
      1.4.0

    • offsetCurvesInward

      public static processing.core.PShape offsetCurvesInward(processing.core.PShape shape, PGS_Contour.OffsetStyle style, double spacing)
      Generates inward-facing offset curves from a shape. Curves are generated until they collapse.
      Parameters:
      shape - a path, polygon or multipolygon (GROUP) shape
      style - the type of curve join (BEVEL, MITER, or ROUND)
      spacing - the distance between each curve, must be >=1
      Returns:
      a GROUP PShape where each child is a single curve or a group of curves created at the same step

    • offsetCurvesInward

      public static processing.core.PShape offsetCurvesInward(processing.core.PShape shape, PGS_Contour.OffsetStyle style, double spacing, int curves)
      Generates N inward-facing offset curves from a shape.
      Parameters:
      shape - a path, polygon or multipolygon (GROUP) shape
      style - the type of curve join (BEVEL, MITER, or ROUND)
      spacing - the distance between each curve, must be >=1
      curves - the number of curves to generate (including the original shape outline)
      Returns:
      a GROUP PShape where each child is a single curve or a group of curves created at the same step

    • offsetCurvesOutward

      public static processing.core.PShape offsetCurvesOutward(processing.core.PShape shape, PGS_Contour.OffsetStyle style, double spacing, int curves)
      Generates N outward-facing offset curves from a shape.
      Parameters:
      shape - a path, polygon or multipolygon (GROUP) shape
      style - the type of curve join (BEVEL, MITER, or ROUND)
      spacing - the distance between each curve, must be >=1
      curves - the number of curves to generate (including the original shape outline)
      Returns:
      a GROUP PShape where each child is a single curve or a group of curves created at the same step
      See Also: