From 15270616ed51d416fc801d598edb5357a5e40b63 Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:17:30 -0400
Subject: [PATCH 01/11] Add docstring for AbstractAffineMap

---
 src/affine.jl | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/affine.jl b/src/affine.jl
index 7ef6227..dbf4e54 100644
--- a/src/affine.jl
+++ b/src/affine.jl
@@ -1,3 +1,9 @@
+"""
+    abstract type AbstractAffineMap <: Transformation
+
+`AbstractAffineMap` is the supertype of all affine transformations,
+including linear transformations.
+"""
 abstract type AbstractAffineMap <: Transformation end
 
 """

From 2d66c0928b12b3d0c0281667bcac5a1baf55cb1d Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:19:42 -0400
Subject: [PATCH 02/11] Add type headers to type docstrings

---
 src/core.jl | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/core.jl b/src/core.jl
index 4ab3bf9..eb25a9b 100644
--- a/src/core.jl
+++ b/src/core.jl
@@ -6,6 +6,8 @@
 # transform_deriv() and transform_deriv_params()
 
 """
+    abstract type Transformation
+
 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
@@ -15,6 +17,8 @@ Efficient compositions can optionally be defined by `compose()` (equivalently `
 abstract type Transformation end
 
 """
+    IdentityTransformation <: Transformation
+
 The `IdentityTransformation` is a singleton `Transformation` that returns the
 input unchanged, similar to `identity`.
 """
@@ -23,8 +27,10 @@ struct IdentityTransformation <: Transformation; end
 @inline (::IdentityTransformation)(x) = x
 
 """
-A `ComposedTransformation` simply executes two transformations successively, and
-is the fallback output type of `compose()`.
+    ComposedTransformation{T1, T2} <: Transformation
+
+A `ComposedTransformation` simply executes two transformations `T2` and `T1`
+successively, and is the fallback output type of `compose()`.
 """
 struct ComposedTransformation{T1 <: Transformation, T2 <: Transformation} <: Transformation
     t1::T1

From 65ed727a4490a2908cac5af0029df6fbf914923e Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:21:01 -0400
Subject: [PATCH 03/11] Add setup code for doctests

---
 docs/make.jl     |  9 ++++++++-
 test/runtests.jl | 13 ++++++++++---
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/docs/make.jl b/docs/make.jl
index 5758a5a..046da1e 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,5 +1,12 @@
-using Documenter
 using CoordinateTransformations
+using Documenter
+
+DocMeta.setdocmeta!(
+    CoordinateTransformations,
+    :DocTestSetup,
+    :(using CoordinateTransformations),
+    recursive = true,
+)
 
 makedocs(
     sitename = "CoordinateTransformations.jl",
diff --git a/test/runtests.jl b/test/runtests.jl
index ef0e081..916a93d 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -4,15 +4,22 @@ using CoordinateTransformations
 using ForwardDiff: Dual, partials
 using StaticArrays
 using Unitful
-using Documenter: doctest
+using Documenter
 using Aqua
 
 @testset "CoordinateTransformations" begin
-
-    doctest(CoordinateTransformations, manual=false)
     include("core.jl")
     include("coordinatesystems.jl")
     include("affine.jl")
     include("perspective.jl")
+
     Aqua.test_all(CoordinateTransformations)
+
+    DocMeta.setdocmeta!(
+        CoordinateTransformations,
+        :DocTestSetup,
+        :(using CoordinateTransformations),
+        recursive=true,
+    )
+    doctest(CoordinateTransformations, manual=true)
 end

From 7c6ca1bf2ef4a1c1d128a3e8bfd02839615c98e8 Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:21:08 -0400
Subject: [PATCH 04/11] Move hash sign

---
 test/coordinatesystems.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/coordinatesystems.jl b/test/coordinatesystems.jl
index 5ffa94a..fe9ee7e 100644
--- a/test/coordinatesystems.jl
+++ b/test/coordinatesystems.jl
@@ -473,7 +473,7 @@
                      partials(rθϕ_gn.θ, 1) partials(rθϕ_gn.θ, 2) partials(rθϕ_gn.θ, 3);
                      partials(rθϕ_gn.ϕ, 1) partials(rθϕ_gn.ϕ, 2) partials(rθϕ_gn.ϕ, 3) ]
         m = transform_deriv(s_from_cyl, rθz)
-#        @test isapprox(m, m_gn; atol = 1e-12)
+        #@test isapprox(m, m_gn; atol = 1e-12)
         @test m ≈ m_gn
 
         @testset "Common types" begin

From 7aab011f48e9b3c1c5bab7d1df83dcf6082b7281 Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:21:53 -0400
Subject: [PATCH 05/11] Factor out doctest setup code

---
 src/coordinatesystems.jl | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/coordinatesystems.jl b/src/coordinatesystems.jl
index c4ee472..3f19c26 100644
--- a/src/coordinatesystems.jl
+++ b/src/coordinatesystems.jl
@@ -104,8 +104,6 @@ orthogonal projection of `v` on the `xy` plane.
 * `ϕ` is the latitude. It is the angle from `v_xy` to `v`.
 
 ```jldoctest
-julia> using CoordinateTransformations
-
 julia> v = randn(3);
 
 julia> sph = SphericalFromCartesian()(v);

From 362168bc9a5814b94e0996dd97972d5122b4c77b Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:23:06 -0400
Subject: [PATCH 06/11] Line wrapping

---
 src/affine.jl            |  2 +-
 src/coordinatesystems.jl | 24 ++++++++++++++++--------
 src/core.jl              |  9 ++++++---
 3 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/src/affine.jl b/src/affine.jl
index dbf4e54..abfd8c3 100644
--- a/src/affine.jl
+++ b/src/affine.jl
@@ -120,7 +120,7 @@ end
 """
     AffineMap(trans::Transformation, x0)
 
-Create an Affine transformation corresponding to the differential transformation
+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`.
 """
diff --git a/src/coordinatesystems.jl b/src/coordinatesystems.jl
index 3f19c26..d07a086 100644
--- a/src/coordinatesystems.jl
+++ b/src/coordinatesystems.jl
@@ -129,7 +129,8 @@ function Spherical(r, θ, ϕ)
 end
 
 Base.show(io::IO, x::Spherical) = print(io, "Spherical(r=$(x.r), θ=$(x.θ) rad, ϕ=$(x.ϕ) rad)")
-Base.isapprox(p1::Spherical, p2::Spherical; kwargs...) = isapprox(p1.r, p2.r; kwargs...) && isapprox(p1.θ, p2.θ; kwargs...) && isapprox(p1.ϕ, p2.ϕ; kwargs...)
+Base.isapprox(p1::Spherical, p2::Spherical; kwargs...) =
+    isapprox(p1.r, p2.r; kwargs...) && isapprox(p1.θ, p2.θ; kwargs...) && isapprox(p1.ϕ, p2.ϕ; kwargs...)
 
 """
     Cylindrical(r, θ, z)
@@ -151,7 +152,8 @@ function Cylindrical(r, θ, z)
 end
 
 Base.show(io::IO, x::Cylindrical) = print(io, "Cylindrical(r=$(x.r), θ=$(x.θ) rad, z=$(x.z))")
-Base.isapprox(p1::Cylindrical, p2::Cylindrical; kwargs...) = isapprox(p1.r, p2.r; kwargs...) && isapprox(p1.θ, p2.θ; kwargs...) && isapprox(p1.z, p2.z; kwargs...)
+Base.isapprox(p1::Cylindrical, p2::Cylindrical; kwargs...) =
+    isapprox(p1.r, p2.r; kwargs...) && isapprox(p1.θ, p2.θ; kwargs...) && isapprox(p1.z, p2.z; kwargs...)
 
 """
     SphericalFromCartesian()
@@ -217,7 +219,8 @@ function transform_deriv(::SphericalFromCartesian, x::AbstractVector)
           -fxy*cxy  cxy     zero(T);
            f*x[1]   f*x[2]  rxy/(r*r) ]
 end
