wsic package

Subpackages

Submodules

wsic.cli module

Console script for wsic.

class wsic.cli.MutuallyExclusiveOption(*args, **kwargs)[source]

Bases: Option

Click Option to enforce mutual exclusivity with other options.

handle_parse_result(ctx, opts, args)[source]

Handle parse result.

wsic.cli.get_writer_class(out_path, writer)[source]

Get writer class for given extension and writer.

Parameters:

  • out_path (Path) – Output path.

  • writer (str) – Writer.

Returns:

Writer class.

Return type:

wsic.writers.Writer

wsic.codecs module

Custom codecs for wsic.

wsic.codecs.register_codecs()[source]

Add additional codecs to the numcodecs registry.

Codecs from imagecodecs include: - JPEG - PNG - DEFLATE - JPEG 2000 - JPEG-LS - JPEG XR - JPEG XL - WebP

Return type:

None

wsic.enums module

Enumerated types used by wsic.

class wsic.enums.Codec(value)[source]

Bases: str, Enum

Compression codecs / algorithms / formats.

AVIF = 'AVIF'
BLOSC = 'Blosc'
BLOSC2 = 'Blosc2'
BROTLI = 'Brotli'
BZ2 = 'BZ2'
DEFLATE = 'DEFLATE'
DELTA = 'Delta'
GIF = 'GIF'
GZIP = 'GZIP'
J2K = 'J2K'
JPEG = 'JPEG'
JPEG2000 = 'JPEG 2000'
JPEGLS = 'JPEG-LS'
JPEGXL = 'JPEG XL'
JPEGXR = 'JPEG XR'
LERC = 'LERC'
LJPEG = 'LJPEG'
LZ4 = 'LZ4'
LZ4F = 'LZ4F'
LZ77 = 'LZ77'
LZMA = 'LZMA'
LZW = 'LZW'
NONE = 'None'
PACKBITS = 'PackBits'
PNG = 'PNG'
QOI = 'QOI'
SNAPPY = 'Snappy'
WEBP = 'WebP'
ZFP = 'ZFP'
ZLIB = 'Zlib'
ZLIBNG = 'ZlibNG'
ZOPFLI = 'Zopfli'
ZSTD = 'Zstd'
condensed()[source]

Convert to a string without spaces or dashes.

Return type:

str

classmethod from_dicom_transfer_syntax(uid)[source]

Convert DICOM UID to Compression enum.

Parameters:

uid (str) –

Return type:

Codec

classmethod from_string(string)[source]

Convert string to Compression enum.

Parameters:

string (str) –

Return type:

Codec

classmethod from_tiff(compression)[source]

Convert TIFF compression value to Compression enum.

Parameters:

compression (int) – TIFF compression value.

Return type:

Codec

to_dicom_transfer_syntax(lossless=True)[source]

Convert to a DICOM UID (str) for transfer syntax.

Parameters:

lossless (bool) –

Return type:

str

to_numcodecs_config(level=None, dtype=None)[source]

Convert to numcodecs Codec ID string.

Parameters:

  • level (Number | None) –

  • dtype (str | None) –

Return type:

Dict[str, Any]

class wsic.enums.ColorSpace(value)[source]

Bases: str, Enum

Color spaces.

BT1700 = 'YUV'
BT601 = 'YCbCr'
CIELAB = 'CIE L*a*b*'
CIELUV = 'CIE L*u*v*'
CMYK = 'CMYK'
CMYKA = 'CMYKA'
GRAY = 'Grey'
GRAYSCALE = 'Grey'
GREY = 'Grey'
GREYSCALE = 'Grey'
HSL = 'HSL'
HSV = 'HSV'
LINEAR = 'Linear'
LLAB = 'LLAB'
LMS = 'LMS'
MINISBLACK = 'Grey'
MINISWHITE = 'Min is White'
OKLAB = 'OKLab'
PALETTE = 'Palette'
REC601 = 'YCbCr'
RGB = 'RGB'
RGBA = 'RGBA'
RLAB = 'RLAB'
SRGB = 'RGB'
XYB = 'XYB'
YCBCR = 'YCbCr'
YCC = 'YCoCg'
YCOCG = 'YCoCg'
YCRCB = 'YCrCb'
YUV = 'YUV'
condensed()[source]

Convert to a string without spaces, dashes, and asterisks.

Return type:

str

classmethod from_dicom(photometric)[source]

Convert DICOM value to ColorSpace enum.

Parameters:

photometric (str) – DICOM photometric value.

Return type:

ColorSpace

classmethod from_string(string)[source]

Convert string to ColorSpace enum.

Parameters:

string (str) –

Return type:

Codec

classmethod from_tiff(photometric, compression=None)[source]

Convert TIFF value to ColorSpace enum.

Parameters:

  • photometric (int) – TIFF photometric value.

  • compression (int | None) – TIFF compression value.

Return type:

ColorSpace

to_dicom_photometric_interpretation(subsampling=(4, 2, 2))[source]

Convert to DICOM photometric interpretation.

Parameters:

subsampling (Tuple[int, int]) –

Return type:

str

to_jp2()[source]

Convert to JPEG2000 color space.

Return type:

ColorSpace

to_tiff()[source]

Convert to tifffile compatible color space.

Return type:

ColorSpace

wsic.magic module

Detect file type by searching for signatures (magic numbers).

class wsic.magic.Incantation(spells)[source]

Bases: object

Perform a sequence of spells.

Spells are performed in order and nesting of spells is supported.

Nesting defines alternating conjunction and disjunction of spells. For example, ALL top level spell or sequence of spells must succeed, ANY one of the second level spell must succeed, etc.

