AffineMap <: AbstractAffineMap

A concrete affine transformation. To construct the mapping x -> M*x + v, use

AffineMap(M, v)

where M is a matrix and v a vector. An arbitrary Transformation may be converted into an affine approximation by linearizing about a point x using

AffineMap(trans, [x])

For transformations which are already affine, x may be omitted.

AffineMap(from_points => to_points) → trans

Create an Affine transformation that approximately maps the from points to the to points. At least n+1 non-degenerate points are required to map an n-dimensional space. If there are more points than this, the transformation will be over-determined and a least-squares solution will be computed.

AffineMap(trans::Transformation, x0)

Create an Affine transformation corresponding to the differential transformation of x0 + dx according to trans, i.e. the Affine transformation that is locally most accurate in the vicinity of x0.

LinearMap <: AbstractAffineMap

A general linear transformation, constructed using LinearMap(M) for any matrix-like object M.


Construct a perspective transformation. The perspective transformation takes, e.g., a point in 3D space and "projects" it onto a 2D virtual screen of an ideal pinhole camera (at distance 1 away from the camera). The camera is oriented towards the positive-Z axis (or in general, along the final dimension) and the sign of the x and y components is preserved for objects in front of the camera (objects behind the camera are also projected and therefore inverted - it is up to the user to cull these as necessary).

This transformation is designed to be used in composition with other coordinate transformations, defining e.g. the position and orientation of the camera. For example:

cam_transform = PerspectiveMap() ∘ inv(AffineMap(cam_rotation, cam_position))
screen_points = map(cam_transform, points)

(see also cameramap)


Spherical(r, θ, ϕ) - 3D spherical coordinates

There are many Spherical coordinate conventions and this library uses a somewhat exotic one. Given a vector v with Cartesian coordinates xyz, let v_xy = [x,y,0] be the orthogonal projection of v on the xy plane.

  • r is the radius. It is given by norm(v, 2).
  • θ is the azimuth. It is the angle from the x-axis to v_xy
  • ϕ is the latitude. It is the angle from v_xy to v.

```jldoctest julia> using CoordinateTransformations

julia> v = randn(3);

julia> sph = SphericalFromCartesian()(v);

julia> r = sph.r; θ=sph.θ; ϕ=sph.ϕ;

julia> v ≈ [r * cos(θ) * cos(ϕ), r * sin(θ) * cos(ϕ), r*sin(ϕ)] true


The Transformation supertype defines a simple interface for performing transformations. Subtypes should be able to apply a coordinate system transformation on the correct data types by overloading the call method, and usually would have the corresponding inverse transformation defined by Base.inv(). Efficient compositions can optionally be defined by compose() (equivalently ).

Translation(v) <: AbstractAffineMap
Translation(dx, dy)       (2D)
Translation(dx, dy, dz)   (3D)

Construct the Translation transformation for translating Cartesian points by an offset v = (dx, dy, ...)


Returns the inverse (or reverse) of the transformation trans

cameramap(scale, offset)

Create a transformation that takes points in real space (e.g. 3D) and projects them through a perspective transformation onto the focal plane of an ideal (pinhole) camera with the given properties.

The scale sets the scale of the screen. For a standard digital camera, this would be scale = focal_length / pixel_size. Non-square pixels are supported by providing a pair of scales in a tuple, scale = (scale_x, scale_y). Positive scales represent a camera looking in the +z axis with a virtual screen in front of the camera (the x,y coordinates are not inverted compared to 3D space). Note that points behind the camera (with negative z component) will be projected (and inverted) onto the image coordinates and it is up to the user to cull such points as necessary.

The offset = (offset_x, offset_y) is used to define the origin in the imaging plane. For instance, you may wish to have the point (0,0) represent the top-left corner of your imaging sensor. This measurement is in the units after applying scale (e.g. pixels).

(see also PerspectiveMap)

compose(trans1, trans2)
trans1 ∘ trans2

Take two transformations and create a new transformation that is equivalent to successively applying trans2 to the coordinate, and then trans1. By default will create a ComposedTransformation, however this method can be overloaded for efficiency (e.g. two affine transformations naturally compose to a single affine transformation).

recenter(trans::Union{AbstractMatrix,Transformation}, origin::Union{AbstractVector, Tuple}) -> ctrans

Return a new transformation ctrans such that point origin serves as the origin-of-coordinates for trans. Translation by ±origin occurs both before and after applying trans, so that if trans is linear we have

ctrans(origin) == origin

As a consequence, recenter only makes sense if the output space of trans is isomorphic with the input space.

For example, if trans is a rotation matrix, then ctrans rotates space around origin.

transform_deriv(trans::Transformation, x)

A matrix describing how differentials on the parameters of x flow through to the output of transformation trans.