-transform_deriv_params(::SphericalFromCartesian, x::AbstractVector) = error("SphericalFromCartesian has no parameters")
+transform_deriv_params(::SphericalFromCartesian, x::AbstractVector) =
+    error("SphericalFromCartesian has no parameters")
 
 function (::CartesianFromSpherical)(x::Spherical)
     sθ, cθ = sincos(x.θ)
@@ -231,7 +234,8 @@ function transform_deriv(::CartesianFromSpherical, x::Spherical{T}) where T
               sθ*cϕ  x.r*cθ*cϕ -x.r*sθ*sϕ ;
               sϕ     zero(T)    x.r * cϕ  ]
 end
-transform_deriv_params(::CartesianFromSpherical, x::Spherical) = error("CartesianFromSpherical has no parameters")
+transform_deriv_params(::CartesianFromSpherical, x::Spherical) =
+    error("CartesianFromSpherical has no parameters")
 
 # Cartesian <-> Cylindrical
 function (::CylindricalFromCartesian)(x::AbstractVector)
@@ -251,7 +255,8 @@ function transform_deriv(::CylindricalFromCartesian, x::AbstractVector)
               -f*c      c        zero(T) ;
                zero(T)  zero(T)  one(T)  ]
 end
-transform_deriv_params(::CylindricalFromCartesian, x::AbstractVector) = error("CylindricalFromCartesian has no parameters")
+transform_deriv_params(::CylindricalFromCartesian, x::AbstractVector) =
+    error("CylindricalFromCartesian has no parameters")
 
 function (::CartesianFromCylindrical)(x::Cylindrical)
     sθ, cθ = sincos(x.θ)
