nd2tool

Introduction

Provides the command line tool, nd2tool, that can be used to:

make a short summary of the meta data in a nd2 file (--info),
extract all metadata (--meta) from nd2 file or specific portions (--meta-file, --meta-coord, --meta-frame, --meta-text, --meta-exp), and,
export the image data to tif file(s). Either one per Field of View (FOV) (--composite), or one file per FOV and color.

The RAM usage is low. Only one image plane is loaded into RAM at the same time. As an example, a 23 GB ND2 image can typically be converted to tiff files using less than 100 Mb of RAM.

nd2tool should be considered as experimental since it is only tested on a few images. If it does not work for your images, please submit a bug report, or simply find a tool that suits you better; some alternatives are listed in the references. At the moment it only supports loops over XY, Color and Z, i.e., not over time. It is furthermore limited to nd2 files where the image data is stored as 16-bit unsigned int.

Example usage

$ nd2tool iiQV015_20220630_001.nd2
3 FOV in 4 channels:
   #1 '  A647', _em=710.0 #E10000  ir
   #2 'SpGold', _em=572.0 #FFFF00
   #3 '  A488', _em=543.0 #00FF00
   #4 '  dapi', _em=385.0 #8900FF  uv
Bits per pixel: 16, significant: 16
dx=324.5 nm, dy=324.5 nm, dz=300.0 nm
NA=0.750, ni=1.000
Objective Name: Plan Apo VC 20x DIC N2
Objective Magnification: 20.0X
Volume size: 2048 x 2048 x 241
Looping: Dimensions: XY(3) x (4) x Z(241)
Writing to iiQV015_20220630_001/A647_001.tif
Writing to iiQV015_20220630_001/SpGold_001.tif
...
Writing to iiQV015_20220630_001/dapi_003.tif

See the man page for the full documentation (i.e. man nd2tool) or use nd2tool --help for a quick recap.

Installation

The standard procedure: get required libraries, compile and then install. These instructions are for Ubuntu 22.04 LTS (might work on WSL for Windows as well).

# get dependencies
sudo apt-get update
sudo apt-get install libcjson1 libcjson-dev libtiff5-dev build-essential
make release  # compile

After building, the preferred way to install is to first make a .deb file like this:

./makedeb_ubuntu_2204.sh
sudo apt-get install ./nd2tool_*.deb
# Then you can uninstall with
# sudo apt-get remove nd2tool

For systems that don't use deb files, this might work:

sudo make install   # Install binary and man page

Please check the makefile so that the install paths makes sense on your machine if you use this install option.

Reporting bugs

Please use the issue tracking system on github to report bugs or to get in touch. Have a look on the roadmap before submitting suggestions or making pull requests.

References

Alternative command line tools for nd2 files:

ggirelli/radiantkit - Command line tool for conversion from nd2 to tiff as well as lots of other stuff. Unfortunately the repository has been archived but the code is still useful. Uses the Python package nd2reader.

GUI tools for nd2 files:

Nikon NIS Elements (Viewer) unfortunately not for Linux.
FIJI/ImageJ

Python libraries/tools for nd2 files:

Open-Science-Tools/nd2reader a pure Python package for reading nd2 files. I.e. not using the Nikon library.
tlambert03/nd2 a Python package that uses and ships Nikons shared objects.

Libraries used by nd2tool:

cJSON for parsing JSON data.
libTIFF for writing tif files.
Nikon's nd2 library for reading nd2 files (with permission to redistribute the shared objects).
the GNU C library

Related/useful:

Interactively explore JSON data Copy and paste the JSON output from nd2tool (--meta-file, --meta-frame, --meta-exp) here for a quick overview. See also JSON specification if you are new to this.