diff --git a/src/operations/crop.jl b/src/operations/crop.jl index 3eef3998..f7e58821 100644 --- a/src/operations/crop.jl +++ b/src/operations/crop.jl @@ -206,7 +206,7 @@ Arguments -------------- - **`size`** : `NTuple` or `Vararg` of `Int` that denote the - output size for each dimension. + output size in pixel for each dimension. Examples -------------- diff --git a/src/operations/flip.jl b/src/operations/flip.jl index 656c8e8d..d207efd2 100644 --- a/src/operations/flip.jl +++ b/src/operations/flip.jl @@ -1,7 +1,58 @@ # TODO: implement methods for n-dim arrays +""" + FlipX <: Augmentor.AffineOperation + +Description +-------------- + +Reverses the x-order of each pixel row. Another way of describing +it would be to mirror the image on the y-axis, or to mirror the +image horizontally. + +If created using the parameter `p`, the operation will be lifted +into `Either(p=>FlipX(), 1-p=>NoOp())`, where `p` denotes the +probability of applying `FlipX` and `1-p` the probability for +applying [`NoOp`](@ref). See the documentation of +[`Either`](@ref) for more information. + +Usage +-------------- + + FlipX() + + FlipX(p) + +Arguments +-------------- + +- **`p`** : Optional. Probability of applying the operation. Must + be in the interval [0,1]. + +Examples +-------------- + +```julia +julia> using Augmentor + +julia> img = [200 150; 50 1] +2×2 Array{Int64,2}: + 200 150 + 50 1 + +julia> img_new = augment(img, FlipX()) +2×2 Array{Int64,2}: + 150 200 + 1 50 +``` + +see also +-------------- + +[`FlipY`](@ref), [`Either`](@ref), [`augment`](@ref) +""" immutable FlipX <: AffineOperation end -FlipX(p) = Either(FlipX(), p) +FlipX(p::Number) = Either(FlipX(), p) @inline supports_stepview(::Type{FlipX}) = true @@ -31,8 +82,59 @@ end # -------------------------------------------------------------------- +""" + FlipY <: Augmentor.AffineOperation + +Description +-------------- + +Reverses the y-order of each pixel column. Another way of +describing it would be to mirror the image on the x-axis, or to +mirror the image vertically. + +If created using the parameter `p`, the operation will be lifted +into `Either(p=>FlipY(), 1-p=>NoOp())`, where `p` denotes the +probability of applying `FlipY` and `1-p` the probability for +applying [`NoOp`](@ref). See the documentation of +[`Either`](@ref) for more information. + +Usage +-------------- + + FlipY() + + FlipY(p) + +Arguments +-------------- + +- **`p`** : Optional. Probability of applying the operation. Must + be in the interval [0,1]. + +Examples +-------------- + +```julia +julia> using Augmentor + +julia> img = [200 150; 50 1] +2×2 Array{Int64,2}: + 200 150 + 50 1 + +julia> img_new = augment(img, FlipY()) +2×2 Array{Int64,2}: + 50 1 + 200 150 +``` + +see also +-------------- + +[`FlipX`](@ref), [`Either`](@ref), [`augment`](@ref) +""" immutable FlipY <: AffineOperation end -FlipY(p) = Either(FlipY(), p) +FlipY(p::Number) = Either(FlipY(), p) @inline supports_stepview(::Type{FlipY}) = true diff --git a/src/operations/noop.jl b/src/operations/noop.jl index a630100b..8843c2e3 100644 --- a/src/operations/noop.jl +++ b/src/operations/noop.jl @@ -1,3 +1,12 @@ +""" + NoOp <: Augmentor.AffineOperation + +Identity transformation that does not do anything with the given +image but instead passes it along unchanged (without copying). + +Usually used in combination with [`Either`](@ref) to denote a +"branch" that does not perform any computation. +""" immutable NoOp <: AffineOperation end @inline supports_eager(::Type{NoOp}) = false diff --git a/src/operations/resize.jl b/src/operations/resize.jl index 8f590562..a498033f 100644 --- a/src/operations/resize.jl +++ b/src/operations/resize.jl @@ -1,3 +1,46 @@ +""" + Resize <: Augmentor.Operation + +Description +-------------- + +Transforms the image into a fixed specified pixel size. + +This operation does not take any measures to preserve aspect +ratio of the source image. Instead, the original image will +simply be resized to the given dimensions. This is useful when +one needs a set of images to all be of the exact same size. + +Usage +-------------- + + Resize(; height=64, width=64) + + Resize(size) + + Resize(size...) + +Arguments +-------------- + +- **`size`** : `NTuple` or `Vararg` of `Int` that denote the + output size in pixel for each dimension. + +Examples +-------------- + +```julia +using Augmentor +img = testpattern() + +augment(img, Resize(30, 40)) +``` + +see also +-------------- + +[`CropSize`](@ref), [`augment`](@ref) +""" immutable Resize{N} <: Operation size::NTuple{N,Int} diff --git a/src/operations/rotation.jl b/src/operations/rotation.jl index f5e1db4c..7f571505 100644 --- a/src/operations/rotation.jl +++ b/src/operations/rotation.jl @@ -1,7 +1,61 @@ # TODO: implement methods for n-dim arrays +""" + Rotate90 <: Augmentor.AffineOperation + +Description +-------------- + +Rotates the image upwards 90 degrees. This is a special case +rotation because it can be performed very efficiently by simply +rearranging the existing pixels. However, it is generally not the +case that the output image will have the same size as the input +image, which is something to be aware of. + +If created using the parameter `p`, the operation will be lifted +into `Either(p=>Rotate90(), 1-p=>NoOp())`, where `p` denotes the +probability of applying `Rotate90` and `1-p` the probability for +applying [`NoOp`](@ref). See the documentation of +[`Either`](@ref) for more information. + +Usage +-------------- + + Rotate90() + + Rotate90(p) + +Arguments +-------------- + +- **`p`** : Optional. Probability of applying the operation. Must + be in the interval [0,1]. + +Examples +-------------- + +```julia +julia> using Augmentor + +julia> img = [200 150; 50 1] +2×2 Array{Int64,2}: + 200 150 + 50 1 + +julia> img_new = augment(img, Rotate90()) +2×2 Array{Int64,2}: + 150 1 + 200 50 +``` + +see also +-------------- + +[`Rotate180`](@ref), [`Rotate270`](@ref), [`Rotate`](@ref), +[`Either`](@ref), [`augment`](@ref) +""" immutable Rotate90 <: AffineOperation end -Rotate90(p) = Either(Rotate90(), p) +Rotate90(p::Number) = Either(Rotate90(), p) @inline supports_permute(::Type{Rotate90}) = true @@ -32,8 +86,61 @@ end # -------------------------------------------------------------------- +""" + Rotate180 <: Augmentor.AffineOperation + +Description +-------------- + +Rotates the image 180 degrees. This is a special case rotation +because it can be performed very efficiently by simply +rearranging the existing pixels. Furthermore, the output image +will have the same dimensions as the input image. + +If created using the parameter `p`, the operation will be lifted +into `Either(p=>Rotate180(), 1-p=>NoOp())`, where `p` denotes the +probability of applying `Rotate180` and `1-p` the probability for +applying [`NoOp`](@ref). See the documentation of +[`Either`](@ref) for more information. + +Usage +-------------- + + Rotate180() + + Rotate180(p) + +Arguments +-------------- + +- **`p`** : Optional. Probability of applying the operation. Must + be in the interval [0,1]. + +Examples +-------------- + +```julia +julia> using Augmentor + +julia> img = [200 150; 50 1] +2×2 Array{Int64,2}: + 200 150 + 50 1 + +julia> img_new = augment(img, Rotate180()) +2×2 Array{Int64,2}: + 1 50 + 150 200 +``` + +see also +-------------- + +[`Rotate90`](@ref), [`Rotate270`](@ref), [`Rotate`](@ref), +[`Either`](@ref), [`augment`](@ref) +""" immutable Rotate180 <: AffineOperation end -Rotate180(p) = Either(Rotate180(), p) +Rotate180(p::Number) = Either(Rotate180(), p) @inline supports_stepview(::Type{Rotate180}) = true @@ -48,8 +155,63 @@ end # -------------------------------------------------------------------- +""" + Rotate270 <: Augmentor.AffineOperation + +Description +-------------- + +Rotates the image upwards 270 degrees, which can also be +described as rotating the image downwards 90 degrees. This is a +special case rotation, because it can be performed very +efficiently by simply rearranging the existing pixels. However, +it is generally not the case that the output image will have the +same size as the input image, which is something to be aware of. + +If created using the parameter `p`, the operation will be lifted +into `Either(p=>Rotate270(), 1-p=>NoOp())`, where `p` denotes the +probability of applying `Rotate270` and `1-p` the probability for +applying [`NoOp`](@ref). See the documentation of +[`Either`](@ref) for more information. + +Usage +-------------- + + Rotate270() + + Rotate270(p) + +Arguments +-------------- + +- **`p`** : Optional. Probability of applying the operation. Must + be in the interval [0,1]. + +Examples +-------------- + +```julia +julia> using Augmentor + +julia> img = [200 150; 50 1] +2×2 Array{Int64,2}: + 200 150 + 50 1 + +julia> img_new = augment(img, Rotate270()) +2×2 Array{Int64,2}: + 50 200 + 1 150 +``` + +see also +-------------- + +[`Rotate90`](@ref), [`Rotate180`](@ref), [`Rotate`](@ref), +[`Either`](@ref), [`augment`](@ref) +""" immutable Rotate270 <: AffineOperation end -Rotate270(p) = Either(Rotate270(), p) +Rotate270(p::Number) = Either(Rotate270(), p) @inline supports_permute(::Type{Rotate270}) = true @@ -96,6 +258,59 @@ end # -------------------------------------------------------------------- +""" + Rotate <: Augmentor.AffineOperation + +Description +-------------- + +Rotate the image upwards for the given `degree`. This operation +can only be described as an affine transformation and will in +general cause other operations of the pipeline to use their +affine formulation as well (if they have one). + +In contrast to the special case rotations outlined above, the +type `Rotate` can describe any arbitrary number of degrees. It +will always perform the rotation around the center of the image. +This can be particularly useful when combining the operation with +[`CropNative`](@ref). + +Usage +-------------- + + Rotate(degree) + +Arguments +-------------- + +- **`degree`** : `Real` or `AbstractVector` of `Real` that denote + the rotation angle(s) in degree. If a vector is provided, + then a random element will be sampled each time the operation + is applied. + +Examples +-------------- + +```julia +using Augmentor +img = testpattern() + +# rotate exactly 45 degree +augment(img, Rotate(45)) + +# rotate between 10 and 20 degree upwards +augment(img, Rotate(10:20)) + +# rotate one of the five specified degrees +augment(img, Rotate([-10, -5, 0, 5, 10])) +``` + +see also +-------------- + +[`Rotate90`](@ref), [`Rotate180`](@ref), [`Rotate270`](@ref), +[`CropNative`](@ref), [`augment`](@ref) +""" immutable Rotate{T<:AbstractVector} <: AffineOperation degree::T diff --git a/src/operations/scale.jl b/src/operations/scale.jl index 5f862f8e..95bec348 100644 --- a/src/operations/scale.jl +++ b/src/operations/scale.jl @@ -1,3 +1,64 @@ +""" + Scale <: Augmentor.AffineOperation + +Description +-------------- + +Multiplies the image height and image width by the specified +`factors`. This means that the size of the output image depends +on the size of the input image. + +The provided `factors` can either be numbers or vectors of +numbers. + +- If numbers are provided, then the operation is deterministic + and will always scale the input image with the same factors. + +- In the case vectors are provided, then each time the operation + is applied a valid index is sampled and the elements + corresponding to that index are used as scaling factors. + +The scaling is performed relative to the image center, which can +be useful when following the operation with [`CropNative`](@ref). + +Usage +-------------- + + Scale(factors) + + Scale(factors...) + +Arguments +-------------- + +- **`factors`** : `NTuple` or `Vararg` of `Real` or + `AbstractVector` that denote the scale factor(s) for each + array dimension. If only one variable is specified it is + assumed that height and width should be scaled by the same + factor(s). + +Examples +-------------- + +```julia +using Augmentor +img = testpattern() + +# half the image size +augment(img, Scale(0.5)) + +# uniformly scale by a random factor from 1.2, 1.3, or 1.4 +augment(img, Scale([1.2, 1.3, 1.4])) + +# scale by either 0.5x0.7 or by 0.6x0.8 +augment(img, Scale([0.5, 0.6], [0.7, 0.8])) +``` + +see also +-------------- + +[`Zoom`](@ref), [`Resize`](@ref), [`augment`](@ref) +""" immutable Scale{N,T<:AbstractVector} <: AffineOperation factors::NTuple{N,T} diff --git a/src/operations/shear.jl b/src/operations/shear.jl index 15e41648..ee7dfadf 100644 --- a/src/operations/shear.jl +++ b/src/operations/shear.jl @@ -1,3 +1,53 @@ +""" + ShearX <: Augmentor.AffineOperation + +Description +-------------- + +Shear the image horizontally for the given `degree`. This +operation can only be described as an affine transformation and +will in general cause other operations of the pipeline to use +their affine formulation as well (if they have one). + +It will always perform the transformation around the center of +the image. This can be particularly useful when combining the +operation with [`CropNative`](@ref). + +Usage +-------------- + + ShearX(degree) + +Arguments +-------------- + +- **`degree`** : `Real` or `AbstractVector` of `Real` that denote + the shearing angle(s) in degree. If a vector is provided, + then a random element will be sampled each time the operation + is applied. + +Examples +-------------- + +```julia +using Augmentor +img = testpattern() + +# shear horizontally exactly 5 degree +augment(img, ShearX(5)) + +# shear horizontally between 10 and 20 degree to the right +augment(img, ShearX(10:20)) + +# shear horizontally one of the five specified degrees +augment(img, ShearX([-10, -5, 0, 5, 10])) +``` + +see also +-------------- + +[`ShearY`](@ref), [`CropNative`](@ref), [`augment`](@ref) +""" immutable ShearX{T<:AbstractVector} <: AffineOperation degree::T @@ -31,6 +81,56 @@ end # -------------------------------------------------------------------- +""" + ShearY <: Augmentor.AffineOperation + +Description +-------------- + +Shear the image vertically for the given `degree`. This operation +can only be described as an affine transformation and will in +general cause other operations of the pipeline to use their +affine formulation as well (if they have one). + +It will always perform the transformation around the center of +the image. This can be particularly useful when combining the +operation with [`CropNative`](@ref). + +Usage +-------------- + + ShearY(degree) + +Arguments +-------------- + +- **`degree`** : `Real` or `AbstractVector` of `Real` that denote + the shearing angle(s) in degree. If a vector is provided, + then a random element will be sampled each time the operation + is applied. + +Examples +-------------- + +```julia +using Augmentor +img = testpattern() + +# shear vertically exactly 5 degree +augment(img, ShearY(5)) + +# shear vertically between 10 and 20 degree upwards +augment(img, ShearY(10:20)) + +# shear vertically one of the five specified degrees +augment(img, ShearY([-10, -5, 0, 5, 10])) +``` + +see also +-------------- + +[`ShearX`](@ref), [`CropNative`](@ref), [`augment`](@ref) +""" immutable ShearY{T<:AbstractVector} <: AffineOperation degree::T diff --git a/src/operations/zoom.jl b/src/operations/zoom.jl index dc52201e..bbcbae79 100644 --- a/src/operations/zoom.jl +++ b/src/operations/zoom.jl @@ -1,3 +1,68 @@ +""" + Zoom <: Augmentor.Operation + +Description +-------------- + +Scales the image height and image width by the specified +`factors`, but crops the image such that the original size is +preserved. + +The provided `factors` can either be numbers or vectors of +numbers. + +- If numbers are provided, then the operation is deterministic + and will always scale the input image with the same factors. + +- In the case vectors are provided, then each time the operation + is applied a valid index is sampled and the elements + corresponding to that index are used as scaling factors. + +In contrast to [`Scale`](@ref) the size of the output image is +the same as the size of the input image, while the content is +scaled the same way. The same effect could be achieved by +following a [`Scale`](@ref) with a [`CropSize`](@ref), with the +caveat that one would need to know the exact size of the input +image before-hand. + +Usage +-------------- + + Zoom(factors) + + Zoom(factors...) + +Arguments +-------------- + +- **`factors`** : `NTuple` or `Vararg` of `Real` or + `AbstractVector` that denote the scale factor(s) for each + array dimension. If only one variable is specified it is + assumed that height and width should be scaled by the same + factor(s). + +Examples +-------------- + +```julia +using Augmentor +img = testpattern() + +# half the image size +augment(img, Zoom(0.5)) + +# uniformly scale by a random factor from 1.2, 1.3, or 1.4 +augment(img, Zoom([1.2, 1.3, 1.4])) + +# scale by either 0.5x0.7 or by 0.6x0.8 +augment(img, Zoom([0.5, 0.6], [0.7, 0.8])) +``` + +see also +-------------- + +[`Scale`](@ref), [`Resize`](@ref), [`augment`](@ref) +""" immutable Zoom{N,T<:AbstractVector} <: Operation factors::NTuple{N,T}