org.locationtech.jts.geom.util

Represents an affine transformation on the 2D Cartesian plane. It can be used to transform a {link Coordinate} or {link Geometry}. An affine transformation is a mapping of the 2D plane into itself via a series of transformations of the following basic types:

• reflection (through a line)

• rotation (around the origin)

• scaling (relative to the origin)

• shearing (in both the X and Y directions)

• translation

In general, affine transformations preserve straightness and parallel lines, but do not preserve distance or shape.

An affine transformation can be represented by a 3x3 matrix in the following form:

<blockquote> <pre> T = | m00 m01 m02 | | m10 m11 m12 | | 0 0 1 | </pre> </blockquote> A coordinate P = (x, y) can be transformed to a new coordinate P' = (x', y') by representing it as a 3x1 matrix and using matrix multiplication to compute: <blockquote> <pre> | x' | = T x | x | | y' | | y | | 1 | | 1 | </pre> </blockquote>

=== Transformation Composition ===

Affine transformations can be composed using the {link #compose} method. Composition is computed via multiplication of the transformation matrices, and is defined as:

<blockquote> <pre> A.compose(B) = T_B x T_A </pre> </blockquote> This produces a transformation whose effect is that of A followed by B. The methods {link #reflect}, {link #rotate}, {link #scale}, {link #shear}, and {link #translate} have the effect of composing a transformation of that type with the transformation they are invoked on.

The composition of transformations is in general <i>not</i> commutative.

=== Transformation Inversion ===

Affine transformations may be invertible or non-invertible. If a transformation is invertible, then there exists an inverse transformation which when composed produces the identity transformation. The {link #getInverse} method computes the inverse of a transformation, if one exists.

Builds an {link AffineTransformation} defined by a set of control vectors. A control vector consists of a source point and a destination point, which is the image of the source point under the desired transformation.

A transformation is well-defined by a set of three control vectors if and only if the source points are not collinear. (In particular, the degenerate situation where two or more source points are identical will not produce a well-defined transformation). A well-defined transformation exists and is unique. If the control vectors are not well-defined, the system of equations defining the transformation matrix entries is not solvable, and no transformation can be determined.

No such restriction applies to the destination points. However, if the destination points are collinear or non-unique, a non-invertible transformations will be generated.

This technique of recovering a transformation from its effect on known points is used in the Bilinear Interpolated Triangulation algorithm for warping planar surfaces.

Supports creating {link AffineTransformation}s defined by various kinds of inputs and transformation mapping rules.

Extracts a representative {link Coordinate} from each connected component of a {link Geometry}.

Maps the members of a {link GeometryCollection} into another <tt>GeometryCollection</tt> via a defined mapping function.

Combines {link Geometry}s to produce a {link GeometryCollection} of the most appropriate type. Input geometries which are already collections will have their elements extracted first. No validation of the result geometry is performed. (The only case where invalidity is possible is where {link Polygonal} geometries are combined and result in a self-intersection).

A class which supports creating new {link Geometry}s which are modifications of existing ones, maintaining the same type structure. Geometry objects are intended to be treated as immutable. This class "modifies" Geometrys by traversing them, applying a user-defined {link GeometryEditorOperation}, {link CoordinateSequenceOperation} or {link CoordinateOperation} and creating new Geometrys with the same structure but (possibly) modified components.

Examples of the kinds of modifications which can be made are:

• the values of the coordinates may be changed. The editor does not check whether changing coordinate values makes the result Geometry invalid

• the coordinate lists may be changed (e.g. by adding, deleting or modifying coordinates). The modified coordinate lists must be consistent with their original parent component (e.g. a <tt>LinearRing</tt> must always have at least 4 coordinates, and the first and last coordinate must be equal)

• components of the original geometry may be deleted (e.g. holes may be removed from a Polygon, or LineStrings removed from a MultiLineString). Deletions will be propagated up the component tree appropriately.

All changes must be consistent with the original Geometry's structure (e.g. a <tt>Polygon</tt> cannot be collapsed into a <tt>LineString</tt>). If changing the structure is required, use a {link GeometryTransformer}.

This class supports creating an edited Geometry using a different <code>GeometryFactory</code> via the {link #GeometryEditor(GeometryFactory)} constructor. Examples of situations where this is required is if the geometry is transformed to a new SRID and/or a new PrecisionModel.

<b>Usage Notes</b>

• The resulting Geometry is not checked for validity. If validity needs to be enforced, the new Geometry's {link Geometry#isValid} method should be called.

• By default the UserData of the input geometry is not copied to the result.

Extracts the components of a given type from a {link Geometry}.

Methods to map various collections of {link Geometry}s via defined mapping functions.

A framework for processes which transform an input {link Geometry} into an output {link Geometry}, possibly changing its structure and type(s). This class is a framework for implementing subclasses which perform transformations on various different Geometry subclasses. It provides an easy way of applying specific transformations to given geometry types, while allowing unhandled types to be simply copied. Also, the framework ensures that if subcomponents change type the parent geometries types change appropriately to maintain valid structure. Subclasses will override whichever <code>transformX</code> methods they need to to handle particular Geometry types.

A typically usage would be a transformation class that transforms <tt>Polygons</tt> into <tt>Polygons</tt>, <tt>LineStrings</tt> or <tt>Points</tt>, depending on the geometry of the input (For instance, a simplification operation). This class would likely need to override the {link #transformMultiPolygon(MultiPolygon, Geometry)} method to ensure that if input Polygons change type the result is a <tt>GeometryCollection</tt>, not a <tt>MultiPolygon</tt>.

The default behaviour of this class is simply to recursively transform each Geometry component into an identical object by deep copying down to the level of, but not including, coordinates.

All <code>transformX</code> methods may return <code>null</code>, to avoid creating empty or invalid geometry objects. This will be handled correctly by the transformer. <code>transform<i>XXX</i></code> methods should always return valid geometry - if they cannot do this they should return <code>null</code> (for instance, it may not be possible for a transformLineString implementation to return at least two points - in this case, it should return <code>null</code>). The {link #transform(Geometry)} method itself will always return a non-null Geometry object (but this may be empty).

Extracts all the {link LineString} elements from a {link Geometry}.

Extracts all the 1-dimensional ({link LineString}) components from a {link Geometry}. For polygonal geometries, this will extract all the component {link LinearRing}s. If desired, <code>LinearRing</code>s can be forced to be returned as <code>LineString</code>s.

Indicates that an {link AffineTransformation} is non-invertible.

Extracts all the 0-dimensional ({link Point}) components from a {link Geometry}.

Extracts all the {link Polygon} elements from a {link Geometry}.

A visitor to {link Geometry} components, which allows short-circuiting when a defined condition holds.

Creates geometries which are shaped like multi-armed stars with each arm shaped like a sine wave. These kinds of geometries are useful as a more complex geometry for testing algorithms.