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.

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