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, perceputally_uniform_channel_colors=False, 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.

  • perceputally_uniform_channel_colors (bool) – Whether or not to add perceptually uniform channel colors

  • 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, perceputally_uniform_channel_colors=False)[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.

  • perceputally_uniform_channel_colors (bool) – Whether or not to add perceptually uniform channel colors.

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, pixel_physical_size_xyu=None, channel_names=None, perceputally_uniform_channel_colors=False)[source]

Update dimensions ome-xml metadata

Used to create a new ome-xml that 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.

  • perceputally_uniform_channel_colors (bool) – Whether or not to add perceptually uniform channel colors

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