napari-imaris-loader

Napari plugin for loading Bitplane imaris files '.ims'


    View project data

    This plugin enables viewing of Bitplane Imaris files, including very large datasets. The GIFs below demonstrate rendering of a ~2TB IMS file containing a 2 color whole mouse brain. The plugin has been tested on datasets as large as 20TB.

    NOTE: For this plugin to work "File/Preferences/Experimental/Render Images Asynchronously" must be selected.

    Open IMS file:

    Open IMS file GIF

    Render in 3D:

    A plugin is provided to dynamically reload the data after selecting the lowest resolution level to be included in the viewer. Since napari only renders the lowest resolution, the user can use this plugin to control the quality of 3D rendering. See features and limitations for tips on suggested usage.

    3D Rendering and Quality Adjustment GIF

    Features

    • Multiscale Rendering
      • Image pyramids which are present in the native IMS format are automatically added to napari during file loading.
    • Chunks are implemented by dask and matched to the chunk sizes stored in each dataset. (Napari appears to only ask for 2D chunks - unclear how helpful this feature is currently)
    • Successfully handles multi-terabyte multi-timepoint multi-channel datasets.
    • Tested with all sample files provided by Bitplane.
    • Higher 3D rendering quality is enabled by a widget that reloads data after specifying the lowest resolution level (higher number = lower resolution) to be included in the multiscale series.

    Known Issues / limitations

    • Currently, this is only an image loader, and there are no features for loading or viewing objects
    • Napari sometimes throws errors indicating that it expected a 3D or 5D array but receives the other.
      • This sometimes but relatively rarely causes napari to crash
      • Would like to enable Asynchronous Tiling of Images, but this results in more instability and causes crashes.

    This napari plugin was generated with Cookiecutter using with @napari's cookiecutter-napari-plugin template.

    Installation

    You can install napari-imaris-loader via pip:

    pip install napari-imaris-loader

    Change Log:

    v0.1.2:

    Fixed: Issue where .ims files containing a single color 2D image would not open.

    Fixed: Issue where using the widget to change resolutions while in 3D rendering would cause a crash. Now the viewer is automatically forced into 2D rendering mode when the widget is used.

    Dependency change: The loader is now dependent in a separate package for loading IMS files. https://pypi.org/project/imaris-ims-file-reader/

    v0.1.3:

    Documentation

    v0.1.4:

    Add napari to install requirements for plugin compatibility

    v0.1.5:

    Changes to napari:

    • now requires napari[all] upon install.
    • requires >=v0.1.5 of imaris-ims-file-reader

    v0.1.6:

    • Fix issue #7 where contrastLimits possibly unbound in reader

    v0.1.7:

    • For squeeze_output=False when opening .ims file for Napari compatibility

    v0.1.8:

    • Add automatic determination of contrast_limits
    • Fix bug in squeeze_output

    Contributing

    Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

    License

    Distributed under the terms of the BSD-3 license, "napari-imaris-loader" is free and open source software

    Issues

    If you encounter any problems, please file an issue along with a detailed description.

    Version:

    • 0.1.8

    Release date:

    • 13 April 2022

    First released:

    • 21 October 2021

    License:

    • BSD-3-Clause

    Supported data:

    • Information not submitted

    GitHub activity:

    • Stars: 3
    • Forks: 2
    • Issues + PRs: 0

    Python versions supported:

    Operating system:

    Requirements:

    • napari[all]
    • napari-plugin-engine (>=0.1.4)
    • imaris-ims-file-reader (>=0.1.5)
    • numpy
    • h5py
    • dask

    Sign up to receive updates