openslide-sharp, a .NET tool that exports OpenSlide slides as Deep Zoom tiles (like openslide-python's deepzoom_tile.py) or as an OME-Zarr store. The native OpenSlide library for Windows x64, Linux x64/arm64 and macOS x64/arm64 is included.
dotnet tool install -g OpenSlideSharp.Tool
openslide-sharp deepzoom slide.svs # slide.dzi and slide_files/
openslide-sharp deepzoom slide.svs -r # slide/ with an HTML viewer
openslide-sharp omezarr slide.svs # slide.zarr/The package is about 37 MB (85 MB installed), as it holds the OpenSlide and SkiaSharp libraries of every platform OpenSlide supports. On Windows, a native library cannot be loaded from a path longer than 260 characters (MAX_PATH), and the libraries sit up to about 180 characters below the tool path. Keep a --tool-path short; the -g location (%USERPROFILE%\.dotnet\tools) is fine.
| Option | Default | |
|---|---|---|
-o, --output <name> |
slide file name without extension | output base name |
-s, --size <pixels> |
254 | tile size |
-e, --overlap <pixels> |
1 | overlap of adjacent tiles |
-f, --format jpeg|png |
jpeg |
tile format |
-Q, --quality <quality> |
90 | JPEG quality, 0 to 100 |
-B, --ignore-bounds |
off | export the entire scan area |
-c, --color-mode default|embed|ignore |
default |
see Color |
-j, --jobs <count> |
processor count | worker threads, at most 4 × the processor count |
-r, --viewer |
off | write a directory with an HTML viewer |
Without -r the output is <name>.dzi and <name>_files/{level}/{col}_{row}.{jpeg|png}. With -r it is a directory <name>/ holding slide.dzi and slide_files/, the same for each associated image under a file-safe name (<slug>.dzi, <slug>_files/, the slug made as deepzoom_tile.py does), index.html and static/ (OpenSeadragon, its scale bar plugin, their images and licenses). The page embeds the DZI documents, so it also works when opened from disk.
| Option | Default | |
|---|---|---|
-o, --output <dir> |
<slide name>.zarr |
output directory |
--ngff 0.5|0.4 |
0.5 |
NGFF 0.5 on Zarr v3, or 0.4 on Zarr v2 |
--chunk <pixels> |
512 | chunk size, 16 to 8192 |
--compression none|gzip |
none |
chunk compression |
--gzip-level <level> |
6 | 0 to 9 |
-B, --ignore-bounds |
off | export the entire scan area |
-c, --color-mode default|ignore |
default |
see Color |
-j, --jobs <count> |
processor count | worker threads, at most 4 × the processor count |
--associated |
off | also export the associated images |
Every key of the store is written as a file, with / in the key as directories. With --associated, each associated image becomes a store of its own, <output>/../<slide name>_associated/<slug>.zarr; an output that is that _associated directory itself is refused (exit code 1).
- Outputs are relative to the current directory unless a path is given.
- Every output directory (
<name>_files/, the-rdirectory<name>/, each.zarrstore, the_associateddirectory) gets an empty.openslide-sharp-outputmarker file before anything else. Existing output is replaced, but an existing output directory only if it holds that marker or is empty. Any other existing directory, a symbolic link or junction where an output directory would go (even one to a directory with the marker), or a file there (such as an extensionless slide with-r), stops the export with exit code 1 and nothing is deleted. Root directories, the current directory and its ancestors, directories holding the slide, and a MIRAX slide's data directory (name/next toname.mrxs) are never deleted. - An output directory being replaced is first renamed to
.<name>.openslide-sharp-old-<id>next to it, in one step; then the old<name>.dziis deleted, before any new file is written, and the renamed directory is deleted. If the rename fails (on Windows, while a program has a file in it open), the export stops with exit code 1 and nothing has changed. If only the delete fails, a warning names what is left and the export goes on; the next export to the same output deletes it (only while it still holds the marker, which is deleted last). - Every file is written to
.<file>.tmpnext to it and then moved into place, so no file is ever partially written. The.dziis written after the tiles, and the OME-Zarr root metadata (zarr.json, or.zgroupand.zattrs) after every chunk and level, so an interrupted export is not mistaken for a complete one. - Progress goes to stderr, at most once a second:
Tiling <image>: <done>/<total> tiles. Warnings (see Color) and errors go to stderr too, prefixed withopenslide-sharp:. - Ctrl+C stops the export once the files being written are complete.
- Before anything is written,
deepzoomchecks that each tile, and the slide region read for it, fits in a .NET array (width × height × 4bytes, just under 2 GiB); with an-sor-etoo large for that it stops with exit code 2. A tile never extends past its level, so a tile size larger than the slide is fine. - Exit codes: 0 on success, 1 if the slide cannot be opened or the export fails, 2 for invalid arguments, 130 when canceled.
-jabove 4 × the processor count is lowered to that, with a note on stderr.
Each worker holds one tile or chunk at a time, and OpenSlide keeps a tile cache of 32 MiB for the slide. On top of that:
deepzoom: aboutjobs × 5 × (size + 2 × overlap)² × 4bytes at most, for the region each worker reads, the tile it scales it to, and the encoded file (about 1.3 MiB per worker with the defaults).omezarr: about(cache + jobs) × chunk² × 4bytes, wherecache = min(max(2 × jobs, 4), max(jobs, 1 GiB / (chunk² × 4)))regions are kept so that the three channels of a chunk are rendered once. With the default 512-pixel chunks that is about3 × jobsMiB; the cache never holds more than 1 GiB, unless the jobs alone need more (one region each, for example 256 MiB per job with--chunk 8192).
The tool's own code is under the MIT license. The package also contains, each under its own license, which are in the package's licenses/ folder or in LICENSE.txt:
- OpenSlide 4.x from openslide-bin, LGPL-2.1, with the libraries built into it (
licenses/openslide-bin/<platform>/, each with aVERSIONS.mdlisting their versions). The source is the openslide-bin source tarball named inlicenses/openslide-bin/openslide-bin.json(URL and sha256). The same file,openslide-bin-<binVersion>.tar.gz, is attached to the GitHub release of the package's version (tagv<version>), which keeps it after a nightly openslide-bin build is removed; check it against that sha256. - SkiaSharp, MIT, with Skia (BSD-3-Clause) and the libraries in its native build (
licenses/skiasharp/). - OpenSeadragon, BSD-3-Clause, and its scale bar plugin, in the public domain (NIST), written with
-r(licenses/viewer/). - System.CommandLine, MIT.
The package license is LICENSE.txt, which states these terms and where each license text is.
Each image (the slide, and each associated image) is handled with its own ICC profile; an image without one is the same in every mode.
default: tiles and chunks are converted to sRGB. If the profile cannot be converted, a warning is written once for the image, Deep Zoom tiles carry the profile instead (unless it is too large for a JPEG), and OME-Zarr chunks are written unconverted.embed(Deep Zoom only): pixels are left as they are and tiles carry the profile.ignore: pixels are left as they are and the profile is dropped.