Examples:

>>> # Both of the following spell must succeed to return True:
>>> Incantation(
...     spells=[
...         Spell(b'\x0A'),
...         Spell(b'\x0B'),
...     ],
... )

>>> # Either of the following spell must succeed to return True:
>>> Incantation(
...     spells=[[
...         Spell(b'\x0A'),
...         Spell(b'\x0B'),
...     ]],
... )
Parameters:

  • spells (Sequence[Union[Sequence[Spell], Spell]]) – The sequence of Spells to perform.

  • data (Union[bytes, mmap.mmap]) – The data to perform the incantation on.

static conjunction(spells, data)[source]

Check that ALL spells succeed.

Parameters:

  • spells (Spell | Sequence[Spell]) –

  • data (bytes | mmap) –

Return type:

bool

static disjunction(spells, data)[source]

Check that ANY spell succeeds.

Parameters:

  • spells (Spell | Sequence[Spell]) –

  • data (bytes | mmap) –

Return type:

bool

perform(data)[source]

Check that the incantation succeeds.

Parameters:

data (bytes | mmap) –

Return type:

bool

spells: Sequence[Sequence[Spell] | Spell]
class wsic.magic.Spell(magic, offset=0)[source]

Bases: object

A magic number (or regex) and optional offset to search for in data.

When the spell is ‘performed’ it will return True if the data contains the magic. Magic can be a bytes object (AKA a magic number) or a compiled regular expression.

Parameters:

  • magic (bytes or re.Pattern) – The magic to search for.

  • offset (int, optional) – The offset to start searching from. None means that the magic may be anywhere.

magic: bytes | Pattern
offset: int | None = 0
perform(data)[source]

Check if data contains magic.

Parameters:

data (bytes or mmap.mmap) – The data to search.

Returns:

True if the spell was successful, i.e. if the data contains magic.

Return type:

bool

wsic.magic.header_bytes(header_length, file_handle)[source]

Read in bytes from the start as a header for checking.

If 0 or None is given for header_length, the entire file is memory mapped.

Parameters:

  • header_length (int) – The number of bytes to read from the start of the file. If 0 or None, the entire file is memory mapped and checked.

  • file_handle (file) – The file handle to read from.

Returns:

The header bytes or memory mapped bytes.

Return type:

bytes | mmap

wsic.magic.pentagram()[source]

Print a pentagram.

Return type:

None

wsic.magic.summon_file_types(path, header_length=1024)[source]

Perform a series of incantations to determine the file types.

A list of types is returned becuse the file may contain multiple magic numbers or patterns. E.g. a file may be

Parameters:

  • path (PathLike) – The path to the file.

  • header_length (int, optional) – The number of bytes at the start of the file to read for checking. If None, the entire file is memory mapped and checked.

Returns:

A list of file types for which this file has the correct magic.

Return type:

List[Tuple[str, …]]

wsic.multiprocessing module

wsic.readers module

class wsic.readers.DICOMWSIReader(path)[source]

Bases: Reader

Reader for DICOM Whole Slide Images (WSIs) using wsidicom.

DICOM Whole Slide Imaging: https://dicom.nema.org/Dicom/DICOMWSI/

Parameters:

path (Path) –

get_tile(index, decode=True)[source]

Get tile at index.

Parameters:

  • index (Tuple[int, int]) – The index of the tile to get.

  • decode (bool, optional) – Whether to decode the tile. Defaults to True.

Returns:

The tile at index.

Return type:

np.ndarray

performance_check()[source]

Check attributes of the file and warn if they are not optimal.

A ‘DimensionOrganizationType’ of TILED_SPARSE versus TILED_FULL will negatively impact performance.

Return type:

None

class wsic.readers.JP2Reader(path)[source]

Bases: Reader

Reader for JP2 files using glymur.

Parameters:

path (Path) – Path to file.

thumbnail(shape, approx_ok=False)[source]

Generate a thumbnail image of (or near) the requested shape.

Parameters:

  • shape (Tuple[int, ...]) – Shape of the thumbnail.

  • approx_ok (bool) – If True, return a thumbnail that is approximately the requested shape. It will be equal to or larger than the requested shape (the next largest shape possible via an integer block downsampling).

Returns:

Thumbnail.

Return type:

np.ndarray

class wsic.readers.OpenSlideReader(path)[source]

Bases: Reader

Reader for OpenSlide files using openslide-python.

Parameters:

path (Path) –

get_tile(index, decode=True)[source]

Get tile at index.

Parameters:

  • index (Tuple[int, int]) – The index of the tile to get.

  • decode (bool, optional) – Whether to decode the tile. Defaults to True.

Returns:

The tile at index.

Return type:

np.ndarray

class wsic.readers.Reader(path)[source]

Bases: ABC

Base class for readers.

Parameters:

path (str | Path) –

classmethod from_file(path)[source]

Return reader for file.

Parameters:

path (Path) – Path to file.

Returns:

Reader for file.

Return type:

Reader

get_tile(index, decode=True)[source]

Get tile at index.

Parameters:

  • index (Tuple[int, int]) – The index of the tile to get.

  • decode (bool, optional) – Whether to decode the tile. Defaults to True.

Returns:

The tile at index.

Return type:

np.ndarray

property original_shape: Tuple[int, ...]

Return the original shape of the image.

static pbar(iterable, *args, **kwargs)[source]

Return an iterator that displays a progress bar.

Uses tqdm if installed, otherwise falls back to a simple iterator.

