Biomedical Imaging Quickstart

biomedical imaging
life sciences
quickstart
This tutorial covers the basics of working with histopathology images using TileDB-BioImaging.

This quickstart gives you a rapid introduction to TileDB-BioImaging and its capabilities. After completing this tutorial, you will learn how to do the following:

Prerequisites

Familiarize yourself with Jupyter notebooks to run data exploration and analysis efficiently. You can review Jupyter’s documentation on installing and running notebooks.

If running this tutorial locally, you’ll need to install the TileDB-BioImaging package and its dependencies. You can install them using pip:

pip install 'tiledb-bioimg[full]'

If you’re running this tutorial through a TileDB workspace, you can skip the installation step as the packages you need are already installed as part of the Genomics image.

Setup

First, create a directory to store the files for this tutorial.

Ingestion

To get started with bio-images on TileDB, import the TileDB-BioImaging package. You will then have two alternative APIs to ingest your images into TileDB.

The first option is using Converters:

from tiledb.bioimg.converters.ome_tiff import OMETiffConverter

The second option is using Wrappers:

from tiledb.bioimg import Converters, from_bioimg

Both of these APIs offer similar functionality, with the latter being a wrapper of the former. The package supports converters for multiple source formats, and the TileDB team is continuously adding more. The following formats are currently supported:

The Converters enumeration gives a list of all the supported converters you can use for ingesting images. Each converter offers a function taking a source path and storage destination for the converted TileDB multi-resolution image group. To import and use each of the supported converters, you can choose between using each converter’s API directly like the following:

OMETiffConverter.to_tiledb(src, dest, level_min=0)
OpenSlideConverter.to_tiledb(src, dest, level_min=0)
OMEZarrConverter.to_tiledb(src, dest, level_min=0)
PNGConverter.to_tiledb(src, dest, level_min=0)

You can also use the wrappers’ API for a more concise view:

from_bioimg(src, dest, level_min=0, converter=Converters.OMETIFF)
from_tiledb(src, dest, level_min=0, converter=Converters.OSD)
OMEZarrConverter.to_tiledb(src, dest, level_min=0, converter=Converters.OMEZARR)
PNGConverter.to_tiledb(src, dest, level_min=0, Converters.PNG)

Use the Wrappers API to ingest a sample image into TileDB. For this quickstart, you’ll use the OMETIFF converter to ingest an OME-TIFF image.

import os
import shutil

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)

from_bioimg(data_home, data_dest, converter=Converters.OMETIFF)
tiledb.bioimg.converters.ome_tiff.OMETiffConverter
Tip

Check out the tutorials section to learn about advanced ingestion configurations like Batch Ingestion and Chunked Ingestion.

Read data

You may read image data with the TileDB-Py API directly, or by using the OpenSlide Python-compatible API.

TileDB-Py API

import tiledb

with tiledb.Group(data_dest, "r") as ds:
    with tiledb.open(ds[0].uri) as A:
        print(A[0:99, 0:99])
OrderedDict([('intensity', array([[[221, 255, 158, ..., 243, 241, 246],
        [230, 255, 218, ..., 243, 241, 246],
        [222, 230, 231, ..., 243, 241, 246],
        ...,
        [165, 141, 145, ..., 244, 246, 248],
        [140, 164, 195, ..., 244, 246, 248],
        [122, 157, 189, ..., 244, 246, 248]],

       [[182, 172, 141, ..., 243, 241, 246],
        [172, 189, 160, ..., 243, 241, 246],
        [170, 210, 189, ..., 243, 241, 246],
        ...,
        [114,  88,  83, ..., 244, 246, 248],
        [ 78, 102, 138, ..., 244, 246, 248],
        [ 75,  89, 106, ..., 244, 246, 248]],

       [[221, 196, 164, ..., 243, 241, 246],
        [226, 212, 197, ..., 243, 241, 246],
        [184, 186, 189, ..., 243, 241, 246],
        ...,
        [147, 131, 137, ..., 244, 246, 248],
        [128, 124, 136, ..., 244, 246, 248],
        [120, 125, 138, ..., 244, 246, 248]]], dtype=uint8))])
Tip

For a more in-depth tutorial on using the TileDB-Py API to read TileDB-BioImaging data, check out the Read Biomedical Images with TileDB-Py tutorial.

OpenSlide Python API

from tiledb.bioimg.openslide import TileDBOpenSlide

# Construct OpenSlide API wrapper
img = TileDBOpenSlide(data_dest)
region_data = img.read_region(location=(0, 0), level=0, size=(100, 100))
region_data
array([[[221, 182, 221],
        [255, 172, 196],
        [158, 141, 164],
        ...,
        [246, 246, 243],
        [246, 246, 243],
        [246, 246, 243]],

       [[230, 172, 226],
        [255, 189, 212],
        [218, 160, 197],
        ...,
        [246, 246, 243],
        [246, 246, 243],
        [246, 246, 243]],

       [[222, 170, 184],
        [230, 210, 186],
        [231, 189, 189],
        ...,
        [246, 246, 243],
        [246, 246, 243],
        [246, 246, 243]],

       ...,

       [[140,  78, 128],
        [164, 102, 124],
        [195, 138, 136],
        ...,
        [243, 243, 243],
        [243, 243, 243],
        [243, 243, 243]],

       [[122,  75, 120],
        [157,  89, 125],
        [189, 106, 138],
        ...,
        [243, 243, 243],
        [243, 243, 243],
        [243, 243, 243]],

       [[188, 139, 171],
        [184, 107, 171],
        [180,  85, 171],
        ...,
        [243, 243, 243],
        [243, 243, 243],
        [243, 243, 243]]], dtype=uint8)

Visit the OpenSlide Python API documentation for all available commands. For a more in-depth tutorial on using the OpenSlide Python API to read TileDB-BioImaging data, check out the Read Biomedical Images with OpenSlide tutorial.

Visualization

If you want to take advantage of TileDB’s built-in viewer, you can preview bioimaging assets within in the TileDB UI after registering them. You can always use other visualization tools like Pillow:

import PIL

img = PIL.Image.fromarray(region_data)
img

You can also use TileDB’s other integrations with famous rendering tools like napari, as shown in the napari tutorial.

Export to OME formats

The TileDB-BioImaging library offers a utility function to export a TileDB stored image to different OME formats.

import os

from tiledb.bioimg import Converters, to_bioimg

data_export = os.path.join(root_dir, "data_out.svs")
to_bioimg(data_dest, data_export, converter=Converters.OMETIFF)
tiledb.bioimg.converters.ome_tiff.OMETiffConverter

Cleanup

Clean up in the end by removing the tutorial data.

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