micycle.pgs

Class PGS_Transformation

java.lang.Object

micycle.pgs.PGS_Transformation

public final class PGS_Transformation
extends Object

Various geometric and affine transformations for PShapes that affect vertex coordinates.

Notably, these transformation methods affect the vertex coordinates of PShapes, unlike Processing's transform methods that affect the affine matrix of shapes only (and thereby leave vertex coordinates in-tact).

Author:

Michael Carleton

Method Summary

Modifier and Type	Method and Description
static processing.core.PShape	align(processing.core.PShape sourceShape, processing.core.PShape transformShape) Aligns one polygon shape to another, using Procrustes analysis to find the optimal transformation.
static processing.core.PShape	align(processing.core.PShape alignShape, processing.core.PShape baseShape, double alignmentRatio) Aligns one polygon shape to another, using Procrustes analysis to find the optimal transformation.
static processing.core.PShape	flipHorizontal(processing.core.PShape shape) Flips the shape horizontally based on its centre point.
static processing.core.PShape	flipHorizontal(processing.core.PShape shape, double y) Flips the shape horizontally based on a line given by its Y location.
static processing.core.PShape	flipVertical(processing.core.PShape shape) Flips the shape vertically based on its centre point.
static processing.core.PShape	flipVertical(processing.core.PShape shape, double x) Flips the shape vertically based on a line given by its X location.
static processing.core.PShape	homotheticTransformation(processing.core.PShape shape, processing.core.PVector center, double scaleX, double scaleY) Calculates a Homothetic Transformation of a shape.
static processing.core.PShape	originScale(processing.core.PShape shape, double scale) Scales a shape relative to the origin (0,0).
static processing.core.PShape	resize(processing.core.PShape shape, double targetWidth, double targetHeight) Resizes a shape (based on its envelope) to the given dimensions, relative to its center point.
static processing.core.PShape	resizeByHeight(processing.core.PShape shape, double targetHeight) Resizes a shape (based on its envelope) to the given height relative to its center point; the width is resized accordingly to maintain the shape's aspect ratio.
static processing.core.PShape	resizeByMajorAxis(processing.core.PShape shape, double targetSize) Resizes a shape (based on the longest axis of its envelope) to the given size relative to its center point.
static processing.core.PShape	resizeByWidth(processing.core.PShape shape, double targetWidth) Resizes a shape (based on its envelope) to the given width relative to its center point; the height is resized accordingly to maintain the shape's aspect ratio.
static processing.core.PShape	rotate(processing.core.PShape shape, processing.core.PVector point, double angle) Rotates a shape around a given point.
static processing.core.PShape	rotateAroundCenter(processing.core.PShape shape, double angle) Rotates a shape around its centroid.
static processing.core.PShape	scale(processing.core.PShape shape, double scale) Scales the dimensions of the shape by a scaling factor relative to its center point.
static processing.core.PShape	scale(processing.core.PShape shape, double scaleX, double scaleY) Scales the shape relative to its center point.
static processing.core.PShape	scaleArea(processing.core.PShape shape, double scale) Scales the area of a given shape by a specified scale factor.
static processing.core.PShape	scaleAreaTo(processing.core.PShape shape, double targetArea) Scales the given PShape to the target area, relative to its center point.
static processing.core.PShape	shear(processing.core.PShape shape, double angleX, double angleY) Shears a given shape by specified angles along the x and y axis and returns the result as a new PShape.
static processing.core.PShape	touchScale(processing.core.PShape shape, processing.core.PShape boundary, double tolerance) Scales a shape (based on its centroid) so that it touches the boundary of another shape.
static processing.core.PShape	translate(processing.core.PShape shape, double x, double y) Translates a shape by the given coordinates.
static processing.core.PShape	translateCentroidTo(processing.core.PShape shape, double x, double y) Translates a shape such that its centroid aligns with the specified (x, y) coordinates.
static processing.core.PShape	translateCornerTo(processing.core.PShape shape, double x, double y) Translates the given shape such that the upper-left corner of its bounding box aligns with the specified (x, y) coordinates.
static processing.core.PShape	translateEnvelopeTo(processing.core.PShape shape, double x, double y) Translates a shape such that the centroid of its bounding box is equivalent to the given coordinates.
static processing.core.PShape	translateTo(processing.core.PShape shape, double x, double y) Deprecated. Use translateCentroidTo() instead.
static processing.core.PShape	translateToOrigin(processing.core.PShape shape) Translates the given shape such that the upper-left corner of its bounding box aligns with the origin point (0, 0) of the Processing coordinate system.

Methods inherited from class java.lang.Object

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

Method Detail

scale

public static processing.core.PShape scale(processing.core.PShape shape,
                                           double scale)

Scales the dimensions of the shape by a scaling factor relative to its center point.

Parameters:

shape -

scale - X and Y axis scale factor

Returns:

scale

public static processing.core.PShape scale(processing.core.PShape shape,
                                           double scaleX,
                                           double scaleY)

Scales the shape relative to its center point.

Parameters:

shape -