@@ -263,7 +268,8 @@ function transform_deriv(::CartesianFromCylindrical, x::Cylindrical{T}) where {T
               sθ       x.r*cθ  zero(T) ;
               zero(T)  zero(T) one(T)  ]
 end
-transform_deriv_params(::CartesianFromPolar, x::Cylindrical) = error("CartesianFromCylindrical has no parameters")
+transform_deriv_params(::CartesianFromPolar, x::Cylindrical) =
+    error("CartesianFromCylindrical has no parameters")
 
 function (::CylindricalFromSpherical)(x::Spherical)
     sϕ, cϕ = sincos(x.ϕ)
@@ -274,7 +280,8 @@ function transform_deriv(::CylindricalFromSpherical, x::Spherical)
     M2 = transform_deriv(CartesianFromSpherical(), x)
     return M1*M2
 end
-transform_deriv_params(::CylindricalFromSpherical, x::Spherical) = error("CylindricalFromSpherical has no parameters")
+transform_deriv_params(::CylindricalFromSpherical, x::Spherical) =
+    error("CylindricalFromSpherical has no parameters")
 
 function (::SphericalFromCylindrical)(x::Cylindrical)
     Spherical(hypot(x.r,x.z),x.θ,atan(x.z,x.r))
@@ -284,7 +291,8 @@ function transform_deriv(::SphericalFromCylindrical, x::Cylindrical)
     M2 = transform_deriv(CartesianFromCylindrical(), x)
     return M1*M2
 end
-transform_deriv_params(::SphericalFromCylindrical, x::Cylindrical) = error("SphericalFromCylindrical has no parameters")
+transform_deriv_params(::SphericalFromCylindrical, x::Cylindrical) =
+    error("SphericalFromCylindrical has no parameters")
 
 Base.inv(::SphericalFromCartesian)   = CartesianFromSpherical()
 Base.inv(::CartesianFromSpherical)   = SphericalFromCartesian()
