Extract selected images from a KTX2 file.

SYNOPSIS

ktx extract [option...] input-file output-path

DESCRIPTION

ktx extract can extract one or multiple images from the KTX2 file specified as the input-file argument and, based on the format, save them as Raw, EXR or PNG image files to the output-path. If the input-file is '-' the file will be read from the stdin. If the output-path is '-' the output file will be written to the stdout. If the input file is invalid the first encountered validation error is displayed to the stderr and the command exits with the relevant non-zero status code.

The output-path is interpreted as output filepath for single and output directory for multi-image extracts. When extracting multiple images with either '–all' or any of the 'all' args the following naming is used for each output file:

output-path/output_level{}_face{}_layer{}_depth{}.extension

Where the _level{} part is only present if the source texture has more than 1 level
Where the _face{} part is only present if the source texture is cubemap or cubemap array (Cubemap)
Where the _layer{} part is only present if the source texture is an array texture (Array)
Where the _depth{} part is only present if the source texture baseDepth is more than 1 (3D)
Where the {} is replaced with the numeric index of the given component starting from 0
Where the extension part is "raw", "png" or "exr" based on the export format
Note: The inclusion of the optional parts are determined by the source texture regardless of which images are requested.

For non-raw exports the output image format is chosen to be the smallest related lossless format:

_UNORM formats exported as PNG with RGB/RGBA 8/16 bit
_SINT/_UINT formats exported as EXR with R/RG/RGB/RGBA Half/Float/UInt
_SFLOAT/_UFLOAT formats exported as EXR with R/RG/RGB/RGBA Half/Float/UInt
D16_UNORM exported as PNG with luminance (Gray) 16 bit
Other Depth/Stencil formats exported as EXR with D/S/DS Half/Float

The following options are available:

--transcode <target>: Transcode the texture to the target format before executing the extract. Requires the input file to be transcodable (it must be either BasisLZ supercompressed or has UASTC color model in the DFD). This option matches the functionality of the ktx transcode command. If the target option is not set the r8, rg8, rgb8 or rgba8 target will be selected based on the number of channels in the input texture. Block compressed transcode targets can only be saved in raw format. Case-insensitive. Possible options are: etc-rgb | etc-rgba | eac-r11 | eac-rg11 | bc1 | bc3 | bc4 | bc5 | bc7 | astc | r8 | rg8 | rgb8 | rgba8. etc-rgb is ETC1; etc-rgba, eac-r11 and eac-rg11 are ETC2.

--uri <uri>: KTX Fragment URI. https://registry.khronos.org/KTX/specs/2.0/ktx-frag.html
--level [0-9]+ | all: Level to extract. When 'all' is used every level is exported. Defaults to 0.
--layer [0-9]+ | all: Layer to extract. When 'all' is used every layer is exported. Defaults to 0.
--face [0-9]+ | all: Face to extract. When 'all' is used every face is exported. Defaults to 0.
--depth [0-9]+ | all: Depth slice to extract. When 'all' is used every depth is exported. Defaults to 0.
--all: Extract every image slice from the texture.
--raw: Extract the raw image data without any conversion.

-h, --help: Print this usage message and exit.
-v, --version: Print the version number of this program and exit.

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

HISTORY

Version 4.0

Initial version

AUTHOR

Mátyás Császár [Vader], RasterGrid www.rastergrid.com
Daniel Rákos, RasterGrid www.rastergrid.com