Skip to main content

Fast N-dimensional numpy array tiling and merging with overlapping, padding and tapering support

Project description

tiler

CI Coverage Status PyPI version

Please note: work in progress! Until a stable release, please avoid using this package in production!

This package provides tools for N-dimensional tiling (patch extraction) and subsequent merging with built-in tapering (window) function support.

This is especially helpful for various heavy-processing tasks such as semantic segmentation in deep learning, especially in domains where images do not fit into GPU memory (2D hyperspectral satellite images, 2D whole slide images, 2D videos, 3D tomographic data etc.).

Implemented features

  • Data reader agnostic: works with numpy arrays
  • N-dimensional array tiling (note: currently tile shape must have the same number of dimensions as the array)
  • Optional in-place tiling (without creating copies)
  • Supports channel dimension: dimension that will not be tiled
  • Supports batching of tiles
  • Overlapping support: you can specify tile percentage or directly overlap size
  • Window functions: Merger accepts weights for the tile as an array or a scipy window
  • Convenient access to the tiles: with an iterator or a separate getter
  • Easy merging to the full size: just add the processed tile to the Merger

Quick start

This is an example of basic functionality.
You can also 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(image_shape=image.shape,
              tile_shape=(3, 250, 250),
              channel_dimension=2)

# You can access tiles with an iterator
for tile_id, tile in tiler(image):
    print(f'Tile {tile_id} out of {len(tiler)} tiles.')

# You can access tiles individually
tile_3 = tiler.get_tile(image, 3)

# You can access tiles in batches
tiles_in_batches = [batch for _, batch in tiler(image, batch_size=10, drop_last=True)]

# Setup merger object with constant window
merger = Merger(tiler, window='boxcar')

# Merge one by one
for tile_id, tile in tiler(image):
   merger.add(tile_id, some_processing_fn(tile))
final_image = merger.merge(unpad=True)

# Merge in batches
merger.reset()
for batch_id, batch in tiler(image, batch_size=10):
   merger.add_batch(batch_id, 10, batch)
final_image_batches = merger.merge(unpad=True)

final_image.shape, final_image_batches.shape
>>> (3, 1920, 1080), (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 .

Roadmap

  • Proper documentation
  • Teaser image for github
  • Easy generation of tiling for specific window in mind (i.e. so that every element has the window weight sum of 1.0)
  • Add border windows generation (like in Pielawski et. al - see references))
  • PyTorch Tensors support
    • merging on GPU like in pytorch-toolbelt?
  • More examples
  • Implement windows functions and remove scipy dependency (we need only a couple of functions that generate windows)
  • PyTorch Dataset class convenience wrapper?
  • Arbitrary sized tiles (m-dim window over n-dim array, m <= n)?
  • Optional augmentation modes for smoother segmentations?
    • D4 rotation group
    • Mirroring
  • Benchmark with plain for loops, determine overhead

Motivation & other tiling/patching packages

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

However, other libraries might fit you better than tiler:

Moreover, some approaches have been described in the literature:

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.1.3.tar.gz (16.9 kB view hashes)

Uploaded source

Built Distribution

tiler-0.1.3-py3-none-any.whl (16.3 kB view hashes)

Uploaded py3

Supported by

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