Inspect Biomedical Images with the OpenSlide API

Learn how to read a biomedical image with TileDB Openslide API.

Slicing and reading your data in TileDB is an essential step to accessing and deriving value from your data. For this reason, you have two options on how you can read your data into TileDB. In this tutorial, you will learn how to read and slice your biomedical imaging data by using the TileDBOpenSlide API. This API has been designed on top of the popular OpenSlide API, to offer a familiar means to access your data.

Setup

Start by importing the necessary modules for this tutorial and creating a directory to hold the data.

Python

import os
import shutil

from tiledb.bioimg.converters.ome_tiff import OMETiffConverter
from tiledb.bioimg.openslide import TileDBOpenSlide

root_dir = os.path.expanduser("~/tiledb-bioimg-openslide")

if os.path.exists(root_dir):
    shutil.rmtree(root_dir)

os.makedirs(root_dir)

Image properties

Start by ingesting an image into TileDB.

Python

import requests

url = "https://github.com/libvips/libvips/raw/refs/heads/master/test/test-suite/images/CMU-1-Small-Region.svs"
response = requests.get(url, stream=True)

data_home = os.path.join(root_dir, "data.svs")
data_dest = os.path.join(root_dir, "data.tdb")

with open(data_home, "wb") as out_file:
    shutil.copyfileobj(response.raw, out_file)

Python

OMETiffConverter.to_tiledb(data_home, data_dest, level_min=0)

tiledb.bioimg.converters.ome_tiff.OMETiffConverter

You can create a slide of the image by using the TileDBOpenSlide wrapper and query the image properties as follows:

Python

slide = TileDBOpenSlide(data_dest)
print("level_count:", slide.level_count)
print("dimensions:", slide.dimensions)
print("level_dimensions:", slide.level_dimensions)
print("level_downsamples:", slide.level_downsamples)
print("levels:", slide.levels)
print("group_properties:", slide.properties)

level_count: 1
dimensions: (2220, 2967)
level_dimensions: ((2220, 2967),)
level_downsamples: (1.0,)
levels: (0,)
group_properties: {'axes': 'YXC', 'channels': '["RED", "GREEN", "BLUE"]', 'dataset_type': 'bioimg', 'fmt_version': 2, 'json_tiffwriter_kwargs': '{"bigtiff": false, "byteorder": "<", "append": true, "imagej": false, "ome": false}', 'levels': '[{"level": 0, "name": "l_0.tdb", "axes": "CYX", "shape": [3, 2967, 2220]}]', 'metadata': '{"channels": {"intensity": [{"id": "0", "name": "red", "color": {"red": 255, "green": 0, "blue": 0, "alpha": 255}, "min": 0.0, "max": 255.0}, {"id": "1", "name": "green", "color": {"red": 0, "green": 255, "blue": 0, "alpha": 255}, "min": 0.0, "max": 255.0}, {"id": "2", "name": "blue", "color": {"red": 0, "green": 0, "blue": 255, "alpha": 255}, "min": 0.0, "max": 255.0}]}, "axes": [{"originalAxes": ["Y", "X", "C"], "originalShape": [2967, 2220, 3], "storedAxes": ["C", "Y", "X"], "storedShape": [3, 2967, 2220], "axesMapping": {"Y": ["Y"], "X": ["X"], "C": ["C"]}}]}', 'original_metadata': '{"svs_metadata": "Aperio Image Library v11.2.1 \\r\\n46000x32914 [42673,5576 2220x2967] (240x240) JPEG/RGB Q=30;Aperio Image Library v10.0.51\\r\\n46920x33014 [0,100 46000x32914] (256x256) JPEG/RGB Q=30|AppMag = 20|StripeWidth = 2040|ScanScope ID = CPAPERIOCS|Filename = CMU-1|Date = 12/29/09|Time = 09:59:15|User = b414003d-95c6-48b0-9369-8010ed517ba7|Parmset = USM Filter|MPP = 0.4990|Left = 25.691574|Top = 23.449873|LineCameraSkew = -0.000424|LineAreaXOffset = 0.019265|LineAreaYOffset = -0.000313|Focus Offset = 0.000000|ImageID = 1004486|OriginalWidth = 46920|Originalheight = 33014|Filtered = 5|OriginalWidth = 46000|OriginalHeight = 32914"}', 'pixel_depth': '{"0": 1}', 'pkg_version': '0.3.7', 'valid': 1}

The API offers also a more granular access to each level’s properties, where you can query information about each resolution layer

Python

slide.level_properties(0)

{'json_write_kwargs': '{"subifds": 0, "metadata": {"axes": "YXS"}, "extratags": [], "photometric": {"py/reduce": [{"py/type": "tifffile.tifffile.PHOTOMETRIC"}, {"py/tuple": [2]}]}, "planarconfig": {"py/reduce": [{"py/type": "tifffile.tifffile.PLANARCONFIG"}, {"py/tuple": [1]}]}, "extrasamples": {"py/tuple": []}, "rowsperstrip": 0, "bitspersample": 8, "compression": {"py/reduce": [{"py/type": "tifffile.tifffile.COMPRESSION"}, {"py/tuple": [7]}]}, "predictor": 1, "subsampling": {"py/tuple": [2, 2]}, "jpegtables": {"py/b64": "/9j/2wBDABsSFBcUERsXFhceHBsgKEIrKCUlKFE6PTBCYFVlZF9VXVtqeJmBanGQc1tdhbWGkJ6jq62rZ4C8ybqmx5moq6T/xAAfAAABBQEBAQEBAQAAAAAAAAAAAQIDBAUGBwgJCgv/xAC1EAACAQMDAgQDBQUEBAAAAX0BAgMABBEFEiExQQYTUWEHInEUMoGRoQgjQrHBFVLR8CQzYnKCCQoWFxgZGiUmJygpKjQ1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4eLj5OXm5+jp6vHy8/T19vf4+fr/2Q=="}, "colormap": null, "subfiletype": {"py/reduce": [{"py/type": "tifffile.tifffile.FILETYPE"}, {"py/tuple": [0]}]}, "software": "", "tile": {"py/tuple": [240, 240]}, "datetime": null, "resolution": {"py/tuple": [1.0, 1.0]}, "resolutionunit": 2}',
 'level': 0}

Read a resolution level

You can read a whole resolution level by defining the level ID:

Python

level_0 = slide.read_level(0)

You can then visualize it as follows:

Python

import cv2
import matplotlib.pylab as pylab

norm_img3d = cv2.normalize(
    src=level_0, dst=None, alpha=0, beta=255, norm_type=cv2.NORM_MINMAX, dtype=cv2.CV_8U
)
pylab.imshow(norm_img3d)

Slice a resolution level

You can slice image data of a specific level with the read_region method by defining the upper left coordinates and the size of your slice.

Python

img_region = slide.read_region((1000, 1000), 0, slide.dimensions)

Python

norm_img_region = cv2.normalize(
    src=img_region,
    dst=None,
    alpha=0,
    beta=255,
    norm_type=cv2.NORM_MINMAX,
    dtype=cv2.CV_8U,
)
pylab.imshow(norm_img_region)