Skip to main content

Command-line tool and python library for visualising small 3D datasets

Project description


Simple matplotlib-based tool for viewing small amounts of 3D image data; helpful for debugging. Supports python 2.7 and 3.4+.

Adapted from this matplotlib recipe.


pip install smalldataviewer

Some file types require additional dependencies:

  • HDF5: h5py

    • pip install h5py

  • zarr, N5: z5py

    • conda install -c cpape -c conda-forge z5py


As executable

usage: smalldataviewer [-h] [-i INTERNAL_PATH] [-t TYPE] [-o ORDER]
                       [-f OFFSET] [-s SHAPE] [-v]

positional arguments:
  path                  Path to file containing a 3D dataset

optional arguments:
  -h, --help            show this help message and exit
  -i INTERNAL_PATH, --internal_path INTERNAL_PATH
                        Internal path of dataset inside HDF5, N5, zarr or npz
                        file. If JSON, assumes the outer object is a dict, and
                        internal_path is the key of the array
  -t TYPE, --type TYPE  Dataset file type. Inferred from extension if not
  -o ORDER, --order ORDER
                        Order of non-channel axes for axis labelling purposes
                        (data is not transposed): dimension 0 will be scrolled
                        through, dimension 1 will be on the up-down axis,
                        dimension 2 will be on the left-right axis, and
                        dimension 3, if it exists, will be used as the colour
                        channels. Default "zyx".
  -f OFFSET, --offset OFFSET
                        3D offset of ROI from (0, 0, 0) in pixels, in the form
  -s SHAPE, --shape SHAPE
                        3D shape of ROI in pixels, in the form
  -v, --verbose         Increase logging verbosity
smalldataviewer my_data.hdf5 -i /my_group/my_volume

Note: because of the circumstances under which python holds file descriptors open, and under which matplotlib blocks, the executable form reads the data into memory in its entirety. If your data are too big for this, look at small chunks with the --offset (-f) and --shape (-s) options.

As library

from smalldataviewer import DataViewer, dataviewer_from_file

import numpy as np
data = np.random.random((30, 100, 100))

viewer = DataViewer(data)  # or

viewer2 = DataViewer.from_file("my_data.npz", "volume")

Note: Dataviewer.from_file reads the requested data from the file into memory. DataViewer does not, by default. However, you may need to, depending on the rest of your script.

Other formats

Support for many data formats comes from the excellent library imageio. Even more formats are available with plugins: see the imageio docs for more details.


Install a development environment (not including z5py) with make install-dev

Run tests in your current python environment with make test

Run tests against all supported python versions with make test-all

If you would like to add support for a new file type:

  1. Add to tests/common a function which creates such a file and returns whether

    it needs an internal path, and add it to file_constructors.

  2. Add to smalldataviewer.files.FileReader a function which reads such a file,

    returning a numpy array, and add a mapping from likely file extensions to a single file type in NORMALISED_TYPES (see examples).

  3. Don’t forget to specify any dependencies in smalldataviewer.ext,

    extras_require in, and requirements.txt

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

smalldataviewer-0.6.0.tar.gz (10.2 kB view hashes)

Uploaded source

Built Distribution

smalldataviewer-0.6.0-py2.py3-none-any.whl (15.5 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page