Create a KTX2 file from various input files.

SYNOPSIS

ktx create [option...] input-file... output-file

DESCRIPTION

ktx create can create, encode and supercompress a KTX2 file from the input images specified as the input-file... arguments and save it as the output-file. The last positional argument is treated as the output-file. 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.

Each input-file must be a valid EXR (.exr), PNG (.png) or Raw (.raw) file. PNG files with luminance (L) or luminance + alpha (LA) data will be converted to RGB as LLL and RGBA as LLLA before processing further. The input file formats must be compatible with the requested KTX format enum and must have at least the same level of precision and number of channels. Any unused channel will be discarded silently.

The number of input-files specified must match the expected number of input images based on the used options.

OPTIONS

General Options

The following are available:

--format <enum>

KTX format enum that specifies the data format for the images in the created texture. The enum names match the VkFormat names without the VK_FORMAT_ prefix. The VK_FORMAT_ prefix is ignored if present. Case insensitive. Required.

If the format is an ASTC format a texture object with the target format R8G8B8_{SRGB,UNORM} or R8G8B8A8_{SRGB,UNORM} is created then encoded to the specified ASTC format. The latter format is chosen if alpha is present in the input. SRGB or UNORM is chosen depending on the specified ASTC format. The ASTC-specific and common encoder options listed below become valid, otherwise they are ignored. This matches the functionality of the ktx encode command when an ASTC format is specified.

When used with --encode it specifies the target format before the encoding step. In this case it must be one of:

R8_UNORM
R8_SRGB
R8G8_UNORM
R8G8_SRGB
R8G8B8_UNORM
R8G8B8_SRGB
R8G8B8A8_UNORM
R8G8B8A8_SRGB

The format will be used to verify and load all input files into a texture before performing any specified encoding.

--encode basis-lz | uastc

Encode the texture with the specified codec before saving it. This option matches the functionality of the ktx encode command. With each choice, the specific and common encoder options listed below become valid, otherwise they are ignored. Case-insensitive.

basis-lz:: Supercompress the image data with transcodable ETC1S / BasisLZ. RED images will become RGB with RED in each component (RRR). RG images will have R in the RGB part and G in the alpha part of the compressed texture (RRRG). When set, the basis-lz options become valid.
uastc:: Create a texture in high-quality transcodable UASTC format. When set the uastc options become valid.

--1d

Create a 1D texture. If not set the texture will be a 2D or 3D texture.

--cubemap

Create a cubemap texture. If not set the texture will be a 2D or 3D texture.

--raw

Create from raw image data.

--width

Base level width in pixels. Required with --raw. For non-raw, if not set, the image width is used otherwise the image is resampled to this width and any provided mip levels are resampled proportionately. For non-raw it enables use of the 'Generate Mipmap' options listed under --generate-mipmap to tune the resampler.

--height

Base level height in pixels. Required with --raw. For non-raw, if not set, the image height is used otherwise the image is resampled to this height and any provided mip levels are resampled proportionately. For non-raw it enables use of the 'Generate Mipmap' options listed under --generate-mipmap to tune the resampler.

--depth

Base level depth in pixels. If set the texture will be a 3D texture.

--layers

Number of layers. If set the texture will be an array texture.

--levels

Number of mip levels. This is the number of level images to include in the texture being created. If --generate-mipmap is specified this number of level images will be generated otherwise this number of input images must be provided. Generates an error if the value is greater than the maximum possible for the specified dimensions of the texture or, for non-raw, the dimensions of the base level image as possibly modified by --scale.

--runtime-mipmap

Runtime mipmap generation mode. Sets up the texture to request the mipmaps to be generated by the client application at runtime.

--generate-mipmap

Causes mipmaps to be generated during texture creation. If --levels is not specified the maximum possible mip level will be generated. This option is mutually exclusive with –runtime-mipmap and cannot be used with SINT, UINT or 3D textures. When set it enables the use of the following 'Generate Mipmap' options.

