![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
#author("2018-12-06T20:54:03+09:00","default:kuran","kuran") [[kuran_kuran page!]] ASTC codec version 1.3 Copyright (C) 2011-2013 ARM Limited All rights reserved. Use of this software is subject to terms of its license. Usage: Compress to texture file: astcenc -c <inputfile> <outputfile> <rate> [options] Decompress from texture file: astcenc -d <inputfile> <outputfile> [options] Compress, then immediately decompress to image: astcenc -t <inputfile> <outputfile> <rate> [options] Compare two files (no compression or decompression): astcenc -compare <file1> <file2> [options] When encoding/decoding a texture for use with the LDR-SRGB submode, use -cs, -ds, -ts instead of -c, -d, -t. When encoding/decoding a texture for use with the LDR-linear submode, use -cl, -dl, -tl instead of -c, -d, -t. For compression, the input file formats supported are * PNG (*.png) * Targa (*.tga) * JPEG (*.jpg) * GIF (*.gif) (non-animated only) * BMP (*.bmp) * Radiance HDR (*.hdr) * Khronos Texture KTX (*.ktx) * DirectDraw Surface DDS (*.dds) * Half-Float-TGA (*.htga) * OpenEXR (*.exr; only if 'exr_to_htga' is present in the path) For the KTX and DDS formats, the following subset of the format features are supported; the subset is: * 2D and 3D textures supported * Uncompressed only, with unorm8, unorm16, float16 or float32 components * R, RG, RGB, BGR, RGBA, BGRA, Luminance and Luminance-Alpha texel formats * In case of multiple image in one file (mipmap, cube-faces, texture-arrays) the codec will read the first one and ignore the other ones. When using HDR or 3D textures, it is recommended to use the KTX or DDS formats. Separate 2D image slices can be assembled into a 3D image using the -array option. The output file will be an ASTC compressed texture file (recommended filename ending .astc) For decompression, the input file must be an ASTC compressed texture file; the following formats are supported for output: * Targa (*.tga) * KTX (*.ktx) * DDS (*.dds) * Half-Float-TGA (*.htga) * OpenEXR (*.exr; only if t'exr_to_htga' is present in the path) Targa is suitable only for 2D LDR images; for HDR and/or 3D images, please use KTX or DDS. For compression, the <rate> argument specifies the bitrate or block dimension to use. This argument can be specified in one of two ways: * A decimal number (at least one actual decimal needed). This will cause the codec to interpret the number as a desired bitrate, and pick a block size to match that bitrate as closely as possible. For example, if you want a bitrate of 2.0 bits per texel, then specifiy the <rate> argument as 2.0 * A block size. This specifies the block dimensions to use along the X, Y (and for 3D textures) Z axes. The dimensions are separated with the character x, with no spaces. For 2D textures, the supported dimensions along each axis are picked from the set {4,5,6,8,10,12}; for 3D textures, the supported dimensions are picked from the set {3,4,5,6}. For example, if you wish to encode a 2D texture using the 10x6 block size (10 texels per block along the X axis, 6 texels per block along the Y axis, then specify the <rate> argument as 10x6 . Some examples of supported 2D block sizes are: 4x4 -> 8.0 bpp 5x5 -> 5.12 bpp 6x6 -> 3.56 bpp 8x6 -> 2.67 bpp 8x8 -> 2.0 bpp 10x8 -> 1.6 bpp 10x10 -> 1.28 bpp 10x12 -> 1.07 bpp 12x12 -> 0.89 bpp If you try to specify a bitrate that can potentially map to multiple different block sizes, the codec will choose the block size with the least lopsided aspect ratio (e.g. if you specify 2.67, then the codec will choose the 8x6 block size, not 12x4) Below is a description of all the available options. Most of them make sense for encoding only, however there are some that affect decoding as well (such as -dsw and the normal-presets) Built-in error-weighting Presets: --------------------------------- The presets provide easy-to-use combinations of encoding options that are designed for use with certain commonly-occurring kinds of textures. -normal_psnr For encoding, assume that the input texture is a normal map with the X and Y components of the actual normals in the Red and Green color channels. The codec will then move the 2nd component to Alpha, and apply an error-weighting function based on angular error. It is possible to use this preset with texture decoding as well, in which case it will expand the normal map from 2 to 3 components after the actual decoding. The -normal_psnr preset as a whole is equivalent to the options "-rn -esw rrrg -dsw raz1 -ch 1 0 0 1 -oplimit 1000 -mincorrel 0.99" . -normal_percep Similar to -normal_psnr, except that it tries to optimize the normal map for best possible perceptual results instead of just maximizing angular PSNR. The -normal_percep preset as a whole is equivalent to the options "-normal_psnr -b 2.5 -v 3 1 1 0 50 0 -va 1 1 0 50 -dblimit 60" . -mask Assume that the input texture is a texture that contains unrelated content in its various color channels, and where it is undesirable for errors in one channel to affect the other channels. Equivalent to "-v 3 1 1 0 25 0.03 -va 0 25" . -alphablend Assume that the input texture is an RGB-alpha texture where the alpha component is used to represent opacity. (0=fully transparent, 1=fully opaque) Equivalent to "-a 1" . -hdr Assume that the input texture is an HDR texture. If an alpha channel is present, it is treated as an LDR channel (e.g. opacity) Optimize for 4th-root error for the color and linear error for the alpha. Equivalent to "-forcehdr_rgb -v 0 0.75 0 1 0 0 -va 0.02 1 0 0 -dblimit 999" -hdra Assume that the input texture is an HDR texture, and optimize for 4th-root error. If an alpha channel is present, it is assumed to be HDR and optimized for 4th-root error as well. Equivalent to "-forcehdr_rgba -v 0 0.75 0 1 0 0 -va 0.75 0 1 0 -dblimit 999" -hdr_log -hdra_log Assume that the input texture is an HDR texture, and optimize for logarithmic error. This should give better results than -hdr on metrics like "logRMSE" and "mPSNR", but the subjective quality (in particular block artifacts) is generally significantly worse than -hdr. "-hdr_log" is equivalent to "-forcehdr_rgb -v 0 1 0 1 0 0 -va 0.02 1 0 0 -dblimit 999" "-hdra_log" is equivalent to "-forcehdr_rgba -v 0 1 0 1 0 0 -va 1 0 1 0 -dblimit 999" Performance-quality tradeoff presets: ------------------------------------- These are presets that provide different tradeoffs between encoding performance and quality. Exactly one of these presets has to be specified for encoding; if this is not done, the codec reports an error message. -veryfast Run codec in very-fast-mode; this generally results in substantial quality loss. -fast Run codec in fast-mode. This generally results in mild quality loss. -medium Run codec in medium-speed-mode. -thorough Run codec in thorough-mode. This should be sufficient to fix most cases where "-medium" provides inadequate quality. -exhaustive Run codec in exhaustive-mode. This usually produces only marginally better quality than "-thorough" while considerably increasing encode time. Low-level error weighting options: ---------------------------------- These options provide low-level control of the error-weighting options that the codec provides. -v <radius> <power> <baseweight> <avgscale> <stdevscale> <mixing-factor> Compute the per-texel relative error weighting for the RGB color channels as follows: weight = 1 / (<baseweight> + <avgscale> * average^2 + <stdevscale> * stdev^2) The average and stdev are computed as the average-value and the standard deviation across a neighborhood of each texel; the <radius> argument specifies how wide this neighborhood should be. If this option is given without -va, it affects the weighting of RGB color components only, while alpha is assigned the weight 1.0 . The <mixing-factor> parameter is used to control the degree of mixing between color channels. Setting this parameter to 0 causes the average and stdev computation to be done completely separately for each color channel; setting it to 1 causes the results from the red, green and blue color channel to be combined into a single result that is applied to all three channels. It is possible to set the mixing factor to a value between 0 and 1 in order to obtain a result in-between. The <power> argument is a power used to raise the values of the input pixels before computing average and stdev; e.g. a power of 0.5 causes the codec to take the square root of every input pixel value before computing the averages and standard deviations. -va <baseweight> <power> <avgscale> <stdevscale> Used together with -v; it computes a relative per-texel weighting for the alpha component based on average and standard deviation in the same manner as described for -v, but with its own <baseweight>, <power>, <avgscale> and <stdevscale> parameters. -a <radius> For textures with alpha channel, scale per-texel weights by alpha. The alpha value chosen for scaling of any particular texel is taken as an average across a neighborhood of the texel. The <radius> argument gives the radius of this neighborhood; a radius of 0 causes the texel's own alpha value to be used with no contribution from neighboring texels. -ch <red_weight> <green_weight> <blue_weight> <alpha_weight> Assign relative weight to each color channel. If this option is combined with any of the other options above, the other options are used to compute a weighting, then the weigthing is multiplied by the weighting provided by this argument. -rn Assume that the red and alpha color channels (after swizzle) represent the X and Y components for a normal map, and scale the error weighting so as to match angular error as closely as possible. The reconstruction function for the Z component is assumed to be Z=sqrt(1 - X^2 - X^2). -b <weighting> Increase error weight for texels at compression-block edges and corners; the parameter specifies how much the weights are to be modified, with 0 giving no modification. Higher values should reduce block-artifacts, at the cost of worsening other artifacts. Low-level performance-quality tradeoff options: ----------------------------------------------- These options provide low-level control of the performance-quality tradeoffs that the codec provides. -plimit <number> Test only <number> different partitionings. Higher numbers give better quality at the expense of longer encode time; however large values tend to give diminishing returns. This parameter can be set to a number from 1 to 1024. By default, this limit is set based on the active preset, as follows: -veryfast : 2 -fast : 4 -medium : 25 -thorough : 100 -exhaustive : 1024 -dblimit <number> Stop compression work on a block as soon as the PSNR of the block, as measured in dB, exceeds this limit. Higher numbers give better quality at the expense of longer encode times. If not set explicitly, it is set based on the currently-active block size and preset, as listed below (where N is the number of texels per block): -veryfast : dblimit = MAX( 53-19*log10(N), 70-35*log10(N) ) -fast : dblimit = MAX( 63-19*log10(N), 85-35*log10(N) ) -medium : dblimit = MAX( 70-19*log10(N), 95-35*log10(N) ) -thorough : dblimit = MAX( 77-19*log10(N), 105-35*log10(N) ) -exhaustive : dblimit = 999 Note that the compressor is not actually guaranteed to reach these PSNR numbers for any given block; also, at the point where the compressor discovers that it has exceeded the dblimit, it may have exceeded it by a large amount, so it is still possible to get a PSNR value that is substantially higher than the dblimit would suggest. This option is ineffective for HDR textures. -oplimit <factor> If the error term from encoding with 2 partitions is greater than the error term from encoding with 1 partition by more than the specified factor, then cut compression work short. By default, this factor is set based on the active preset, as follows: -veryfast : 1.0 -fast : 1.0 -medium : 1.2 -thorough : 2.5 -exhaustive : 1000 The codec will not apply this factor if the input texture is a normal map (content resembles a normal-map, or one of the -normal_* presets is used). -mincorrel <value> For each block, the codec will compute the correlation coefficients between any two color components; if no pair of colors have a correlation coefficient below the cutoff specified by this switch, the codec will abstain from trying the dual-weight-planes. By default, this factor is set based on the active preset, as follows: -veryfast : 0.5 -fast : 0.5 -medium : 0.75 -thorough : 0.95 -exhaustive : 0.99 If the input texture is a normal-map (content resembles a normal-map or one of the -normal_* presets are used) the codec will use a value of 0.99. -bmc <value> Cutoff on the set of block modes to use; the cutoff is a percentile of the block modes that are most commonly used. The value takes a value from 0 to 100, where 0 offers the highest speed and lowest quality, and 100 offers the highest quality and lowest speed. By default, this factor is set based on the active preset, as follows: -veryfast : 25 -fast : 50 -medium : 75 -thorough : 95 -exhaustive : 100 This option is ineffective for 3D textures. -maxiters <value> Maximum number of refinement iterations to apply to colors and weights. Minimum value is 1; larger values give slight quality increase at expense of mild performance loss. By default, the iteration count is picked based on the active preset, as follows: -veryfast : 1 -fast : 1 -medium : 2 -thorough : 4 -exhaustive : 4 Other options: -------------- -array <size> Loads a an array of 2D image slices as a 3D image. The filename given is used as a base, and decorated with _0, _1, up to _<size-1> prior to loading each slice. So -array 3 input.png would load input_0.png, input_1.png and input_2.png as slices at z=0,1,2 respectively. -forcehdr_rgb Force the use of HDR endpoint modes. By default, only LDR endpoint modes are used. If alpha is present, alpha is kept as LDR. -forcehdr_rgba Force the use of HDR endpoint modes. By default, only LDR endpoint modes are used. If alpha is present, alpha is forced into HDR as well. -esw <swizzlepattern> Swizzle the color components before encoding. The swizzle pattern is specified as a 4-character string, where the characters specify which color component will end up in the Red, Green, Blue and Alpha channels before encoding takes place. The characters may be taken from the set (r,g,b,a,0,1), where r,g,b,a use color components from the input texture and 0,1 use the constant values 0 and 1. As an example, if you have an input RGBA texture where you wish to switch around the R and G channels, as well as replacing the alpha channel with the constant value 1, a suitable swizzle option would be: -esw grb1 Note that if -esw is used together with any of the error weighting functions, the swizzle is considered to be applied before the error weighting function. -dsw <swizzlepattern> Swizzle pattern to apply after decoding a texture. This pattern is specified in the samw way as the pre-encoding swizzle pattern for the -sw switch. However, one additional character is supported, namely 'z' for constructing the third component of a normal map. -srgb Convert input image from sRGB to linear-RGB before encode; convert output image from linear-RGB to sRGB after decode. For encode, the transform is applied after swizzle; for decode, the transform is applied before swizzle. -j <numthreads> Run encoding with multithreading, using the specified number of threads. If not specified, the codec will autodetect the number of available logical CPUs and spawn one thread for each. Use "-j 1" if you wish to run the codec in single-thread mode. -silentmode Suppresses all output from the codec, except in case of errors. If this switch is not provided, the codec will display the encoding settings it uses and show a progress counter during encode. -time Displays time taken for entire run, together with time taken for coding step only. If requested, this is output even in -silentmode. -showpsnr In test mode (-t), displays PSNR difference between input and output images, in dB, even if -silentmode is specified. Works for LDR images only. -mpsnr <low> <high> Set the low and high f-stop values to use for the mPSNR error metric. Default is low=-10, high=10. The mPSNR error metric only applies to HDR textures. This option can be used together with -compare . Tips & tricks: -------------- ASTC, being a block-based format, is moderately prone to block artifacts. If block artifacts are a problem when compressing a given texture, adding some or all of following command-line options may help: -b 1.8 -v 2 1 1 0 25 0.1 -va 1 1 0 25 -dblimit 60 The -b option is a general-purpose block-artifact reduction option. The -v and -va options concentrate effort where smooth regions lie next to regions with high detail (such regions are particularly prone to block artifacts otherwise). The -dblimit option is sometimes also needed to reduce block artifacts in regions with very smooth gradients. If a texture exhibits severe block artifacts in only some, but not all, of the color channels (common problem with mask textures), then it may help to use the -ch option to raise the weighting of the affected color channel(s). For example, if the green color channel in particular suffers from block artifacts, then using the commandline option -ch 1 6 1 1 should improve the result significantly.
