API References

local_binary_pattern([method], X; kwargs...)

Compute the local binary pattern of gray image X using LBP method method.

Arguments

• method::LocalBinaryPattern: the method used to calculate the LBP values.
• X::AbstractMatrix: the input image matrix. For colorful images, one can manually convert it to some monochrome space, e.g., Gray, the L-channel of Lab. One could also do channelwise LBP and then concatenate together.

Parameters

The parameters control whether and what degree additional encoding passses are used to compute more patterns that are more robust/invariant to certain changes, e.g., rotation. The following lists are ordered as encoding order. For example, if rotation=true and uniform_degree=2, then rotation encoding will be applied first.

• rotation=false: set true to generate patterns that are invariant to rotation [3]. For example, pattern 0b00001101 is equivalent to 0b01000011 when rotation=true.
• uniform_degree: the threshold number of pattern uniform degree. From [2] a typical choice is 2.If it is nothing(default value) then no uniform encoding is applied.

Examples

The following example uses O-LBP (original LBP) [1-4].

julia> X = [6 7 9; 5 6 3; 2 1 7]
3×3 Matrix{Int64}:
 6  7  9
 5  6  3
 2  1  7

julia> local_binary_pattern(X)[2,2] # 0b1010_1001
0xa9

julia> local_binary_pattern(X; rotation=true)[2,2] #0b0011_0101
0x35

julia> local_binary_pattern(X; uniform_degree=2)[2,2] # miscellaneous pattern
0x09

The following example uses MB-LBP(multi-block LBP) [6-7].

julia> X = zeros(Int, 9, 9); X[1:3, 1:3] .= 50; X[4:6, 4:6] .= 1; X[7:9, 7:9] .= 50; X
9×9 Matrix{Int64}:
 50  50  50  0  0  0   0   0   0
 50  50  50  0  0  0   0   0   0
 50  50  50  0  0  0   0   0   0
  0   0   0  1  1  1   0   0   0
  0   0   0  1  1  1   0   0   0
  0   0   0  1  1  1   0   0   0
  0   0   0  0  0  0  50  50  50
  0   0   0  0  0  0  50  50  50
  0   0   0  0  0  0  50  50  50

julia> local_binary_pattern(LBP((3,3)), X)[4, 4] # 0b1000_0001
0x81

julia> local_binary_pattern(LBP((3,3)), X; rotation=true)[4, 4] # 0b0000_0011
0x03

julia> local_binary_pattern(LBP((3,3)), X; uniform_degree=2)[4, 4] # miscellaneous pattern
0x09

Extended help

Local binary pattern

The following is how local binary pattern is calculated, the original version[1]:

3x3 block     center-thresholded     weights         multiplied by weights      sum
6  7  9         1  1  1              1  8  32          1   8  32
5  6  3  ==>    0  x  0     ==>      2  x  64  ==>     0   x  0            ==>  169
2  1  7         1  0  1              4  16 128         0   0  128

Any binary pattern of length 8, i.e., the center-thresholded result, can be uniquely represented as an UInt8 value; the weighted sum is the encoding process.

Multi-block local binary pattern

This is usually called MB-LBP[5] or Locally Assembled Binary (LAB) feature[6] in the literature. The following is how the block-version of local binary pattern computed with block_size=(3, 3).

