ktx_extract(1)

ktx_extract(1) — KTX Tools Reference 🎀

okay so bestie, welcome to the ktx_extract(1) glow-up page from the KTX Tools Reference. This command is literally here to extract selected images from a KTX2 file, and we’re gonna cover every flag, path, status code, and tiny detail. no cap. 💖✨

🌸 NAME 🌸

ktx_extract — ktx extract

Extract selected images from a KTX2 file. 🦋

✨ SYNOPSIS ✨

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

💅 DESCRIPTION 💅

okay so ktx extract can pull one image or multiple images out of the KTX2 file you pass as input-file, and depending on the format it saves them as Raw, EXR, or PNG image files to output-path. If input-file is '-', the file is read from stdin. If output-path is '-', the output file is written to stdout. And if the input file is invalid? The first validation error it encounters gets displayed to stderr, and the command exits with the relevant non-zero status code. periodt. 😭

output-path is interpreted as an output filepath for a single extract and as an output directory for multi-image extracts. When you’re extracting multiple images with either --all or any of the all args, each output file gets named like this:

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

• the _level{} part is only there if the source texture has more than 1 level
• the _face{} part is only there if the source texture is a cubemap or cubemap array (Cubemap)
• the _layer{} part is only there if the source texture is an array texture (Array)
• the _depth{} part is only there if the source texture’s baseDepth is more than 1 (3D)
• the {} gets replaced with the numeric index of that component, starting from 0
• the extension part is "raw", "png", or "exr" based on the export format

Note: the inclusion of the optional parts is 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

🔥 OPTIONS 🔥

The following options are available:

• --transcode <target> — Transcode the texture to target format before running the extract. This requires the input file to be transcodable — it must be either BasisLZ supercompressed or have a 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 is selected based on the number of channels in the input texture. Block compressed transcode targets can only be saved in raw format. It’s 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

---

okay that’s the whole manual, bestie — Version 0.0.0, Tue Jan 1 1980 00:00:00, ktx_extract(1). mwah, slay, bye. 💅🎀💖