--mipmap-filter <filter>: Specifies the filter to use when generating the mipmaps. Case insensitive. Ignored unless –generate-mipmap, –scale, –width or –height are specified for non-raw input.
Possible options are: box | tent | bell | b-spline | mitchell | blackman | lanczos3 | lanczos4 | lanczos6 | lanczos12 | kaiser | gaussian | catmullrom | quadratic_interp | quadratic_approx | quadratic_mix. Defaults to lanczos4.
--mipmap-filter-scale <float>: The filter scale to use. Defaults to 1.0. Ignored unless –generate-mipmap, –scale, –width or –height are specified for non-raw input.
--mipmap-wrap <mode>: Specify how to sample pixels near the image boundaries. Case insensitive. Ignored unless –generate-mipmap, –scale, –width or –height are specified for non-raw input.
Possible options are: wrap | reflect | clamp. Defaults to clamp.

Avoid mipmap generation if the Output TF (see TRANSFER FUNCTION HANDLING below) is non-linear and is not sRGB.

--scale

Scale images as they are loaded. Cannot be used with –raw. It enables use of the 'Generate Mipmap' options listed under --generate-mipmap to tune the resampler.

--normalize

Normalize input normals to have a unit length. Only valid for linear normal textures with 2 or more components. For 2-component inputs 2D unit normals are calculated. Do not use these 2D unit normals to generate X+Y normals with --normal-mode. For 4-component inputs a 3D unit normal is calculated. 1.0 is used for the value of the 4th component. Cannot be used with --raw.

--swizzle [rgba01]{4}

KTX swizzle metadata.

--input-swizzle [rgba01]{4}

Pre-swizzle input channels.

--assign-tf <transfer function>

--assign-oetf <transfer function>

Deprecated and will be removed. Use --assign-tf instead.

--assign-primaries <primaries>

Note: bt601-ebu and bt601-smpte, supported in previous releases, have been replaced with names consistent with khr_df_primaries_e.

--assign-texcoord-origin <corner>

Force the created texture to indicate that the texture coordinate origin s=0, t=0 is at the specified corner of the logical image. Case insensitive. Possible options are top-left | bottom-left. -front | -back can be appended and one of these is required when --depth is specified. Must be top-left if --cubemap is specified. Absent —convert-texcoord-origin, the effect of this option is to cause KTXorientation metadata indicating the specified origin to be written to the output file. Example values are "rd" (top-left) and "ru" (bottom-left) or, when --depth is specified, "rdi" (top-left-front) and "rui" (bottom-left-front).

--convert-tf <transfer function>

Convert the input image(s) to the specified transfer function, if different from the transfer function of the input file(s). If both this and --assign-tf are specified, conversion will be performed from the assigned transfer function to the transfer function specified by this option, if different. Cannot be used with --raw. Case insensitive. The options are: linear | srgb. The following srgb aliases are also supported: srgb_eotf | scrgb | scrgb_eotf. See TRANSFER FUNCTION HANDLING below for more information.

--convert-oetf <transfer function>

Deprecated and will be removed. Use --convert-tf instead.

--convert-primaries <primaries>

Convert the input image(s) to the specified color primaries, if different from the color primaries of the input file(s) or the one specified by --assign-primaries. If both this and --assign-primaries are specified, conversion will be performed from the assigned primaries to the primaries specified by this option, if different. This option is not allowed to be specified when --assign-primaries is set to 'none'. Cannot be used with --raw. Possible options match the khr_df_primaries_e enumerators without the KHR_DF_PRIMARIES_ prefix. The KHR_DF_PRIMARIES_ prefix is ignored if present. Case insensitive. The options are: bt709 | srgb | bt601_ebu | bt601_smpte | bt2020 | ciexyz | aces | acescc | ntsc1953 | pal525 | displayp3 | adobergb

