Description: Clean up man pages Author: Mathieu Malaterre Forwarded: https://github.com/libjxl/libjxl/pull/1288 Last-Update: 2022-03-29 Index: libjxl/doc/man/cjxl.txt =================================================================== --- libjxl.orig/doc/man/cjxl.txt +++ libjxl/doc/man/cjxl.txt @@ -31,40 +31,31 @@ cjxl input.gif output.jxl Options ------- --h:: ---help:: - Displays the options that `cjxl` supports. On its own, it will only show - basic options. It can be combined with `-v` or `-v -v` to show increasingly - advanced options as well. +--container='0|1':: + 0 = Do not encode using container format (strip Exif/XMP/JPEG bitstream reconstruction data).1 = Force using container format (default: use only if needed). --v:: ---verbose:: - Increases verbosity. Can be repeated to increase it further, and also - applies to `--help`. +--jpeg_store_metadata='0|1':: + If --lossless_jpeg=1, store JPEG reconstruction metadata in the JPEG XL container (for lossless reconstruction of the JPEG codestream).(default: 1) -d 'distance':: --distance='distance':: - The preferred way to specify quality. It is specified in multiples of a - just-noticeable difference. That is, `-d 0` is mathematically lossless, - `-d 1` should be visually lossless, and higher distances yield denser and - denser files with lower and lower fidelity. Lossy sources such as JPEG and - GIF files are compressed losslessly by default, and in the case of JPEG - files specifically, the original JPEG can then be reconstructed bit-for-bit. - For lossless sources, `-d 1` is the default. + Max. butteraugli distance, lower = higher quality. + 0.0 = mathematically lossless. Default for already-lossy input (JPEG/GIF). + 1.0 = visually lossless. Default for other input. + Recommended range: 0.5 .. 3.0. Mutually exclusive with --quality. -q 'quality':: --quality='quality':: - Alternative way to indicate the desired quality. 100 is lossless and lower - values yield smaller files. There is no lower bound to this quality - parameter, but positive values should approximately match the quality - setting of libjpeg. + Quality setting (is remapped to --distance). Range: -inf .. 100. + 100 = mathematically lossless. Default for already-lossy input (JPEG/GIF). + Other input gets encoded as per --distance default. + Positive quality values roughly match libjpeg quality. + Mutually exclusive with --distance. -e 'effort':: --effort='effort':: - Controls the amount of effort that goes into producing an ``optimal'' file - in terms of quality/size. That is to say, all other parameters being equal, - a higher effort should yield a file that is at least as dense and possibly - denser, and with at least as high and possibly higher quality. + Encoder effort setting. Range: 1 .. 9. + Default: 7. Higher number is more effort (slower). + Recognized effort settings, from fastest to slowest, are: + @@ -78,6 +69,176 @@ Recognized effort settings, from fastest - 8 or ``kitten'' - 9 or ``tortoise'' +--brotli_effort='B_EFFORT':: + Brotli effort setting. Range: 0 .. 11. + Default: 9. Higher number is more effort (slower). + +--faster_decoding='0|1|2|3|4':: + Favour higher decoding speed. 0 = default, higher values give higher speed at the expense of quality + +-p:: +--progressive:: + Enable progressive/responsive decoding. + +--premultiply='-1|0|1':: + Force premultiplied (associated) alpha. + +--keep_invisible='0|1':: + Force disable/enable preserving color of invisible pixels (default: 1 if + lossless, 0 if lossy). + +--group_order='0|1':: + Order in which 256x256 groups are stored in the codestream for progressive rendering. Value not provided means 'encoder default', 0 means 'scanline order', 1 means 'center-first order'. + +--center_x='0..XSIZE':: + Determines the horizontal position of center for the center-first group order. The value -1 means 'use the middle of the image', other values [0..xsize) set this to a particular coordinate. + +--center_y='0..YSIZE':: + Determines the vertical position of center for the center-first group order. The value -1 means 'use the middle of the image', other values [0..ysize) set this to a particular coordinate. + +--progressive_ac:: + Use the progressive mode for AC. + +--qprogressive_ac:: + Use the progressive mode for AC with shift quantization. + +--progressive_dc='num_dc_frames':: + Progressive-DC setting. Valid values are: -1, 0, 1, 2. + +-m='0|1':: +--modular='0|1':: + Use modular mode (not provided = encoder chooses, 0 = enforce VarDCT, 1 = enforce modular mode). + +-j='0|1':: +--lossless_jpeg='0|1':: + If the input is JPEG, losslessly transcode JPEG, rather than using reencode pixels. + +--jpeg_reconstruction_cfl='0|1':: + Enable/disable chroma-from-luma (CFL) for lossless JPEG reconstruction. + +--num_threads='N':: + Number of worker threads (-1 == use machine default, 0 == do not use multithreading). + +--num_reps='N':: + How many times to compress. (For benchmarking). + +--photon_noise='ISO3200':: + Adds noise to the image emulating photographic film noise. The higher the given number, the grainier the image will be. As an example, a value of 100 gives low noise whereas a value of 3200 gives a lot of noise. The default value is 0. + +--dots='0|1':: + Force disable/enable dots generation. (not provided = default, 0 = disable, 1 = enable). + +--patches='0|1':: + Force disable/enable patches generation. (not provided = default, 0 = disable, 1 = enable). + +--resampling='-1|1|2|4|8':: + Resampling for extra channels. Default of -1 applies resampling only for low quality. Value 1 does no downsampling (1x1), 2 does 2x2 downsampling, 4 is for 4x4 downsampling, and 8 for 8x8 downsampling. + +--ec_resampling='1|2|4|8':: + Resampling for extra channels. Default of -1 applies resampling only for low quality. Value 1 does no downsampling (1x1), 2 does 2x2 downsampling, 4 is for 4x4 downsampling, and 8 for 8x8 downsampling. + +--already_downsampled:: + Do not downsample the given input before encoding, but still signal that the decoder should upsample. + +--epf='-1|0|1|2|3':: + Edge preserving filter level, -1 to 3. Value -1 means: default (encoder chooses), 0 to 3 set a strength. + +--gaborish='0|1':: + Force disable/enable the gaborish filter. (not provided = default, 0 = disable, 1 = enable). + +--intensity_target='N':: + Upper bound on the intensity level present in the image in nits. Leaving this set to its default of 0 lets libjxl choose a sensible default value based on the color encoding. + +-x='key=value':: +--dec-hints='key=value':: + color_space indicates the ColorEncoding, see Description(); icc_pathname refers to a binary file containing an ICC profile. + +--override_bitdepth=0=use from image, 1-32=override + If nonzero, store the given bit depth in the JPEG XL file metadata (1-32), instead of using the bit depth from the original input image. + +-I 'F':: +--iterations='F':: + [modular encoding] Fraction of pixels used to learn MA trees as a percentage. -1 = default, 0 = no MA and fast decode, 50 = default value, 100 = all.Higher values use more encoder memory. + +-C 'K':: +--modular_colorspace='K':: + [modular encoding] color transform: -1=default, 0=RGB (none), 1-41=RCT (6=YCoCg, default: try several, depending on speed) + +-g 'K':: +--modular_group_size='K':: + [modular encoding] group size: -1 == default. 0 => 128, 1 => 256, 2 => 512, 3 => 1024 + +-P 'K':: +--modular_predictor='K':: + [modular encoding] predictor(s) to use: ++ +- 0=zero, +- 1=left, +- 2=top, +- 3=avg0, +- 4=select, +- 5=gradient, +- 6=weighted, +- 7=topright, +- 8=topleft, +- 9=leftleft, +- 10=avg1, +- 11=avg2, +- 12=avg3, +- 13=toptop predictive average +- 14=mix 5 and 6, +- 15=mix everything. ++ +Default 14, at slowest speed default 15 + +-E 'K':: +--modular_nb_prev_channels='K':: + [modular encoding] number of extra MA tree properties to use + +--modular_palette_colors='K':: + [modular encoding] Use color palette if number of colors is smaller than or equal to this, or -1 to use the encoder default. + +--modular_lossy_palette:: + [modular encoding] quantize to a palette that has fewer entries than would be necessary for perfect preservation; for the time being, it is recommended to set --palette=0 with this option to use the default palette only + +-X 'PERCENT':: +--pre-compact='PERCENT':: + [modular encoding] Use Global channel palette if the number of colors is smaller than this percentage of range. Use 0-100 to set an explicit percentage, -1 to use the encoder default. + +-Y 'PERCENT':: +--post-compact='PERCENT':: + [modular encoding] Use Local (per-group) channel palette if the number of colors is smaller than this percentage of range. Use 0-100 to set an explicit percentage, -1 to use the encoder default. + +--codestream_level='K':: + The codestream level. Either `-1`, `5` or `10`. + +-R 'K':: +--responsive='K':: + [modular encoding] do Squeeze transform, 0=false, 1=true (default: true if lossy, false if lossless) + +-V +--version:: + Print encoder library version number and exit. + +--quiet:: + Be more silent + +--frame_indexing='string':: + If non-empty, a string matching '^(0*|1[01]*)'. If this string has a '1' in i-th position, then the i-th frame will be indexed in the frame index box. + +-v:: +--verbose:: + Increases verbosity. Can be repeated to increase it further, and also + applies to `--help`. + +-h:: +--help:: + Displays the options that `cjxl` supports. On its own, it will only show + basic options. It can be combined with `-v` or `-v -v` to show increasingly + advanced options as well. + + + Examples -------- Index: libjxl/doc/man/djxl.txt =================================================================== --- libjxl.orig/doc/man/djxl.txt +++ libjxl/doc/man/djxl.txt @@ -24,23 +24,65 @@ produced, with names of the form "'outpu Options ------- --h:: ---help:: - Displays the options that `djxl` supports. +-V:: +--version:: + Print version number and exit + +--num_reps='N':: + Sets the number of times to decompress the image. Used for benchmarking, the default is 1. + +--num_threads='N':: + Sets the number of threads to use. The default 0 value means the machine default. + +--bits_per_sample='N':: + Sets the output bit depth. The default 0 value means the original (input) bit depth. + +--display_nits='0.3-250':: + If set to a non-zero value, tone maps the image the given peak display luminance. + +--color_space='RGB_D65_SRG_Rel_Lin':: + Defaults to original (input) color space + +-s 'N':: +--downsampling='N':: + If set and the input JXL stream is progressive and contains hints for target downsampling ratios, the decoder will skip any progressive passes that are not needed to produce a partially decoded image intended for this downsampling ratio. + +--allow_partial_files:: + Allow decoding of truncated files. -j:: --pixels_to_jpeg:: - By default, if the input JPEG XL contains a recompressed JPEG file, - djxl reconstructs the exact original JPEG file if the output file has the - `.jpg` (or `.jpeg`) filename extension. - This flag causes the decoder to instead decode the image to pixels and - encode a new (lossy) JPEG in this case. + By default, if the input JPEG XL contains a recompressed JPEG file, djxl reconstructs the exact original JPEG file. This flag causes the decoder to instead decode the image to pixels and encode a new (lossy) JPEG. The output file if provided must be a .jpg or .jpeg file. + +-q 'N':: +--jpeg_quality='N':: + Sets the JPEG output quality, default is 95. Setting an output quality implies --pixels_to_jpeg. + +--norender_spotcolors + Disables rendering spot colors. + +--preview_out='FILENAME':: + If specified, writes the preview image to this file. + +--icc_out='FILENAME':: + If specified, writes the ICC profile of the decoded image to this file. + +--orig_icc_out='FILENAME':: + If specified, writes the ICC profile of the original image to this file. This can be different from the ICC profile of the decoded image if --color_space was specified, or if the image was XYB encoded and the color conversion to the original profile was not supported by the decoder. +--metadata_out='FILENAME':: + If specified, writes decoded metadata info to this file in JSON format. Used by the conformance test script + +--print_read_bytes:: + Print total number of decoded bytes. + +--quiet:: + Silence output (except for errors). + +-h:: +--help:: + Displays the options that `djxl` supports. --q 'quality':: ---jpeg_quality='quality':: - When decoding to `.jpg`, use this output quality. This option implicitly - enables the --pixels_to_jpeg option. Examples @@ -54,6 +96,25 @@ $ djxl input.jxl output.png $ djxl lossless-jpeg.jxl reconstructed.jpeg ---- +# Lossless compression + +Lossless pixel compression only preserves the pixels losslessly, not the input +bitstream. To check that the pixels are identical, one can do something like +the following (if this says 0, then the maximum pixel error is 0, so it's +lossless): + +---- +# Lossless compression of PNG: +$ cjxl -d 0.0 input.png lossless.png + +# Decompress a JPEG XL file to PNG +$ djxl lossless.jxl lossless.png + +$ compare -metric pae input.png lossless.png null: +0 (0) +---- + + See also --------