imgal 0.3.0

A fast and open-source scientific image processing and algorithm library.
Documentation

crates.io license

Imgal (IMaGe Algorithm Library) is a fast and open-source scientific image processing and algorithm library. This library is directly inspired by imagej-ops, SciJava Ops, ImgLib2, and the ImageJ2 ecosystem. The imgal library aims to offer users access to fast and well documented image algorithms as a functional programming style library. Imgal is organized as a monorepo with the imgal crate as the core Rust library that contains the algorithm logic while imgal_c, imgal_java and imgal_python serve imgal's C, Java and Python language bindings respectively.

Usage

Using imgal with Rust

To use imgal in your Rust project add it to your crate's dependencies and import the desired algorithm namespaces.

[dependencies]
imgal = "0.3.0"

The example below demonstrates how to create a 3D linear gradient image (with variable offset, scale and size) and perform simple image statistics and thresholding:

use imgal::prelude::*;
use imgal::simulation::gradient::linear_gradient_3d;
use imgal::statistics::{min_max, sum};
use imgal::threshold::global::otsu_value;

fn main() -> Result<(), ImgalError> {
    // create 3D linear gradient data
    let offset = 5;
    let scale = 20.0;
    let shape: (usize, usize, usize) = (50, 50, 50);
    let data = linear_gradient_3d(offset, scale, shape);

    // calculate the Otsu threshold value with an image histogram of 256 bins
    // with 4 parallel threads
    let threshold = otsu_value(&data, Some(256), Some(4))?;

    // print image statistics and Otsu threshold
    println!("[INFO] min/max: {:?}", min_max(&data, None)?);
    println!("[INFO] sum: {}", sum(&data, None));
    println!("[INFO] otsu threshold: {}", threshold);
    Ok(())
}

Running this example with cargo run returns the following to the console:

[INFO] min/max: (0.0, 880.0)
[INFO] sum: 49500000
[INFO] otsu threshold: 417.65625

Building from source

Although its not particularly useful on its own, you can build the imgal core Rust library from the root of the repository with:

$ cargo build --release

[!NOTE]

--release is necessary to compile speed optimized libraries and utilize compiler optimizations.

Benchmarks

Imgal uses divan for benchmarks. You can run all the benchmarks at once with:

$ cargo bench

Or all the benchmarks in a given namespace (e.g. statistics) with:

$ cargo bench -- statistics

Or a specific subset of benchmarks (i.e. run only the parallel statistics benchmarks):

$ cargo bench --bench statistics -- parallel

Documentation

Each function in imgal is documented and published on docs.rs.

License

Imgal is a dual-licensed project with your choice of: