Added cameramap convenience function

Can now automatically compose together camera coordinates and image
coordinate transformations (from origin, focal length, etc).

Author: Andy Ferris

src/CoordinateTransformations.jl

@@ -28,7 +28,7 @@ export SphericalFromCartesian, CartesianFromSpherical,
 # Common transformations
 export AbstractAffineMap
 export AffineMap, LinearMap, Translation
-export PerspectiveMap
+export PerspectiveMap, cameramap
 
 include("core.jl")
 include("coordinatesystems.jl")

src/affine.jl

@@ -8,7 +8,7 @@ abstract AbstractAffineMap <: Transformation
 Construct the `Translation` transformation for translating Cartesian points by
 an offset `v = (dx, dy, ...)`
 """
-immutable Translation{V <: AbstractVector} <: AbstractAffineMap
+immutable Translation{V} <: AbstractAffineMap
     v::V
 end
 Translation(x::Tuple) = Translation(SVector(x))
@@ -39,9 +39,9 @@ end
     LinearMap(M)
 
 A general linear transformation, constructed using `LinearMap(M)`
-for any `AbstractMatrix` `M`.
+for any matrix-like object `M`.
 """
-immutable LinearMap{M <: AbstractMatrix} <: AbstractAffineMap
+immutable LinearMap{M} <: AbstractAffineMap
     m::M
 end
 Base.show(io::IO, trans::LinearMap)   = print(io, "LinearMap($(trans.m))") # TODO make this output more petite
@@ -95,7 +95,7 @@ converted into an affine approximation by linearizing about a point `x` using
 
 For transformations which are already affine, `x` may be omitted.
 """
-immutable AffineMap{M <: AbstractMatrix, V <: AbstractVector} <: AbstractAffineMap
+immutable AffineMap{M, V} <: AbstractAffineMap
     m::M
     v::V
 end

src/core.jl

@@ -37,6 +37,15 @@ Base.show(io::IO, trans::ComposedTransformation) = print(io, "($(trans.t1) ∘ $
     trans.t1(trans.t2(x))
 end
 
+function Base.:(==)(trans1::ComposedTransformation, trans2::ComposedTransformation)
+    (trans1.t1 == trans2.t1) && (trans1.t2 == trans2.t2)
+end
+
+function Base.isapprox(trans1::ComposedTransformation, trans2::ComposedTransformation; kwargs...)
+    isapprox(trans1.t1, trans2.t1; kwargs...) && isapprox(trans1.t2, trans2.t2; kwargs...)
+end
+
+
 """
     compose(trans1, trans2)
     trans1 ∘ trans2

src/perspective.jl

@@ -4,14 +4,19 @@
 Construct a perspective transformation. The persepective 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).
+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`)
 """
 immutable PerspectiveMap <: Transformation
 end
@@ -24,3 +29,67 @@ end
 @inline function (::PerspectiveMap)(v::StaticVector)
     return pop(v) * inv(v[end])
 end
+
+Base.@pure Base.isapprox(::PerspectiveMap, ::PerspectiveMap; kwargs...) = true
+
+"""
+    cameramap(property = value, ...)
+
+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.
+
+All properties are optional. Valid properties include:
+
+ * `focal_length` (in physical units)
+ * `pixel_size` (in physical units) or `pixel_size_x` and `pixel_size_y`
+ * `offset_x` and `offset_y` (in pixels)
+ * `origin` (a vector) and `orientation` (a rotation matrix)
+
+By default, the camera looks towards the postive-`z` axis from `(0,0,0)` 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 therefor inverted - it
+is up to the user to cull these as necessary).
+
+If `origin` and `orientation` are specified, the camera is translated to `origin`
+and rotated by `orientation` before the perspective map is applied.
+
+(see also `PerspectiveMap`)
+"""
+function cameramap(;focal_length = nothing,
+                    pixel_size = nothing,
+                    pixel_size_x = nothing,
+                    pixel_size_y = nothing,
+                    offset_x = nothing,
+                    offset_y = nothing,
+                    origin = nothing,
+                    orientation = nothing)
+
+    trans = PerspectiveMap()
+
+    if pixel_size === nothing # (this form of if-else-end is handled well by the compiler... the author is looking forward to v0.6 where !(::Bool) is pure...)
+    else
+        pixel_size_x = pixel_size
+        pixel_size_y = pixel_size
+    end
+
+    # Apply camera rotations, if necessary
+    if origin === nothing && orientation === nothing
+    else
+        trans = trans ∘ inv(AffineMap(orientation, origin))
+    end
+
+    # Apply camera scaling, if necessary
+    if isa(focal_length, Void) && isa(pixel_size_x, Void) && isa(pixel_size_y, Void)
+    else
+        trans = LinearMap(UniformScaling(focal_length/pixel_size)) ∘ trans
+    end
+
+    # Apply pixel offset, if necessary
+    if isa(offset_x, Void) && isa(offset_y, Void)
+    else
+        trans = Translation(SVector(-offset_x, -offset_y)) ∘ trans
+    end
+
+    return trans
+end

test/runtests.jl

@@ -3,10 +3,14 @@ using Base.Test
 using ForwardDiff: Dual, partials
 using StaticArrays
 
+# See https://github.com/JuliaLang/julia/issues/18858
+Base.isapprox(a::UniformScaling, b::UniformScaling; kwargs...) = isapprox(a.λ, b.λ; kwargs...)
+
 @testset "CoordinateTransformations" begin
 
     include("core.jl")
     include("coordinatesystems.jl")
     include("affine.jl")
+    include("perspective.jl")
 
 end