Parameters:

  • iterable (Iterable) – Iterable to iterate over.

  • args (tuple) – Positional arguments to pass to tqdm.

  • kwargs (dict) – Keyword arguments to pass to tqdm.

Returns:

Iterator that displays a progress bar.

Return type:

Iterator

thumbnail(shape, approx_ok=False)[source]

Generate a thumbnail image of (or near) the requested shape.

Parameters:

  • shape (Tuple[int, ...]) – Shape of the thumbnail.

  • approx_ok (bool) – If True, return a thumbnail that is approximately the requested shape. It will be equal to or larger than the requested shape (the next largest shape possible via an integer block downsampling).

Returns:

Thumbnail.

Return type:

np.ndarray

class wsic.readers.TIFFReader(path)[source]

Bases: Reader

Reader for TIFF files using tifffile.

Parameters:

path (Path) –

get_tile(index, decode=True)[source]

Get tile at index.

Parameters:

  • index (Tuple[int, int]) – The index of the tile to get.

  • decode (bool, optional) – Whether to decode the tile. Defaults to True.

Returns:

The tile at index.

Return type:

np.ndarray

property original_shape: Tuple[int, ...]

Return the original shape of the image.

thumbnail(shape, approx_ok=False)[source]

Get a thumbnail of the image.

Uses xarray/dask block map to get the thumbnail.

Parameters:

  • shape (Tuple[int, ...]) – The shape of the thumbnail to get.

  • approx_ok (bool, optional) – Whether to use an approximate thumbnail. Defaults to False.

Returns:

The thumbnail of the image.

Return type:

np.ndarray

class wsic.readers.ZarrReader(path, axes=None)[source]

Bases: Reader

Reader for zarr files.

Parameters:

  • path (str | Path) –

  • axes (str | None) –

wsic.types module

wsic.utils module

class wsic.utils.TimeoutWarning(message, timeout=0.1, stacklevel=5)[source]

Bases: object

Context manager that warns if the context takes too long to execute.

Parameters:

  • message (str) – The warning message to display.

  • timeout (float) – The timeout in seconds.

  • stacklevel (int) – The stacklevel to pass to warnings.warn.

wsic.utils.block_downsample_shape(shape, downsample, block_shape)[source]

Calculate the shape of an array after downsampling in fixed size chunks.

Parameters:

  • shape (Tuple[int, ...]) –

  • downsample (float) –

  • block_shape (Tuple[int, ...]) –

Return type:

Tuple[int, …]

wsic.utils.block_reduce(array, block_shape, func, **func_kwargs)[source]

Reduce the array by applying a function to each block.

Creates a view using view_as_blocks and applies the function to each block.

Parameters:

  • array (np.ndarray) – The array to reduce.

  • block_shape (Tuple[int, ...]) – The shape of the blocks.

  • func (Callable[[np.ndarray], np.ndarray]) – The function to apply to each block.

  • func_kwargs (Dict[str, Any]) – Keyword arguments to pass to func.

Returns:

The reduced array.

Return type:

np.ndarray

wsic.utils.cv2_resize(array, shape, interpolation, cv2_kwargs)[source]

Resize an array using cv2.resize.

Parameters:

  • array (np.ndarray) – The array to resize.

  • shape (Tuple[int, ...]) – The shape of the output array.

  • interpolation (str) – The interpolation method to use.

  • cv2_kwargs (Dict[str, Any]) – Keyword arguments to pass to cv2.resize.

Returns:

The resized array.

Return type:

np.ndarray

wsic.utils.downsample_shape(baseline_shape, downsample, rounding_func=<built-in function floor>)[source]

Calculate the shape of an array after downsampling by a factor.

The shape is calculated by dividing the shape of the baseline array by the downsample factor. The output is rounded to the nearest integer using the provided rounding function. E.g. for a founding function of floor, the following opertion is performed \(\lfloor \frac{shape}{downsample} \rfloor\). If a channel dimension is specified, the dimension is left unchanged.

Parameters:

  • baseline_shape (Tuple[int, ...]) – The shape of the array to downsample.

  • downsample (int) – The downsample factor.

  • rounding_func (Callable[[int], int]) – The rounding function to use. Defaults to floor. Any function which takes a single Number and returns an int such as math.floor or math.ceil can be used. Note that the behaviour of floor differs for negative numbers, e.g. floor(-1) = -2. The int function is sigificantly faster than floor.

Returns:

The shape of the downsampled array.

Return type:

Tuple[int, …]

Examples

>>> dowmsample_shape((13, 13), 2)
(6, 6)

>>> dowmsample_shape((13, 13, 3), 2)
(6, 6, 3)

>>> dowmsample_shape((13, 13, 3), 2, channel_dim=2)
(6, 6, 3)

>>> downsample_shape((13, 13, 3), 2, -1, ceil)
(7, 7, 3)
wsic.utils.main_process()[source]

Return whether the current process is the main process.

Return type:

bool

wsic.utils.mean_pool(image, pool_size)[source]

Reduce an image by applying a mean to each block.

Uses wsic.utils.block_reduce to apply np.mean in blocks to an image.

This is significantly slower than cv2.INTER_AREA interpolation and scipy.ndimage.zoom, but a used as fallback for when neither optional dependency is available.

Note that the output shape will always round down to the nearest integer:

\[\left\lfloor \frac{\texttt{image.shape}}{\texttt{pool\_size}} \right\rfloor\]
Parameters:

  • image (np.ndarray) – The image to reduce.

  • pool_size (int) – The size of the blocks to apply np.mean to.

Returns:

The reduced image.

Return type:

np.ndarray

wsic.utils.mosaic_shape(array_shape, tile_shape)[source]

