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 and Description
static class	PGS_Contour.OffsetStyle Specifies the join style for offset curves.

Method Summary

Modifier and Type	Method and 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 Detail

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:

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(PShape, double, double)

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

See Also:

#offsetCurvesOutward(PShape, OffsetStyle, double, int) offsetCurvesOutward()} for outward-facing curves.

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

See Also:

#offsetCurvesOutward(PShape, OffsetStyle, double, int) offsetCurvesOutward()} for outward-facing curves.

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:

offsetCurvesInward(PShape, OffsetStyle, double)