basisu.exe Command Line Tool Options

Note: This is a work in progress.

Usage: basisu filename [filename ...]

The default mode is compression of one or more BMP/PNG/TGA/JPG files to a ETC1S .basis file. Alternate modes:

-unpack: Use transcoder to unpack .basis file to one or more .ktx/.png files

-validate: Validate and display information about a .basis file

-compare: Compare two BMP/PNG/TGA/JPG images specified with -file, output PSNR and SSIM statistics and RGB/A delta images Unless an explicit mode is specified, if one or more files have the .basis extension this tool defaults to unpack mode.

-info: Display high-level information about a .basis file

-version: Print basisu version and exit

Important: By default, the compressor assumes the input is in the sRGB colorspace (like photos/albedo textures). If the input is NOT sRGB (like a normal map), be sure to specify -linear for less artifacts. Depending on the content type, some experimentation may be needed.

Filenames prefixed with a @ symbol are read as filename listing files. Listing text files specify which actual filenames to process (one filename per line).

Options:

-file filename.png/bmp/tga/jpg: Input image filename, multiple images are OK, use -file X for each input filename (prefixing input filenames with -file is optional)

-alpha_file filename.png/bmp/tga/jpg: Input alpha image filename, multiple images are OK, use -file X for each input filename (must be paired with -file), images converted to REC709 grayscale and used as input alpha

-multifile_printf: printf() format strint to use to compose multiple filenames

-multifile_first: The index of the first file to process, default is 0 (must specify -multifile_printf and -multifile_num)

-multifile_num: The total number of files to process.

-level X: Set encoding speed vs. quality tradeoff. Range is 0-5, default is 1. Higher values=slower, but higher quality.

-q X: Set quality level, 1-255, default is 128, lower=better compression/lower quality/faster, higher=less compression/higher quality/slower, default is 128. For even higher quality, use -max_endpoints/-max_selectors.

-linear: Use linear colorspace metrics (instead of the default sRGB), and by default linear (not sRGB) mipmap filtering.

-output_file filename: Output .basis/.ktx filename

-output_path: Output .basis/.ktx files to specified directory.

-debug: Enable codec debug print to stdout (slightly slower).

-debug_images: Enable codec debug images (much slower).

-stats: Compute and display image quality metrics (slightly slower).

-tex_type <2d, 2darray, 3d, video, cubemap>: Set Basis file header's texture type field. Cubemap arrays require multiples of 6 images, in X+, X-, Y+, Y-, Z+, Z- order, each image must be the same resolutions.

2d=arbitrary 2D images, 2darray=2D array, 3D=volume texture slices, video=video frames, cubemap=array of faces. For 2darray/3d/cubemaps/video, each source image's dimensions and # of mipmap levels must be the same.

For video, the .basis file will be written with the first frame being an I-Frame, and subsequent frames being P-Frames (using conditional replenishment). Playback must always occur in order from first to last image.

-framerate X: Set framerate in header to X/frames sec.

-individual: Process input images individually and output multiple .basis files (not as a texture array)

-fuzz_testing: Use with -validate: Disables CRC16 validation of file contents before transcoding

UASTC options:

-uastc: Enable UASTC texture mode, instead of the default ETC1S mode. Significantly higher texture quality, but larger files. (Note that .basis files must be losslessly compressed by the user.)

-uastc_level: Set UASTC encoding level. Range is [0,4], default is 2, higher=slower but higher quality. 0=fastest/lowest quality, 3=slowest practical option, 4=impractically slow/highest achievable quality

-uastc_rdo_q X: Enable UASTC RDO post-processing and set UASTC RDO quality scalar to X. Lower values=higher quality/larger LZ compressed files, higher values=lower quality/smaller LZ compressed files. Good range to try is [.2-4].

-uastc_rdo_d X: Set UASTC RDO dictionary size in bytes. Default is 32768. Lower values=faster, but less compression.

More options: -max_endpoints X: Manually set the max number of color endpoint clusters from 1-16128, use instead of -q

-max_selectors X: Manually set the max number of color selector clusters from 1-16128, use instead of -q

-y_flip: Flip input images vertically before compression

-normal_map: Tunes codec parameters for better quality on normal maps (linear colorspace metrics, linear mipmap filtering, no selector RDO, no sRGB)

-no_alpha: Always output non-alpha basis files, even if one or more inputs has alpha

-force_alpha: Always output alpha basis files, even if no inputs has alpha

-seperate_rg_to_color_alpha: Seperate input R and G channels to RGB and A (for tangent space XY normal maps)

-no_multithreading: Disable multithreading

-no_ktx: Disable KTX writing when unpacking (faster)

-etc1_only: Only unpack to ETC1, skipping the other texture formats during -unpack

-disable_hierarchical_endpoint_codebooks: Disable hierarchical endpoint codebook usage, slower but higher quality on some compression levels

Mipmap generation options:

-mipmap: Generate mipmaps for each source image

-mip_srgb: Convert image to linear before filtering, then back to sRGB

-mip_linear: Keep image in linear light during mipmap filtering

