ndarray-ndimage 0.6.0

Multidimensional image processing for ArrayBase, the n-dimensional array data structure provided by ndarray.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

#![warn(missing_docs, trivial_casts, trivial_numeric_casts, unused_qualifications)]

//! The `ndarray-image` crate provides multidimensional image processing for `ArrayBase`,
//! the *n*-dimensional array data structure provided by [`ndarray`].

use ndarray::{arr3, Array, Array3, ArrayRef, ArrayRef3, Dimension, ShapeBuilder};

mod filters;
mod interpolation;
mod measurements;
mod morphology;
mod pad;

pub use filters::{
    con_corr::{convolve, convolve1d, correlate, correlate1d, prewitt, sobel},
    gaussian::{gaussian_filter, gaussian_filter1d},
    median::median_filter,
    min_max::{
        maximum_filter, maximum_filter1d, maximum_filter1d_to, minimum_filter, minimum_filter1d,
        minimum_filter1d_to,
    },
    uniform::{uniform_filter, uniform_filter1d},
    BorderMode,
};
pub use interpolation::{shift, spline_filter, spline_filter1d, zoom};
pub use measurements::{label, label_histogram, largest_connected_components, most_frequent_label};
pub use morphology::{binary_closing, binary_dilation, binary_erosion, binary_opening};
pub use pad::{pad, pad_to, PadMode};

/// 3D mask
pub type Mask = Array3<bool>;

/// 3D common kernels. Also called Structuring Element.
#[derive(Clone, Debug, PartialEq)]
pub enum Kernel3d {
    /// Diamond/star kernel (center and sides).
    ///
    /// Equivalent to SciPy `generate_binary_structure(3, 1)`.
    Star,
    /// Ball kernel (center and sides).
    ///
    /// Equivalent to SciPy `generate_binary_structure(3, 2)`.
    Ball,
    /// 3x3x3 cube.
    ///
    /// Equivalent to SciPy `generate_binary_structure(3, 3)`.
    Full,
}

impl Kernel3d {
    /// Generate a binary 3D kernel.
    pub fn generate(&self) -> Array3<bool> {
        match self {
            Kernel3d::Star => arr3(&[
                [[false, false, false], [false, true, false], [false, false, false]],
                [[false, true, false], [true, true, true], [false, true, false]],
                [[false, false, false], [false, true, false], [false, false, false]],
            ]),
            Kernel3d::Ball => arr3(&[
                [[false, true, false], [true, true, true], [false, true, false]],
                [[true, true, true], [true, true, true], [true, true, true]],
                [[false, true, false], [true, true, true], [false, true, false]],
            ]),
            Kernel3d::Full => Array3::from_elem((3, 3, 3), true),
        }
    }
}

/// Utility function that returns a new *n*-dimensional array of dimension `shape` with the same
/// datatype and memory order as the input `arr`.
pub fn array_like<A, D, Sh>(arr: &ArrayRef<A, D>, shape: Sh, elem: A) -> Array<A, D>
where
    A: Clone,
    D: Dimension,
    Sh: ShapeBuilder<Dim = D>,
{
    // TODO `is_standard_layout` only works on owned arrays. Change it if using `ArrayBase`.
    if arr.is_standard_layout() {
        Array::from_elem(shape, elem)
    } else {
        Array::from_elem(shape.f(), elem)
    }
}

/// Utilitary function that returns the mask dimension minus 1 on all dimensions.
pub fn dim_minus<A>(mask: &ArrayRef3<A>, n: usize) -> (usize, usize, usize)
where
    A: Clone,
{
    let (width, height, depth) = mask.dim();
    (width - n, height - n, depth - n)
}

// TODO Use x.round_ties_even() when available on stable
// https://github.com/rust-lang/rust/issues/96710
fn round_ties_even(x: f64) -> f64 {
    let i = x as i32;
    let f = (x - i as f64).abs();
    if f == 0.5 {
        if i & 1 == 1 {
            // -1.5, 1.5, 3.5, ...
            (x.abs() + 0.5).copysign(x)
        } else {
            (x.abs() - 0.5).copysign(x)
        }
    } else {
        x.round()
    }
}

#[cfg(test)]
mod tests {
    use crate::round_ties_even;

    #[test]
    fn test_round_ties_even() {
        assert_eq!(round_ties_even(-2.51), -3.0);
        assert_eq!(round_ties_even(-2.5), -2.0);
        assert_eq!(round_ties_even(-1.5), -2.0);
        assert_eq!(round_ties_even(-0.5), -0.0);
        assert_eq!(round_ties_even(-0.1), 0.0);
        assert_eq!(round_ties_even(-0.0), 0.0);
        assert_eq!(round_ties_even(0.0), 0.0);
        assert_eq!(round_ties_even(0.1), 0.0);
        assert_eq!(round_ties_even(0.5), 0.0);
        assert_eq!(round_ties_even(1.5), 2.0);
        assert_eq!(round_ties_even(2.5), 2.0);
        assert_eq!(round_ties_even(2.51), 3.0);
    }
}