OpenSlide Rust

Rust bindings to OpenSlide (https://openslide.org/).

This work has no affiliations with the official OpenSlide project.

Requirements

This library has been built for

OpenSlide 3.4.1
Rust 1.30

I cannot guarantee that it works for other versions.

Building OpenSlide

Download the OpenSlide 3.4.1 from https://openslide.org/download/ to some location (here, DOWNLOAD_DIR)

Build the project somewhere (here, BUILD_DIR):

cd BUILD_DIR
tar xvzf DOWNLOAD_DIR/openslide-3.4.1.tar.gz
cd openslide-3.4.1
./configure
make
sudo make install

In the build output, you will see something like this

Libraries have been installed in:
   /usr/local/lib

To make the library discoverable, we append it (call it LIB_DIR) to the LD_LIBRARY_PATH environment variable

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:LIB_DIR

You should now be able to compile, and run a project using this OpenSlide binding. See the examples folder for examples.

Interface

This library provides both a native interface, and a more convenient interface.

Native interface

The native interface contains the raw bindings to the OpenSlide API, without any fluff. This interface should be close to the C interface in the original library, both with regards to function naming and documentation. This serves at least two purposes:

1: You can easily use the documentation for the C library 2: If you are not happy with my convenience wrappers, you could use this raw api to create your own.

//! Example using the raw binding api

extern crate failure;
extern crate openslide;

use failure::Error;
use openslide::bindings;

fn main() -> Result<(), Error> {
    let filename = "assets/CMU-1-Small-Region.svs";
    let osr = bindings::open(filename)?;
    let num_levels = bindings::get_level_count(osr)?;
    println!("Slide has {} levels", num_levels);
    bindings::close(osr);

    Ok(())
}

Note that few or none assertions are made on correct use (like checking for valid number of levels or non-negative zoom factors). Also, as shown in the small example above, you have to close the slide explicitly.

Convenience interface

The convenience interface wraps the native interface and provides a more rust-like interface. These wrappings will enforce correct use via the type system and other checks. There is also no need to explicitly close an open slide, as the OpenSlide struct implements the Drop trait.

//! Example using the convenience binding api

extern crate failure;
extern crate openslide;

use std::path::Path;
use failure::Error;
use openslide::OpenSlide;

fn main() -> Result<(), Error> {
    let filename = Path::new("assets/CMU-1-Small-Region.svs");
    let os = openslide::OpenSlide::new(&filename)?;
    let num_levels = os.get_level_count()?;
    println!("Slide has {} levels", num_levels);

    Ok(())
}