diff --git a/src/core.jl b/src/core.jl
index eb25a9b..1307005 100644
--- a/src/core.jl
+++ b/src/core.jl
@@ -112,7 +112,8 @@ recenter(trans::Transformation, origin::Tuple) = recenter(trans, SVector(origin)
 A matrix describing how differentials on the parameters of `x` flow through to
 the output of transformation `trans`.
 """
-transform_deriv(trans::Transformation, x) = error("Differential matrix of transform $trans with input $x not defined")
+transform_deriv(trans::Transformation, x) =
+    error("Differential matrix of transform $trans with input $x not defined")
 
 transform_deriv(::IdentityTransformation, x) = I
 
@@ -130,9 +131,11 @@ end
 A matrix describing how differentials on the parameters of `trans` flow through
 to the output of transformation `trans` given input `x`.
 """
-transform_deriv_params(trans::Transformation, x) = error("Differential matrix of parameters of transform $trans with input $x not defined")
+transform_deriv_params(trans::Transformation, x) =
+    error("Differential matrix of parameters of transform $trans with input $x not defined")
 
-transform_deriv_params(::IdentityTransformation, x) = error("IdentityTransformation has no parameters")
+transform_deriv_params(::IdentityTransformation, x) =
+    error("IdentityTransformation has no parameters")
 
 function transform_deriv_params(trans::ComposedTransformation, x)
     x2 = trans.t2(x)

From 78ef98857e3acd460629f5cc94029e0c0e30773c Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:26:06 -0400
Subject: [PATCH 07/11] Add more params to makedocs

---
 docs/make.jl | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/make.jl b/docs/make.jl
index 046da1e..b3281f9 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,5 +1,6 @@
 using CoordinateTransformations
 using Documenter
+using Documenter.Remotes: GitHub
 
 DocMeta.setdocmeta!(
     CoordinateTransformations,
@@ -10,6 +11,8 @@ DocMeta.setdocmeta!(
 
 makedocs(
     sitename = "CoordinateTransformations.jl",
+    modules = [CoordinateTransformations],
+    repo = GitHub("JuliaGeometry/CoordinateTransformations.jl"),
     pages = [
         "Introduction" => "index.md",
         "API" => "api.md",

From 2294ce47a2b7270bb3b878db43fb5ec2eb215cc4 Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:26:24 -0400
Subject: [PATCH 08/11] Manually categorize API reference page

---
 docs/src/api.md | 48 ++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 4 deletions(-)

diff --git a/docs/src/api.md b/docs/src/api.md
index f79f5b5..04bc27d 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -1,7 +1,47 @@
-# CoordinateTransformations.jl documentation
+# API Reference
 
-## API Reference
+## Transformations
+```@docs
+Transformation
+CoordinateTransformations.ComposedTransformation
+IdentityTransformation
+PerspectiveMap
+inv
+cameramap
+compose
+recenter
+transform_deriv
+transform_deriv_params
+```
+
+## Affine maps
+```@docs
+AbstractAffineMap
+AffineMap
+AffineMap(::Transformation, ::Any)
+AffineMap(::Pair)
+LinearMap
+Translation
+```
+
+## 2D Coordinates
+```@docs
+Polar
+PolarFromCartesian
+CartesianFromPolar
+```
+
+## 3D Coordinates
+```@docs
+Cylindrical
+Spherical
+```
 
-```@autodocs
-Modules = [CoordinateTransformations]
+```@docs
+CartesianFromCylindrical
+CartesianFromSpherical
+CylindricalFromCartesian
+CylindricalFromSpherical
+SphericalFromCartesian
+SphericalFromCylindrical
 ```

From eadcb8cdb4a2382e08956e1b23ace80a0bd9c61d Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:26:51 -0400
Subject: [PATCH 09/11] Pull in docs index.md from README.md

---
 docs/src/index.md | 220 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 219 insertions(+), 1 deletion(-)

diff --git a/docs/src/index.md b/docs/src/index.md
index 76f001c..ea8cd05 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1 +1,219 @@
-# CoordinateTransformations.jl
+```@meta
+DocTestSetup = quote
+    using CoordinateTransformations
+end
+```
+# CoordinateTransformations
+
+[![Build Status](https://github.com/JuliaGeometry/CoordinateTransformations.jl/workflows/CI/badge.svg)](https://github.com/JuliaGeometry/CoordinateTransformations.jl/actions?query=workflow%3ACI)
+
+**CoordinateTransformations** is a Julia package to manage simple or complex
+networks of coordinate system transformations. Transformations can be easily
+applied, inverted, composed, and differentiated (both with respect to the
+input coordinates and with respect to transformation parameters such as rotation
+angle). Transformations are designed to be light-weight and efficient enough
+for, e.g., real-time graphical applications, while support for both explicit
+and automatic differentiation makes it easy to perform optimization and
+therefore ideal for computer vision applications such as SLAM (simultaneous
+localization and mapping).
+
+The package provide two main pieces of functionality
+
+1. Primarily, an interface for defining `Transformation`s and applying
+   (by calling), inverting (`inv()`), composing (`∘` or `compose()`) and
+   differentiating (`transform_deriv()` and `transform_deriv_params()`) them.
+
+2. A small set of built-in, composable, primitive transformations for
+   transforming 2D and 3D points (optionally leveraging the *StaticArrays*
+   and *Rotations* packages).
+
+## Quick start
+
+Let's translate a 3D point:
+```julia
+using CoordinateTransformations, Rotations, StaticArrays
+
+x = SVector(1.0, 2.0, 3.0)  # SVector is provided by StaticArrays.jl
+trans = Translation(3.5, 1.5, 0.0)
+
+y = trans(x)
+```
+
+We can either apply different transformations in turn,
+```julia
+rot = LinearMap(RotX(0.3))  # Rotate 0.3 radians about X-axis, from Rotations.jl
+
+z = trans(rot(x))
+```
+or build a composed transformation using the `∘` operator (accessible at the
+REPL by typing `\circ` then tab):
+```julia
+composed = trans ∘ rot  # alternatively, use compose(trans, rot)
+
+composed(x) == z
+```
+A composition of a `Translation` and a `LinearMap` results in an `AffineMap`.
+
+We can invert the transformation:
+```julia
+composed_inv = inv(composed)
+
+composed_inv(z) == x
+```
+
+For any transformation, we can shift the origin to a new point using `recenter`:
+```julia
+rot_around_x = recenter(rot, x)
+```
+Now `rot_around_x` is a rotation around the point `x = SVector(1.0, 2.0, 3.0)`.
+
+
+Finally, we can construct a matrix describing how the components of `z`
+differentiates with respect to components of `x`:
+```julia
+# In general, the transform may be non-linear, and thus we require
+# the value of x to compute the derivative
+∂z_∂x = transform_deriv(composed, x)
+```
+
+Or perhaps we want to know how `y` will change with respect to changes of
+to the translation parameters:
+```julia
+∂y_∂θ = transform_deriv_params(trans, x)
+```
+
+## Interface
+
+Transformations are derived from `Transformation`. As an example, we have
+`Translation{T} <: Transformation`. A `Translation` will accept and translate
+points in a variety of formats, such as `Vector` or `SVector`, but in general
+your custom-defined `Transformation`s could transform any Julia object.
+
+Transformations can be reversed using `inv(trans)`. They can be chained
+together using the `∘` operator (`trans1 ∘ trans2`) or `compose` function (`compose(trans1, trans2)`).
+In this case, `trans2` is applied first to the data, before `trans1`.
+Composition may be intelligent, for instance by precomputing a new `Translation`
+by summing the elements of two existing `Translation`s, and yet other
+transformations may compose to the `IdentityTransformation`. But by default,
+composition will result in a `ComposedTransformation` object which simply
+dispatches to apply the transformations in the correct order.
+
+Finally, the matrix describing how differentials propagate through a transform
+can be calculated with the `transform_deriv(trans, x)` method. The derivatives
+of how the output depends on the transformation parameters is accessed via
+`transform_deriv_params(trans, x)`. Users currently have to overload these methods,
+as no fall-back automatic differentiation is currently included. Alternatively,
+all the built-in types and transformations are compatible with automatic differentiation
+techniques, and can be parameterized by *DualNumbers*' `DualNumber` or *ForwardDiff*'s `Dual`.
+
+## Built-in transformations
+
+A small number of 2D and 3D coordinate systems and transformations are included.
+We also have `IdentityTransformation` and `ComposedTransformation`, which allows us
+to nest together arbitrary transformations to create a complex yet efficient
+transformation chain.
+
+### Coordinate types
+
+The package accepts any `AbstractVector` type for Cartesian coordinates. For speed, we recommend
+using a statically-sized container such as `SVector{N}` from *StaticArrays*.
+
+We do provide a few specialist coordinate types. The `Polar(r, θ)` type is a 2D
+polar representation of a point, and similarly in 3D we have defined
+`Spherical(r, θ, ϕ)` and `Cylindrical(r, θ, z)`.
+
+### Coordinate system transformations
+
+Two-dimensional coordinates may be converted using these parameterless (singleton)
+transformations:
+
+1. [`PolarFromCartesian()`](@ref)
+2. [`CartesianFromPolar()`](@ref)
+
+Three-dimensional coordinates may be converted using these parameterless
+transformations:
+
+1. [`SphericalFromCartesian()`](@ref)
+2. [`CartesianFromSpherical()`](@ref)
+3. [`SphericalFromCylindrical()`](@ref)
+4. [`CylindricalFromSpherical()`](@ref)
+5. [`CartesianFromCylindrical()`](@ref)
+6. [`CylindricalFromCartesian()`](@ref)
+
+However, you may find it simpler to use the convenience constructors like
+`Polar(SVector(1.0, 2.0))`.
+
+### Translations
+
+Translations can be be applied to Cartesian coordinates in arbitrary dimensions,
+by e.g. `Translation(Δx, Δy)` or `Translation(Δx, Δy, Δz)` in 2D/3D, or by
+`Translation(Δv)` in general (with `Δv` an `AbstractVector`). Compositions of
+two `Translation`s will intelligently create a new `Translation` by adding the
+translation vectors.
+
+### Linear transformations
+
+Linear transformations (a.k.a. linear maps), including rotations, can be
+encapsulated in the `LinearMap` type, which is a simple wrapper of an
+`AbstractMatrix`.
+
+You are able to provide any matrix of your choosing, but your choice of type
+will have a large effect on speed. For instance, if you know the dimensionality
+of your points (e.g. 2D or 3D) you might consider a statically sized matrix
+like `SMatrix` from *StaticArrays.jl*. We recommend performing 3D rotations
+using those from *Rotations.jl* for their speed and flexibility. Scaling will
+be efficient with Julia's built-in `UniformScaling`. Also note that compositions
+of two `LinearMap`s will intelligently create a new `LinearMap` by multiplying
+the transformation matrices.
+
+### Affine maps
+
+An Affine map encapsulates a more general set of transformation which are
+defined by a composition of a translation and a linear transformation. An
+`AffineMap` is constructed from an `AbstractVector` translation `v` and an
+`AbstractMatrix` linear transformation `M`. It will perform the mapping
+`x -> M*x + v`, but the order of addition and multiplication will be more obvious
+(and controllable) if you construct it from a composition of a linear map
+and a translation, e.g. `Translation(v) ∘ LinearMap(v)` (or any combination of
+`LinearMap`, `Translation` and `AffineMap`).
+
+`AffineMap`s can be constructed to fit point pairs `from_points => to_points`:
+
+```jldoctest
+julia> from_points = [[0, 0], [1, 0], [0, 1]];
+
+julia> to_points   = [[1, 1], [3, 1], [1.5, 3]];
+
+julia> AffineMap(from_points => to_points)
+AffineMap([1.9999999999999996 0.5; -5.551115123125783e-16 2.0], [0.9999999999999999, 1.0000000000000002])
+```
+
+The points can be supplied as a collection of vectors or as a matrix with points as columns.
+
+### Perspective transformations
+
+The perspective transformation maps real-space coordinates to those on a virtual
+"screen" of one lesser dimension. For instance, this process is used to render
+3D scenes to 2D images in computer generated graphics and games. It is an ideal
+model of how a pinhole camera operates and is a good approximation of the modern
+photography process.
+
+The `PerspectiveMap()` command creates a `Transformation` to perform the
+projective mapping. It can be applied individually, but is particularly
+powerful when composed with an `AffineMap` containing the position and
+orientation of the camera in your scene. For example, to transfer `points` in 3D
+space to 2D `screen_points` giving their projected locations on a virtual camera
+image, you might use the following code:
+
+```julia
+cam_transform = PerspectiveMap() ∘ inv(AffineMap(cam_rotation, cam_position))
+screen_points = map(cam_transform, points)
+```
+
+There is also a `cameramap()` convenience function that can create a composed
+transformation that includes the intrinsic scaling (e.g. focal length and pixel
+size) and offset (defining which pixel is labeled `(0,0)`) of an imaging system.
+
+## Acknowledgements
+
+- The [Fugro Roames organization](https://github.com/FugroRoames)

From 97c5448c2675eec804362cbb24e84c9ce0ff40c9 Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:27:19 -0400
Subject: [PATCH 10/11] Enable documenter deploy on CI

---
 .github/workflows/ci.yml | 35 +++++++++++++++++------------------
 1 file changed, 17 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 89694ca..24c08fc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,21 +33,20 @@ jobs:
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-# Enable the below for Documenter build
-#  docs:
-#    name: Documentation
-#    runs-on: ubuntu-latest
-#    steps:
-#      - uses: actions/checkout@v1
-#      - uses: julia-actions/setup-julia@latest
-#        with:
-#          version: '1.3'
-#      - run: julia --project=docs -e '
-#          using Pkg;
-#          Pkg.develop(PackageSpec(; path=pwd()));
-#          Pkg.instantiate();'
-#      - run: julia --project=docs docs/make.jl
-#        env:
-#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#          # Needed due to https://github.com/JuliaDocs/Documenter.jl/issues/1177
-#          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v1
+      - name: Install dependencies
+        run: julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate();'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Needed due to https://github.com/JuliaDocs/Documenter.jl/issues/1177
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia --project=docs docs/make.jl

From 73f365c9d1c76a6e2654aabdc0b041d680829576 Mon Sep 17 00:00:00 2001
From: Abhro R <5664668+abhro@users.noreply.github.com>
Date: Sat, 15 Jun 2024 16:27:32 -0400
Subject: [PATCH 11/11] Call deploydocs in docs/make.jl

---
 docs/make.jl | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/make.jl b/docs/make.jl
index b3281f9..856cdff 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -18,3 +18,7 @@ makedocs(
         "API" => "api.md",
     ],
 )
+
+deploydocs(
+    repo = "github.com/JuliaGeometry/CoordinateTransformations.jl.git"
+)