-mip_scale X: Set mipmap filter kernel's scale, lower=sharper, higher=more blurry, default is 1.0

-mip_filter X: Set mipmap filter kernel, default is kaiser, filters: box, tent, bell, blackman, catmullrom, mitchell, etc.

-mip_renorm: Renormalize normal map to unit length vectors after filtering

-mip_clamp: Use clamp addressing on borders, instead of wrapping

-mip_smallest X: Set smallest pixel dimension for generated mipmaps, default is 1 pixel

By default, mipmap filtering will occur in sRGB space (for the RGB color channels) unless -linear is specified. You can override this behavior with -mip_srgb/-mip_linear.

Backend endpoint/selector RDO codec options:

-no_selector_rdo: Disable backend's selector rate distortion optimizations (slightly faster, less noisy output, but lower quality per output bit)

-selector_rdo_thresh X: Set selector RDO quality threshold, default is 1.25, lower is higher quality but less quality per output bit (try 1.0-3.0)

-no_endpoint_rdo: Disable backend's endpoint rate distortion optimizations (slightly faster, less noisy output, but lower quality per output bit)

-endpoint_rdo_thresh X: Set endpoint RDO quality threshold, default is 1.5, lower is higher quality but less quality per output bit (try 1.0-3.0)

Hierarchical virtual selector codebook options:

-global_sel_pal: Always use vitual selector palettes (instead of custom palettes), slightly smaller files, but lower quality, slower encoding

-no_auto_global_sel_pal: Don't automatically use virtual selector palettes on small images

-no_hybrid_sel_cb: Don't automatically use hybrid virtual selector codebooks (for higher quality, only active when -global_sel_pal is specified)

-global_pal_bits X: Set virtual selector codebook palette bits, range is [0,12], default is 8, higher is slower/better quality

-global_mod_bits X: Set virtual selector codebook modifier bits, range is [0,15], defualt is 8, higher is slower/better quality

-hybrid_sel_cb_quality_thresh X: Set hybrid selector codebook quality threshold, default is 2.0, try 1.5-3, higher is lower quality/smaller codebooks

Set various fields in the Basis file header:

-userdata0 X: Set 32-bit userdata0 field in Basis file header to X (X is a signed 32-bit int)

-userdata1 X: Set 32-bit userdata1 field in Basis file header to X (X is a signed 32-bit int)

Various command line examples:

basisu x.png : Compress sRGB image x.png to x.basis using default settings (multiple filenames OK)

basisu x.basis : Unpack x.basis to PNG/KTX files (multiple filenames OK)

basisu -file x.png -mipmap -y_flip : Compress a mipmapped x.basis file from an sRGB image named x.png, Y flip each source image

basisu -validate -file x.basis : Validate x.basis (check header, check file CRC's, attempt to transcode all slices)

basisu -unpack -file x.basis : Validates, transcodes and unpacks x.basis to mipmapped .KTX and RGB/A .PNG files (transcodes to all supported GPU texture formats)

basisu -q 255 -file x.png -mipmap -debug -stats : Compress sRGB x.png to x.basis at quality level 255 with compressor debug output/statistics

basisu -linear -max_endpoints 16128 -max_selectors 16128 -file x.png : Compress non-sRGB x.png to x.basis using the largest supported manually specified codebook sizes

basisu -linear -global_sel_pal -no_hybrid_sel_cb -file x.png : Compress a non-sRGB image, use virtual selector codebooks for improved compression (but slower encoding)

basisu -linear -global_sel_pal -file x.png: Compress a non-sRGB image, use hybrid selector codebooks for slightly improved compression (but slower encoding)

basisu -tex_type video -framerate 20 -multifile_printf "x%02u.png" -multifile_first 1 -multifile_count 20 : Compress a 20 sRGB source image video sequence (x01.png, x02.png, x03.png, etc.) to x01.basis

Note: For video use, it's recommended you use a very powerful machine with many cores. Use -slower for better codebook generation, specify very large codebooks using -max_endpoints and -max_selectors, and reduce the default endpoint RDO threshold (-endpoint_rdo_thresh) to around 1.25. Videos may have mipmaps and alpha channels. Videos must always be played back by the transcoder in first to last image order. Video files currently use I-Frames on the first image, and P-Frames using conditional replenishment on subsequent frames. Compression level details:

Level 0: Fastest, but has marginal quality and is a work in progress. Brittle on complex images. Avg. Y dB: 35.45

Level 1: Hierarchical codebook searching. 36.87 dB, ~1.4x slower vs. level 0. (This is the default setting.)

Level 2: Full codebook searching. 37.13 dB, ~1.8x slower vs. level 0. (Equivalent the the initial release's default settings.)

Level 3: Hierarchical codebook searching, codebook k-means iterations. 37.15 dB, ~4x slower vs. level 0

Level 4: Full codebook searching, codebook k-means iterations. 37.41 dB, ~5.5x slower vs. level 0. (Equivalent to the initial release's -slower setting.)

Level 5: Full codebook searching, twice as many codebook k-means iterations, best ETC1 endpoint opt. 37.43 dB, ~12x slower vs. level 0