ktx_compare(1)

📦 version 4.4.2, in nixos 26.05, nixpkgs unstable

💅 ktx_compare(1) — the KTX Tools Reference glow-up

okay so bestie, gather round, because this is the manual page for ktx_compare from the KTX Tools Reference and it's genuinely so useful. 🎀

✨ NAME ✨

ktx_compare — ktx compare. literally just: compare two KTX2 files. that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

ktx compare [option...] input-file1 input-file2

💖 DESCRIPTION 💖

ktx compare compares the two KTX2 files you pass as the input-file1 and input-file2 arguments and outputs any mismatch in texture information and/or image data. no cap, it catches everything.

the command implicitly calls validate and prints any found errors and warnings to stdout. and listen — if any of the specified input files are invalid, then the comparison is done on a best effort basis and may be incomplete. so like, it tries its best, but don't come for it. 😭

the JSON output formats conform to the https://schema.khronos.org/ktx/compare_v0.json schema even if the input file is invalid and certain information cannot be parsed or displayed. also! for JSON outputs the KTX file identifier is printed using "\u001A" instead of "\x1A", because an unescaped "\x1A" sequence inside a JSON string breaks nearly every JSON tool. rude of it honestly. note that this does not change the value of the string, only its representation. 💅

🫶 Note

ktx compare prints using UTF-8 encoding. if your console is not set for UTF-8 you will see incorrect characters in output of the file identifier on each side of the "KTX nn". not the console's best moment tbh 🙈

⭐ OPTIONS ⭐

The following options are available:

  • --format text | json | mini-json — specifies the report output format. possible options are:
    • text — Human readable text based format.
    • json — Formatted JSON.
    • mini-json — Minified JSON.

The default format is text.

  • --content raw | image | ignore — controls how image content is compared. possible options are:
    • raw — Encoded image data is compared verbatim, as it appears in the file.
    • image — Effective image data is compared per texel block.
    • ignore — Ignore image contents.

The default mode is raw, meaning that the encoded image data must match exactly.

Note: when the mode is set to image, the effective image data of individual mip levels, layers, and faces is compared texel block by texel block after applying one or more of the following transformations, if needed:

  • If the texture is supercompressed (e.g. using Zstandard or ZLIB), the images are deflated before comparison.
  • If the texture is encoded using BasisLZ, the images are transcoded to R8G8B8A_UNORM before comparison.

For block compressed textures and textures encoded using UASTC the texel blocks are the individual compressed blocks, while for other formats the texel blocks are the individual pixels of the image.

When comparing files that use different supercompression schemes, or otherwise different encoding, additional options may need to be used to avoid unexpected differences being reported related to the meta information of the files. for example:

  • The supercompression scheme can be ignored with --ignore-supercomp.
  • Compressed byte length and other index section differences can be ignored with --ignore-index all or --ignore-index level.
  • DFD section differences can be ignored with --ignore-dfd all or --ignore-dfd all-except-color-space.
  • BDFD bytesPlane value differences can be ignored with --ignore-bdfd-bytesplane.
  • SGD section differences can be ignored with --ignore-sgd all or --ignore-sgd payload.
  • --per-pixel-output all | <number> | none — controls whether per pixel / texel block difference output is generated when --content is set to image:
    • all — Every single difference is output (may result in a very large output). like, huge. be warned 💀
    • <number> — At most the specified number of differences are output.
    • none — No per pixel / texel block differences are output.

The default mode is none to limit the verbosity of the output.

  • --allow-invalid-input — perform best effort comparison even if any of the input files are invalid.
  • --ignore-format-header — ignore the vkFormat and typeSize fields in the file header.

Note: useful when comparing textures with and without BasisLZ encoding, respectively.

  • --ignore-supercomp — ignore supercompression scheme in the file header.

Note: use the --ignore-sgd option to also ignore the SGD section, if needed.

  • --ignore-index all | level | none — controls the comparison of index entries in the file headers. possible options are:
    • all — Ignore all index entries.
    • level — Ignore level index entries only.
    • none — Do not ignore any index entries.

The default mode is none, meaning that all index entries will be compared.

  • --ignore-dfd all | all-except-color-space | unknown | extended | none — controls the comparison of DFD blocks. possible options are:
    • all — Ignore all DFD blocks.
    • all-except-color-space — Ignore all DFD blocks except the color space information in the basic DFD block.
    • unknown — Ignore any unrecognized DFD blocks.
    • extended — Ignore all DFD blocks except the basic DFD block.
    • none — Do not ignore any DFD blocks.

The default mode is none, meaning that all DFD entries will be compared.

  • --ignore-bdfd-bytesplane — ignore BDFD bytesPlane values. useful when comparing pre-spec-2.0.4 supercompressed files with 2.0.4+ supercompressed or non-supercompressed ones, as bytesPlane is set to zero in older supercompressed files. (older files really said "bytesPlane? never heard of her") 😌
  • --ignore-metadata all | <key>[,...] | none — controls the comparison of metadata (KVD) entries. possible options are:
    • all — Ignore all metadata entries.
    • <key>[,...] — Ignore the specified comma separated list of metadata keys.
    • none — Do not ignore any metadata entries.

The default mode is none, meaning that all metadata entries will be compared.

  • --ignore-sgd all | unknown | payload | none — controls the comparison of the SGD section. possible options are:
    • all — Ignore the SGD section.
    • unknown — Ignore any unrecognized SGD section.
    • payload — Ignore any unrecognized SGD section and the payload of any known SGD section.
    • none — Do not ignore the SGD section.

The default mode is none, meaning that SGD sections will always be compared.

Note: --ignore-sgd payload can be used to compare BasisLZ SGD headers without expecting an exact match for the individual SGD payload sections.

  • -h, --help — print this usage message and exit. 🫶
  • -v, --version — print the version number of this program and exit.
📌 note — reports about image content mismatches when --content is set to raw or image include the following information: - The level, layer, and face index of the image where the difference was found.
📌 note — reports about individual texel block differences when --content is set to image include the following additional information: - The texel coordinates within the image where the difference was found. These coordinates are the raw coordinates of the image and are not affected by metadata such as KTXorientation. - The packed elements of the texel block output as an array of hexadecimal values. Each packed element has a byte size equal to the typeSize value of the image. - The channel values of the texel block output as an array of integer (for integer and normalized formats) or floating point (for floating point formats) values. In case of floating point formats NaN, +inf, and -inf are used to indicate values that are not a number or represent infinities, respectively. The output order of the channels always follow the order they appear in the BDFD.

🌈 EXIT STATUS 🌈

  • 0 — Success 🎉
  • 1 — Command line error
  • 2 — IO failure
  • 3 — Invalid input file
  • 4 — Runtime or library error
  • 5 — Not supported state or operation
  • 6 — Requested feature is not yet implemented
  • 7 — Input files are different 👀 (the whole point of the tool, honestly)

🦋 HISTORY 🦋

  • Version 4.0
    • Initial version — everyone's gotta start somewhere ✨

👑 AUTHOR 👑

  • Daniel Rákos, RasterGrid www.rastergrid.com

and that's the whole page, bestie! this one's from Version 0.0.0, dated Tue Jan 1 1980 00:00:00 — iconic timestamp, love that for it 🎀 go forth and compare your KTX2 files, you absolute main character 💜

📦 where this page comes from