KTX Tools Reference 4.4.0
Libraries and tools to create and read KTX image texture files.
Loading...
Searching...
No Matches
ktx compare

Compare two KTX2 files.

SYNOPSIS

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

DESCRIPTION

ktx compare compares the two KTX2 files specified as the input-file1 and input-file2 arguments and outputs any mismatch in texture information and/or image data. The command implicitly calls validate and prints any found errors and warnings to stdout. If any of the specified input files are invalid then comparison is done based on best effort and may be incomplete.

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. Additionally, for JSON outputs the KTX file identifier is printed using "\u001A" instead of "\x1A" as an unescaped "\x1A" sequence inside a JSON string breaks nearly every JSON tool. 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".

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 to be 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).
<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.
--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 be always 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 @b raw or @b image
include the following information: <br />
- 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 @b image
include the following additional information: <br />
- 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 @b 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 @b 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 @b NaN, @b +inf, and @b -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

HISTORY

Version 4.0
  • Initial version

AUTHOR

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