Calculate the shape of a grid of tiles which covers an array.

Parameters:

  • shape (Tuple[int, ...]) – The shape of the array to cover.

  • tile_shape (Tuple[int, ...]) – The shape of the tiles.

  • array_shape (Tuple[int, ...]) –

Returns:

The shape of the tiles which cover shape.

Return type:

Tuple[int, …]

Examples

>>> tile_shape((13, 13), (8, 8))
(2, 2)

>>> tile_shape((13, 13, 3), (8, 8))
(2, 2)

>>> tile_shape((13, 13, 3), (8, 8, 3))
(2, 2, 1)
wsic.utils.mpp2ppu(mpp, units)[source]

Convert microns per pixel (mpp) to pixels per unit.

Parameters:

  • mpp (float) – The microns per pixel.

  • units (Union[str, int]) – The units to convert to. Valid units are: ‘um’, ‘mm’, ‘cm’, ‘inch’, 2 (TIFF inches), and 3 (TIFF cm).

Return type:

float

wsic.utils.pillow_resize(array, shape, interpolation, pil_kwargs)[source]

Resize an array using PIL.Image.resize.

Parameters:

  • array (np.ndarray) – The array to resize.

  • shape (Tuple[int, ...]) – The shape of the output array.

  • interpolation (str) – The interpolation method to use.

  • pil_kwargs (Dict[str, Any]) – Keyword arguments to pass to PIL.Image.resize.

Returns:

The resized array.

Return type:

np.ndarray

wsic.utils.ppu2mpp(ppu, units)[source]

Convert pixels per unit to microns per pixel (mpp).

Parameters:

  • ppu (float) – The pixels per unit.

  • units (Union[str, int]) – The units to convert from. Valid units are: ‘um’, ‘mm’, ‘cm’, ‘inch’, 2 (TIFF inches), and 3 (TIFF cm).

Return type:

float

wsic.utils.resize_array(array, shape, interpolation='bilinear', cv2_kwargs=None, pil_kwargs=None, zoom_kwargs=None)[source]

Resize an array (image).

Tries to use the fastest method available by trying several libraries in turn. The order of preference is:

  1. cv2.resize

  2. ‘PIL.Image.resize’

  3. scipy.ndimage.zoom

  4. Nearest neighbour subsampling

Parameters:

  • array (np.ndarray) – The array to resize.

  • shape (Tuple[int, ...]) – The shape of the output array.

  • interpolation (Union[str, int]) – The interpolation method to use. Defaults to bilinear.

  • cv2_kwargs (Dict[str, Any]) – Keyword arguments to pass to cv2.resize.

  • pil_kwargs (Dict[str, Any]) – Keyword arguments to pass to PIL.Image.resize.

  • zoom_kwargs (Dict[str, Any]) – Keyword arguments to pass to scipy.ndimage.zoom. Defaults to {“mode”: “reflect”}.

  • Returns –

    np.ndarray:

    The resized array.

Return type:

ndarray

wsic.utils.scale_to_fit(shape, max_shape)[source]

Find the scale factor to fit shape into a max shape.

Given a shape and a max shape, find the scale factor to apply to the shape to fit it within the max shape while preserving the aspect ratio.

Parameters:

  • shape (Tuple[int, ...]) – The shape to fit.

  • max_shape (Tuple[int, ...]) – The maximum shape to fit into.

Returns:

The scale factor to apply to the shape to fit it within the

Return type:

float

wsic.utils.scipy_resize(array, shape, interpolation, zoom_kwargs)[source]

Resize an array using scipy.ndimage.zoom.

Parameters:

  • array (np.ndarray) – The array to resize.

  • shape (Tuple[int, ...]) – The shape of the output array.

  • interpolation (str) – The interpolation method to use.

  • zoom_kwargs (Dict[str, Any]) – Keyword arguments to pass to scipy.ndimage.zoom. Defaults to {“mode”: “reflect”}.

Returns:

The resized array.

Return type:

np.ndarray

wsic.utils.strictly_increasing(iterable)[source]

Check if an iterable is strictly increasing.

Parameters:

iterable (Iterable) –

Return type:

bool

wsic.utils.tile_slices(index, shape)[source]

Create a tuple of slices to read a tile region from an array.

Parameters:

  • location (Tuple[int, ...]) – The index of the tile e.g. the (ith, jth) tile in a 2d grid.

  • shape (Tuple[int, ...]) – The shape of the tiles in the grid.

  • index (Tuple[int, ...]) –

Returns:

The slices to read the tile region from an array-like.

Return type:

Tuple[slice, …]

wsic.utils.varnames(var, f_backs=1, squeeze=True)[source]

Get the name(s) of a variable.

A bit of a hack, but works for most cases. Good for debugging and making logging messages more helpful. Works by inspecting the call stack and finding the name of the variable in the caller’s frame by checking the object’s ID. There may be multiple variable names with the same ID and hence a tuple of name strings is returned.

Parameters:

  • var (Any) – The variable to get the name of.

  • f_backs (int) – The number of frames to go back in the call stack.

  • squeeze (bool) – If only one name is found in the call frame, return it as a string instead of a tuple of strings

Returns:

The name(s) of the variable.

Return type:

Optional[Union[Tuple[str], str]]

Examples

>>> foo = "bar"
>>> varnames(foo)
foo

>>> foo = "bar"
>>> baz = foo
>>> varnames(foo)
(foo, baz)

>>> varnames("bar")  # Literals will return None
None
wsic.utils.view_as_blocks(array, block_shape)[source]

View an array as a grid of non-overlapping blocks.