scaleX - X-axis scale factor

scaleY - Y-axis scale factor

Returns:

originScale

public static processing.core.PShape originScale(processing.core.PShape shape,
                                                 double scale)

Scales a shape relative to the origin (0,0).

Parameters:

shape -

scale - scale factor

Returns:

Since:

1.3.0

scaleArea

public static processing.core.PShape scaleArea(processing.core.PShape shape,
                                               double scale)

Scales the area of a given shape by a specified scale factor. The shape is scaled relative to its center point.

Parameters:

shape - The PShape to be scaled.

scale - The scale factor by which the area of the shape should be scaled.

Returns:

A new PShape representing the scaled shape.

Since:

1.4.0

scaleAreaTo

public static processing.core.PShape scaleAreaTo(processing.core.PShape shape,
                                                 double targetArea)

Scales the given PShape to the target area, relative to its center point.

Parameters:

shape - The PShape to be scaled.

targetArea - The target area for the shape.

Returns:

The scaled PShape (now having an area of targetArea).

Since:

1.4.0

resize

public static processing.core.PShape resize(processing.core.PShape shape,
                                            double targetWidth,
                                            double targetHeight)

Resizes a shape (based on its envelope) to the given dimensions, relative to its center point.

Parameters:

shape -

targetWidth - width of the output copy

targetHeight - height of the output copy

Returns:

resized copy of input shape

resizeByWidth

public static processing.core.PShape resizeByWidth(processing.core.PShape shape,
                                                   double targetWidth)

Resizes a shape (based on its envelope) to the given width relative to its center point; the height is resized accordingly to maintain the shape's aspect ratio.

Parameters:

shape - the shape to resize

targetWidth - width of the output

Returns:

resized copy of input shape

Since:

1.3.0

See Also:

resizeByHeight(PShape, double), #resizeByLargest(PShape, double)

resizeByHeight

public static processing.core.PShape resizeByHeight(processing.core.PShape shape,
                                                    double targetHeight)

Resizes a shape (based on its envelope) to the given height relative to its center point; the width is resized accordingly to maintain the shape's aspect ratio.

Parameters:

shape - the shape to resize

targetHeight - height of the output

Returns:

resized copy of input shape

Since:

1.3.0 resized copy of input shape

See Also:

resizeByWidth(PShape, double), #resizeByLargest(PShape, double)

resizeByMajorAxis

public static processing.core.PShape resizeByMajorAxis(processing.core.PShape shape,
                                                       double targetSize)

Resizes a shape (based on the longest axis of its envelope) to the given size relative to its center point.

For example, if the shape's width is larger than its height, the width is set to targetSize and the height is resized to maintain the shape's aspect ratio.

Parameters:

shape - the shape to resize

targetLargest - the new length of its longest axis

Returns:

resized copy of input shape

Since:

1.3.0

See Also:

resizeByWidth(PShape, double), resizeByHeight(PShape, double)

touchScale

public static processing.core.PShape touchScale(processing.core.PShape shape,
                                                processing.core.PShape boundary,
                                                double tolerance)

Scales a shape (based on its centroid) so that it touches the boundary of another shape. The scaling shape's centroid must lie outside the other shape.

Parameters:

shape - the shape to scale. its centroid should be outside container

boundary -

tolerance - >=0

translate

public static processing.core.PShape translate(processing.core.PShape shape,
                                               double x,
                                               double y)

Translates a shape by the given coordinates.

Parameters:

shape - shape to translate

x - the value to translate by in the x direction

y - the value to translate by in the y direction

Returns:

translated copy of input

translateTo

public static processing.core.PShape translateTo(processing.core.PShape shape,
                                                 double x,
                                                 double y)

Deprecated. Use translateCentroidTo() instead.

Translates a shape such that its centroid is equivalent to the given coordinates.

Parameters:

shape - shape to translate

x - target centroid X

y - target centroid Y

Returns:

translated shape

translateCentroidTo

public static processing.core.PShape translateCentroidTo(processing.core.PShape shape,
                                                         double x,
                                                         double y)

Translates a shape such that its centroid aligns with the specified (x, y) coordinates. The centroid of a polygon is its "center of mass" or geometric center.

Parameters:

shape - The PShape instance to be translated.

x - The horizontal coordinate to which the centroid of the shape's bounding polygon should be aligned. Measured in pixels from the left of the container.

y - The vertical coordinate to which the centroid of the shape's bounding polygon should be aligned. Measured in pixels from the top of the container.

Returns:

A new PShape instance that is a translation of the input shape such that the centroid of its bounding polygon aligns with the specified coordinates.

Since:

