Read Biomedical Images with TileDB-Py

Learn how to read a biomedical image with TileDB-Py API.

Slicing and reading your data in TileDB is essential step to access 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 and slice your biomedical imaging data by using the native TileDB-Py API. This API is the main interface for interacting with TileDB in Python.

Note

To use the TileDB-Py API with biomedical images effectively, you should first have a good understanding of the TileDB-BioImaging underlying data model.

Setup

Start by importing the necessary libraries needed for this tutorial.

Python

import os
import shutil

import cv2
import matplotlib.pylab as pylab
import tiledb
from tiledb.bioimg.converters.ome_tiff import OMETiffConverter

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

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

os.makedirs(root_dir)

Image Properties

TileDB, after ingesting an image, stores the whole image as a TileDB group.

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

Querying the properties of the image is the same as querying the metadata of the TileDB group.

Python

img_grp = tiledb.Group(data_dest, "r")
img_properties = img_grp.meta
img_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}

Each resolution layer is now a TileDB array and member of the image TileDB group. To get a more granular access to each level’s properties you need to access the metadata of the members of the group. The members are TileDB arrays representing each resolution level.

Python

level_0 = tiledb.open(img_grp[0].uri)
level_0.schema

Domain

Name Domain Tile Data Type Is Var-length Filters C (0, 2) 3 uint32 False Name Option Level ZstdFilter level 0 Y (0, 2966) 1024 uint32 False Name Option Level ZstdFilter level 0 X (0, 2219) 1024 uint32 False Name Option Level ZstdFilter level 0

Attributes

Name Data Type Is Var-Len Is Nullable Filters intensity uint8 False False Name Option Level ZstdFilter level 0

Cell Order

row-major

Tile Order

row-major

Sparse

False

Python

for metadata in level_0.meta.items():
    print(metadata)

('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 accessing the corresponding member of the group and slicing the whole domain.

Note

The attribute name of all the pixel cells stored in a TileDB array is defined as intensity.

Python

level_0 = tiledb.open(img_grp[0].uri)
img = level_0[:]["intensity"]

and visualize it as following:

Python

transposed_img = img.transpose(1, 2, 0)
norm_img3d = cv2.normalize(
    src=transposed_img,
    dst=None,
    alpha=0,
    beta=255,
    norm_type=cv2.NORM_MINMAX,
    dtype=cv2.CV_8U,
)
pylab.imshow(norm_img3d)

Warning

The TileDB-Py API is built for general purpose use and doesn’t assume anything about the data you’re working with (like the fact that it’s an image). This means that when you select parts of an image by using slicing, you may need to transpose the data afterwards. Transposing essentially reorders the data so that it’s in the correct format for other image processing libraries to understand.

Slice a resolution level

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

Python

img = level_0[:, 1000:, 1000:]["intensity"]
img.shape

(3, 1967, 1220)

Python

transposed_img = img.transpose(1, 2, 0)
norm_img3d = cv2.normalize(
    src=transposed_img,
    dst=None,
    alpha=0,
    beta=255,
    norm_type=cv2.NORM_MINMAX,
    dtype=cv2.CV_8U,
)
pylab.imshow(norm_img3d)