Note: bt601-ebu and bt601-smpte, supported in previous releases, have been replaced with names consistent with khr_df_primaries_e.

--convert-texcoord-origin <corner>

Convert the input image(s) so the texture coordinate origin s=0, t=0, is at the specified corner of the logical image. If both this and --assign-texcoord-origin are specified, conversion will be performed from the assigned origin to the origin specified by this option, if different. The default for images in KTX files is top-left which corresponds to the origin in most image file formats. Cannot be used with --raw. Case insensitive. Possible options are: top-left | bottom-left. -front | -back can be appended and one of these is required when --depth is specified. Must be top-left if --cubemap is specified.

Input images whose origin does not match corner will be flipped vertically. KTXorientation metadata indicating the the specified origin is written to the output file. Example values are "rd" (top-left) and "ru" (bottom-left) or, when --depth is specified, "rdi" (top-left-front) and "rui" (bottom-left-back). Generates an error if the input image origin is unknown as is the case with raw image data. Use --assign-texcoord-origin to specify the orientation.

Note: ktx create cannot rotate or flip incoming images, except for a y-flip, so use an an image processing tool to reorient images whose first data stream pixel is not at the logical top-left or bottom-left of the image before using as input here. Such images may be indicated by Exif-style orientation metadata in the file.

--fail-on-color-conversions

Generates an error if any input images would need to be color converted.

--warn-on-color-conversions

Generates a warning if any input images are color converted. Adds warnings for explicitly requested and visually lossless implicit conversions to that generated for visually lossy conversions.

--no-warn-on-color-conversions

Disable all warnings about color conversions including that for visually lossy conversions. Overrides --warn-on-color-conversions should both be specified.

--fail-on-origin-changes

Generates an error if any of the input images would need to have their origin changed.

--warn-on-origin-changes

Generates a warning if any of the input images have their origin changed..

--zstd <level>: Supercompress the data with Zstandard. Cannot be used with ETC1S / BasisLZ format. Level range is [1,22]. Lower levels give faster but worse compression. Values above 20 should be used with caution as they require more memory.
--zlib <level>: Supercompress the data with ZLIB. Cannot be used with ETC1S / BasisLZ format. Level range is [1,9]. Lower levels give faster but worse compression.

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

Specific and Common Encoding Options

The following are available. Specific options become valid only if their encoder has been selected. Common encoder options become valid when an encoder they apply to has been selected. Otherwise they are ignored.

ASTC:

--astc-quality <level>

The quality level configures the quality-performance tradeoff for the compressor; more complete searches of the search space improve image quality at the expense of compression time. Default is 'medium'. The quality level can be set between fastest (0) and exhaustive (100) via the following fixed quality presets:

Level	Quality
fastest	(equivalent to quality = 0)
fast	(equivalent to quality = 10)
medium	(equivalent to quality = 60)
thorough	(equivalent to quality = 98)
exhaustive	(equivalent to quality = 100)

--astc-perceptual

The codec should optimize for perceptual error, instead of direct RMS error. This aims to improve perceived image quality, but typically lowers the measured PSNR score. Perceptual methods are currently only available for normal maps and RGB color data.

basis-lz:

--clevel <level>

ETC1S / BasisLZ compression level, an encoding speed vs. quality tradeoff. Range is [0,6], default is 1. Higher values are slower but give higher quality. Use --qlevel first.

--qlevel <level>

ETC1S / BasisLZ quality level. Range is [1,255]. Lower gives better compression/lower quality/faster. Higher gives less compression/higher quality/slower. --qlevel automatically determines values for --max-endpoints, --max-selectors, --endpoint-rdo-threshold and --selector-rdo-threshold for the target quality level. Setting these options overrides the values determined by -qlevel which defaults to 128 if neither it nor --max-endpoints and --max-selectors have been set.

Note that both of --max-endpoints and --max-selectors must be set for them to have any effect. If all three options are set, a warning will be issued that --qlevel will be ignored.

