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.

A 2D contour is a closed sequence (a cycle) of 3 or more connected 2D oriented straight line segments called contour edges. The endpoints of the contour edges are called vertices. Each contour edge shares its endpoints with at least two other contour edges.

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
    distanceField(processing.core.PShape shape, double spacing)
    Generates a contour map based on a distance field of a shape.
    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 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.
    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 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.

      Parameters:
      shape - a single polygon (that can contain holes), or a multi polygon (whose polygons can contain holes)
      Returns:
      when the input is a single polygon, returns a GROUP PShape containing 3 children: child 1 = GROUP PShape of skeleton faces; child 2 = LINES PShape of branches (lines that connect skeleton to edge); child 3 = LINES PShape of bones (the pure straight skeleton). For multi-polygons, a master GROUP shape of skeleton GROUP shapes (described above) is returned.

    • 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. The "elevation" (or z value) of points is the euclidean distance between a point in the shape and the given "high" point.

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

      Parameters:
      shape -
      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, 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 a contour map based on a distance field of a shape.

      A distance field maps each point within the shape to the shortest distance between that point and the shape boundary.

      Parameters:
      shape - polygonal shape
      spacing - distance represented by successive contour lines
      Returns:
      GROUP shape, where each child is a closed contour line or contour line partition
      Since:
      1.3.0

    • 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: