emmt / LocalFilters.jl

Multi-dimensional local filters (convolution, mathematical morphology, etc.) for Julia.
Other
36 stars 5 forks source link
convolution julia-language mathematical-morphology multi-dimensional

LocalFilters.jl

Doc. Dev Doc. Stable License Build Status Build Status Coverage

Julia package LocalFilters implements multi-dimensional local filters such as discrete convolution or correlation, local mean, mathematical morphology, etc., and provides support to build custom local filters.

The Reference Manual provides more exhaustive documentation. This page summarizes the principles and the features of LocalFilters. This document is structured as follows:

Packages with overlapping functionalities:

Available filters

LocalFilters provides a number of linear and non-linear filters. All methods have an in-place counterpart which can be called to avoid allocations.

Linear filters

LocalFilters provides the following linear filters:

Mathematical morphology

LocalFilters implements the following mathematical morphology operations:

In mathematical morphology, the structuring element B defines the local neighborhood of each index in the source array. It can be a sliding hyper-rectangular Cartesian window or an array of Booleans to define a more complex neighborhood shape. If B is a single odd integer (as it is by default), the structuring element is assumed to be a sliding window of size B along every dimension of A.

Other non-linear filters

LocalFilters provides an instance of the bilateral filter:

Build your own filters

In LocalFilters, a local filtering operation, say dst = filter(A, B) with A the source of the operation and B the neighborhood or the kernel associated with the filter, is implemented by the following pseudo-code:

for i ∈ indices(dst)
    v = initial isa Function ? initial(A[i]) : initial
    for j ∈ indices(A) ∩ (indices(B) + i)
        v = update(v, A[j], B[j-i])
    end
    dst[i] = final(v)
end

where indices(A) denotes the set of indices of A while indices(B) + i denotes the set of indices j such that j - i ∈ indices(B) with indices(B) the set of indices of B. In other words, j ∈ indices(A) ∩ (indices(B) + i) means all indices j such that j ∈ indices(A) and j - i ∈ indices(B), hence A[j] and B[j-i] are in-bounds.In LocalFilters, indices i and j are Cartesian indices for multi-dimensional arrays, thus indices(A) is the analogous of CartesianIndices(A) in Julia in that case. For vectors, indices i and j are linear indices.

The behavior of the filter is completely determined by the neighborhood or kernel B, by the type of the state variable v initialized by initial for each entry of the destination, and by the methods update and final.

Such a filter can be applied by calling localfilter! as:

localfilter!(dst, A, B, initial, update, final = identity) -> dst

As shown by the following examples, this simple scheme allows the implementation of a variety of linear and non-linear local filters:

Installation

To install the last official version, press the ] key to enter Julia's Pkg REPL mode and type:

add LocalFilters

at the ... pkg> prompt.

The LocalFilters package is pure Julia code and nothing has to be build.