The same method as in scikit-image and several other libraries, using the numpy.lib.stride_tricks.as_strided function to produce a view.

Parameters:

  • array (np.ndarray) – The array to view.

  • block_shape (Tuple[int, ...]) – The shape of the blocks.

Returns:

The array view as a grid of non-overlapping blocks.

Return type:

np.ndarray

wsic.utils.warn_unused(var, name=None, ignore_none=True, ignore_falsey=False)[source]

Warn the user if a variable has a non None or non falsey value.

See https://docs.python.org/3/library/stdtypes.html#truth-value-testing for an explanation of what evaluates to true and false.

Used when some kwargs are defined for API consistency and to satisfy the Liskov Substitution Principle (LSP).

Parameters:

  • var (Any) – The variable to check.

  • name (Optional[str]) – The name of the variable. If None, the variable name will be obtained from the call frame.

  • ignore_none (bool) – If True, do not warn if the variable is None.

  • ignore_falsey (bool) – If True, do not warn if the variable is any falsey value.

Return type:

None

wsic.utils.wrap_index(index, shape, reverse=True)[source]

Wrap an index to the shape of an array.

Parameters:

  • index (Tuple[int, ...]) – The index to wrap.

  • shape (Tuple[int, ...]) – The shape of the array.

  • reverse (bool) – If True, wrap the index to the opposite end of the array.

Returns:

The wrapped index and any overflow.

Return type:

Tuple[Tuple[int, …], int]

Examples

>>> wrap_index((0, 3), (3, 3))
((1, 0), 0)

>>> wrap_index((1, 4), (3, 3))
((2, 1), 0)

>>> wrap_index((3, 1), (3, 3), reverse=False)
((0, 2), 0)

wsic.writers module

class wsic.writers.DICOMWSIWriter(path, shape, tile_size=(256, 256), dtype=<class 'numpy.uint8'>, color_space=None, codec=None, compression_level=0, microns_per_pixel=None, pyramid_downsamples=None, overwrite=False, verbose=False, **kwargs)[source]

Bases: Writer

Writer for DICOM WSI images using wsidicom.

Notes

Parameters:

  • path (str | Path) –

  • shape (Tuple[int, int]) –

  • tile_size (Tuple[int, int]) –

  • dtype (dtype) –

  • color_space (ColorSpace | None) –

  • codec (Codec | None) –

  • compression_level (int) –

  • microns_per_pixel (Tuple[float, float]) –

  • pyramid_downsamples (List[int] | None) –

  • overwrite (bool) –

  • verbose (bool) –

copy_from_reader(reader, num_workers=2, read_tile_size=None, timeout=10, downsample_method=None)[source]

Write pixel data to by copying from a Reader.

Parameters:

  • reader (Reader) – Reader object.

  • num_workers (int, optional) – Number of workers to use. Defaults to 2.

  • read_tile_size (Tuple[int, int], optional) – Tile size to read. Defaults to None. This will use the tile size of the writer if None.

  • timeout (float, optional) – Timeout for workers. Defaults to 10s.

  • downsample_method (str, optional) – Downsample method to use when building pyramid levels. Defaults to None. Valid downsample methods are: “cv2”, “scipy”, “np”, None.

Return type:

None

transcode_from_reader(reader, downsample_method=None)[source]
Parameters:
Return type:

None

class wsic.writers.JP2Writer(path, shape, tile_size=(256, 256), dtype=<class 'numpy.uint8'>, color_space=ColorSpace.RGB, codec='jpeg2000', compression_level=0, microns_per_pixel=None, pyramid_downsamples=None, overwrite=False, verbose=False, **kwargs)[source]

Bases: Writer

Tile-wise JP2 writer using glymur.

Note that when writing tiled JP2 files, the tiles must all be the same size and must be written in the order left-to-right, then top-to-bottom (row-by-row). Tiles cannot be skipped.

Parameters:

  • path (PathLike) – Path to output file.

  • shape (Tuple[int, int]) – A (width, height) tuple of image size in pixels.

  • tile_size (Tuple[int, int], optional) – A (width, height) tuple of tile size in pixels. Defaults to (256, 256).

  • dtype (np.dtype, optional) – Data type of output image. Defaults to np.uint8.

  • color_space (ColorSpace, optional) – Color space the output image. Defaults to “rgb”.

  • compression (str, optional) – Compression type. Currently only JPEG 2000 compression is supported. Defaults to None.

  • compression_level (int, optional) – Compression level. Currently unused. Defaults to None.

  • microns_per_pixel (Tuple[float, float], optional) – A (width, height) tuple of microns per pixel. Defaults to None.

  • pyramid_downsamples (List[int], optional) – A list of downsamples to create. Unused but included for API consistency. Defaults to None.

  • overwrite (bool, optional) – Overwrite existing file. Defaults to False.

  • verbose (bool, optional) – Print more output. Defaults to False.

  • codec (Codec | None) –

copy_from_reader(reader, num_workers=2, read_tile_size=None, timeout=10.0, downsample_method=None)[source]

Write pixel data to by copying from a Reader.

Parameters:

  • reader (Reader) – Reader object.

  • num_workers (int, optional) – Number of workers to use. Defaults to 2.

  • read_tile_size (Tuple[int, int], optional) – Tile size to read. Defaults to None. This will use the tile size of the writer if None.

  • timeout (float, optional) – Timeout for workers. Defaults to 10s.

  • downsample_method (str, optional) – Downsample method to use. Defaults to None. Not used for JP2Writer, but included for API consistency.

Return type:

None