Note also that --qlevel will only determine values for --endpoint-rdo-threshold and --selector-rdo-threshold when its value exceeds 128, otherwise their defaults will be used.

--max-endpoints <arg>

Manually set the maximum number of color endpoint clusters. Range is [1,16128]. Default is 0, unset.

--endpoint-rdo-threshold <arg>

Set endpoint RDO quality threshold. The default is 1.25. Lower is higher quality but less quality per output bit (try [1.0,3.0]). This will override the value chosen by --qlevel.

--max-selectors <arg>

Manually set the maximum number of color selector clusters from [1,16128]. Default is 0, unset.

--selector-rdo-threshold <arg>

Set selector RDO quality threshold. The default is 1.25. Lower is higher quality but less quality per output bit (try [1.0,3.0]). This will override the value chosen by --qlevel.

--no-endpoint-rdo

Disable endpoint rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is to do endpoint RDO.

--no-selector-rdo

Disable selector rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is to do selector RDO.

uastc:

--uastc-quality <level>

This optional parameter selects a speed vs quality tradeoff as shown in the following table:

Level	Speed	Quality
0	Fastest	43.45dB
1	Faster	46.49dB
2	Default	47.47dB
3	Slower	48.01dB
4	Very slow	48.24dB

You are strongly encouraged to also specify --zstd to losslessly compress the UASTC data. This and any LZ-style compression can be made more effective by conditioning the UASTC texture data using the Rate Distortion Optimization (RDO) post-process stage. When uastc encoding is set the following options become available for controlling RDO:

--uastc-rdo

Enable UASTC RDO post-processing.

--uastc-rdo-l <lambda>

Set UASTC RDO quality scalar (lambda) to lambda. Lower values yield higher quality/larger LZ compressed files, higher values yield lower quality/smaller LZ compressed files. A good range to try is [.25,10]. For normal maps a good range is [.25,.75]. The full range is [.001,10.0]. Default is 1.0.

Note that previous versions used the --uastc-rdo-q option which was removed because the RDO algorithm changed.

--uastc-rdo-d <dictsize>

Set UASTC RDO dictionary size in bytes. Default is 4096. Lower values=faster, but give less compression. Range is [64,65536].

--uastc-rdo-b <scale>

Set UASTC RDO max smooth block error scale. Range is [1.0,300.0]. Default is 10.0, 1.0 is disabled. Larger values suppress more artifacts (and allocate more bits) on smooth blocks.

--uastc-rdo-s <deviation>

Set UASTC RDO max smooth block standard deviation. Range is [.01,65536.0]. Default is 18.0. Larger values expand the range of blocks considered smooth.

--uastc-rdo-f

Do not favor simpler UASTC modes in RDO mode.

--uastc-rdo-m

Disable RDO multithreading (slightly higher compression, deterministic).

common:

--normal-mode

Only valid for linear textures with two or more components. If the input texture has three or four linear components it is assumed to be a three component linear normal map storing unit length normals as (R=X, G=Y, B=Z). A fourth component will be ignored. The map will be converted to a two component X+Y normal map stored as (RGB=X, A=Y) prior to encoding. If unsure that your normals are unit length, use --normalize. If the input has 2 linear components it is assumed to be an X+Y map of unit normals.

The Z component can be recovered programmatically in shader code by using the equations:

        nml.xy = texture(...).ga;              // Load in [0,1]
        nml.xy = nml.xy * 2.0 - 1.0;           // Unpack to [-1,1]
        nml.z = sqrt(1 - dot(nml.xy, nml.xy)); // Compute Z

For ETC1S / BasisLZ encoding, '--encode basis-lz', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality.

--threads <count>

Explicitly set the number of threads to use during compression. By default, ETC1S / BasisLZ will use the number of threads reported by thread::hardware_concurrency or 1 if value returned is 0.

--no-sse

