Overview
In this library the following classes are available:
- MLImageFormat
Class to manage a stored file for saving, loading or information retrieval. It is used mostly by the module classes.
- MLImageFormatTools
Collection of independent static file IO classes used mostly by mlImageFormat.
- MLImageFormatTag
Tag class used in mlImageFormatTagList
- MLImageFormatTagList
Class describing the list of tag information stored in a file.
Internal helper classes, not to be used, because they are subject to change:
- MLImageFormatInfos
Class to describe the internal state of an open file.
MLImageFormatIdxTable
Class to manage the internal index table for pages in an file.
Description of the ML File Format
The following paragraphs describe the structure of the MLImageFormat version 000.000.000 and MLImageFormat version 000.001.000.
1. Overview description
The file format can be considered as a sequence of bytes containing the following information:
- Version string
ML_FILE_VERSION_STRING
The null-terminated Version string of file, given by the constant ML_FILE_VERSION_STRING, something like "MLImageFormatVersion.000.000.000". Its length is not intended to change in future versions, only the digits at the end.
- First three digits mean that format is incompatible with other versions having not the same three digits.
- Second three digits mean that format can read older versions but older versions cannot read new ones.
- Third three digits mean that format can read older versions and older versions can read new ones.
- Tag List
Pairs of null-terminated strings of type (name, value).
The first pair is given by the null-terminated tag name TAG_LIST_SIZE_IN_BYTES_TAG followed by an also null-terminated string containing the number of bytes in the file containing tag-value pairs. This number of bytes also includes the TAG_LIST_SIZE_IN_BYTES_TAG + value pair.
The number of bytes at the start of the file containing both, the version string and the first tag and value pair TAG_LIST_SIZE_IN_BYTES_TAG + value will not exceed ML_MAX_VERSION_AND_FIRST_PAIR_SIZE bytes.
- Index table
The tag list is followed by a binary area containing index information to find stored page data in the file. For a page with an id ID the ID's entry in this table will contain storage location start and end and whether the page is compressed or not. See mlPagedImage.h for details how page ids are used. The structure of an entry is defined by the non public internal class ML_PageIdxType defined in mlIMageFormatInfos.h.
Note that index entries are stored in the endianess of the system which created the file.
- Page Data
The index table is followed by page data. The location and the structure of the page contents are defined by the corresponding entries of the index table. Note that page data is stored in the endianess of the system which created the file.
NOTES:
The entries of the index table and page data is stored in the endianess of the system which stored the file. See the ML_ENDIANESS tag in tag list to find out the endianess of the system which stored the file. Byte swapping may be necessary to restore these data values correctly.
2. The Tag List
2.1 Obligatory Tags
- Tag list size in bytes
TAG_LIST_SIZE_IN_BYTES_TAG
Size of entire tag list in bytes, including all terminating null characters.
- Data Endianess
ML_ENDIANESS
The endianess of the system where the file has been stored.
- Default voxel value.
ML_DEFAULT_VOXEL_TAG
Default voxel value used for pages which are not stored in file:
It defaults to the default value of the stored data type defined in tag ML_IMAGE_DTYPE.
- Compressor Name
ML_COMPRESSOR_NAME
Name of the compressor used to compress the data, default is "" which means no compression.
- Compressor version
ML_COMPRESSOR_VERSION
Version of the compressor used to compress the data, default is "".
- Number of compression tags
ML_NUM_COMPRESSION_TAGS
The number of stored tags containing information about used compression scheme and values, it defaults to 0.
- Compression tags
ML_COMPRESSION_TAG_< IDX >:< COMPRESSION_TAG_NAME >
...
ML_COMPRESSION_TAG_< ML_NUM_COMPRESSION_TAGS-1 >:< COMPRESSION_TAG_NAME >
The compression scheme and arguments used to compress the page data. The first tag - if available - defines the compression scheme and other tags specify scheme dependent parameters.
- Number of user tags
ML_NUM_USER_TAGS
The number of user defined tags, it defaults to 0.
- User tags
ML_USER_TAG_< IDX >:< USER_TAG_NAME >
...
ML_USER_TAG_< ML_NUM_USER_TAGS_-1 >:< USER_TAG_NAME >
The tags defined by the calling application - if available.
- Number of private tags
ML_NUM_PRIVATE_TAGS
The number of private tags, it defaults to 0 if available. It is not always stored.
- Private tags
ML_PRIVATE_TAG_< IDX >:< PRIVATE_TAG_NAME >
...
ML_PRIVATE_TAG_< ML_NUM_PRIVATE_TAGS_-1 >:< PRIVATE_TAG_NAME >
Tags defined for internal puroposes - if available.
- Name of Data Type
ML_IMAGE_DTYPE
The ML data type of the stored image. This might also be the name of a registered voxel type.
- Byte Size of Data Type
ML_IMAGE_DTYPE_SIZE
The byte size of the stored voxel type for systems which may not know all ML of registered voxel types.
- Description of Data Type
ML_IMAGE_DTYPE_DESC
The structure description of the stored voxel type for systems which may not know all ML of registered voxel types. See MLTypeInfos for meaning of this string components.
- The minimum and maximum voxel values of the image voxels:
ML_MIN_VOXEL_VALUE
ML_MAX_VOXEL_VALUE
- Image extent
ML_IMAGE_EXT_X, ML_IMAGE_EXT_Y,
ML_IMAGE_EXT_Z, ML_IMAGE_EXT_C,
ML_IMAGE_EXT_T, ML_IMAGE_EXT_U
The 6 extents of the stored ML image.
- Page extent
ML_PAGE_EXT_X, ML_PAGE_EXT_Y,
ML_PAGE_EXT_Z, ML_PAGE_EXT_C,
ML_PAGE_EXT_T, ML_PAGE_EXT_U
The 6 extents of each stored page.
- Voxel to World matrix
- ML_WORLD_MATRIX_00, ML_WORLD_MATRIX_01, ML_WORLD_MATRIX_02, ML_WORLD_MATRIX_03
- ML_WORLD_MATRIX_10, ML_WORLD_MATRIX_11, ML_WORLD_MATRIX_12, ML_WORLD_MATRIX_13
- ML_WORLD_MATRIX_20, ML_WORLD_MATRIX_21, ML_WORLD_MATRIX_22, ML_WORLD_MATRIX_23
- ML_WORLD_MATRIX_30, ML_WORLD_MATRIX_31, ML_WORLD_MATRIX_32, ML_WORLD_MATRIX_33
The to world matrix of the stored image. The last two characters of the elements values can be used exactly as corresponding indices to address the Matrix4 class elements.
- Dimension information
- ML_NUM_C_DIM_INFOS
- ML_NUM_T_DIM_INFOS
- ML_NUM_U_DIM_INFOS
The number of elements in the C, T and U dimension data structures of stored image.
2.2 Optional Tags
Often more tags are stored, which, however are not always available:
- Values of the C, T and U-dim information lists.
- ML_C_DIM_INFOS_< ENTRY_NUM >
- ML_T_DIM_INFOS_< ENTRY_NUM >
- ML_U_DIM_INFOS_< ENTRY_NUM > They start with tags named with following prefixes completed with the entry numbers. The number of available entries is defined by the tags ML_NUM_C_DIM_INFOS, ML_NUM_T_DIM_INFOS, and ML_NUM_U_DIM_INFOS:
- Values of user image properties
The number of available entries is defined by the tag ML_NUM_USER_IMAGE_PROPERTY_TAGS. They start with tags named with following prefix completed with the entry numbers: ML_USER_IMAGE_PROPERTY_TAG_< ENTRY_NUM >, the values.
- Checksum activation tag.
ML_USES_CHECKSUM enables uses checksum calculation and storage in file in all versions after MeVisLab1.5RC. Checksum checks are automatically disabled if data is compressed with lossy compressors.
- Partial pages activation tag.
ML_USES_PARTIAL_PAGES enables storing partial pages if they reach outside valid image areas. The reduced amount of compresed and stored data, in a few case even significantly. May not be set in older versions of the file format. If this tag is available then the file format number will be MLImageFormat version 000.001.000 and MLImageFormat version 000.000.000 version code will not be able to read those files any more. Code of MLImageFormat version 000.001.000 will still be able to read files of MLImageFormat version 000.000.000 of course.
3. The Index Table
For each page of the stored image there is an entry in the index table ordered like the page ids of the corresponding PagedImage. Note that index table entries are stored in an endian dependent format an need to be converted to the endianess of the system where it is loaded into memory.
One entry is defined as follows:
- Page position start as MLint64 integer value.
Denotes the start position of the page data in the file or -1 if the page content shall be reconstructed from the page default value described below.
- Page position end as MLint64 integer value.
Denotes the end position of the page data in the file or -1 if the page content shall be reconstructed from the page default value described below.
- Compression flag
1 if page is compressed, 0 otherwise
- 3 checksum bytes. 24 bit checksum for data stored in page.
- 1 flag byte. Bit 0: If enabled then the format may store partial pages, too. Bit 1-7: reserved.
- 11 reserved bytes. Reserved data area for future extensions of the format.
- Page default value.
The first voxel of the stored page, often used as fill value if it is known that the page has only one value.
4. Page Data
After the index table section the page data is located.
Notes:
- The location of the data of a page is defined by the corresponding entries in the index table, it is not necessarily located in any order of page ids.
- Page data may not be available at all, for example if the index table entry for the page has specified no position and will unpack page data from default values.
- There may be gaps or unused areas between chunks of page data due to future data defragmenting if pages are overwritten.
- The internal format of page data may differ.
- The stored data is purely the content of the image page without additional information.
- If a compressor is used it is applied as last step directly before writing the data to disk and as first step before loading the data from disk.
- The page data is always stored in the endianess of the system which writes the data. The endianess of this system is denoted in the tag ML_ENDIANESS.
Endianess correction is done after loading and decompression of the data.
- If a data compressor is used the internal format completely depends on the internal specification of the compressor.
- There may be gaps or unused areas between chunks of page data due to future data defragmenting if pages are overwritten.
1.9.1