class wsic.writers.SVSWriter(path, shape, tile_size=(256, 256), dtype=<class 'numpy.uint8'>, color_space=ColorSpace.RGB, codec=Codec.JPEG, compression_level=0, microns_per_pixel=None, pyramid_downsamples=None, overwrite=False, verbose=False, **kwargs)[source]

Bases: Writer

Aperio SVS writer using tifffile.

Notes

  • When writing tiled TIFF files, the tiles must all be the same size and must be written in the order left-to-right, then top-to-bottom (row-by-row). Tiles cannot be skipped.

  • Microns per pixel (MPP) is taken from microns per pixel of the reader if not provided. If microns per pixel is set to None, microns per pixel will not be written to the file.

  • The SVS MPP metadata is the mean of microns_per_pixel from init or the reader.

  • Apparent magnification (AppMag) can be specified as a float to the optional “app_mag” kwarg.

  • If only an MPP resolution is given, the AppMag will be approximated from the MPP (by AppMag = 10 / MPP) and rounded to the nearest common AppMag (10, 20,40, 50, 60, 80, 100, 125, 150, 200, 250, 312.5, 375, 500, 600, 750, 1000, 1250). If neither MPP or AppMag are given, no resolution will be written to the file.

Parameters:

  • path (PathLike) – Path to output file.

  • shape (Tuple[int, int]) – A (width, height) tuple of image size in pixels.

  • tile_size (Tuple[int, int], optional) – A (width, height) tuple of tile size in pixels. Defaults to (256, 256).

  • dtype (np.dtype, optional) – Data type of output image. Defaults to np.uint8.

  • color_space (ColorSpace, optional) – color_space. Defaults to “rgb”.

  • compression (str, optional) – Compression type. Defaults to “jpeg”.

  • compression_level (int, optional) – Compression level. Defaults to 95. Currently unused.

  • microns_per_pixel (Tuple[float, float], optional) – A (width, height) tuple of microns per pixel. Defaults to None.

  • pyramid_downsamples (List[int], optional) – A list of downsamples to create. Should be strictly inceasing for maximum compatibility. Defaults to None.

  • overwrite (bool, optional) – Overwrite existing file. Defaults to False.

  • verbose (bool, optional) – Print more output. Defaults to False.

  • ome (bool) – Write OME-TIFF metadata. Defaults to False.

  • app_mag (float) – Apparent magnification. Defaults to None.

  • codec (Codec | None) –

copy_from_reader(reader, num_workers=2, read_tile_size=None, timeout=10.0, downsample_method=None)[source]

Write pixel data to by copying from a Reader.

Parameters:

  • reader (Reader) – Reader object.

  • num_workers (int, optional) – Number of workers to use. Defaults to 2.

  • read_tile_size (Tuple[int, int], optional) – Tile size to read. Defaults to None. This will use the tile size of the writer if None.

  • timeout (float, optional) – Timeout for workers. Defaults to 10s.

  • downsample_method (str, optional) – Downsample method to use when building pyramid levels. Defaults to None. Valid downsample methods are: “cv2”, “scipy”, “np”, None.

Return type:

None

class wsic.writers.TIFFWriter(path, shape, tile_size=(256, 256), dtype=<class 'numpy.uint8'>, color_space='rgb', codec='jpeg', compression_level=-1, microns_per_pixel=None, pyramid_downsamples=None, overwrite=False, verbose=False, *, ome=False)[source]

Bases: Writer

Tile-wise TIFF writer using tifffile.

Note that when writing tiled TIFF files, the tiles must all be the same size and must be written in the order left-to-right, then top-to-bottom (row-by-row). Tiles cannot be skipped.

Notes

The following notes are from the TIFF 6.0 Specification.

  • TileWidth and TileLength (height) must each be a multiple of 16.

  • “Offsets [bytes from the start of file to each tile blob and therefore the tile ordering when writing] are ordered left-to-right and top-to-bottom.”

  • “For PlanarConfiguration = 2, the offsets for the first component plane are stored first, followed by all the offsets for the second component plane, and so on.”

The full specification is available at: https://web.archive.org/web/20210108174645/https://www.adobe.io/content/dam/udp/en/open/standards/tiff/TIFF6.pdf

Parameters:

  • path (PathLike) – Path to output file.

  • shape (Tuple[int, int]) – A (width, height) tuple of image size in pixels.

  • tile_size (Tuple[int, int], optional) – A (width, height) tuple of tile size in pixels. Defaults to (256, 256).

  • dtype (np.dtype, optional) – Data type of output image. Defaults to np.uint8.

  • color_space (ColorSpace, optional) – color_space. Defaults to “rgb”.

  • compression (str, optional) – Compression type. Defaults to “jpeg”.

  • compression_level (int, optional) – Compression level. Defaults to -1 (highest / lossless).

  • microns_per_pixel (Tuple[float, float], optional) – A (width, height) tuple of microns per pixel. Defaults to None.

  • pyramid_downsamples (List[int], optional) – A list of downsamples to create. Should be strictly inceasing for maximum compatibility. Defaults to None.

  • overwrite (bool, optional) – Overwrite existing file. Defaults to False.

  • verbose (bool, optional) – Print more output. Defaults to False.

  • ome (bool) – Write OME-TIFF metadata. Defaults to False.

  • codec (Codec | None) –

copy_from_reader(reader, num_workers=2, read_tile_size=None, timeout=10.0, downsample_method=None)[source]

Write pixel data to by copying from a Reader.

