Supported volume formats - abria/TeraStitcher GitHub Wiki

We have decoupled the volume format (i.e. how files are arranged on the disk) from the image file format (e.g. .tif, .jpe). Please refer to the Built-in I/O plugins section for the list of supported file formats.

Here we describe:

• a volume format that can be directly imported into TeraStitcher (i.e. two-level hierarchy of folders)
• what you need in all the other cases (i.e. an xml volume descriptor)

You can directly import your volume into TeraStitcher if tiles are organized as follows:

Root directory containing all the acquisition’s folders and files.

First level in the folder hierarchy and named as FFFFFF (6 digits). It contains one row or one column of tiles which share the coordinate FFFFFF along the first axis of the used reference system.

Second level in the folder hierarchy and named as FFFFFF_SSSSSS (6 + 6 digits). It may be empty (empty tile) or contain one stack of images which share the coordinates FFFFFF and SSSSSS along the first and second axes of the used reference system, respectively.

Image file named as ZZZZZZ (6 digits) corresponding to the coordinate along the Z axis. Both 2D and 3D image files are supported. As to the specific image format (e.g. .tif, .jpe), please refer to the Built-in I/O plugins section.

Reference system used. In this example, the reference system is (V,H,D) (or, equivalently, (Y,X,Z)). More generally, it could be any combination of axes provided that the third axis is always D (or, equivalently, Z).

Coordinates FFFFFF, SSSSSS and ZZZZZZ are expressed in tenths of microns. However, you can use your own scale provided that you scale accordingly the voxel size parameters.

TeraStitcher supports any volume format consisting of a 2D matrix of tiles which divide the volume in the XY plane. Let us refer to it as the TiledXY volume format. Each tile can be composed either by a series of 2D image files (TiledXY|2Dseries) or by a series of 3D image files (TiledXY|3Dseries).

Starting from TeraStitcher v.1.9.x, no assumptions are made on how files are arranged on the disk. They could be stored either in separated folders or even all in the same folder.

3D-tiling support (i.e. TiledXYZ) is in development (see Developments).

Download the example here.

volume format identifier. For 2D-tiling over 2D image series (as in this case), it is TiledXY|2Dseries For 2D-tiling over 3D image series is TiledXY|3Dseries.

---

identifier of the I/O plugin to be used to read the image files.

---

absolute path of the acquisition root directory.

---

voxel dimensions (in microns*) along the three axes. The minus "-" sign indicates that the corresponding axis is rotated by 180°.

*You can use your own scale provided that you scale accordingly all the measures (i.e. voxel size, origin, and mechanical displacements).

---

origin (in millimeters*) of the reference system.

*You can use your own scale provided that you scale accordingly all the measures (i.e. voxel size, origin, and mechanical displacements).

---

estimated displacement (in microns*) between two adjacent stacks along V and H axes.

*You can use your own scale provided that you scale accordingly all the measures (i.e. voxel size, origin, and mechanical displacements).

---

number of rows in the 2D matrix of tiles.

---

number of columns in the 2D matrix of tiles.

---

number of slices per tile. In the case of sparse matrices and incomplete tiles (sparse data), this is the maximum number of slices per tile.

With the term "slice" we mean the tile image data sampled at a certain coordinate along D (or Z). For 2D image series, a slice does correspond to an image file, which is not necessarily true for 3D image series.

---

number of channels

---

number of bytes used to code the voxels of one channel

---

indices (starting from 0) of the position in the tile matrix of the stack of slices

---

estimated absolute position (in voxels) of the current tile in the image space respect to the origin.

Before running the Place tiles step, this position is calculated using mechanical_displacements for X and Y and assuming perfect alignment along Z (i.e., ABS_D=0 for all tiles).

After running the Place tiles step, this is the "globally optimal" tile position calculated by TeraStitcher and used to merge tiles in the Merge step.

---

whether the corresponding tile is stitchable or not ("no" for all tiles initially, but you can edit this later to exclude specific tiles from stitching).

---

relative path to stacks_dir of the folder containing the current tile. In other words, all image files for this tile should be stored within stacks_dir/DIR_NAME

No assumptions are made here about the directory name. If you provide an XML descriptor, you can name your directories as you prefer.

---

regular expression used to select the image files within the stack folder indicated in DIR_NAME. For instance, if we have filenames like 123456_123456_123456.tiff, the regular expression to be used is [0-9]+_[0-9]+_[0-9]+.tiff. A good website to learn and try regular expressions is RegExr.
If you do not need to use this functionality, you can omit this attribute or leave it blank "".

Supported starting from TeraStitcher v.1.9.x. This functionality allows importing any possible TiledXY volume format, including bunches of image files stored in one single folder.

---

available slices along D (or Z).
For complete tiles, insert "[0,N)" where N = stack_slices
For empty tiles, leave it blank "".
For incomplete tiles, insert a sequence of intervals"[a1,b1);...[ai,bi]" separated by ; where [ai,bi) is your ith interval containing slices from ai to bi-1.

incomplete tiles are supported for TiledXY|2Dseries only. Support for TiledXY|3Dseries is currently in development (see Developments).

Download the example here.

Please refer to XML descriptor for TiledXY|2Dseries for the xml attributes not described in this section.

number of 3D image blocks in the current tile.

---

comma-separated block dimensions. Blank if tile is empty.

---

comma-separated block coordinates along D (or Z). Blank if tile is empty.