public final class PGS_Conversion extends Object
PShapes
and
JTS's Geometries
, along with various other formats. It also
offers additional utility methods to assist with handling PShapes
.
Though certain conversion methods are utilised internally by the library, they have been kept public to cater to more complex user requirements.
Note: JTS Geometries
do not provide support for bezier curves. As
such, bezier curves are linearised/divided into straight line segments during
the conversion process from PShape
to JTS Geometry
.
Two configurable boolean flags influence the conversion process:
PRESERVE_STYLE
(set to true by default), and
HANDLE_MULTICONTOUR
(set to false by default). Users are encouraged
to review these flags as part of more complicated workflows with this class.
Modifier and Type | Field and Description |
---|---|
static boolean |
HANDLE_MULTICONTOUR
A boolean flag that, when true, enables a specialised subroutine during the
fromPShape() conversion to correctly convert
single PShapes comprised of multiple contours, each representing a
separate shape. |
static boolean |
PRESERVE_STYLE
A boolean flag that affects whether a PShape's style (fillColor, strokeColor,
strokeWidth) is preserved during
PShape->Geometry->PShape
conversion (i.e. |
Modifier and Type | Method and Description |
---|---|
static processing.core.PShape |
copy(processing.core.PShape shape)
Produces a deep copy / clone of the input shape.
|
static processing.core.PShape |
disableAllFill(processing.core.PShape shape)
Calls setFill(false) on a PShape and all its children.
|
static processing.core.PShape |
disableAllStroke(processing.core.PShape shape)
Calls setStroke(false) on a PShape and all its children.
|
static processing.core.PShape |
flatten(Collection<processing.core.PShape> shapes)
Flattens a collection of PShapes into a single GROUP PShape which has the
input shapes as its children.
|
static processing.core.PShape |
flatten(processing.core.PShape... shapes)
Flattens a collection of PShapes into a single GROUP PShape which has the
input shapes as its children.
|
static processing.core.PShape |
fromArray(double[][] shape,
boolean close)
Creates a PShape from an array of doubles representing coordinates.
|
static processing.core.PShape |
fromChildren(Collection<processing.core.PShape> children)
Creates a single GROUP shape whose children shapes are the list given.
|
static processing.core.PShape |
fromCubicBezier(processing.core.PVector start,
processing.core.PVector controlPoint1,
processing.core.PVector controlPoint2,
processing.core.PVector end)
Creates a PATH PShape representing a cubic bezier curve, given by its
parameters.
|
static processing.core.PShape |
fromEncodedPolyline(String encodedPolyline)
Converts a geometry in Encoded Polyline format into a PShape.
|
static processing.core.PShape |
fromGeoJSON(String json)
Converts a GeoJSON representation of a shape into its PShape counterpart.
|
static processing.core.PShape |
fromGraph(org.jgrapht.graph.SimpleGraph<processing.core.PVector,PEdge> graph)
Converts a given SimpleGraph consisting of PVectors and PEdges into a PShape
by polygonizing its edges.
|
static <V,E> processing.core.PShape |
fromGraph(org.jgrapht.graph.SimpleGraph<V,E> graph,
double normalizationFactor,
double boundsX,
double boundsY)
Takes as input a graph and computes a layout for the graph vertices using a
Force-Directed placement algorithm (not vertex coordinates, if any exist).
|
static processing.core.PShape |
fromHexWKB(String shapeWKB)
Converts a geometry in Well-Known Binary hex format into a PShape.
|
static processing.core.PShape |
fromJava2D(Shape shape)
Converts a Java2D/java.awt Shape to a Processing PShape.
|
static org.locationtech.jts.geom.Geometry |
fromPShape(processing.core.PShape shape)
Transforms a PShape into a corresponding JTS Geometry.
|
static processing.core.PShape |
fromPVector(Collection<processing.core.PVector> vertices)
Generates a shape from a list of vertices.
|
static processing.core.PShape |
fromPVector(List<processing.core.PVector> shell,
List<List<processing.core.PVector>> holes)
Generates a polygonal shape from lists of vertices representing its shell and
holes.
|
static processing.core.PShape |
fromPVector(processing.core.PVector... vertices)
Generates a shape from a list of vertices.
|
static processing.core.PShape |
fromQuadraticBezier(processing.core.PVector start,
processing.core.PVector controlPoint,
processing.core.PVector end)
Creates a PATH PShape representing a quadratic bezier curve, given by its
parameters.
|
static processing.core.PShape |
fromWKB(byte[] shapeWKB)
Converts a geometry in Well-Known Binary format into a PShape.
|
static processing.core.PShape |
fromWKB(String filename)
Reads a shape from a (binary) file containing the Well-Known Binary
representation of it.
|
static processing.core.PShape |
fromWKT(String textRepresentation)
Converts a geometry in Well-Known Text format into a PShape.
|
static List<processing.core.PShape> |
getChildren(processing.core.PShape shape)
Recurses a GROUP PShape, finding all of its non-GROUP child PShapes.
|
static int |
getFillColor(processing.core.PShape shape)
Retrieves the fill color of a PShape.
|
static processing.core.PShape |
reorderChildren(processing.core.PShape shape,
Comparator<processing.core.PShape> comparator)
Reorders the child shapes of a given shape.
|
static processing.core.PShape |
roundVertexCoords(processing.core.PShape shape)
Rounds the x and y coordinates (to the closest int) of all vertices belonging
to the shape, mutating the shape.
|
static processing.core.PShape |
setAllFillColor(processing.core.PShape shape,
int color)
Sets the fill color for the PShape and all of its children recursively (and
disables stroke).
|
static processing.core.PShape |
setAllStrokeColor(processing.core.PShape shape,
int color,
double strokeWeight)
Sets the stroke color for the PShape and all of its children recursively.
|
static processing.core.PShape |
setAllStrokeToFillColor(processing.core.PShape shape)
Sets the stroke color equal to the fill color for the PShape and all of its
descendent shapes individually (that is, each child shape belonging to the
shape (if any) will have its stroke color set to its own fill color,
and not the parent-most shape's fill color).
|
static processing.core.PShape |
setAllStrokeToFillColor(processing.core.PShape shape,
double strokeWeight)
Sets the stroke color equal to the fill color, and the strokeWeight to the
specified value, for the PShape and all of its descendent shapes individually
(that is, each child shape belonging to the shape (if any) will have its
stroke color set to its own fill color, and not the parent-most
shape's fill color).
|
static double[][] |
toArray(processing.core.PShape shape,
boolean keepClosed)
Converts a simple PShape into an array of its coordinates.
|
static org.jgrapht.graph.SimpleGraph<processing.core.PVector,PEdge> |
toCentroidDualGraph(processing.core.PShape mesh)
Converts a mesh-like PShape into its centroid-based undirected dual-graph.
|
static processing.core.PShape |
toCircles(Collection<processing.core.PVector> circles)
Creates a PShape having circle geometries representing a collection of
circles.
|
static org.jgrapht.graph.SimpleGraph<processing.core.PShape,org.jgrapht.graph.DefaultEdge> |
toDualGraph(processing.core.PShape mesh)
Converts a mesh-like PShape into its undirected, unweighted dual-graph.
|
static String |
toEncodedPolyline(processing.core.PShape shape)
Writes a single holeless shape into the string representation of its
Google Encoded Polyline format.
|
static String |
toGeoJSON(processing.core.PShape shape)
Writes a shape into the string representation of its GeoJSON format.
|
static org.jgrapht.graph.SimpleGraph<processing.core.PVector,PEdge> |
toGraph(processing.core.PShape shape)
Transforms a given PShape into a simple graph representation.
|
static String |
toHexWKB(processing.core.PShape shape)
Writes a shape into the hexadecimal string representation of its
Well-Known Binary format.
|
static Shape |
toJava2D(processing.core.PShape shape)
Creates a Java2D/java.awt Shape representing a PShape.
|
static processing.core.PShape |
toPointsPShape(Collection<processing.core.PVector> points)
Transforms a list of points into a POINTS PShape.
|
static processing.core.PShape |
toPointsPShape(processing.core.PVector... vertices)
Transforms a variable arg list of points into a POINTS PShape.
|
static processing.core.PShape |
toPShape(Collection<? extends org.locationtech.jts.geom.Geometry> geometries)
Converts a collection of JTS Geometries into a corresponding GROUP PShape.
|
static processing.core.PShape |
toPShape(org.locationtech.jts.geom.Geometry g)
Converts a JTS Geometry into a corresponding PShape.
|
static List<processing.core.PVector> |
toPVector(processing.core.PShape shape)
Extracts the vertices of a PShape into a list of PVectors.
|
static byte[] |
toWKB(processing.core.PShape shape)
Writes a shape into Well-Known Binary format.
|
static void |
toWKB(processing.core.PShape shape,
String filename)
Converts a shape into Well-Known Binary format and writes the bytes to
a file.
|
static String |
toWKT(processing.core.PShape shape)
Writes the Well-Known Text representation of a shape.
|
public static boolean PRESERVE_STYLE
PShape->Geometry->PShape
conversion (i.e. when toPShape(fromPShape(myPShape))
is called).
Default = true
.public static boolean HANDLE_MULTICONTOUR
fromPShape()
conversion to correctly convert
single PShapes comprised of multiple contours, each representing a
separate shape. If set to false
, the fromPShape()
method assumes that in multi-contour shapes, every contour
beyond the first represents a hole, which is generally an adequate
assumption.
This feature is disabled by default because it necessitates additional
computation, such as determining polygon ring orientations, and is seldom
required (unless one is dealing with fonts, I have observed). Default =
false
.
For more information, refer to the discussion on this topic at GitHub.
public static processing.core.PShape toPShape(org.locationtech.jts.geom.Geometry g)
The conversion process follows the geometry types supported by JTS, namely:
GEOMETRYCOLLECTION
:
Converted to a GROUP PShape if it contains multiple geometries. For single
geometry collections, it extracts and converts the single geometry.MULTIPOLYGON
: Similar to
GeometryCollection, MultiPolygons are converted to a GROUP PShape, with each
polygon converted to a child PShape.MULTILINESTRING
:
MultiLineStrings are handled in the same way as GeometryCollections and
MultiPolygons, converted to a GROUP PShape containing child PShapes.LINEARRING
and
LINESTRING
: These are converted to a
PATH PShape, preserving the closed or open nature of the original
LineString.POLYGON
: Converted to a PATH PShape,
with each contour of the polygon represented as a series of vertices in the
PShape. Inner contours, or 'holes' in the polygon, are handled
separately.POINT
and
MULTIPOINT
: These are converted to a
GEOMETRY PShape with each point represented as a vertex.Please note that any unsupported geometry types will result in an error message.
If PRESERVE_STYLE
is enabled and the geometry includes user data in
the form of PShapeData, the style from the data is applied to the resulting
PShape.
g
- The JTS geometry to convert.public static processing.core.PShape toPShape(Collection<? extends org.locationtech.jts.geom.Geometry> geometries)
In case the collection only contains a single geometry, this method will instead return a PShape that directly corresponds to that single geometry. It will not be wrapped in a GROUP shape in this case.
geometries
- A collection of JTS Geometries to convert into a PShape.public static org.locationtech.jts.geom.Geometry fromPShape(processing.core.PShape shape)
During this transformation, any bezier curve elements within the input PShape are linearised, meaning they are sampled at regular, equidistant intervals. This process results in the created geometry having a greater number of vertices than the original PShape.
Additionally, please be aware that the method does not preserve multi-level child shape hierarchies present in the input PShape. All child shapes are flattened to the same level in the output geometry.
The conversion process depends on the PShape's type and can be broadly categorized as follows:
PConstants.GROUP
: The method recursively converts each child of
the PShape into a corresponding Geometry and groups these into a
GeometryCollection.PShape.GEOMETRY
and PShape.PATH
: Here, the method further
distinguishes between the kinds of the shape. For POLYGON, PATH and
unspecified kinds, it creates a Geometry from the vertices of the PShape. For
special paths (e.g., POINTS, LINES), it uses a separate conversion
routine.PShape.PRIMITIVE
: It converts the PShape using a separate routine
dedicated to primitive shapes.
If PRESERVE_STYLE
is enabled, the method preserves the style of the
PShape in the output Geometry as user data.
Lastly, any affine transformations applied to the PShape (which do not directly affect its vertices) are also applied to the resulting Geometry (baked into its coordinates).
shape
- The PShape to convert into a JTS Geometry.public static final processing.core.PShape toPointsPShape(processing.core.PVector... vertices)
vertices
- public static final processing.core.PShape toPointsPShape(Collection<processing.core.PVector> points)
public static final processing.core.PShape toCircles(Collection<processing.core.PVector> circles)
circles
- The collection of PVector objects representing the circles.
The x and y components represent the center of the circle, and
the z component represents the radius.public static List<processing.core.PVector> toPVector(processing.core.PShape shape)
The function navigates through all children of the given shape if it is of
the GROUP type, recursively flattening their vertices and adding them to the
list. In the case of PShape primitives, where the getVertex()
method fails, the shape is converted to its equivalent path representation
before vertex extraction.
If the input shape represents a closed polygon, the method returns an "unclosed" version of the shape. This means that the duplicate vertex that closes the shape (which is identical to the first vertex) is omitted from the output.
The resulting list contains all vertices from the input PShape in the order they appear in the shape.
shape
- the PShape from which vertices are to be extractedpublic static org.jgrapht.graph.SimpleGraph<processing.core.PVector,PEdge> toGraph(processing.core.PShape shape)
The edge weights in the graph are set to the length of the corresponding edge in the shape.
shape
- the PShape to convert into a graphtoDualGraph(PShape)
public static processing.core.PShape fromGraph(org.jgrapht.graph.SimpleGraph<processing.core.PVector,PEdge> graph)
graph
- the graph to be converted into a PShape.public static <V,E> processing.core.PShape fromGraph(org.jgrapht.graph.SimpleGraph<V,E> graph, double normalizationFactor, double boundsX, double boundsY)
The output is a rather abstract representation of the input graph, and not a geometric equivalent (unlike most other conversion methods in the class).
V
- any vertex typeE
- any edge typegraph
- the graph whose edges and vertices to lay outnormalizationFactor
- normalization factor for the optimal distance,
between 0 and 1.boundsX
- horizontal vertex boundsboundsY
- vertical vertex boundspublic static org.jgrapht.graph.SimpleGraph<processing.core.PShape,org.jgrapht.graph.DefaultEdge> toDualGraph(processing.core.PShape mesh)
The output is a dual graph of the input; it has a vertex for each face (PShape) of the input, and an edge for each pair of faces that are adjacent.
mesh
- a GROUP PShape, whose children constitute the polygonal faces of
a conforming mesh. A conforming mesh consists of adjacent
cells that not only share edges, but every pair of shared edges
are identical (having the same coordinates) (such as a
triangulation).toGraph(PShape)
public static org.jgrapht.graph.SimpleGraph<processing.core.PVector,PEdge> toCentroidDualGraph(processing.core.PShape mesh)
The output is a dual graph of the input; it has a vertex for each centroid of the face of the input, and an edge (connecting the centroids) for each pair of faces that are adjacent. Each vertex represents the geometric center or centroid of the respective face in the mesh.
mesh
- a GROUP PShape, whose children constitute the polygonal faces of
a conforming mesh. A conforming mesh consists of adjacent
cells that not only share edges, but every pair of shared edges
are identical (having the same coordinates) (such as a
triangulation).toDualGraph(PShape)
,
PGS_ShapePredicates.centroid(PShape)
public static String toWKT(processing.core.PShape shape)
shape
- shape to processfromWKT(String)
public static processing.core.PShape fromWKT(String textRepresentation)
textRepresentation
- one or more Geometry Tagged Text strings, separated
by whitespacetoWKT(PShape)
public static byte[] toWKB(processing.core.PShape shape)
shape
- shape to processfromWKB(byte[])
,
toHexWKB(PShape)
public static void toWKB(processing.core.PShape shape, String filename)
shape
- shape to processfilename
- Absolute file path (with filename and extension). Prefix with
"./" for a relative path.public static processing.core.PShape fromWKB(byte[] shapeWKB)
shapeWKB
- byte representation of shape to processtoWKB(PShape)
public static processing.core.PShape fromWKB(String filename)
filename
- Absolute file path (with filename and extension). Prefix with
"./" for a relative path.public static String toHexWKB(processing.core.PShape shape)
shape
- shape to processtoWKB(PShape)
public static processing.core.PShape fromHexWKB(String shapeWKB)
shapeWKB
- hex string WKB representation of shape to processtoWKB(PShape)
public static String toEncodedPolyline(processing.core.PShape shape)
shape
- single (holeless) polygon or linepublic static processing.core.PShape fromEncodedPolyline(String encodedPolyline)
encodedPolyline
- an encoded polyline string representing a shapepublic static String toGeoJSON(processing.core.PShape shape)
shape
- public static processing.core.PShape fromGeoJSON(String json)
json
- GeoJSON stringpublic static Shape toJava2D(processing.core.PShape shape)
shape
- the PShape to convertpublic static processing.core.PShape fromJava2D(Shape shape)
If the shape contains bezier components (such as CubicCurve2D
,
these are decomposed into straight-line segments in the output.
shape
- the Java2D shape to convertpublic static processing.core.PShape fromPVector(Collection<processing.core.PVector> vertices)
vertices
- list of (un)closed shape verticesfromPVector(PVector...)
public static processing.core.PShape fromPVector(processing.core.PVector... vertices)
vertices
- list of (un)closed shape vertices#fromPVector(List)
public static processing.core.PShape fromPVector(List<processing.core.PVector> shell, @Nullable List<List<processing.core.PVector>> holes)
In theory, the shell should be orientated CW and the holes CCW, but this method will detect orientation and handle it accordingly, so the orientation of input does not matter.
shell
- vertices of the shell of the polygonholes
- (optional) list of holespublic static double[][] toArray(processing.core.PShape shape, boolean keepClosed)
shape
- a simple shape (closed polygon or open line) represented by
a coordinate array [[x1, y1], [x2, y2]...]keepClosed
- flag to determine whether to keep the (last) closing vertex
in the output if the input forms a closed polygon#fromArray(double[][])
public static processing.core.PShape fromArray(double[][] shape, boolean close)
shape
- coordinate array representing a simple shape (closed polygon or
open line) [[x1, y1], [x2, y2]...]close
- close the coordinates (if unclosed)#toArray(PShape)
public static processing.core.PShape flatten(Collection<processing.core.PShape> shapes)
flatten(PShape...)
public static processing.core.PShape flatten(processing.core.PShape... shapes)
flatten(Collection)
public static List<processing.core.PShape> getChildren(processing.core.PShape shape)
Note: this method differs from PShape.getChildren()
. That method will return GROUP child shapes, whereas
this method will recurse such shapes, returing their non-group children (in
other words, this method explores the whole tree of shapes, returning
non-group shapes only).
shape
- public static processing.core.PShape fromChildren(Collection<processing.core.PShape> children)
children
- public static int getFillColor(processing.core.PShape shape)
shape
- The PShape object for which to retrieve the fill color.public static processing.core.PShape setAllFillColor(processing.core.PShape shape, int color)
shape
- #setAllStrokeColor(PShape, int, float)
public static processing.core.PShape setAllStrokeColor(processing.core.PShape shape, int color, double strokeWeight)
shape
- #setAllFillColor(PShape, int)}
public static processing.core.PShape setAllStrokeToFillColor(processing.core.PShape shape)
shape
- public static processing.core.PShape setAllStrokeToFillColor(processing.core.PShape shape, double strokeWeight)
shape
- public static processing.core.PShape reorderChildren(processing.core.PShape shape, Comparator<processing.core.PShape> comparator)
Creates a new GROUP shape, having the same children as the input, but in a different order; child shapes of the new shape are ordered according to the given comparator.
shape
- a GROUP shapecomparator
- PShape comparison functionpublic static processing.core.PShape disableAllFill(processing.core.PShape shape)
shape
- public static processing.core.PShape disableAllStroke(processing.core.PShape shape)
shape
- public static processing.core.PShape roundVertexCoords(processing.core.PShape shape)
public static processing.core.PShape copy(processing.core.PShape shape)
shape
- the PShape to copypublic static processing.core.PShape fromQuadraticBezier(processing.core.PVector start, processing.core.PVector controlPoint, processing.core.PVector end)
start
- controlPoint
- end
- public static processing.core.PShape fromCubicBezier(processing.core.PVector start, processing.core.PVector controlPoint1, processing.core.PVector controlPoint2, processing.core.PVector end)
start
- controlPoint1
- controlPoint2
- end
- Copyright © 2023. All rights reserved.