Forbid use of the SSE instruction set. Ignored if CPU does not support SSE. SSE can only be disabled for the basis-lz and uastc encoders. Ignored for other encoders..

--compare-ssim: Calculate encoding structural similarity index measure (SSIM) and print it to stdout. Requires Basis-LZ, UASTC or ASTC encoding.
--compare-psnr: Calculate encoding peak signal-to-noise ratio (PSNR) and print it to stdout. Requires Basis-LZ, UASTC or ASTC encoding.

TRANSFER FUNCTION HANDLING

The diagram below shows all assignments and conversions that can take place.

┌──────────┐                                     ┌─────────┐
│          ├──────────────────1─────────────────►│         │
│          │  ┌───────────┐                      │         │
│ Input    │  │           │                      │         │
│ Transfer │  │ --assign- ├──────────2──────────►│Output   │
│ function │  │   tf      │    ┌────────────┐    │Transfer │
│ from     │  │           ├─3─►│            │    │Function │
│ file     │  │           │    │ --convert- │    │         │
│ metadata │  └───────────┘    │   tf       ├3,4►│         │
│          │                   │            │    │         │
│          ├────────4─────────►│            │    │         │
└──────────┘                   └────────────┘    └─────────┘

Processing Paths

Pass through. No options specified.
--assign-tf specified.
--assign-tf and --convert-tf specified.
--convert-tf specified.

Details

Transfer function handling proceeds as follows:

If --format specifies one of the *_SRGB{,_*} formats and Output Transfer Function is not sRGB (a.k.a scRGB) an error is generated.
If --format does not specify one of the *_SRGB{,_*} formats, an sRGB variant exists and Output Transfer Function is sRGB (a.k.a scRGB), an error is generated.
Otherwise, the transfer function of the output KTX file is set to Output Transfer Function.
If neither --assign-tf nor --convert-tf is specified:
- If the Input Transfer Function is not sRGB (a.k.a scRGB) for *_SRGB{,_*} formats an implicit conversion to sRGB is done, equivalent to --convert-tf srgb.
- If the Input Transfer Function is not linear for formats that are not one of the *_SRGB{,_*} formats, an implicit conversion to linear is done equivalent to --convert-tf linear.
Supported inputs for implicit or explicit conversion are linear, sRGB, ITU (a.k.a BT601, BT.709, BT.2020 and SMPTE170M) and PQ EOTF. An error is generated if an unsupported conversion is required.
Supported outputs for implicit or explicit conversion are linear and sRGB, An error is generated if an unsupported conversion is required.
Output Transfer Function for a format that is not one of the *_SRGB{,_*} formats can be set to a non-linear transfer function via --assign-tf.
A warning is generated if a visually lossy color-conversion is performed. sRGB to linear is considered visually lossy because there is a high chance it will introduce artifacts visible to the human eye such as banding. The warning can be suppressed with --no-warn-on-color-conversions. A warning or an error on any color conversion can be requested with --warn-on-color-conversions or --fail-on-color-conversions .

Note

When --format does not specify one of the *_SRGB{,_*} formats and Output Transfer Function is not linear:

the KTX file may be much less portable due to limited hardware support of such inputs.
avoid using --generate-mipmap as the filters can only decode sRGB.
avoid encoding to ASTC, BasisLz/ETC1S or UASTC. The encoders' quality metrics are designed for linear and sRGB.

Changes since last Release

--assign-oetf and --convert-oetf are deprecated and will be removed. Use --assign-tf and --convert-tf instead.
The parameter value for --assign-tf can now be any of the transfer functions known to the Khronos Data Format Specification.
A warning is now generated if a visually lossy color conversion will be performed. The warning can be suppressed with --no-warn-on-color-conversions.

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.3

Initial version

Version 4.4

Reorganize encoding options.
Improve explanation of use of --format with --encode.
Improve explanation of ASTC encoding.

AUTHOR

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