czi-chksum

czi-chksum calculates reproducible, content-oriented checksums for Carl Zeiss Image (CZI) documents.

Unlike a conventional whole-file checksum, it processes the constituent parts of a CZI document: image sub-blocks, attachments, and metadata XML. For image sub-blocks, it can hash either the decoded bitmaps or the raw, potentially compressed data stored in the CZI file. The individual hashes are aggregated so that the result does not depend on the order in which sub-blocks or attachments occur in the file.

Prebuilt archives for Windows, Linux, and macOS are available from the GitHub Releases page.

Extract the archive and run the executable found in its bin directory. No installation is required.

czi-chksum --input <file.czi> [options]

For example, print only the combined checksum using the default XXH128 algorithm and decoded-bitmap mode:

czi-chksum --input example.czi --verbosity extra-quiet

80ff9475c220cd442cdc319c90c421d9

On Windows, depending on the current directory, the command may be invoked as:

.\czi-chksum.exe --input example.czi --verbosity extra-quiet

Use --help to display all command-line options and --version to display the program and libCZI versions.

The --subblock-hash-mode option determines which image representation is hashed:

• decoded-bitmap (default) hashes the decoded bitmap pixels of each image sub-block. This is useful when equivalent image content should produce the same result regardless of how it is compressed in the CZI file.
• raw-data hashes the raw, potentially compressed data as stored in each image sub-block. Changes to compression or encoded representation can therefore change the checksum even when the decoded bitmaps are identical.

The mode affects image data only. Relevant sub-block information, embedded sub-block metadata, and sub-block attachments are included in either mode.

czi-chksum --input example.czi --subblock-hash-mode decoded-bitmap
czi-chksum --input example.czi --subblock-hash-mode raw-data

Checksums produced using different modes should not be compared.

Select the hash algorithm with --algorithm:

• xxh128 (default)
• md5

czi-chksum --input example.czi --algorithm md5

These algorithms and the order-independent aggregation are intended to detect accidental content differences. They must not be used for authentication, digital signatures, or protection against deliberate manipulation.

Select the output with --verbosity:

standard is accepted as an alias for normal.

The combined checksum represents:

• image sub-block content and relevant sub-block information;
• sub-block metadata and sub-block attachments;
• document attachments and their identifying information;
• document metadata XML and its optional attachment.

Hashes within each content category are aggregated independently of item order and then combined into the final checksum.

For reliable comparisons, use the same czi-chksum version, hash algorithm, and sub-block hash mode for all files being compared.

A C++17 compiler, CMake 3.16 or newer, Git, and internet access during configuration are required. CMake fetches the pinned source revisions of libCZI, CLI11, and xxHash together with libCZI's required dependencies.

Configure and build a release version:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Run the black-box tests:

ctest --test-dir build --build-config Release --output-on-failure

Install the executable and its license documentation into a local directory:

cmake --install build \
    --prefix install \
    --config Release \
    --component czi-chksum

On Windows PowerShell, use backticks for line continuation or place the command on one line.

Continuous integration builds and tests the project on:

• Windows x86-64
• Windows ARM64
• Linux x86-64
• macOS Arm64

czi-chksum is licensed under the MIT License. Third-party components are distributed under their respective licenses; see the third-party license notices for the complete notices and license texts included with binary releases.

Release binaries statically link libCZI under LGPL-3.0-or-later. See the static LGPL relinking guide for the pinned source and build information needed to rebuild with a modified libCZI.