145 lines
4.6 KiB
Groff
145 lines
4.6 KiB
Groff
.TH "ktx_extract" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
ktx_extract \- ktx extract
|
|
.PP
|
|
Extract selected images from a KTX2 file\&.
|
|
.SH "SYNOPSIS"
|
|
.PP
|
|
ktx extract [option\&.\&.\&.] \fIinput-file\fP \fIoutput-path\fP
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
\fBktx\fP \fBextract\fP can extract one or multiple images from the KTX2 file specified as the \fIinput-file\fP argument and, based on the format, save them as Raw, EXR or PNG image files to the \fIoutput-path\fP\&. If the \fIinput-file\fP is '-' the file will be read from the stdin\&. If the \fIoutput-path\fP 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\&.
|
|
|
|
.PP
|
|
The \fIoutput-path\fP 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:
|
|
.PP
|
|
.nf
|
|
output-path/output_level{}_face{}_layer{}_depth{}\&.extension
|
|
.fi
|
|
.PP
|
|
.IP "\(bu" 2
|
|
Where the \fI_level{}\fP part is only present if the source texture has more than 1 level
|
|
.IP "\(bu" 2
|
|
Where the \fI_face{}\fP part is only present if the source texture is cubemap or cubemap array (Cubemap)
|
|
.IP "\(bu" 2
|
|
Where the \fI_layer{}\fP part is only present if the source texture is an array texture (Array)
|
|
.IP "\(bu" 2
|
|
Where the \fI_depth{}\fP part is only present if the source texture baseDepth is more than 1 (3D)
|
|
.IP "\(bu" 2
|
|
Where the \fI{}\fP is replaced with the numeric index of the given component starting from 0
|
|
.IP "\(bu" 2
|
|
Where the \fIextension\fP part is "raw", "png" or "exr" based on the export format
|
|
.br
|
|
Note: The inclusion of the optional parts are determined by the source texture regardless of which images are requested\&.
|
|
.PP
|
|
|
|
.PP
|
|
For non-raw exports the output image format is chosen to be the smallest related lossless format:
|
|
.IP "\(bu" 2
|
|
_UNORM formats exported as PNG with RGB/RGBA 8/16 bit
|
|
.IP "\(bu" 2
|
|
_SINT/_UINT formats exported as EXR with R/RG/RGB/RGBA Half/Float/UInt
|
|
.IP "\(bu" 2
|
|
_SFLOAT/_UFLOAT formats exported as EXR with R/RG/RGB/RGBA Half/Float/UInt
|
|
.IP "\(bu" 2
|
|
D16_UNORM exported as PNG with luminance (Gray) 16 bit
|
|
.IP "\(bu" 2
|
|
Other Depth/Stencil formats exported as EXR with D/S/DS Half/Float
|
|
.PP
|
|
.SH "OPTIONS"
|
|
.PP
|
|
The following options are available:
|
|
|
|
.PP
|
|
.IP "\fB--transcode <target>
|
|
.IP "" 1c
|
|
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 \fBktx transcode\fP 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\&.
|
|
|
|
.PP
|
|
|
|
.PP
|
|
.IP "\fB--uri <uri>
|
|
.IP "" 1c
|
|
KTX Fragment URI\&. https://registry.khronos.org/KTX/specs/2.0/ktx-frag.html
|
|
|
|
.PP
|
|
.IP "\fB--level [0-9]+ | all
|
|
.IP "" 1c
|
|
Level to extract\&. When 'all' is used every level is exported\&. Defaults to 0\&.
|
|
|
|
.PP
|
|
.IP "\fB--layer [0-9]+ | all
|
|
.IP "" 1c
|
|
Layer to extract\&. When 'all' is used every layer is exported\&. Defaults to 0\&.
|
|
|
|
.PP
|
|
.IP "\fB--face [0-9]+ | all
|
|
.IP "" 1c
|
|
Face to extract\&. When 'all' is used every face is exported\&. Defaults to 0\&.
|
|
|
|
.PP
|
|
.IP "\fB--depth [0-9]+ | all
|
|
.IP "" 1c
|
|
Depth slice to extract\&. When 'all' is used every depth is exported\&. Defaults to 0\&.
|
|
|
|
.PP
|
|
.IP "\fB--all
|
|
.IP "" 1c
|
|
Extract every image slice from the texture\&.
|
|
|
|
.PP
|
|
.IP "\fB--raw
|
|
.IP "" 1c
|
|
Extract the raw image data without any conversion\&.
|
|
|
|
.PP
|
|
|
|
.PP
|
|
.IP "\fB-h, --help
|
|
.IP "" 1c
|
|
Print this usage message and exit\&.
|
|
|
|
.PP
|
|
.IP "\fB-v, --version
|
|
.IP "" 1c
|
|
Print the version number of this program and exit\&.
|
|
|
|
.PP
|
|
.SH "EXIT STATUS"
|
|
.PP
|
|
.IP "\(bu" 2
|
|
0 - Success
|
|
.IP "\(bu" 2
|
|
1 - Command line error
|
|
.IP "\(bu" 2
|
|
2 - IO failure
|
|
.IP "\(bu" 2
|
|
3 - Invalid input file
|
|
.IP "\(bu" 2
|
|
4 - Runtime or library error
|
|
.IP "\(bu" 2
|
|
5 - Not supported state or operation
|
|
.IP "\(bu" 2
|
|
6 - Requested feature is not yet implemented
|
|
.PP
|
|
.SH "HISTORY"
|
|
.PP
|
|
\fBVersion 4\&.0\fP
|
|
.RS 4
|
|
|
|
.IP "\(bu" 2
|
|
Initial version
|
|
.PP
|
|
.RE
|
|
.PP
|
|
.SH "AUTHOR"
|
|
.PP
|
|
.IP "\(bu" 2
|
|
Mátyás Császár [Vader], RasterGrid www\&.rastergrid\&.com
|
|
.IP "\(bu" 2
|
|
Daniel Rákos, RasterGrid www\&.rastergrid\&.com
|
|
.PP
|
|
|