From a8a8235b0119cb694ef93e1ab83d884f54b72e37 Mon Sep 17 00:00:00 2001
From: Tim Holy <tim.holy@gmail.com>
Date: Tue, 11 Apr 2017 11:00:16 -0500
Subject: [PATCH] Add docstring for `warp`

---
 src/warp.jl | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/src/warp.jl b/src/warp.jl
index 5aad88a7..47319941 100644
--- a/src/warp.jl
+++ b/src/warp.jl
@@ -26,6 +26,67 @@ end
 
 warp{T}(img::AbstractInterpolation{T}, tform, fill=_default_fill(T)) = warp(extrapolate(img, fill), tform)
 
+"""
+    warp(img, tform) -> imgw
+
+Transform the coordinates of `img`, returning a new `imgw` satisfying
+`imgw[x] = img[tform(x)]`. `tform` should be defined using
+CoordinateTransformations.jl.
+
+# Interpolation scheme
+
+At off-grid points, `imgw` is calculated by interpolation. The default
+is linear interpolation, used when `img` is a plain array, and `NaN`
+values are used to indicate locations for which `tform(x)` was outside
+the bounds of the input `img`. For more control over the interpolation
+scheme---and how beyond-the-edge points are handled---pass it in as an
+`AbstractExtrapolation` from Interpolations.jl.
+
+# The meaning of the coordinates
+
+The output array `imgw` has indices that would result from applying
+`tform` to the indices of `img`. This can be very handy for keeping
+track of how pixels in `imgw` line up with pixels in `img`.
+
+If you just want a plain array, you can "strip" the custom indices
+with `parent(imgw)`.
+
+# Examples: a 2d rotation (see JuliaImages documentation for pictures)
+
+```jldoctest
+julia> using Images, CoordinateTransformations, TestImages, OffsetArrays
+
+julia> img = testimage("lighthouse");
+
+julia> indices(img)
+(Base.OneTo(512),Base.OneTo(768))
+
+# Rotate around the center of `img`
+julia> tfm = recenter(RotMatrix(pi/4), center(img))
+AffineMap([0.707107 -0.707107; 0.707107 0.707107], [347.01,-68.7554])
+
+julia> imgw = warp(img, tfm);
+
+julia> indices(imgw)
+(-196:709,-68:837)
+
+# Alternatively, specify the origin in the image itself
+julia> img0 = OffsetArray(img, -30:481, -384:383);  # origin near top of image
+
+julia> rot = LinearMap(RotMatrix(pi/4))
+LinearMap([0.707107 -0.707107; 0.707107 0.707107])
+
+julia> imgw = warp(img0, rot);
+
+julia> indices(imgw)
+(-293:612,-293:611)
+
+julia> imgr = parent(imgw);
+
+julia> indices(imgr)
+(Base.OneTo(906),Base.OneTo(905))
+```
+"""
 function warp(img::AbstractExtrapolation, tform)
     inds = autorange(img, tform)
     out = OffsetArray(Array{eltype(img)}(map(length, inds)), inds)