Parameters:

  • reader (Reader) – Reader object.

  • num_workers (int, optional) – Number of workers to use. Defaults to 2.

  • read_tile_size (Tuple[int, int], optional) – Tile size to read. Defaults to None. This will use the tile size of the writer if None.

  • timeout (float, optional) – Timeout for workers. Defaults to 10s.

  • downsample_method (str, optional) – Downsample method to use when building pyramid levels. Defaults to None. Valid downsample methods are: “cv2”, “scipy”, “np”, None.

Return type:

None

transcode_from_reader(reader, downsample_method=None)[source]
Parameters:
Return type:

None

class wsic.writers.Writer(path, shape, tile_size=(256, 256), dtype=<class 'numpy.uint8'>, color_space=ColorSpace.RGB, codec=None, compression_level=0, microns_per_pixel=None, pyramid_downsamples=None, overwrite=False, verbose=False)[source]

Bases: ABC

Base class for image writers.

Parameters:

  • path (PathLike) – Path to the output file.

  • shape (Tuple[int, int]) – Shape of the output image.

  • tile_size (Tuple[int, int], optional) – A (width, height) tuple of output tile size in pixels. Defaults to (256, 256).

  • dtype (np.dtype, optional) – Data type of the output image. Defaults to np.uint8.

  • color_space (ColorSpace, optional) – Color space the output image. Defaults to “rgb”.

  • compression (str, optional) – Compression codec to use. Defaults to None. Not all writers support compression.

  • compression_level (int, optional) – Compression level to use. Defaults to 0 (lossless / maximum).

  • microns_per_pixel (Tuple[float, float], optional) – A (width, height) tuple of microns per pixel. Defaults to None.

  • pyramid_downsamples (List[int], optional) – A list of downsamples to use in the pyramid. Defaults to None. Not all writers support pyramids.

  • overwrite (bool, optional) – Overwrite output file if it exists. Defaults to False.

  • verbose (bool, optional) – Print more output. Defaults to False.

  • codec (Codec | None) –

T = ~T
abstract copy_from_reader(reader, num_workers=2, read_tile_size=None, timeout=10.0, downsample_method=None)[source]

Write pixel data to by copying from a Reader.

Parameters:

  • reader (Reader) – Reader object.

  • num_workers (int, optional) – Number of workers to use. Defaults to 2.

  • read_tile_size (Tuple[int, int], optional) – Tile size to read. Defaults to None. This will use the tile size of the writer if None.

  • timeout (float, optional) – Timeout for workers. Defaults to 10s.

  • downsample_method (str, optional) – Downsample method to use when building pyramid levels. Defaults to None. Valid downsample methods are: “cv2”, “scipy”, “np”, None.

Return type:

None

static level_progress(iterable, **kwargs)[source]

Wrapper for a tile yeilding iterable when writing a level.

Used to display progress when copying from a reader.

Some of the tqdm defaults are overridden but can be changed by passing values as kwargs. Parameters which differ to the tqdm defaults here are: - smoothing = 0.1 - colour = “magenta”

Parameters:

  • iterable (Iterable) – The iterable to wrap.

  • **kwargs (dict) – Extra kwargs for tqdm. Overrides defaults.

Return type:

Iterator[T]

static pyramid_progress(iterable, **kwargs)[source]

Wrap an iterable in a progress bar.

Used to display progress when copying from a reader.

Some of the tqdm defaults are overridden but can be changed by passing values as kwargs. Parameters which differ to the tqdm defaults here are: - smoothing = 0 - colour = “magenta”

Parameters:

  • iterable (Iterable) – The iterable to wrap.

  • **kwargs (dict) – Extra kwargs for tqdm. Overrides defaults.

Return type:

Iterator

reader_tile_iterator(reader, num_workers=2, read_tile_size=None, yield_tile_size=None, intermediate=None, timeout=10.0)[source]

Returns an iterator which returns tiles generated by reader.

Parameters:

  • reader (Reader) – Reader to read tiles from.

  • num_workers (int, optional) – Number of workers to use. Defaults to 2.

  • read_tile_size (Tuple[int, int], optional) – A (width, height) tuple of read tile size in pixels. Defaults to self.tile_size.

  • intermediate (np.ndarray, optional) – An intermediate image to write tiles to.

  • yield_tile_size (Tuple[int, int] | None) –

  • timeout (float) –

Returns:

Iterator which returns tiles generated by reader.

Return type:

Iterator

transcode_from_reader(reader, downsample_method=None)[source]
Parameters:
Return type:

None

static transcode_progress(iterable, **kwargs)[source]

Progress bar for transcoding.

Parameters:

  • iterable (Iterable) – Iterable to wrap.

  • **kwargs – Keyword arguments to pass to the progress bar.

Return type:

Iterable

class wsic.writers.ZarrIntermediate(path, shape, tile_size=(256, 256), dtype=<class 'numpy.uint8'>, color_space='rgb', codec=None, compression_level=0, microns_per_pixel=None, pyramid_downsamples=None, overwrite=False, verbose=False, *, zero_after_read=False)[source]

Bases: Writer, Reader

Zarr intermediate reader/writer.

A convenience reader/writer which is also a context manager. This allows for changing of tile order or size when converting between formats and also avoids decoding the same tile from the original file twice. This is particularly useful for formats which are very computationally costly to decode such as JPEG 2000.