1.3.0 (superceeds translateTo()

translateEnvelopeTo

public static processing.core.PShape translateEnvelopeTo(processing.core.PShape shape,
                                                         double x,
                                                         double y)

Translates a shape such that the centroid of its bounding box is equivalent to the given coordinates. This method differs a little from translateTo() because that uses center of shape's "mass", whereas this is visual center (however both are usually similar, if not identical).

Parameters:

shape - shape to translate

x - the x-coordinate of new position of the shape's bounding box centroid point

y - the y-coordinate of new position of the shape's bounding box centroid point

Returns:

translated shape

Since:

1.3.0

translateCornerTo

public static processing.core.PShape translateCornerTo(processing.core.PShape shape,
                                                       double x,
                                                       double y)

Translates the given shape such that the upper-left corner of its bounding box aligns with the specified (x, y) coordinates.

Parameters:

shape - The PShape instance to be translated.

x - The horizontal coordinate to which the upper-left corner of the shape's bounding box is to be aligned. Measured in pixels from the left of the container.

y - The vertical coordinate to which the upper-left corner of the shape's bounding box is to be aligned. Measured in pixels from the top of the container.

Returns:

A new PShape instance that is a translation of the input shape such that the upper-left corner of its bounding box aligns with the specified coordinates.

Since:

1.3.0

translateToOrigin

public static processing.core.PShape translateToOrigin(processing.core.PShape shape)

Translates the given shape such that the upper-left corner of its bounding box aligns with the origin point (0, 0) of the Processing coordinate system.

Parameters:

shape - The PShape instance to be translated.

Returns:

A new PShape instance that is a translation of the input shape such that the upper-left corner of its bounding box aligns with the origin point (0, 0).

homotheticTransformation

public static processing.core.PShape homotheticTransformation(processing.core.PShape shape,
                                                              processing.core.PVector center,
                                                              double scaleX,
                                                              double scaleY)

Calculates a Homothetic Transformation of a shape.

A Homothetic Transformation is a special geometric transformation that enlarges or shrinks geometries by a scale factor that is the same in all directions according to a centric point.

Parameters:

shape - shape input

center - coordinate of the center/origin position of the operation

scaleX - X scale factor

scaleY - Y scale factor

align

public static processing.core.PShape align(processing.core.PShape sourceShape,
                                           processing.core.PShape transformShape)

Aligns one polygon shape to another, using Procrustes analysis to find the optimal transformation. The transformation includes translation, rotation and scaling to maximize overlap between the two shapes.

Parameters:

alignShape - the polygon shape to be transformed and aligned to the other shape.

baseShape - the shape that the other shape will be aligned to.

Returns:

a new PShape that is the transformed and aligned version of sourceShape.

Since:

1.4.0

align

public static processing.core.PShape align(processing.core.PShape alignShape,
                                           processing.core.PShape baseShape,
                                           double alignmentRatio)

Aligns one polygon shape to another, using Procrustes analysis to find the optimal transformation. The transformation includes translation, rotation and scaling to maximize overlap between the two shapes.

This method signature aligns the shape according to a provided ratio, indicating how much alignment transformation to apply.

Parameters:

alignShape - the polygon shape to be transformed and aligned to the other shape.

baseShape - the shape that the other shape will be aligned to.

alignmentRatio - a value in [0,1] indicating how much to transform the shape from its original position to its most aligned position. 0 means no transformation, 1 means maximum alignment.

Returns:

a new PShape that is the transformed and aligned version of sourceShape.

Since:

1.4.0

rotate

public static processing.core.PShape rotate(processing.core.PShape shape,
                                            processing.core.PVector point,
                                            double angle)

Rotates a shape around a given point.

Parameters:

shape - the shape to tranform/rotate

point - rotation point

angle - the rotation angle, in radians

Returns:

See Also:

rotateAroundCenter(PShape, double)

rotateAroundCenter

public static processing.core.PShape rotateAroundCenter(processing.core.PShape shape,
                                                        double angle)

Rotates a shape around its centroid.

Parameters:

shape -

angle - the rotation angle, in radians

Returns:

See Also:

rotate(PShape, PVector, double)

flipHorizontal

public static processing.core.PShape flipHorizontal(processing.core.PShape shape)

Flips the shape horizontally based on its centre point.

Parameters:

shape -

Returns:

flipHorizontal

public static processing.core.PShape flipHorizontal(processing.core.PShape shape,
                                                    double y)

Flips the shape horizontally based on a line given by its Y location.

Parameters:

shape -

y - y-coordinate of horizontal reflection line

Returns:

flipVertical

public static processing.core.PShape flipVertical(processing.core.PShape shape)

Flips the shape vertically based on its centre point.

Parameters:

shape -

Returns:

flipVertical

public static processing.core.PShape flipVertical(processing.core.PShape shape,
                                                  double x)

Flips the shape vertically based on a line given by its X location.

Parameters:

shape -

x - x-coordinate of vertical reflection line

Returns:

shear

public static processing.core.PShape shear(processing.core.PShape shape,
                                           double angleX,
                                           double angleY)

Shears a given shape by specified angles along the x and y axis and returns the result as a new PShape. Shapes are sheared around their relative position to the origin.

Parameters:

shape - The shape to be sheared.

angleX - The angle by which the shape should be sheared along the x-axis, in radians.

angleY - The angle by which the shape should be sheared along the y-axis, in radians.

Returns:

A new shape representing the sheared shape.