basisu.exe Command Line Tool Options

Usage: basisu filename [filename ...]

The default mode is compression of one or more PNG files to a .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 PNG 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.

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: 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: 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

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