Package micycle.pgs

Class PGS_Contour

java.lang.Object
micycle.pgs.PGS_Contour

public final class PGS_Contour extends Object
Methods for producing different kinds of shape contours. *

Contours produced by this class are always computed within the interior of shapes. Contour lines and features (such as isolines, medial axes, and fields) are extracted as vector linework following the topology or scalar properties of the enclosed shape area, rather than operations that modify the shape boundary.

Author:
Michael Carleton
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    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 vector contour lines representing a distance field derived from a shape.
    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
    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.
    static processing.core.PShape
    straightSkeleton(processing.core.PShape shape, int k)
    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 trianglution 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.
    • straightSkeleton

      public static processing.core.PShape straightSkeleton(processing.core.PShape shape, int k)
      Computes the straight skeleton for a shape. This method signature accepts an integer to control the number of nearest neighboring edges considered during collision detection. In practice this can speed up computation considerably.

      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)
      k - The number of nearest neighboring edges to consider when searching for collisions using the spatial index. This parameter balances performance and correctness: too few neighbors may miss collisions, while too many may reduce the performance benefits of the spatial index.
      Returns:
      PShape based on the input polygon structure, either as a single or multi-polygon skeleton representation.
      Since:
      2.1
    • 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 -> height of the isoline}
    • distanceField

      public static processing.core.PShape distanceField(processing.core.PShape shape, double spacing)
      Generates vector contour lines representing a distance field derived from a shape.

      The distance field for a shape assigns each interior point a value equal to the shortest Euclidean distance from that point to the shape boundary. This method computes a series of contour lines (isolines), where each line connects points with the same distance value, effectively visualizing the "levels" of the distance field like elevation contours on a topographic map.

      Parameters:
      shape - A polygonal shape for which to calculate the distance field contours.
      spacing - The interval between successive contour lines, i.e., the distance value difference between each contour.
      Returns:
      A GROUP PShape. Each child of the group is a closed contour line or a section (partition) of a contour line, collectively forming the contour map.
      Since:
      1.3.0
    • 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: