Slide I/O

Functions

Methods and classes to read and write slides in the .ome.tiff format

valis.slide_io.convert_to_ome_tiff(src_f, dst_f, level, series=None, xywh=None, colormap=None, tile_wh=None, compression='lzw')[source]

Convert an image to an ome.tiff image

Saves a new copy of the image as a tiled pyramid ome.tiff with valid ome-xml. Uses pyvips to save the image. Currently only writes a single series.

Parameters:

src_f (str) – Path to image to be converted
dst_f (str) – Path indicating where the image should be saved.
level (int) – Pyramid level to be converted.
series (str) – Series to be converted.
xywh (tuple of int, optional) – The region of the slide to be converted. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.
colormap (dict, optional) – Dictionary of channel colors, where the key is the channel name, and the value the color as rgb255. If None (default), the channel colors from current_ome_xml_str will be used, if available. If None, and there are no channel colors in the current_ome_xml_str, then no colors will be added
tile_wh (int) – Tile shape used to save the image. Used to create a square tile, so tile_wh is both the width and height.
compression (str) – Compression method used to save ome.tiff . Default is lzw, but can also be jpeg or jp2k. See pyips for more details.

valis.slide_io.create_ome_xml(shape_xyzct, bf_dtype, is_rgb, pixel_physical_size_xyu=None, channel_names=None, colormap=None)[source]

Create new ome-xmml object

Parameters:

shape_xyzct (tuple of int) – XYZCT shape of image
bf_dtype (str) – String format of Bioformats datatype
is_rgb (bool) – Whether or not the image is RGB
pixel_physical_size_xyu (tuple, optional) – Physical size per pixel and the unit.
channel_names (list, optional) – List of channel names.
colormap (dict, optional) – Dictionary of channel colors, where the key is the channel name, and the value the color as rgb255. If None (default), the channel colors from current_ome_xml_str will be used, if available.

Returns:

new_ome – ome_types.model.OME object containing ome-xml metadata

Return type:

ome_types.model.OME

valis.slide_io.get_slide_reader(src_f, series=None)[source]

Get appropriate SlideReader

If a slide can be read by openslide and bioformats, VipsSlideReader will be used because it can be opened as a pyvips.Image. More common formats, like png, jpeg, etc… will be opened with scikit-image. Everything else will be opened with Bioformats.

Parameters:

src_f (str) – Path to slide
series (int, optional) – The series to be read. If series is None, the the series will be set to the series associated with the largest image. In cases where there is only 1 image in the file, series will be 0.

Returns:

reader – SlideReader class that can read the slide and and convert them to images or pyvips.Images at the specified level and series. They also contain a MetaData object that contains information about the slide, like dimensions at each level, physical units, etc…

Return type:

SlideReader

Notes

pyvips will be used to open ome-tiff images when series is 0

valis.slide_io.init_jvm(jar=None, mem_gb=10)[source]

Initialize JVM for BioFormats

Parameters:: mem_gb (int) – Amount of memory, in GB, for JVM

valis.slide_io.kill_jvm()[source]: Kill JVM for BioFormats

valis.slide_io.save_ome_tiff(img, dst_f, ome_xml=None, tile_wh=1024, compression='lzw')[source]

Save an image in the ome.tiff format using pyvips

Parameters:

img (pyvips.Image, ndarray) – Image to be saved. If a numpy array is provided, it will be converted to a pyvips.Image.
ome_xml (str, optional) – ome-xml string describing image’s metadata. If None, it will be createdd
tile_wh (int) – Tile shape used to save img. Used to create a square tile, so tile_wh is both the width and height.
compression (str) – Compression method used to save ome.tiff . Default is lzw, but can also be jpeg or jp2k. See pyips for more details.

valis.slide_io.update_xml_for_new_img(current_ome_xml_str, new_xyzct, bf_dtype, is_rgb, series, pixel_physical_size_xyu=None, channel_names=None, colormap=None)[source]

Update dimensions ome-xml metadata

Used to create a new ome-xmlthat reflects changes in an image, such as its shape

If current_ome_xml_str is invalid or None, a new ome-xml will be created

Parameters:

current_ome_xml_str (str) – ome-xml string that needs to be updated
new_xyzct (tuple of int) – XYZCT shape of image
bf_dtype (str) – String format of Bioformats datatype
is_rgb (bool) – Whether or not the image is RGB
pixel_physical_size_xyu (tuple, optional) – Physical size per pixel and the unit.
channel_names (list, optional) – List of channel names.
colormap (dict, optional) – Dictionary of channel colors, where the key is the channel name, and the value the color as rgb255. If None (default), the channel colors from current_ome_xml_str will be used, if available. If None, and there are no channel colors in the current_ome_xml_str, then no colors will be added

Returns:

new_ome – ome_types.model.OME object containing ome-xml metadata

Return type:

ome_types.model.OME

Classes

MetaData

class valis.slide_io.MetaData(name, server, series=0)[source]

Store slide metadata

To be filled in by a SlideReader object

name

Name of slide.

Type:: str

series

Series number.

Type:: int

server

String indicating what was used to read the metadata.

Type:: str

slide_dimensions: Dimensions of all images in the pyramid (width, height).

is_rgb

Whether or not the image is RGB.

Type:: bool

pixel_physical_size_xyu: Physical size per pixel and the unit.

channel_names

List of channel names. None if image is RGB

Type:: list

n_channels

Number of channels.

Type:: int

original_xml

Xml string created by bio-formats

Type:: str

bf_datatype

String indicating bioformats image datatype

Type:: str

optimal_tile_wh

Tile width and height used to open and/or save image

Type:: int

__init__(name, server, series=0)[source]

Parameters:

name (str) – Name of slide.
server (str, optional) – String indicating what was used to read the metadata.
series (int, optional) – Series number.

SlideReader

class valis.slide_io.SlideReader(src_f, *args, **kwargs)[source]

Read slides and get metadata

slide_f

Path to slide

Type:: str

metadata

MetaData containing some basic metadata about the slide

Type:: MetaData

series

Image series

Type:: int

__init__(src_f, *args, **kwargs)[source]

Parameters:: src_f (str) – Path to slide

create_metadata()[source]

Create and fill in a MetaData object

Returns:: metadata – MetaData object containing metadata about slide
Return type:: MetaData

slide2image(level, xywh=None, *args, **kwargs)[source]

Convert slide to image

Parameters:

level (int) – Pyramid level
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

img – An image of the slide or the region defined by xywh

Return type:

ndarray

slide2vips(level, xywh=None, *args, **kwargs)[source]

Convert slide to pyvips.Image

Parameters:

level (int) – Pyramid level
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

vips_slide – An of the slide or the region defined by xywh

Return type:

pyvips.Image

BioFormatsSlideReader

class valis.slide_io.BioFormatsSlideReader(src_f, series=None, *args, **kwargs)[source]

Bases: SlideReader

Read slides using BioFormats

Uses the packages jpype and bioformats-jar

create_metadata()[source]

Create and fill in a MetaData object

Returns:: metadata – MetaData object containing metadata about slide
Return type:: MetaData

get_channel(level, series, channel)

Get channel from slide

Parameters:

level (int) – Pyramid level
series (int) – Series number
channel (str, int) – Either the name of the channel (string), or the index of the channel (int)

Returns:

img_channel – Specified channel sliced from the slide/image

Return type:

ndarray

get_tiles_parallel(level, tile_bbox_list, pixel_type, series=0)[source]: Get tiles to slice from the slide

scale_physical_size(level)

Get resolution pyramid level

Scale resolution to be for requested pyramid level

Parameters:: level (int) – Pyramid level
Returns:: level_xy_per_px
Return type:: tuple

property series: Slide series

slide2image(level, series=None, xywh=None, *args, **kwargs)[source]

Convert slide to image

Parameters:

level (int) – Pyramid level
series (int, optional) – Series number. Defaults to 1
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

img – An image of the slide or the region defined by xywh

Return type:

ndarray

slide2vips(level, series=None, xywh=None, tile_wh=None, *args, **kwargs)[source]

Convert slide to pyvips.Image

This method uses Bioformats to slice tiles from the slides, and then stitch them together using pyvips.

Parameters:

level (int) – Pyramid level
series (int, optional) – Series number. Defaults to 0
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.
tile_wh (int, optional) – Size of tiles used to contstruct vips_slide

Returns:

vips_slide – An of the slide or the region defined by xywh

Return type:

pyvips.Image

VipsSlideReader

class valis.slide_io.VipsSlideReader(src_f, *args, **kwargs)[source]

Bases: SlideReader

Read slides using pyvips Pyvips includes OpenSlide and so can read those formats as well.

use_openslide

Whether or not openslide can be used to read this slide.

Type:: bool

is_ome

Whether ot not the side is an ome.tiff.

Type:: bool

Notes

When using openslide, lower levels can only be read without distortion, if pixman version 0.40.0 is installed. As of Oct 7, 2021, Macports only has pixman version 0.38, which produces distorted lower level images. If using macports may need to install from source do “./configure –prefix=/opt/local/” when installing from source.

create_metadata()[source]

Create and fill in a MetaData object

Returns:: metadata – MetaData object containing metadata about slide
Return type:: MetaData

get_channel(level, series, channel)

Get channel from slide

Parameters:

level (int) – Pyramid level
series (int) – Series number
channel (str, int) – Either the name of the channel (string), or the index of the channel (int)

Returns:

img_channel – Specified channel sliced from the slide/image

Return type:

ndarray

scale_physical_size(level)

Get resolution pyramid level

Scale resolution to be for requested pyramid level

Parameters:: level (int) – Pyramid level
Returns:: level_xy_per_px
Return type:: tuple

slide2image(level, xywh=None, *args, **kwargs)[source]

Convert slide to image

Parameters:

level (int) – Pyramid level.
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

img – An image of the slide or the region defined by xywh

Return type:

ndarray

slide2vips(level, xywh=None, *args, **kwargs)[source]

Convert slide to pyvips.Image

Parameters:

level (int) – Pyramid level
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

vips_slide – An of the slide or the region defined by xywh

Return type:

pyvips.Image

FlattenedPyramidReader

class valis.slide_io.FlattenedPyramidReader(src_f, *args, **kwargs)[source]

Bases: VipsSlideReader

Read flattened pyramid using pyvips Read slide pyramids where each page/plane is a channel in the pyramid. An example would be one where the plane dimensions are something like [(600, 600), (600, 600), (600, 600), (300, 300), (300, 300), (300, 300)] for a 3 channel image with 2 pyramid levels. It seems that bioformats does not recognize these as pyramid images.

create_metadata()[source]

Create and fill in a MetaData object

Returns:: metadata – MetaData object containing metadata about slide
Return type:: MetaData

get_channel(level, series, channel)

Get channel from slide

Parameters:

level (int) – Pyramid level
series (int) – Series number
channel (str, int) – Either the name of the channel (string), or the index of the channel (int)

Returns:

img_channel – Specified channel sliced from the slide/image

Return type:

ndarray

scale_physical_size(level)

Get resolution pyramid level

Scale resolution to be for requested pyramid level

Parameters:: level (int) – Pyramid level
Returns:: level_xy_per_px
Return type:: tuple

slide2image(level, xywh=None, *args, **kwargs)[source]

Convert slide to image

Parameters:

level (int) – Pyramid level.
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

img – An image of the slide or the region defined by xywh

Return type:

ndarray

slide2vips(level, xywh=None, *args, **kwargs)[source]

Convert slide to pyvips.Image

Parameters:

level (int) – Pyramid level
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

vips_slide – An of the slide or the region defined by xywh

Return type:

pyvips.Image

ImageReader

class valis.slide_io.ImageReader(src_f, *args, **kwargs)[source]

Bases: SlideReader

Read image using scikit-image

create_metadata()[source]

Create and fill in a MetaData object

Returns:: metadata – MetaData object containing metadata about slide
Return type:: MetaData

get_channel(level, series, channel)

Get channel from slide

Parameters:

level (int) – Pyramid level
series (int) – Series number
channel (str, int) – Either the name of the channel (string), or the index of the channel (int)

Returns:

img_channel – Specified channel sliced from the slide/image

Return type:

ndarray

scale_physical_size(level)

Get resolution pyramid level

Scale resolution to be for requested pyramid level

Parameters:: level (int) – Pyramid level
Returns:: level_xy_per_px
Return type:: tuple

slide2image(xywh=None, *args, **kwargs)[source]

Convert slide to image

Parameters:

level (int) – Pyramid level
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

img – An image of the slide or the region defined by xywh

Return type:

ndarray

slide2vips(xywh=None, *args, **kwargs)[source]

Convert slide to pyvips.Image

Parameters:

level (int) – Pyramid level
xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

Returns:

vips_slide – An of the slide or the region defined by xywh

Return type:

pyvips.Image