```text 2 3 2 | 7 6 6 | 2 1 3 1 2 3 | 5 3 4 | 7 7 3 6 5 4 | 1 4 5 | 1 5 8 –––––––––––––––- sum compare weighted sum 1 2 3 | 1 7 3 | 8 3 7 28 41 37 0 1 0 0 8 0 1 2 1 | 4 3 6 | 5 2 2 ==> 20 38 45 ==> 0 x 1 ==> 0 x 64 ==> 200 1 2 7 | 5 3 6 | 4 7 7 33 31 39 0 0 1 0 0 128 –––––––––––––––- 4 2 4 | 8 1 5 | 3 7 7 5 7 4 | 1 1 1 | 3 4 3 3 3 1 | 5 1 8 | 1 8 3

Rotation-invariant encoding

The rotation-invariant encoding is to map all elements in the bitrotation equivalent class to the minimal value of this class. For example, 0b11010000 and 0b01000011 belongs to the same class because bitrotate(0b01000011, -2) == 0b11010000, thus both values are mapped to 0b00001101. See also Eq.(8) in [2].

For 3x3 neighborhood matrix, applying rotation-invariant encoding decreases the possible number of binary patterns from $256$ to $36$.

The interpolation-based version provides more robust result for rotation-invariant pattern, see [2,4] for more details.

Uniform encoding

Authors of [2] states that certain local binary patterns are fundamental properties of texture, providing the vast majority, sometimes over 90 percent, of all 3x3 patterns. Those patterns are called "uniform" as they contain very few spatial transitions. Uniform degree is an additional encoding pass that controls at what circumstances can we set the block to miscellaneous class.

For example, in 8-bit mode, if uniform_degree=2, then 0b00001101 will be encoded as 9 (type miscellaneous) because it has $3$ bit transitions, and 0b00001100 will be unchanged because it only has $2$ bit transitions.

References

• [1] T. Ojala, M. Pietikäinen, and D. Harwood, “A comparative study of texture measures with classification based on featured distributions,” Pattern Recognition, vol. 29, no. 1, pp. 51–59, Jan. 1996, doi: 10.1016/0031-3203(95)00067-4.
• [2] T. Ojala, M. Pietikäinen, and T. Mäenpää, “A Generalized Local Binary Pattern Operator for Multiresolution Gray Scale and Rotation Invariant Texture Classification,” in Advances in Pattern Recognition — ICAPR 2001, vol. 2013, S. Singh, N. Murshed, and W. Kropatsch, Eds. Berlin, Heidelberg: Springer Berlin Heidelberg, 2001, pp. 399–408. doi: 10.1007/3-540-44732-6_41.
• [3] Pietikäinen, Matti, Timo Ojala, and Zelin Xu. "Rotation-invariant texture classification using feature distributions." Pattern recognition 33.1 (2000): 43-52.
• [4] T. Ojala, M. Pietikainen, and T. Maenpaa, “Multiresolution gray-scale and rotation invariant texture classification with local binary patterns,” IEEE Trans. Pattern Anal. Machine Intell., vol. 24, no. 7, pp. 971–987, Jul. 2002, doi: 10.1109/TPAMI.2002.1017623.
• [5] Zhang, Lun, et al. "Face detection based on multi-block lbp representation." International conference on biometrics. Springer, Berlin, Heidelberg, 2007.
• [6] Yan, Shengye, et al. "Locally assembled binary (LAB) feature with feature-centric cascade for fast and accurate face detection." 2008 IEEE Conference on Computer Vision and Pattern Recognition. IEEE, 2008.

local_binary_pattern([method], X, npoints, radius, interpolation=Linear(); [rotation], [uniform_degree])

Compute the local binary pattern of gray image X using the interpolation-based original method with circular neighborhood matrix.

This produces better result for rotation=true case but is usually slower than the plain 3x3 matrix version local_binary_pattern([method], X).

Arguments

• method::LocalBinaryPattern: the method used to calculate the LBP values.
• X::AbstractMatrix: the input image matrix. For colorful images, one can manually convert it to some monochrome space, e.g., Gray, the L-channel of Lab. One could also do channelwise LBP and then concatenate together.
• npoints::Int(4 ≤ npoints ≤ 32): the number of (uniform-spaced) neighborhood points.
• radius::Real(radius ≥ 1.0): the radius of the circular. Larger radius computes the pattern of a larger local window/block.
• interpolation::Union{Degree, InterpolationType}=Linear(): the interpolation method used to generate non-grid pixel value. In most cases, Linear() are good enough. One can also try other costly interpolation methods, e.g., Cubic(Line(OnGrid()))(also known as "bicubic"), Lanczos(). See also Interpolations.jl for more choices.

Examples

julia> X = [6 7 9; 5 6 3; 2 1 7]
3×3 Matrix{Int64}:
 6  7  9
 5  6  3
 2  1  7

julia> local_binary_pattern(X, 4, 1) # 4-neighbor with circular radius 1
3×3 Matrix{UInt32}:
 0x00000001  0x00000001  0x00000000
 0x00000003  0x00000002  0x0000000e
 0x00000002  0x00000007  0x00000000

julia> local_binary_pattern(X, 4, 1; rotation=true)
3×3 Matrix{UInt32}:
 0x00000001  0x00000001  0x00000000
 0x00000003  0x00000001  0x00000007
 0x00000001  0x00000007  0x00000000

References

• [1] T. Ojala, M. Pietikainen, and T. Maenpaa, “Multiresolution gray-scale and rotation invariant texture classification with local binary patterns,” IEEE Trans. Pattern Anal. Machine Intell., vol. 24, no. 7, pp. 971–987, Jul. 2002, doi: 10.1109/TPAMI.2002.1017623.

average_mode(X, I, offsets) -> value
local_binary_pattern(average_mode, X, args...; kwargs...)

Compute the local binary pattern using the average mode of the block. This is also called mLBP (modified LBP) in the literature [1].

Original local binary pattern compares the neighbors with the center value X[I], this modified version instead uses the mean value of the block.

See also center_mode for original LBP version.

References

• [1] Wikipedia contributors. "Local binary patterns." Wikipedia, The Free Encyclopedia. Wikipedia, The Free Encyclopedia, 17 Nov. 2021. Web. 1 Jan. 2022.

rotation_encoding_table(T, nbits)
rotation_encoding_table(T, X::AbstractUnitRange)

Build the rotation-invariant encoding table. If global runtime cache exists, then reuse it.

RotationEncodingTable{T<:Unsigned}(X)

The lookup table for the quotient space constructed using bitrotate equivalance relation on bit representation of datatype T.

By definition, $a$ is equivalant to $b$($a ~ b$) if there exists $n$ such that bitrotate(a, n) == b.

This equivalance class gives a unique encoding map from $x∈X$ to $a$, where $a$ is the minimal value of the equivalance class $[x]$. For instance, the equivalance class of 0b10101001 (UInt8) is

0b10101001 # 169
0b01010011 # 83
0b10100110 # 166
0b01001101 # 77
0b10011010 # 154
0b00110101 # 53
0b01101010 # 106
0b11010100 # 212

thus f(169) == 0x35 == 53.

julia> using LocalBinaryPatterns: RotationEncodingTable

julia> X = RotationEncodingTable{UInt8}(0:255);

julia> X[169] # 53
0x35

julia> X = RotationEncodingTable{UInt8}(128:255);

julia> X[169] # 154
0x9a

The values in the lookup table is implemented in lazy cache manner so the real computation only happens once at the first retrieval.

This lookup table is used to build an efficient implementation of rotation-invariant local binary pattern [1].

References

• [1] T. Ojala, M. Pietikäinen, and T. Mäenpää, “A Generalized Local Binary Pattern Operator for Multiresolution Gray Scale and Rotation Invariant Texture Classification,” in Advances in Pattern Recognition — ICAPR 2001, vol. 2013, S. Singh, N. Murshed, and W. Kropatsch, Eds. Berlin, Heidelberg: Springer Berlin Heidelberg, 2001, pp. 399–408. doi: 10.1007/3-540-44732-6_41.

uniform_encoding_table(T, X::AbstractUnitRange, degree::Int)

Get the encoding table of X using uniform degree filter.

A uniform degree filter is defined as f(x) = U(x) > degree ? P+1 : x, where P is number of bits of x, and U(x) is the circular bit transition of x with bit representation of datatype T.

For example, 0b0000001 has $2$ bit transitions thus is unchanged, while 0b00000101 has $4$ bit transitions. The transition is count in circular sense, i.e., the highest and lowest bits are also compared.

julia> using LocalBinaryPatterns: uniform_encoding_table

julia> X = uniform_encoding_table(UInt8, 0:255, 2);

julia> X[0b0000001]
0x01

julia> X[0b0000101] # miscellaneous
0x09

This function is used to distinguish local binary patterns from texture patterns and miscellaneous patterns. See [1] for more information.

References

• [1] T. Ojala, M. Pietikäinen, and T. Mäenpää, “A Generalized Local Binary Pattern Operator for Multiresolution Gray Scale and Rotation Invariant Texture Classification,” in Advances in Pattern Recognition — ICAPR 2001, vol. 2013, S. Singh, N. Murshed, and W. Kropatsch, Eds. Berlin, Heidelberg: Springer Berlin Heidelberg, 2001, pp. 399–408. doi: 10.1007/3-540-44732-6_41.