add index page and a swirl example

Author: johnnychen94

docs/Project.toml

@@ -1,14 +1,20 @@
 [deps]
 CoordinateTransformations = "150eb455-5306-5404-9cee-2592286d6298"
+DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+ImageBase = "c817782e-172a-44cc-b673-b171935fbb9e"
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 ImageShow = "4e3cecfd-b093-5904-9786-8bbb286a6a31"
 ImageTransformations = "02fcd773-0e25-5acc-982a-7f6622650795"
 Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
+OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 Rotations = "6038ab10-8711-5258-84ad-4b1120ba62dc"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 
 [compat]
-Documenter = "0.26"
+DemoCards = "0.4"
+Documenter = "0.27"

docs/examples/config.json

@@ -0,0 +1,3 @@
+{
+    "theme": "grid"
+}

docs/examples/operations/swirl.jl

@@ -0,0 +1,70 @@
+# ---
+# cover: assets/swirl.gif
+# title: Swirl effect using warp operation
+# ---
+
+# In this example, we illustrate how to construct a custom warping map
+# and pass it to `warp`. This swirl example comes from
+# [the Princeton Computer Graphics course for Image Warping (Fall 2000)](https://www.cs.princeton.edu/courses/archive/fall00/cs426/lectures/warp/warp.pdf)
+# and [scikit-image swirl example](https://scikit-image.org/docs/dev/auto_examples/transform/plot_swirl.html).
+
+using ImageTransformations
+using OffsetArrays, StaticArrays
+using ImageShow, TestImages
+using LinearAlgebra
+
+img = imresize(testimage("cameraman"), (256, 256));
+
+# As we've illustrated in [image warping](@ref index_image_warping), a warp operation
+# consists of two operations: backward coordinate map `ϕ` and intensity estimator.
+# To implement swirl operation, we need to customize the coordinate map `ϕ`.
+# A valid coordinate map `q = ϕ(p)` follows the following interface:
+#
+# ```julia
+# # SVector comes from StaticArrays
+# ϕ(::SVector{N})::SVector{N} where N
+# ```
+#
+# A cartesian position `(x, y)` can be transfered to/from polar coordinate `(ρ, θ)`
+# using formula:
+#
+# ```julia
+# # Cartesian to Polar
+# ρ = norm(y-y0, x-x0)
+# θ = atan(y/x)
+#
+# # Polar to Cartesian
+# y = y0 + ρ*sin(θ)
+# x = x0 + ρ*cos(θ)
+# ```
+#
+# For given input index `p`, a swirl operation enforces more rotations in its polar coordinate using
+# `θ̃ = θ + ϕ + s*exp(-ρ/r)`, and returns the cartesian index (x̃, ỹ) from the warped polor coordinate
+# (ρ, θ̃). (Here we use the formula from [scikit-image swirl example](https://scikit-image.org/docs/dev/auto_examples/transform/plot_swirl.html)
+# to build our version.)
+
+function swirl(rotation, strength, radius)
+    x0 = OffsetArrays.center(img)
+    r = log(2)*radius/5
+
+    function swirl_map(x::SVector{N}) where N
+        xd = x .- x0
+        ρ = norm(xd)
+        θ = atan(reverse(xd)...)
+
+        ## Note that `x == x0 .+ ρ .* reverse(sincos(θ))`
+        ## swirl adds more rotations to θ based on the distance to center point
+        θ̃ = θ + rotation + strength * exp(-ρ/r)
+        
+        SVector{N}(x0 .+ ρ .* reverse(sincos(θ̃)))
+    end
+
+    warp(img, swirl_map, axes(img))
+end
+
+# Now let's see how radius argument affects the result
+
+preview = ImageShow.gif([swirl(0, 10, radius) for radius in 10:10:150]; fps=5)
+
+using FileIO #src
+save("assets/swirl.gif", preview; fps=5) #src

docs/make.jl

@@ -1,15 +1,24 @@
-using Documenter, ImageCore, ImageTransformations, ImageShow
+using Documenter, DemoCards
+using ImageBase, ImageTransformations, ImageShow
 using TestImages
 using CoordinateTransformations, Interpolations, Rotations
 
-testimage("cameraman") # this is used to trigger artifact download
+# this is used to trigger artifact download and IO backend precompilation
+testimage.(["cameraman", "lighthouse"])
 
+examples, postprocess_cb, examples_assets = makedemos("examples")
 format = Documenter.HTML(edit_link = "master",
-                         prettyurls = get(ENV, "CI", nothing) == "true")
+                         prettyurls = get(ENV, "CI", nothing) == "true",
+                         assets = [examples_assets,])
 
