Skip to main content

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

Project description

tiler

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 tapering (window) functions.

This is especially helpful for semantic segmentation tasks in deep learning, where we often have to work with images that 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
  • Optimized to avoid unnecessary memory copies: numpy views for all tiles, except border tiles that require padding
  • N-dimensional array tiling (but for now tiles must have the same number of dimensions as the array)
  • Supports channel dimension: dimension that will not be tiled
  • Overlapping support: you can specify tile percentage or directly overlap size
  • Access individual tiles with consistent indexing or with a convenience iterator
  • Merging tiles back into a full array with optional un-padding to the original shape
  • Merging supports scipy window functions

Roadmap

  • Proper documentation
  • Teaser image for github
  • Batched tiles
  • Implement overlap-tile strategy
  • Ability to generate tiling for specific window in mind (=> 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

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 .

Examples

For now, only the one examples/tiler_example.py

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:

Academic references

Introducing Hann windows for reducing edge-effects in patch-based image segmentation, Pielawski and Wählby, March 2020

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

Uploaded source

Built Distribution

tiler-0.1.1-py3-none-any.whl (17.6 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