TeraConverter

TeraConverter is a command-line tool for converting terabytes (and more) of multidimensional (3/4/5D) image data from/to different formats. Specifically, it can:

• convert one format (e.g. TIFF series) to another (e.g. Imaris IMS file format)
• generate a multiresolution pyramid suited for real-time visualization with TeraFly and BigDataViewer
• stitch multiple image stacks given their positions (this replaces the Merge step of TeraStitcher)
• perform any of the previous tasks on a x-y-z subset of the input data, with one or multiple CPUs (for more details about parallel execution, see here)
  
  

Quick navigation

	Download and install
	Supported file formats
	Usage
	Demo
	Memory requirements

Download

You can find the latest TeraConverter build within the TeraStitcher-portable package available at this link.

Alternatively, you can build TeraConverter from source along with TeraStitcher by enabling the flags WITH_UTILITY_MODULE_teraconverter and WITH_UTILITY_MODULE_volumeconverter at CMake time.

Supported file formats

• TIFF (3D) [input]
  a multipage 3D TIFF file (grayscale or RGB)
• TIFF (series, 2D) [input/output]
  a folder containing a series (1+) of 2D TIFF files (grayscale or RGB)
• TIFF (tiled, 2D) [input/output]
  y-x-z hierarchy of tiles, each tile is a series of 2D TIFF files (grayscale or RGB)
• TIFF (tiled, 3D) [input/output]
  y-x-z hierarchy of tiles, each tile is a series of multipage 3D TIFF files (grayscale or RGB)
• TIFF (tiled, 4D) [input/output]
  c-y-x-z hierarchy of tiles, each tile is a series of single-channel multipage 3D TIFF files (grayscale only)
• Vaa3D raw [input]
  a 3D Vaa3D raw file (grayscale or multi-channel)
• Vaa3D raw (series, 2D) [input/output]
  a folder containing a series (1+) of 2D Vaa3D raw files (grayscale or multi-channel)
• Vaa3D raw (tiled, 2D) [input/output]
  y-x-z hierarchy of tiles, each tile is a series of 2D Vaa3D raw files (grayscale or multi-channel)
• Vaa3D raw (tiled, 3D) [input/output]
  y-x-z hierarchy of tiles, each tile is a series of 3D Vaa3D raw files (grayscale or multi-channel)
• Vaa3D raw (tiled, 4D) [input/output]
  c-y-x-z hierarchy of tiles, each tile is a series of 3D single-channel Vaa3D raw files (grayscale only)
• HDF5 (BigDataViewer) [input/output]
  a HDF5 file containing a BigDataViewer 3D image (grayscale or multi-channel)
• HDF5 (Imaris IMS) [input/output]
  a HDF5 file containing a Imaris 3D image (grayscale or multi-channel)
• TIFF (unstitched, 3D) [input]
  a TeraStitcher XML descriptor pointing to a valid unstitched image

all the previous formats can be extended to a fifth dimension (time t) either by having one separated file (or folder) for each time point (TIFF and Vaa3D formats), or by storing all time points into one file (HDF5 formats).

all the previous formats, can be extended to a sixth dimension (pyramid resolution layer l) either by having separated folders (TIFF and Vaa3D formats), or by storing all image resolutions into one file (HDF5 formats).

The image below depicts the general schema of the 3D (y-x-z) tiled formats (TIFF and Vaa3D), with the optional c (channel), t (time) and l (pyramid resolution layer) dimensions. The u is the space unit (e.g. 1 micrometer).

Usage

TeraConverter is a command line tool. A user-friendly GUI version including most (but not all) the functionalities of the command-line version is available within Vaa3D under Vaa3D Menu > Advanced > Big-Image-Data > TeraConverter. Here, we describe the basic usage options of the command-line version only. For advanced options, type teraconverter --help.

teraconverter -s=<source> -d=<destination> --sfmt --dfmt [--resolutions] [--width] [--height] [--depth] [--H0] [--H1] [--V0] [--V1] [--D0] [--D1] [--mdata_fname] [--ch_dir] [--clist] [--halve]

---

--sfmt=<string>

Any of the supported input formats listed in the Supported file formats section.

---

--dfmt=<string>

Any of the supported output formats listed in the Supported file formats section.

---

--resolutions=<string>

Resolutions indices ( layers l) of the image pyramid to be produced. l must be in [0,10] and 2^l is the corresponding subsampling factor. Default is 0, that means that only the original resolution (subsampling factor 2^0=1) will be produced. For instance: 0123 means pyramid layers 0, 1, 2 and 3 will be produced; 25 means pyramid layers 2 and 5 will be produced; and so on.

---

--width=<integer>, --height, --depth

Tiles dimension along x, y and z, respectively (for tiled output formats, only).

---

--H0=<integer>, --H1, --V0, --V1, --D0, --D1

[H0,H1) x [V0,V1) x [D0,D1) define the x-y-z subset of the input data to process.

---

--mdata_fname=<string>

File containing general metadata of the image.

---

--ch_dir=<string>

Subdirectory to store the channel (single channel in tiled 4D format only).

---

--clist=<string>

Subset of channels to be converted (default: all).

---

--halve=<string>

Halving method (mean/max, default: mean).

Demo

Download and unpack the example dataset at this link and follow the demo below.

Memory requirements

Let be

• Dx and Dy the x and y dimensions of the input image I
• D = max(Dx, Dy)
• L the lowest requested resolution layer in --resolutions, i.e. the highest integer
• B the number of bytes per pixel (e.g. 1 for 8-bit, 2 for 16-bit)
• C the number of channels (e.g. 1 for grayscale, 3 for RGB)

Then the overall memory requirement for converting an input image I is governed by