XuvTools is developed in a cooperative effort from:
  • Chair of Pattern Recognition and Image Processing [www]
  • Friedrich Miescher Institute for Biomedical Research [www]
  • Center for Biological Systems Analysis [www]

XuvTools Project Files

This documentation is valid for project files of XuvTools 1.8.1. Previous versions can differ significantly. While Xuvtools can read previous project files, they are deprecated and should not be used anymore.

Plain Text Format

The plain text project file format is simple and straightforward. It contains an arbitrary number of key-value-pairs, one per line. Key and value are separated by the assignment operator '='. The following shows a simple example:


The text file constraints are:

  • Text file line separator should be '\n' (but other formats as '\r\n' are accepted as well).
  • Leading and ending whitespace is ignored in all lines
  • Comments can be added. Everything after a double slash '//' is treated as a comment.

HDF5 Format

FIXME: to be added later.

How loading and storing works

This should explain how the configmap and project files work together. The functionality for loading a project file works like this:

  • XuvTools sets a default configmap on startup
  • loading a project file:
    • loads the contents of the file into a string buffer
    • iterates over the buffer and sets for all keys 'stackXXXX_filename' the value to an absolute path
    • adds the contents of the string buffer to the configmap. Note: this does not clear the configmap before!
  • saving a project file:
    • copys the contents of the configmap into a string buffer
    • iterates over the buffer and sets for all keys 'stackXXXX_filename' the value to an relative path
    • dumps the contents of the string buffer to the project file

FIXME: A possible optimization would be to have an attribute exclusion list, that defines values which should not be loaded/stored in project files. One example is the “projectfilename”.

A Minimal Project File

Minimal project files are a useful way for other (thirdparty) software to export information to XuvTools. The following lists the required, essential information to assign multiple stacks with coordinates to a XuvTools project file.

Minimal Project File Options Explained

In the following, the combination “XXXX” means a four digit numeric identifier, that is unique to a stack or tile.

Key Valuetype Value description Explanation
scene_element_size_um vector of floats Z,Y,X elm. size Extent of a single voxel of the dataset in the scene, in um. This is required to work around a bug in the GUI.
xuvstitch_project_version vector of int version The version number of XuvTools this project file is compatible with. XuvTools is backward compatible, so all higher versions should be able to read the project correctly.
stackXXXX string channel Key: This id is the prefix for all other information about the stack.
Value: an arbitrary string (or number). Must be identical for the same channels
stackXXXX_tile tileXXXX tile identifier Value: Which Tile does the stack belong to? Unique id
stackXXXX_stack_file_id string identifier in file Value: This is the identifier for loading and storing the stack
in the file. For most XuvTools file readers (all except HDF5 based), use <series>,<timepoint>,<channel>,
i.e. “0,7,0” for series 0, timepoint 7, channel 0.
See extra paragraph below for more details.
stackXXXX_size_pix vector of integers Z,Y,X size Extent of stack, as in the file (not the (scaled) stack extent in memory)
stackXXXX_element_size_um vector of floats Z,Y,X elm. size Extent of a single voxel of the dataset, in um
stackXXXX_datatype enum Datatype Datatype of the stack in the file:
CHAR = 1, UCHAR = 2, SHORT = 3, USHORT = 4, INT = 5, UINT = 6,
LONG = 7, ULONG = 8, LLONG = 9, ULLONG = 10, FLOAT = 11, DOUBLE = 12
stackXXXX_enabled bool status Value: should this stack be used in the correlation? Default = 1
stackXXXX_filename pathname File name Value: Which File does the stack belong to? “C:\tmp\test.h5”
stackXXXX_color_rgb vector of float R,G,B float Float color values from [0,1] in RGB ordering
tileXXXX_channels vector of stack ids stackXXXX, …, stackZZZZ (Sorted) list of stacks that form the channels of this tile
tileXXXX_abs_pos_um vector of float Z,Y,X position Absolute position of the tile, in um coordinates
tileXXXX_enabled bool status Value: should this tile be used in the correlation? Default = 1

Minimal Project File Example


Referencing Image Stacks in Project Files

XuvTools can make use of a diverse set of image readers/writers. To provide an abstract interface for referencing image stacks in files, the following attributes are used:

stackXXXX_filename Type: string image file name
example: /data/xuvtools_img/2dstitch/img01.tif
stackXXXX_stack_file_id Type: string unique identifier for the series,timepoint,channel of the image stack
A comma-separated unpadded list of integer values, corresponding to series, timepoint, and channel.
example: 0,2,0
devel/project_files.txt · Last modified: 2010/12/22 20:06 by mario
Contact: admin(a)xuvtools.org