add a demo for median filters (#185)

* create examples section

* build docs with julia 1.x

Author: johnnychen94

.gitignore

@@ -3,6 +3,8 @@
 *.jl.mem
 docs/build
 docs/site
+docs/Manifest.toml
+docs/src/democards
 /Manifest.toml
 /.benchmarkci
 /benchmark/*.json

.travis.yml

@@ -1,7 +1,7 @@
 # Until https://github.com/julia-actions/julia-uploadcodecov/issues/1 get fixed
 # submit coverage report via travis
 language: julia
-julia: 1.0
+julia: 1
 os: linux
 notifications:
   email: false

docs/Project.toml

@@ -1,5 +1,14 @@
 [deps]
+DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
+ImageFiltering = "6a3955dd-da59-5b1f-98d4-e7296123deb5"
+ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
+ImageShow = "4e3cecfd-b093-5904-9786-8bbb286a6a31"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 
 [compat]
+DemoCards = "0.3"
 Documenter = "0.24"

docs/demos/config.json

@@ -0,0 +1,4 @@
+{
+    "title": "Examples",
+    "theme": "grid"
+}

docs/demos/filters/median_filter.jl

@@ -0,0 +1,94 @@
+# ---
+# title: Custom median filters
+# cover: assets/median.gif
+# author: Johnny Chen
+# date: 2020-09-23
+# ---
+
+# With median filter as an example, this demo shows how you could construct a custom kernel and
+# pass it to [`mapwindow`](@ref) for common stencil operations.
+
+# Unlike other image processing toolboxes, `ImageFiltering.jl` does not provide you an out-of-box
+# function for median filters. It instead provides the more general [`mapwindow`](@ref) function,
+# which allows you to apply any function to the window around each pixel.
+
+using ImageFiltering, ImageCore, ImageShow # or you could just `using Images`
+using TestImages
+using Statistics
+using Random #hide
+Random.seed!(0) #hide
+
+img = Float64[isodd(i) - isodd(j) for i = 1:5, j = 1:5]
+img[3, 3] = 1000
+img #hide #md
+
+#-
+
+patch_size = (3, 3)
+imgm = mapwindow(median, img, patch_size)
+
+# `mapwindow` provides a high-level interface to loop over the image and call a function (`median`
+# in this demo) on each patch/window. It's performing an operation that is nearly equivalent to the
+# loop below, albeit more efficiently:
+
+## For simplicity, border condition is not included here.
+imgm = zeros(axes(img))
+R = CartesianIndices(img)
+I_first, I_last = first(R), last(R)
+Δ = CartesianIndex(patch_size .÷ 2)
+for I in R
+    patch = max(I_first, I-Δ):min(I_last, I+Δ)
+    imgm[I] = median(img[patch])
+end
+imgm
+
+# Compared to this hand-written loop, `mapwindow` offers additional flexibility in handling the
+# borders and allows you to process only a subset of the windows. For some functions (e.g., `min`,
+# `max`, and `extrema`), `mapwindow` uses a custom implementation that is far more efficient than
+# naively computing the function "freshly" on each window.
+
+# When the input array has `NaN` or some unwanted pixel values, a pre-filtering process is needed to
+# exclude them first. This can be done quite easily by compositing a given kernel operation and a
+# `filter` operation. Let's still take `median` filter as an example.
+
+img[2,2] = NaN
+imgm = mapwindow(median, img, (3,3))
+
+# `NaN` has polluted the output, which is usually not wanted. This can be fixed quite easily by
+# compositing a new filter kernel. This way, we only compute the median value on the non-NaN subset
+# of each patch/window.
+
+_median(patch) = median(filter(x->!isnan(x), patch))
+imgm = mapwindow(_median, img, patch_size)
+
+
+# ## Impulse (Salt and Pepper) noise removal
+
+# Median filters are quite robust to outliers (unusual values), this property can be used to remove
+# salt&pepper noise. An image with `n`-level salt&papper noise is defined as: each pixel `p` has
+# `n/2` probabilty to be filled by `0`(the minimal gamut value), `n/2` probabilty to be filled by
+# `1`(the maximal gamut value), and `1-n` probablity to be undamaged.
+
+img = testimage("cameraman")
+
+n = 0.2 # noise level
+noisy_img = map(img) do p
+    sp = rand()
+    if sp < n/2
+        eltype(img)(gamutmin(eltype(img))...)
+    elseif sp < n
+        eltype(img)(gamutmax(eltype(img))...)
+    else
+        p
+    end
+end
+
+denoised_img = mapwindow(median!, noisy_img, (5, 5))
+
+mosaicview(img, noisy_img, denoised_img; nrow=1)
+
+
+## save covers #src
+using ImageMagick #src
+mkpath("assets") #src
+ImageMagick.save("assets/median.gif", cat(noisy_img, denoised_img; dims=3); fps=1) #src

docs/make.jl

@@ -1,15 +1,26 @@
-using Documenter, ImageFiltering
+using Documenter, DemoCards
+using ImageFiltering
+
+demos, demos_cb, demos_assets = makedemos("demos")
+
+assets = []
+isnothing(demos_assets) || (push!(assets, demos_assets))
+format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true",
+                         assets = assets)
 
 makedocs(
     modules  = [ImageFiltering, Kernel, KernelFactors, ImageFiltering.MapWindow],
-    format   = Documenter.HTML(),
+    format   = format,
     sitename = "ImageFiltering",
     pages    = [
-        "index.md", 
+        "index.md",
+        demos,
         "Function reference" => "function_reference.md"
     ]
 )
 
+demos_cb()
+
 deploydocs(
     repo   = "github.com/JuliaImages/ImageFiltering.jl.git",
     push_preview = true