Merge pull request #33 from lorenzoh/lo/one-of

add `OneOf` and `Maybe` transform wrappers

Author: lorenzoh

Project.toml

@@ -12,6 +12,7 @@ ImageTransformations = "02fcd773-0e25-5acc-982a-7f6622650795"
 Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
 Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+MosaicViews = "e94cdb99-869f-56ef-bcf0-1ae2bcbe0389"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

docs/literate/colortransforms.md

@@ -0,0 +1,8 @@
+# Color transformations
+
+DataAugmentation.jl currently supports the following color transformations for augmentation:
+
+- [`AdjustContrast`](#) randomly adjusts the contrast; and
+- [`AdjustBrightness`](#) randomly adjusts the brightness.
+
+See the docstrings for examples.

docs/literate/stochastic.md

@@ -0,0 +1,19 @@
+# Stochastic transformations
+
+
+When augmenting data, it is often useful to apply a transformation only with some probability or choose from a set of transformations. Unlike in other data augmentation libraries like *albumentations*, in DataAugmentation.jl you can use wrapper transformations for this functionality.
+
+- [`Maybe`](#)`(tfm, p = 0.5)` applies a transformation with probability `p`; and
+- [`OneOf`](#)`([tfm1, tfm2])` randomly selects a transformation to apply.
+
+## Example
+Let's say we have an image classification dataset. For most datasets, horizontally flipping the image does not change the label: a flipped image of a cat still shows a cat. So let's flip every image horizontally half of the time to improve the generalization of the model we might be training.
+
+{cell=main}
+```julia
+using DataAugmentation, TestImages
+item = Image(testimage("lighthouse"))
+tfm = Maybe(FlipX())
+titems = [apply(tfm, item) for _ in 1:8]
+showgrid(titems; ncol = 4, npad = 16)
+```

docs/serve.jl

@@ -2,8 +2,5 @@ using Pkg
 using Pollen
 using DataAugmentation
 
-p = Pollen.documentationproject(DataAugmentation, executecode=true)
-push!(p.rewriters, Pollen.PackageWatcher([DataAugmentation]))
-server = Server(p)
-mode = ServeFilesLazy()
-runserver(server, mode)
+p = Pollen.documentationproject(DataAugmentation)
+Pollen.serve(p)

src/DataAugmentation.jl

@@ -2,13 +2,14 @@ module DataAugmentation
 
 using ColorBlendModes
 using CoordinateTransformations
-using Distributions: Sampleable, Uniform
+using Distributions: Sampleable, Uniform, Categorical
 using ImageDraw
 using Images
 using Images: Colorant, permuteddimsview
 using ImageTransformations
 using ImageTransformations: center, _center, box_extrapolation, warp!
 using Interpolations
+using MosaicViews: mosaicview
 using OffsetArrays: OffsetArray
 using LinearAlgebra: I
 using Parameters
@@ -34,6 +35,7 @@ include("./projective/compose.jl")
 include("./projective/crop.jl")
 include("./projective/affine.jl")
 include("./projective/warp.jl")
+include("./oneof.jl")
 include("./preprocessing.jl")
 include("./colortransforms.jl")
 
@@ -69,6 +71,8 @@ export Item,
     BufferedThreadsafe,
     OneHot,
     Zoom,
+    OneOf,
+    Maybe,
     apply,
     Reflect,
     WarpAffine,
@@ -81,7 +85,8 @@ export Item,
     PadDivisible,
     ResizePadDivisible,
     onehot,
-    showitems
+    showitems,
+    showgrid
 
 
 end # module

src/colortransforms.jl

@@ -9,13 +9,16 @@ from `f ∈ [1-δ, 1+δ]` by multiplying each color channel by `f`.
 You can also pass any `Distributions.Sampleable` from which the
 factor is selected.
 
+## Example
+
 {cell=AdjustBrightness}
 ```julia
 using DataAugmentation, TestImages
 
-img = testimage("lighthouse")
+item = Image(testimage("lighthouse"))
 tfm = AdjustBrightness(0.2)
-apply(tfm, Image(img)) |> showitem
+titems = [apply(tfm, item) for _ in 1:8]
+showgrid(titems; ncol = 4, npad = 16)
 ```
 """
 struct AdjustBrightness{S<:Sampleable} <: Transform
@@ -67,13 +70,16 @@ of the image.
 You can also pass any `Distributions.Sampleable` from which the
 factor is selected.
 
+## Example
+
 {cell=AdjustBrightness}
 ```julia
 using DataAugmentation, TestImages
 
-img = testimage("lighthouse")
+item = Image(testimage("lighthouse"))
 tfm = AdjustContrast(0.2)
-apply(tfm, Image(img)) |> showitem
+titems = [apply(tfm, item) for _ in 1:8]
+showgrid(titems; ncol = 4, npad = 16)
 ```
 """
 struct AdjustContrast{S<:Sampleable} <: Transform

src/oneof.jl

@@ -0,0 +1,79 @@
+"""
+    OneOf(tfms)
+    OneOf(tfms, ps)
+
+Apply one of `tfms` selected randomly with probability `ps` each
+or uniformly chosen if no `ps` is given.
+"""
+struct OneOf{T<:Transform, D<:Sampleable} <: Transform
+    tfms::Vector{T}
+    dist::D
+end
+
+function OneOf(tfms::Vector{<:Transform}, ps = ones(length(tfms)) ./ length(tfms))
+    @assert length(tfms) == length(ps)
+    return OneOf(tfms, Categorical(ps))
+end
+
+function getrandstate(oneof::OneOf)
+    i = rand(oneof.dist)
+    return i, getrandstate(oneof.tfms[i])
+end
+
+
+function apply(oneof::OneOf, item::AbstractItem; randstate = getrandstate(oneof))
+    i, tfmrandstate = randstate
+    return apply(oneof.tfms[i], item; randstate = randstate)
+end
+
+
+function makebuffer(oneof::OneOf, items)
+    return [makebuffer(tfm, items) for tfm in oneof.tfms]
+end
+
+function apply!(bufs, oneof::OneOf, item::AbstractItem; randstate = getrandstate(tfm))
+    i, tfm, tfmrandstate = randstate
+    buf = bufs[i]
+    return apply!(buf, tfm, item; randstate = randstate)
+end
+
+"""
+    Maybe(tfm, p = 0.5) <: Transform
+
+With probability `p`, apply transformation `tfm`.
+"""
+Maybe(tfm, p = 0.5) = OneOf([tfm, Identity()], [p, 1-p])
+
+
+struct OneOfProjective{T<:Transform, D<:Sampleable} <: ProjectiveTransform
+    tfms::Vector{T}
+    dist::D
+end
+
+
+function OneOf(tfms::Vector{<:ProjectiveTransform}, ps = ones(length(tfms)) ./ length(tfms))
+    @assert length(tfms) == length(ps)
+    return OneOfProjective(tfms, Categorical(ps))
+end
+
+
+function getrandstate(oneof::OneOfProjective)
+    i = rand(oneof.dist)
+    return i, getrandstate(oneof.tfms[i])
+end
+
+
+function Maybe(tfm::ProjectiveTransform, p = 1/2)
+    return OneOf([tfm, Project(IdentityTransformation())], [p, 1-p])
+end
+
+
+function getprojection(oneof::OneOfProjective, bounds; randstate = getrandstate(oneof))
+    i, tfmrandstate = randstate
+    return getprojection(oneof.tfms[i], bounds; randstate = tfmrandstate)
+end
+
+
+function makebuffer(oneof::OneOfProjective, items)
+    return [makebuffer(tfm, items) for tfm in oneof.tfms]
+end

src/projective/affine.jl

@@ -131,17 +131,14 @@ angle is selected.
 tfm = Reflect(10)
 ```
 """
-struct Reflect{S<:Sampleable} <: ProjectiveTransform
-    dist::S
+struct Reflect <: ProjectiveTransform
+    γ
 end
-Reflect(γ) = Reflect(Uniform(-abs(γ), abs(γ)))
 
-getrandstate(tfm::Reflect) = rand(tfm.dist)
 
 function getprojection(tfm::Reflect, bounds; randstate = getrandstate(tfm))
-    γ = randstate
     midpoint = sum(bounds) ./ length(bounds)
-    r = γ / 360 * 2pi
+    r = tfm.γ / 360 * 2pi
     return recenter(reflectionmatrix(r), midpoint)
 end
 

src/sequence.jl

@@ -23,8 +23,9 @@ getrandstate(seq::Sequence) = getrandstate.(seq.transforms)
 
 compose(tfm1::Transform, tfm2::Transform) = Sequence(tfm1, tfm2)
 compose(seq::Sequence, tfm::Transform) = Sequence(seq.transforms..., tfm)
-compose(seq::Sequence, ::Identity) = seq
 compose(tfm::Transform, seq::Sequence) = compose(tfm, seq.transforms...)
+compose(::Identity, seq::Sequence) = seq
+compose(seq::Sequence, ::Identity) = seq
 
 
 function apply(seq::Sequence, items::Tuple; randstate = getrandstate(seq))

src/visualization.jl

@@ -34,6 +34,11 @@ function showimage!(dst, img)
 end
 
 
+function showgrid(items; fillvalue = RGBA{N0f8}(0.,0.,0.,0.), kwargs...)
+    imgs = [showitems(item) for item in items]
+    mosaicview(imgs; fillvalue = fillvalue, kwargs...)
+end
+
 showbounds(bounds) = showbounds!(zeros(RGBA{N0f8}, boundssize(bounds)), bounds)
 
 function showbounds!(img, bounds::AbstractArray{<:SVector{2}})