Reader compatibility options#
libCZI normally interprets each sub-block as a two-dimensional X-Y bitmap on a plane selected by coordinates such as Z, C and T. Some acquisition workflows use an alternative dimension convention: a sub-block contains an X-T or X-Z image, with T or Z describing its rows. Reader compatibility options allow these images to be accessed through libCZI’s existing bitmap and accessor APIs.
These options are explicit choices made when opening a document. The default interpretation remains unchanged, and libCZI does not automatically detect which convention an acquisition used.
Why a dimension swap is useful#
The motivating example was a confocal line-scan acquisition: one spatial line was scanned repeatedly over time, and each sub-block contained several of these lines. ZEN displayed the complete X-T image, while reading the same data through libCZI exposed only the first line of each sub-block. The original report is available in MEXlibCZI issue #16.
This reflects a difference in how acquisition dimensions are represented and interpreted. In libCZI’s usual image model, T selects a plane rather than describing rows within a bitmap. Treating the rows as Y makes the complete X-T image available to the existing image-processing operations. The same approach can be used for X-Z sub-blocks.
The workaround adapts the reader’s view of the data; it does not rewrite the document or its XML metadata.
Dimension mapping#
Set ICZIReader::OpenOptions::dimension_swap_workaround to one of:
Value |
Bitmap rows (Y) |
Remaining plane coordinate |
|---|---|---|
|
Original Y |
Original T and Z |
|
Original T start, logical size and stored size |
Original Y becomes T; Z is unchanged |
|
Original Z start, logical size and stored size |
Original Y becomes Z; T is unchanged |
X is unchanged. The swap is applied to both sub-block directory entries and sub-block headers. It affects the information exposed by enumeration, reader statistics, sub-block reads and accessors. Choose either the XT or the XZ workaround; both cannot be selected at once.
Note
After the swap, bitmap rows represent time samples or Z positions, rather than spatial Y positions. Interpret row coordinates and physical units accordingly. XML metadata retains its original dimension descriptions; the workaround does not generate new calibration or timing information.
Opening and composing an X-T image#
Pass the options to ICZIReader::Open before reading the directory:
auto stream = libCZI::CreateStreamFromFile(L"linescan.czi");
auto reader = libCZI::CreateCZIReader();
libCZI::ICZIReader::OpenOptions options;
options.dimension_swap_workaround =
libCZI::ICZIReader::OpenOptions::DimensionSwapWorkaround::XtSubblocks;
reader->Open(stream, &options);
For X-Z data, select XzSubblocks instead. Inspect GetStatistics() and
the enumerated coordinates after opening: the reported bounding box uses
the swapped row coordinates, and the plane coordinates use the mapping above.
For example, if the mapped document has only channel C0 and time coordinate T0 (from the original Y coordinate), its image can be composed as follows:
const auto statistics = reader->GetStatistics();
libCZI::CDimCoordinate plane{
{libCZI::DimensionIndex::C, 0},
{libCZI::DimensionIndex::T, 0}
};
auto accessor = reader->CreateSingleChannelTileAccessor();
auto image = accessor->Get(statistics.boundingBox, &plane, nullptr);
Choose the plane from the dimensions actually reported by the reader; C0T0 is an example, not a universal selection. For large acquisitions, request smaller regions instead of composing the complete bounding box in memory.
Directory and header differences#
Some affected acquisitions also have differences between the sub-block directory and sub-block headers. Handling those differences is a separate choice from swapping dimensions. The default is to use the directory’s information and report a discrepancy when the sub-block is read.
If examination of an affected document shows that it needs the directory’s interpretation despite a header difference, discrepancy reporting can be disabled explicitly:
using Policy = libCZI::ICZIReader::OpenOptions::SubBlockDirectoryInfoPolicy;
options.subBlockDirectoryInfoPolicy =
Policy::SubBlockDirectoryPrecedence | Policy::IgnoreDiscrepancy;
// Set this before calling reader->Open(stream, &options).
SubBlockHeaderPrecedence instead selects the header’s information.
Changing precedence alone does not disable discrepancy reporting: combine
it with IgnoreDiscrepancy if that is also intended.
Ignoring a discrepancy does not establish which source is correct and does not repair the file. Select these settings for documents whose acquisition convention is understood, rather than applying them to all files. See resolution protocol for the default interpretation rules.
Passing options as a string#
libCZI::StringToOpenOptions parses semicolon-separated key=value pairs.
This is useful for wrappers and is also the format accepted by CZIcmd’s
--open-options argument:
auto options = libCZI::StringToOpenOptions(
"dimensionSwapWorkaround=XtSubblocks;"
"subBlockDirectoryInfoDiscrepancy=ignore");
reader->Open(stream, &options);
auto serialized = libCZI::OpenOptionsToString(options);
The example explicitly enables both the XT swap and ignored discrepancies; omit the second pair when discrepancy reporting should remain enabled.
Key |
Values |
Default |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Invalid and Default resolve to the raw sub-block coordinate system.
The frame-of-reference setting is independent of the dimension swap.
Keys and values are case-sensitive. Whitespace around pairs, keys and values
is ignored. Empty input and omitted keys retain the defaults. Unknown or
duplicate keys, invalid values, empty pairs (including a trailing semicolon),
malformed pairs and null input cause std::invalid_argument. Escaping is
not supported. OpenOptionsToString produces all options in a canonical
order and rejects enum values or policy bits it cannot represent.
For command-line examples, see Reader open options.