Parameters:

  • path (PathLike) – Path to the intermediate file. If None, a temporary file will be created.

  • shape (Tuple[int, int]) – Shape of the output file.

  • tile_size (Tuple[int, int], optional) – A (width, height) tuple of zarr chunk size in pixels. Defaults to (256, 256).

  • dtype (np.dtype, optional) – The data type of the output file. Defaults to np.uint8.

  • color_space (ColorSpace, optional) – Unused but kept for compatibility with the Writer base class.

  • compression (str, optional) – Unused but kept for compatibility with the Writer base class. Internally uses default zarr compression.

  • compression_level (int, optional) – Unused but kept for compatibility with the Writer base classes. Internally uses default zarr compression level.

  • microns_per_pixel (float, optional) – Unused but kept for compatibility with the Reader and Writer classes.

  • pyramid_downsamples (List[int], optional) – Unused but kept for compatibility with the Reader and Writer classes.

  • overwrite (bool, optional) – If True, the output file will be overwritten if it exists. Defaults to False.

  • verbose (bool, optional) – If True, print information about the file being written.

  • zero_after_write (bool, optional) – If True, data in the zarr will be zeroed after writing. Defaults to False.

  • codec (Codec | None) –

  • zero_after_read (bool) –

copy_from_reader(reader, num_workers=2, read_tile_size=None, timeout=10.0, downsample_method=None)[source]

Not supported but included for API consistency.

Parameters:

  • reader (Reader) –

  • num_workers (int) –

  • read_tile_size (Tuple[int, int] | None) –

  • timeout (float) –

  • downsample_method (str | None) –

Return type:

None

class wsic.writers.ZarrWriter(path, shape=None, tile_size=(256, 256), dtype=<class 'numpy.uint8'>, color_space=ColorSpace.RGB, codec=Codec.BLOSC, compression_level=9, microns_per_pixel=None, pyramid_downsamples=None, overwrite=False, verbose=False, *, ome=False)[source]

Bases: Writer, Reader

Zarr reader and writer.

Parameters:

  • path (PathLike) – Path to the output zarr.

  • shape (Tuple[int, int]) – Shape of the output zarr.

  • tile_size (Tuple[int, int], optional) – A (width, height) tuple of zarr chunks in pixels. Defaults to (256, 256).

  • dtype (np.dtype, optional) – Data type of the output zarr. Defaults to np.uint8.

  • codec (str, optional) – Compression codec to use. Defaults to None. Not all writers support compression.

  • color_space (ColorSpace, optional) – Color space. Defaults to RGB.

  • compression_level (int, optional) – Compression level to use. Defaults to 0 (lossless / maximum).

  • microns_per_pixel (Tuple[float, float], optional) – A (width, height) tuple of microns per pixel. Defaults to None.

  • pyramid_downsamples (List[int], optional) – A list of downsamples to use in the pyramid. Defaults to None.

  • overwrite (bool, optional) – Overwrite output file if it exists. Defaults to False.

  • verbose (bool, optional) – Print more output. Defaults to False.

  • ome (bool) – Write OME-NGFF metadata. Defaults to False. Currently not implemented.

copy_from_reader(reader, num_workers=2, read_tile_size=None, timeout=10.0, downsample_method=None)[source]

Write pixel data to by copying from a Reader.

Parameters:

  • reader (Reader) – Reader object.

  • num_workers (int, optional) – Number of workers to use. Defaults to 2.

  • read_tile_size (Tuple[int, int], optional) – Tile size to read. Defaults to None. This will use the tile size of the writer if None.

  • timeout (float, optional) – Timeout for workers. Defaults to 10s.

  • downsample_method (str, optional) – Downsample method to use when building pyramid levels. Defaults to None. Valid downsample methods are: “cv2”, “scipy”, “np”, None.

Return type:

None

static get_codec(codec, level, **kwargs)[source]

Get a codec for the given compression method and compression level.

Parameters:

  • codec (str | Codec) –

  • level (int) –

  • kwargs (Dict[str, Any]) –

Return type:

Callable[[bytes], bytes]

static get_transcode_codec(reader)[source]

Get the codec to use for transcoding.

Parameters:

reader (TiffReader) – Reader object.

Returns:

Codec to use for transcoding.

Return type:

numcodecs.Codec

property mosaic_shape: Tuple[int, int] | None
transcode_from_reader(reader, downsample_method=None)[source]

Losslessly transform into a new format from a supported Reader.

Repackages tiles from the Reader to a zarr. Currently only supports transcoding from:

Currently only outputs a single resolution level (level 0).

It may also be possible to transcode the tiles themselves (e.g. JPEG to JPEG XL) or perform simple geometric transforms (flip, rotate, etc). However, this is not yet implemented. Currently, they are simply copied into a new structure.

Parameters:

  • reader (Reader) – Reader object.

  • downsample_method (str, optional) – Downsample method to use for new reduced resolutions. Defaults to None. Valid downsample methods are: “cv2”, “scipy”, “np”, None.

Return type:

None

wsic.writers.downsample_tile(image, factor, method=None)[source]

Downsample an image by a factor.

Parameters:

  • image (np.ndarray) – The image to downsample.

  • factor (int) – The downsampling factor.

  • method (str) – The downsampling method (library) to use. Defaults to None, which tries cv2, then scipy, and falls back to numpy. Valid options are: “cv2”, “pillow”, “scipy”, “np”, None.

Return type:

array

wsic.writers.get_level_tile(yx, tile_size, downsample, read_intermediate_path, downsample_method=None)[source]

Generate tiles for a downsampled level.

Parameters:

  • yx (Tuple[int, int]) – The tile coordinates.

  • tile_size (Tuple[int, int]) – The tile size.

  • downsample (int) – The downsampling factor.

  • read_intermediate_path (PathLike) – The path to the intermediate file (zarr).

  • downsample_method (str) – The downsampling method (library) to use.

Return type:

ndarray

Module contents

Top-level package for wsic.