A command-line toolkit for whole-slide imaging (WSI) files in digital pathology — inspect, edit, and convert slides across every major vendor format, from a single static binary with no runtime dependencies.

wsitools is built for pathology pipelines: edit associated images (like the label) without re-encoding the pyramid, transcode between containers and codecs, generate DeepZoom tiles for web viewers, downsample or crop slides, and check them for structural conformance.

• Inspect — slide summary (levels, codecs, colorspace, metadata), per-IFD and per-tag dumps, content hashing, and structural validation. → info, dump-ifds, hash, validate
• Extract a pixel region — save a rectangular region as a standalone PNG. → region
• Extract an associated image — save the label, macro, thumbnail, or overview as a standalone PNG or JPEG. → extract
• Edit — remove or replace an associated image. The pyramid tile bytes are copied verbatim (no decode/re-encode). → label|macro|thumbnail|overview remove|replace
• Convert & transform — reshape a slide, streaming (no full-resolution raster in memory):
  • Re-container into another format — a lossless tile-copy when the source codec is compatible with the target. → convert --to {cog-wsi, svs, tiff, ome-tiff, dzi, szi, dicom, bif, ife}
  • Transcode the pyramid to a different codec. → convert --codec {jpeg, jpeg2000, jpegxl, avif, webp, htj2k}
  • Downsample to a lower magnification — during a convert, or in place (same container out). → convert --factor N / --target-mag M, or downsample
  • Crop a region — during a convert, or in place. → convert --rect X,Y,W,H, or crop
• App info — report installed codecs and memory limits, or print the version. → doctor, version

Full per-command reference: docs/commands.md.

Reads: Aperio SVS · Hamamatsu NDPI · Philips-TIFF · OME-TIFF · DICOM-WSI · Ventana/Roche BIF · Iris IFE · Leica SCN · generic tiled TIFF · COG-WSI

Writes: SVS · generic TIFF · OME-TIFF · COG-WSI · DICOM-WSI · DeepZoom (DZI) · SZI · BIF · IFE

_{✓* stripped source — decoded and re-encoded into reproducible JPEG tiles rather than bit-exact tile-copied. DICOM-WSI writing is experimental. Full matrix (including OME-OneFrame), convert targets, and per-format caveats: docs/formats.md.}

Download the archive for your platform from the latest release, extract, and run wsitools. Every binary is statically linked and bundles all codecs (jpeg, jpeg2000, htj2k, jpegxl, avif, webp) — no toolchain or libraries needed. Verify with sha256sum -c SHA256SUMS.

macOS binaries are not yet signed or notarized. On first run, clear the quarantine flag with xattr -d com.apple.quarantine wsitools, or allow the binary in System Settings → Privacy & Security. Signing + notarization is planned — see the roadmap.

With Go 1.26+ and the image codec libraries installed (JPEG is the only required one; the rest are optional):

go install github.com/wsilabs/wsitools/cmd/wsitools@latest

Step-by-step instructions for macOS, Linux, and Windows — including a JPEG-only minimal build and how to skip individual codecs — are in docs/INSTALL.md.

# Slide summary (add --json for scripting)
wsitools info slide.svs

# Extract a pixel region as PNG
wsitools region --x 10000 --y 8000 --w 1024 --h 1024 --level 0 -o tile.png slide.svs

# Remove the label image — pyramid bytes untouched, no re-encode
wsitools label remove slide.svs            # → slide_relabeled.svs

# Re-container into COG-WSI (lossless tile-copy when the source codec fits the target)
wsitools convert --to cog-wsi -o slide.cog.tiff slide.svs

# Generate DeepZoom tiles for a web viewer (OpenSeadragon-compatible)
wsitools convert --to dzi -o slide.dzi slide.svs

# Crop a region into the same container (--lossless keeps L0 tiles byte-identical)
wsitools crop --rect 20000,15000,8192,8192 --lossless -o region.svs slide.svs

# Downsample a 40× slide to 20× (same container out)
wsitools downsample -o slide-20x.svs slide-40x.svs

More examples and every flag: docs/commands.md.

• Command reference — every command, flag, and output layout
• Format support — full format × command matrix and caveats
• Installation — per-platform builds, codec selection
• Memory & performance — footprint and the --max-memory limit
• OME-TIFF limitations — what the minimal writer carries
• Roadmap — planned utilities, formats, and signed macOS builds
• Changelog — release notes

make test   # unit + integration tests, race detector
make vet

Integration tests are fixture-gated by WSI_TOOLS_TESTDIR; CI pulls fixtures from wsilabs/wsi-fixtures on every push and PR.

Apache 2.0. See LICENSE.