Table of Contents
XuvTools Project Files
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:
KEY=VALUE
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
: 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
: 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
xuvstitch_project_version=1,8,1 scene_element_size_um=1,1,1 stack0001=0 stack0001_datatype=2 stack0001_element_size_um=1,1,1 stack0001_enabled=1 stack0001_filename=/data/xuvtools_img/2dstitch/img01.tif stack0001_size_pix=7,512,512 stack0001_stack_file_id=0,3,0 stack0001_tile=tile0001 stack0002=0 stack0002_datatype=2 stack0002_element_size_um=1,1,1 stack0002_enabled=1 stack0002_filename=/data/xuvtools_img/2dstitch/img02.tif stack0002_size_pix=7,512,512 stack0002_stack_file_id=0,3,1 stack0002_tile=tile0002 stackcounter=2 stacks=stack0001,stack0002 tile0001_abs_pos_um=1,1,1 tile0001_channels=stack0001 tile0001_enabled=1 tile0002_abs_pos_um=1,1,493 tile0002_channels=stack0002 tile0002_enabled=1 tilecounter=2 tiles=tile0001,tile0002
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 |