-makedocs(modules  = [ImageTransformations],
+makedocs(modules  = [ImageTransformations, ImageBase],
          format   = format,
          sitename = "ImageTransformations",
-         pages    = ["index.md", "reference.md"])
+         pages    = [
+             "index.md",
+             examples,
+             "reference.md"])
+
+postprocess_cb()
 
 deploydocs(repo   = "github.com/JuliaImages/ImageTransformations.jl.git")

docs/src/assets/warp_resize.png

@@ -1,4 +1,83 @@
 # ImageTransformations.jl
 
+```@setup overview
+using ImageShow
+```
+
 This package provides support for image resizing, image rotation, and
 other spatial transformations of arrays.
+
+## Overview
+
+ImageTransformations.jl consists of two sets of API: the low level warping operations, and the high-level operations that built on top of it.
+
+- Low-level warping API:
+  - `warp`: backward-mode warping
+  - `WarpedView`: the lazy view version of `warp`
+  - `InvWarpedView`: the inverse of `WarpedView`
+- high-level spatial operations:
+  - `imresize`: aspect adjustment
+  - `restrict`: a much more efficient version of `imresize` that two-folds/down-samples image to approximate 1/2 size. (This is now provided by ImageBase.)
+  - `imrotate`: rotation
+
+For detailed usage of these functions, please refer to [function references](@ref package_references) and [examples](@ref Examples). The following section explains
+the core concept image warping so that you can get a clear understanding about
+this package while using it.
+
+## [Image warping](@id index_image_warping)
+
+!!! info
+    This is just a very simple explaination on the internal of ImageTransformations. For more information about image warping, you can take a look at [the Princeton Computer Graphics course for Image Warping (Fall 2000)](https://www.cs.princeton.edu/courses/archive/fall00/cs426/lectures/warp/warp.pdf)
+
+Most image spatial transformation operations (e.g., rotation, resizing, translation) fall into the category of warping operation. Mathematically, for given input image `X`, a (backward-mode) warping operation `f` consists of two functions: coordination map `ϕ` and intensity estimator `τ`.
+
+```math
+Y_{i,j} = f(X)_{i, j} = τ(X, ϕ(i, j))
+```
+
+Take the following resizing operation as an example, for every pixel position `p` in output image `Y`, we 1) use the backward coordinate map `ϕ` to get its corresponding pixel position `q` in original image `X`. Since `q` may not be on grid, we need to 2) estimate the value of `X` on position `q` using function `τ`, and finally 3) assign `X[q]` back to `Y[p]`. In Julia words, it is
+
+```julia
+for p in CartesianIndexes(Y)
+    q = ϕ(p) # backward coordinate map
+    v = τ(X, q) # estimate the value
+    Y[p] = v # assign value back
+end
+```
+
+As you may have notice, we use backward coordinate map because this is the simplest way to iterate every pixel of the output image. This is why it is called backward-mode warping. In some literature, it is also called reverse warping.
+
+![warp resize demo](assets/warp_resize.png)
+
+In ImageTransformations, the `warp`-based operation uses Interpolations as our intensity estimator `τ`:
+
+```@example overview
+using Interpolations, ImageCore, TestImages
+using ImageTransformations
+
+X = imresize(testimage("cameraman"), (64, 64)) # use small image as an example
+
+sz = (128, 128)
+Y = similar(X, sz...)
+
+# intensity estimator using interpolation
+itp = interpolate(X, BSpline(Linear())) # bilinear interpolation
+τ(q) = itp(q...)
+
+# A linear coordinate map that satisfies:
+#   - `ϕ(1, 1) == (1, 1)`
+#   - `ϕ(128, 128) == (64, 64)`
+K = (size(X) .- (1, 1))./(sz .- (1, 1))
+b = (1, 1) .- K
+ϕ(p) = @. K*p + b
+
+for p in CartesianIndices(Y)
+    q = ϕ(p.I)
+    Y[p] = τ(q)
+end
+
+mosaic(X, Y; nrow=1)
+```
+
+This is the internal of ImageTransformations. For common usage of ImageTransformations, you should use either the low-level API `warp` or
+high-level API `imresize` and others.

docs/src/index.md

@@ -1,7 +1,25 @@
 # [Package References](@id package_references)
 
 
-```@autodocs
-Modules = [ImageTransformations]
-Order   = [:type, :function]
+# High-level API
+
+```@docs
+ImageBase.restrict
+ImageTransformations.imrotate
+ImageTransformations.imresize
+```
+
+# Low-level warping API
+
+```@docs
+ImageTransformations.warp
+ImageTransformations.WarpedView
+ImageTransformations.InvWarpedView
+ImageTransformations.invwarpedview
+```
+
+# Utilities
+
+```@docs
+ImageTransformations.autorange
 ```