Crate wsi_rs 

wsi-rs

wsi-rs is a whole-slide image reader focused on deterministic public APIs for TIFF-family WSI, DICOM VL WSI, selected vendor containers, and explicit failure behavior for unsupported inputs.

Quick Start

Read a region in level coordinates as an image::RgbaImage:

use wsi_rs::{LevelIdx, RegionRequest, SceneId, SeriesId, Slide};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let slide = Slide::open("sample.svs")?;
    let region = RegionRequest::builder(SceneId::new(0), SeriesId::new(0), LevelIdx::new(0))
        .origin_px((0, 0))
        .size_px((1024, 1024))
        .build()?;

    let image = slide.read_region_rgba(&region)?;
    image.save("region.png")?;
    Ok(())
}

Tile Reads

Use tile-level APIs for viewers, caches, benchmarks, and workflows that need exact tile coordinates:

use wsi_rs::{LevelIdx, SceneId, SeriesId, Slide, TileOutputPreference, TilePixels, TileRequest};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let slide = Slide::open("sample.svs")?;
    let request = TileRequest::builder(SceneId::new(0), SeriesId::new(0), LevelIdx::new(0))
        .tile(0, 0)
        .build()?;

    match slide.read_tile(&request, TileOutputPreference::cpu())? {
        TilePixels::Cpu(tile) => {
            println!("{}x{} tile", tile.width(), tile.height());
        }
        TilePixels::Device(_) => unreachable!("CPU output was requested"),
        _ => unreachable!("CPU output was requested"),
    }
    Ok(())
}

Re-exports

pub use error::WsiError;

pub use properties::Properties;

Modules

error

output

prelude

Common imports for applications using wsi-rs.

properties

Structs

AssociatedImage

Metadata for an associated image (label, macro, thumbnail).

AxesShape

Axis extents beyond x/y. Default is 2D (z=1, c=1, t=1).

CacheConfig

ChannelInfo

CpuTile

Generic decoded pixel buffer.

Dataset

A whole-slide image file (or set of files for DICOM).

DatasetId

Unique identity for cache keying. 128-bit to avoid truncation collisions.

DecodeExecutionOptions

DecodeRouteDecision

DeviceOutputContext

DisplayWindow

Windowing parameters for high-dynamic-range display conversion.

FormatRegistry

IccProfileKey

Identifies the scene and series an ICC profile applies to.

Level

One resolution level in a pyramid.

LevelIdx

Stable index into Series::levels.

PlaneIdx

Plane index for multi-dimensional axes (z/c/t).

PlaneSelection

Selects a z/c/t plane. Default is (0,0,0) for plain 2D reads.

ProbeResult

Result from a cheap file-format probe.

RawCompressedTile

Raw compressed tile bytes that can be copied into another container without decoding pixels.

RawCompressedTileBuilder

Builder for RawCompressedTile that names payload metadata fields.

ReadCancellationToken

Cloneable cooperative cancellation signal for controlled reads.

ReadControl

Cooperative controls applied to a tile read without changing legacy APIs.

RegionRequest

A region request — used by Slide (public API), not by backends.

RegionRequestBuilder

Builder for RegionRequest.

Scene

A distinct scan region within a dataset.

SceneId

Stable index into Dataset::scenes.

Series

A coherent image pyramid sharing the same axes and sample type.

SeriesId

Stable index into Scene::series.

Slide

Top-level handle. Owns the SlideReader + shared cache.

SlideOpenOptions

SlideReadContext

SourceIccProfile

Source ICC profile bytes plus the normalized key and extraction provenance.

SourceIccProfileConflict

Conflict returned when a source ICC profile would make the legacy map ambiguous.

SourceIccProfileKey

Normalized dataset location for an ICC profile found in source metadata.

SvcacheTileSelection

TileEntry

Per-tile position and size in an Irregular layout.

TileHit

Result of tile intersection computation.

TileRequest

A single-tile request — the backend primitive.

TileRequestBuilder

Builder for TileRequest.

TileViewRequest

A viewer/display-tile request.

TileViewRequestBuilder

Builder for TileViewRequest.

Enums

ColorSpace

Declared color model.

Compression

Compression codec for TIFF tile/strip data.

CpuTileData

Typed, aligned sample storage.

CpuTileLayout

Whether channel samples are interleaved or planar.

DecodeRoute

DeviceTile

Renderer-uploadable device payload. Real payload fields land in Phase 5.

EncodedTilePhotometricInterpretation

Photometric interpretation for an encoded tile payload.

IccProfileProvenance

Provenance for ICC profile bytes extracted from source metadata.

LevelSourceKind

Whether a pyramid level is backed by source pixels or generated by the reader.

OutputBackendRequest

PixelFormat

Concrete pixel format for decoded CPU and device-resident surfaces.

ProbeConfidence

RawCompressedTileBuildError

Error returned by RawCompressedTileBuilder when required metadata is missing.

RequestBuildError

Error returned by public request builders when a required field is missing.

SampleType

SvcachePolicy

TileCodecKind

TileLayout

How tiles are organized at a given level.

TileOutputPreference

TilePixels

Output payload from SlideReader::read_tiles and friends.

Traits

DatasetReader

Opens a file and returns a SlideReader.

FormatProbe

Detects whether a file is a given format. Fast, no full parse.

SlideReader

Phase-2 read interface.

Functions

build_svcache

build_svcache_tile_payloads_merge

build_svcache_tile_payloads_replace

build_svcache_tiles

build_svcache_tiles_replace

cache_dir_svcache_path

default_svcache_path

svcache_candidate_paths

svcache_matches_source