Merge pull request #20 from FugroRoames/perspective

The perspective transformation

Author: c42f

README.md

@@ -170,3 +170,27 @@ defined by a composition of a translation and a linear transformation. An
 (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`).
+
+#### 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.

src/CoordinateTransformations.jl

@@ -28,10 +28,12 @@ export SphericalFromCartesian, CartesianFromSpherical,
 # Common transformations
 export AbstractAffineMap
 export AffineMap, LinearMap, Translation
+export PerspectiveMap, cameramap
 
 include("core.jl")
 include("coordinatesystems.jl")
 include("affine.jl")
+include("perspective.jl")
 
 # Deprecations
 export transform

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

@@ -0,0 +1,69 @@
+"""
+    PerspectiveMap()
+
+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) 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
+
+function (::PerspectiveMap)(v::AbstractVector)
+    scale =  1/v[end]
+    return [v[i] * scale for i in 1:length(v)-1]
+end
+
+@inline function (::PerspectiveMap)(v::StaticVector)
+    return pop(v) * inv(v[end])
+end
+
+Base.isapprox(::PerspectiveMap, ::PerspectiveMap; kwargs...) = true
+
+"""
+    cameramap()
+    cameramap(scale)
+    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`)
+"""
+cameramap() = PerspectiveMap()
+cameramap(scale::Number) =
+    LinearMap(UniformScaling(scale)) ∘ PerspectiveMap()
+cameramap(scale::Tuple{Number, Number}) =
+    LinearMap(@SMatrix([scale[1] 0; 0 scale[2]])) ∘ PerspectiveMap()
+cameramap(scale::Number, offset::Tuple{Number,Number}) =
+    AffineMap(UniformScaling(scale), SVector(-offset[1], -offset[2])) ∘ PerspectiveMap()
+cameramap(scale::Tuple{Number, Number}, offset::Tuple{Number,Number}) =
+    AffineMap(@SMatrix([scale[1] 0; 0 scale[2]]), SVector(-offset[1], -offset[2])) ∘ PerspectiveMap()
+

test/perspective.jl

@@ -0,0 +1,8 @@
+@testset "Perspective transformation" begin
+    @test PerspectiveMap()([2.0, -1.0, 0.5]) ≈ [4.0, -2.0]
+
+    @test cameramap(2.0)                  ≈ LinearMap(UniformScaling(2.0)) ∘ PerspectiveMap()
+    @test cameramap((1.1,2.2))            ≈ LinearMap([1.1 0; 0 2.2]) ∘ PerspectiveMap()
+    @test cameramap(1.1,       (3.3,4.4)) ≈ Translation([-3.3,-4.4]) ∘ LinearMap(UniformScaling(1.1)) ∘ PerspectiveMap()
+    @test cameramap((1.1,2.2), (3.3,4.4)) ≈ Translation([-3.3,-4.4]) ∘ LinearMap([1.1 0; 0 2.2]) ∘ PerspectiveMap()
+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