Skip to main content

N-dimensional NumPy array tiling and merging with overlapping, padding and tapering

Project description

tiler_baby_logo tiler

Tiler teaser image

CI Coverage status PyPI version

Github repository | Github issues | Documentation


This python package provides consistent and user-friendly functions for tiling/patching and subsequent merging of NumPy arrays.

Such tiling is often required for various heavy image-processing tasks such as semantic segmentation in deep learning, especially in domains where images do not fit into GPU memory (e.g., hyperspectral satellite images, whole slide images, videos, tomography data).

Please see Quick start section.
If you want to use tiler interactively, I highly recommend napari and napari-tiler plugin.

Features

  • N-dimensional
  • Optional in-place tiling
  • Optional channel dimension (dimension that is not tiled)
  • Optional tile batching
  • Tile overlapping
  • Access individual tiles with an iterator or a getter
  • Tile merging, with optional window functions/tapering

Quick start

You can find more examples in examples.
For more Tiler and Merger functionality, please check documentation.

import numpy as np
from tiler import Tiler, Merger

image = np.random.random((3, 1920, 1080))

# Setup tiling parameters
tiler = Tiler(data_shape=image.shape,
              tile_shape=(3, 250, 250),
              channel_dimension=0)

## Access tiles:
# 1. with an iterator
for tile_id, tile in tiler.iterate(image):
   print(f'Tile {tile_id} out of {len(tiler)} tiles.')
# 1b. the iterator can also be accessed through __call__
for tile_id, tile in tiler(image):
   print(f'Tile {tile_id} out of {len(tiler)} tiles.')
# 2. individually
tile_3 = tiler.get_tile(image, 3)
# 3. in batches
tiles_in_batches = [batch for _, batch in tiler(image, batch_size=10)]

# Setup merging parameters
merger = Merger(tiler)

## Merge tiles:
# 1. one by one
for tile_id, tile in tiler(image):
   merger.add(tile_id, some_processing_fn(tile))
# 2. in batches
merger.reset()
for batch_id, batch in tiler(image, batch_size=10):
   merger.add_batch(batch_id, 10, batch)

# Final merging: applies tapering and optional unpadding
final_image = merger.merge(unpad=True)  # (3, 1920, 1080)

Installation

The latest release is available through pip:

pip install tiler

Alternatively, you can clone the repository and install it manually:

git clone git@github.com:the-lay/tiler.git
cd tiler
pip install

If you are planning to contribute, please take a look at the contribution instructions.

Motivation & other packages

I work on semantic segmentation of patched 3D data and I often found myself reusing tiling functions that I wrote for the previous projects. No existing libraries listed below fit my use case, so that's why I wrote this library.

However, other libraries/examples might fit you better:

Moreover, some related approaches have been described in the literature:

Frequently asked questions

This section is a work in progress.

How do I create tiles with less dimensions than the data array?

Tiler expects tile_shape to have less than or the same number of elements as data_shape. If tile_shape has less elements than data_shape, tile_shape will be prepended with ones to match the size of data_shape.
For example, if you want to get 2d tiles out from 3d array you can initialize Tiler like this: Tiler(data_shape=(128,128,128), tile_shape=(128, 128)) and it will be equivalent to Tiler(data_shape=(128,128,128), tile_shape=(1, 128, 128)).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tiler-0.6.0.tar.gz (978.4 kB view details)

Uploaded Source

Built Distribution

tiler-0.6.0-py3-none-any.whl (17.2 kB view details)

Uploaded Python 3

File details

Details for the file tiler-0.6.0.tar.gz.

File metadata

  • Download URL: tiler-0.6.0.tar.gz
  • Upload date:
  • Size: 978.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for tiler-0.6.0.tar.gz
Algorithm Hash digest
SHA256 a6cd2e1e0ccf6be6685d7ac1fb481fb95204054366ca6ff29bac42c62c878710
MD5 f2e2212b64beb4df32755d402ab20f9e
BLAKE2b-256 05682092c7da4fa1fe764d5afe74a205c872c6466d7d4794d3052ed8794c3370

See more details on using hashes here.

Provenance

The following attestation bundles were made for tiler-0.6.0.tar.gz:

Publisher: pypi-publish.yml on the-lay/tiler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tiler-0.6.0-py3-none-any.whl.

File metadata

  • Download URL: tiler-0.6.0-py3-none-any.whl
  • Upload date:
  • Size: 17.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for tiler-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a102c370306b683e393e7eeab8b733cdc743eedfc156d2fffc7c0fc726e8e352
MD5 6f01a7a51aebffe7da5bb6c056afee02
BLAKE2b-256 7bd9f90c4d992c20f0b9dc62fce11117d8a33bf2ebbc3f264b79123a461d73ae

See more details on using hashes here.

Provenance

The following attestation bundles were made for tiler-0.6.0-py3-none-any.whl:

Publisher: pypi-publish.yml on the-lay/tiler

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page