rebuild operation docs with DemoCards

docs/.gitignore

@@ -1,4 +1,4 @@
 build/
 site/
-src/generated/*
-/Manifest.toml
+src/democards
+/Manifest.toml

docs/Project.toml

@@ -2,6 +2,7 @@
 Augmentor = "02898b10-1f73-11ea-317c-6393d7073e15"
 DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ImageDraw = "4381153b-2b60-58ae-a1ba-fd683676385f"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
 MLDatasets = "eb30cadb-4394-5ae3-aed4-317e484a6458"

docs/make.jl

@@ -1,56 +1,19 @@
-using Documenter, Augmentor
-using Images
+using Documenter, DemoCards
+using Augmentor
 using Random
 using MLDatasets
 
-# predownload the dataset to skip the interactive prompt
-if !isdir(first(Base.DEPOT_PATH))
-    MNIST.download(;i_accept_the_terms_of_use=true)
-end
+ENV["DATADEPS_ALWAYS_ACCEPT"] = true # MLDatasets
 
-# Define the documentation order of the operations. The whole
-# purpose of this vector is literally just to dictate in what
-# chronological order the operations are documented.
-op_fnames = [
-    "flipx",
-    "flipy",
-    "rotate90",
-    "rotate270",
-    "rotate180",
-    "rotate",
-    "shearx",
-    "sheary",
-    "scale",
-    "zoom",
-    "elasticdistortion",
-    "crop",
-    "cropnative",
-    "cropsize",
-    "cropratio",
-    "rcropratio",
-    "resize",
-    "converteltype",
-    "mapfun",
-    "aggmapfun",
-    "splitchannels",
-    "combinechannels",
-    "permutedims",
-    "reshape",
-    "noop",
-    "cacheimage",
-    "either",
-]
-dict_order = Dict(fname * ".md" => i for (i, fname) in enumerate(op_fnames))
-myless(a, b) = dict_order[a] < dict_order[b]
+op_templates, op_theme = cardtheme("grid")
+operations, operations_cb = makedemos("operations", op_templates)
 
-# --------------------------------------------------------------------
-
-Random.seed!(1337)
 format = Documenter.HTML(edit_link = "master",
                          prettyurls = get(ENV, "CI", nothing) == "true",
                          assets = [
                              joinpath("assets", "favicon.ico"),
-                             joinpath("assets", "style.css")
+                             joinpath("assets", "style.css"),
+                             op_theme
                         ]
 )
 
@@ -69,12 +32,14 @@ makedocs(
         ],
         "User's Guide" => [
             "interface.md",
-            hide("operations.md", Any[joinpath("operations", fname) for fname in sort(readdir(joinpath(@__DIR__, "src", "operations")), lt = myless) if splitext(fname)[2] == ".md"]),
+            operations,
         ],
         # "Tutorials" => joinpath.("generated", ExampleWeaver.listmarkdown()),
         hide("Indices" => "indices.md"),
         "LICENSE.md",
     ]
 )
 
+operations_cb()
+
 deploydocs(repo = "github.com/Evizero/Augmentor.jl.git")

docs/operations/affine/config.json

@@ -0,0 +1,12 @@
+{
+  "title": "Affine Transformations",
+  "order": [
+    "flip.jl",
+    "rotate.jl",
+    "shear.jl",
+    "scale.jl",
+    "resize.jl",
+    "zoom.jl"
+  ],
+  "description": "A sizeable amount of the provided operations fall under the category of **affine transformations**. As such, they can be described using what is known as an [affine map](https://en.wikipedia.org/wiki/Affine_transformation), which are inherently compose-able if chained together. However, utilizing such a affine formulation requires (costly) interpolation, which may not always be needed to achieve the desired effect. For that reason do some of the operations below also provide a special purpose implementation to produce their specified result. Those are usually preferred over the affine formulation if sensible considering the complete pipeline."
+}

docs/operations/affine/flip.jl

@@ -0,0 +1,37 @@
+# ---
+# title: Flip
+# cover: flip.gif
+# description: flip the input image horizontally or vertically
+# ---
+
+# [`FlipX`](@ref)/[`FlipY`](@ref) can be used to flip the input image horizontally/vertically.
+
+using Augmentor
+using ImageShow, ImageCore
+
+img_in = testpattern(RGB, ratio=0.5)
+
+mosaicview(
+    img_in,
+    augment(img_in, FlipX()),
+    augment(img_in, FlipY());
+    fillvalue=colorant"white", nrow=1, npad=10
+)
+
+# To perform a random flip, you can also pass the probablity to the constructor. For example, `FlipX(0.5)`
+# flips the image with half chance.
+
+# ## References
+
+#md # ```@docs
+#md # FlipX
+#md # FlipY
+#md # ```
+
+
+## save covers #src
+using ImageMagick #src
+using FileIO #src
+include(joinpath("..", "assets", "utilities.jl")) #src
+cover = make_gif(testpattern(RGB, ratio=0.5), Either(FlipX(), FlipY()), 4) #src
+ImageMagick.save("flip.gif", cover; fps=1) #src

docs/operations/affine/resize.jl

@@ -0,0 +1,30 @@
+# ---
+# title: Resize
+# cover: resize.gif
+# ---
+
+# Set the static size of the image
+
+using Augmentor
+using ImageShow, ImageCore
+
+img_in = testpattern(RGB, ratio=0.5)
+
+mosaicview(
+    img_in,
+    augment(img_in, Resize(240, 320));
+    fillvalue=colorant"white", nrow=1, npad=10
+)
+
+
+# ## References
+
+#md # ```@docs
+#md # Resize
+#md # ```
+
+## save covers #src
+using ImageMagick #src
+include(joinpath("..", "assets", "utilities.jl")) #src
+cover = make_gif(testpattern(RGB, ratio=0.5), Resize(240, 320), 2) #src
+ImageMagick.save("resize.gif", cover; fps=1) #src

docs/operations/affine/rotate.jl

@@ -0,0 +1,54 @@
+# ---
+# title: Rotate
+# cover: rotate.gif
+# description: rotate image anticlockwise
+# ---
+
+# The type [`Rotate`](@ref) defines a generic anticlockwise rotation operation around the center
+# of the image. It is also possible to pass some abstract vector to the constructor, in which case
+# Augmentor will randomly sample one of its elements every time the operation is applied.
+
+using Augmentor
+using ImageShow, ImageCore
+using Random
+Random.seed!(0)
+
+img_in = testpattern(RGB, ratio=0.5)
+mosaicview(
+    img_in,
+
+    ## deterministic rotation
+    augment(img_in, Rotate(45)), 
+
+    ## random rotation
+    augment(img_in, Rotate(-45:45));
+    fillvalue=colorant"white", nrow=1, npad=10
+)
+
+# Note that the output image size will be changed after rotation, [`CropNative`](@ref) can be particalually
+# useful to preserve the image size.
+
+mosaicview(
+    augment(img_in, Rotate(45)),
+    augment(img_in, Rotate(45) |> CropNative(axes(img_in)));
+    nrow=1, npad=10
+)
+
+# Rotation by some special degree (e.g.,90, 180 and 270) can be handled more efficiently without interpolation.
+# Compared to `Rotate(90)`, it is recommended to use [`Rotate90`](@ref) when possible. [`Rotate180`](@ref) and
+# [`Rotate270`](@ref) are available, too.
+
+# ## References
+
+#md # ```@docs
+#md # Rotate
+#md # Rotate90
+#md # Rotate180
+#md # Rotate270
+#md # ```
+
+## save covers #src
+using ImageMagick #src
+include(joinpath("..", "assets", "utilities.jl")) #src
+cover = make_gif(testpattern(RGB, ratio=0.5), Rotate(-20:20), 5) #src
+ImageMagick.save("rotate.gif", cover; fps=1) #src

docs/operations/affine/scale.jl

@@ -0,0 +1,44 @@
+# ---
+# title: Scale
+# cover: scale.gif
+# ---
+
+# Relatively resizing image
+
+using Augmentor
+using ImageShow, ImageCore
+using Random
+
+# In the case that only a single scale factor is specified, the
+# operation will assume that the intention is to scale all
+# dimensions uniformly by that factor.
+
+img_in = testpattern(RGB, ratio=0.5)
+
+mosaicview(
+    img_in,
+    augment(img_in, Scale(0.8)),
+    augment(img_in, Scale(0.8, 1));
+
+    fillvalue=colorant"white", nrow=1, npad=10
+)
+
+# It is also possible to pass some abstract vector(s) to the
+# constructor, in which case Augmentor will randomly sample one of
+# its elements every time the operation is applied.
+
+Random.seed!(1337)
+img_out = [augment(img_in, Scale(0.9:0.05:1.2)) for _ in 1:4]
+mosaicview(img_out...; fillvalue=colorant"white", nrow=2)
+
+# ## References
+
+#md # ```@docs
+#md # Scale
+#md # ```
+
+## save covers #src
+using ImageMagick #src
+include(joinpath("..", "assets", "utilities.jl")) #src
+cover = make_gif(testpattern(RGB, ratio=0.5), Scale(0.9:0.1:1.5), 5) #src
+ImageMagick.save("scale.gif", cover; fps=1) #src

docs/operations/affine/shear.jl

@@ -0,0 +1,49 @@
+# ---
+# title: Shear
+# cover: shear.gif
+# description: shear the input image horizontally or vertically
+# ---
+
+# [`ShearX`](@ref)/[`ShearY`](@ref) can be used to shear the input image horizontally/vertically.
+# The input to the constructor can be a scalar or a vector. In the case of a vector, the transformation
+# will be a stochastic process.
+
+using Augmentor
+using ImageShow, ImageCore
+using Random
+Random.seed!(0)
+img_in = testpattern(RGB, ratio=0.5)
+
+mosaicview(
+    ## deterministic transformation
+    augment(img_in, ShearX(20)),
+    augment(img_in, ShearY(20)),
+
+    ## random transformation
+    augment(img_in, ShearX(-20:20)),
+    augment(img_in, ShearY(-20:20));
+
+    fillvalue=colorant"white", nrow=2, npad=10
+)
+
+# Note that the output image size will be changed after transformation, [`CropNative`](@ref) can be
+# particalually useful to preserve the image size.
+
+mosaicview(
+    augment(img_in, ShearX(10)),
+    augment(img_in, ShearX(10) |> CropNative(axes(img_in)));
+    fillvalue=colorant"white", nrow=1, npad=10
+)
+
+# ## References
+
+#md # ```@docs
+#md # ShearX
+#md # ShearY
+#md # ```
+
+## save covers #src
+using ImageMagick #src
+include(joinpath("..", "assets", "utilities.jl")) #src
+cover = make_gif(testpattern(RGB, ratio=0.5), Either(ShearX(-10:10), ShearY(-10:10)), 5) #src
+ImageMagick.save("shear.gif", cover; fps=1) #src

docs/operations/affine/zoom.jl

@@ -0,0 +1,44 @@
+# ---
+# title: Zoom
+# cover: zoom.gif
+# ---
+
+# Scale without resize
+
+using Augmentor
+using ImageShow, ImageCore
+using Random
+
+# In the case that only a single Zoom factor is specified, the
+# operation will assume that the intention is to Zoom all
+# dimensions uniformly by that factor.
+
+img_in = testpattern(RGB, ratio=0.5)
+
+mosaicview(
+    img_in,
+    augment(img_in, Zoom(1.3)),
+    augment(img_in, Zoom(1.3, 1));
+    fillvalue=colorant"white", nrow=1, npad=10
+)
+
+# It is also possible to pass some abstract vector(s) to the
+# constructor, in which case Augmentor will randomly sample one of
+# its elements every time the operation is applied.
+
+Random.seed!(1337)
+img_out = [augment(img_in, Zoom(0.9:0.05:1.2)) for _ in 1:4]
+
+mosaicview(img_out...; nrow=2)
+
+# ## References
+
+#md # ```@docs
+#md # Zoom
+#md # ```
+
+## save covers #src
+using ImageMagick #src
+include(joinpath("..", "assets", "utilities.jl")) #src
+cover = make_gif(testpattern(RGB, ratio=0.5), Zoom(0.9:0.1:1.5), 5) #src
+ImageMagick.save("zoom.gif", cover; fps=1) #src