tools.md (18625B)
1 # WebP tools 2 3 ## Encoding tool 4 5 The examples/ directory contains tools for encoding (cwebp) and decoding (dwebp) 6 images. 7 8 The easiest use should look like: 9 10 ```shell 11 cwebp input.png -q 80 -o output.webp 12 ``` 13 14 which will convert the input file to a WebP file using a quality factor of 80 on 15 a 0->100 scale (0 being the lowest quality, 100 being the best. Default value is 16 75). 17 18 You might want to try the `-lossless` flag too, which will compress the source 19 (in RGBA format) without any loss. The `-q` quality parameter will in this case 20 control the amount of processing time spent trying to make the output file as 21 small as possible. 22 23 A longer list of options is available using the `-longhelp` command line flag: 24 25 ```shell 26 > cwebp -longhelp 27 Usage: 28 cwebp [-preset <...>] [options] in_file [-o out_file] 29 ``` 30 31 If input size (-s) for an image is not specified, it is assumed to be a PNG, 32 JPEG, TIFF or WebP file. Note: Animated PNG and WebP files are not supported. 33 34 Options: 35 36 ``` 37 -h / -help ............. short help 38 -H / -longhelp ......... long help 39 -q <float> ............. quality factor (0:small..100:big), default=75 40 -alpha_q <int> ......... transparency-compression quality (0..100), 41 default=100 42 -preset <string> ....... preset setting, one of: 43 default, photo, picture, 44 drawing, icon, text 45 -preset must come first, as it overwrites other parameters 46 -z <int> ............... activates lossless preset with given 47 level in [0:fast, ..., 9:slowest] 48 49 -m <int> ............... compression method (0=fast, 6=slowest), default=4 50 -segments <int> ........ number of segments to use (1..4), default=4 51 -size <int> ............ target size (in bytes) 52 -psnr <float> .......... target PSNR (in dB. typically: 42) 53 54 -s <int> <int> ......... input size (width x height) for YUV 55 -sns <int> ............. spatial noise shaping (0:off, 100:max), default=50 56 -f <int> ............... filter strength (0=off..100), default=60 57 -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp), default=0 58 -strong ................ use strong filter instead of simple (default) 59 -nostrong .............. use simple filter instead of strong 60 -sharp_yuv ............. use sharper (and slower) RGB->YUV conversion 61 -partition_limit <int> . limit quality to fit the 512k limit on 62 the first partition (0=no degradation ... 100=full) 63 -pass <int> ............ analysis pass number (1..10) 64 -qrange <min> <max> .... specifies the permissible quality range 65 (default: 0 100) 66 -crop <x> <y> <w> <h> .. crop picture with the given rectangle 67 -resize <w> <h> ........ resize picture (*after* any cropping) 68 -resize_mode <string> .. one of: up_only, down_only, always (default) 69 -mt .................... use multi-threading if available 70 -low_memory ............ reduce memory usage (slower encoding) 71 -map <int> ............. print map of extra info 72 -print_psnr ............ prints averaged PSNR distortion 73 -print_ssim ............ prints averaged SSIM distortion 74 -print_lsim ............ prints local-similarity distortion 75 -d <file.pgm> .......... dump the compressed output (PGM file) 76 -alpha_method <int> .... transparency-compression method (0..1), default=1 77 -alpha_filter <string> . predictive filtering for alpha plane, 78 one of: none, fast (default) or best 79 -exact ................. preserve RGB values in transparent area, default=off 80 -blend_alpha <hex> ..... blend colors against background color 81 expressed as RGB values written in 82 hexadecimal, e.g. 0xc0e0d0 for red=0xc0 83 green=0xe0 and blue=0xd0 84 -noalpha ............... discard any transparency information 85 -lossless .............. encode image losslessly, default=off 86 -near_lossless <int> ... use near-lossless image preprocessing 87 (0..100=off), default=100 88 -hint <string> ......... specify image characteristics hint, 89 one of: photo, picture or graph 90 91 -metadata <string> ..... comma separated list of metadata to 92 copy from the input to the output if present. 93 Valid values: all, none (default), exif, icc, xmp 94 95 -short ................. condense printed message 96 -quiet ................. don't print anything 97 -version ............... print version number and exit 98 -noasm ................. disable all assembly optimizations 99 -v ..................... verbose, e.g. print encoding/decoding times 100 -progress .............. report encoding progress 101 ``` 102 103 Experimental Options: 104 105 ``` 106 -jpeg_like ............. roughly match expected JPEG size 107 -af .................... auto-adjust filter strength 108 -pre <int> ............. pre-processing filter 109 ``` 110 111 The main options you might want to try in order to further tune the visual 112 quality are: 113 114 -preset -sns -f -m 115 116 Namely: 117 118 * `preset` will set up a default encoding configuration targeting a particular 119 type of input. It should appear first in the list of options, so that 120 subsequent options can take effect on top of this preset. Default value is 121 'default'. 122 * `sns` will progressively turn on (when going from 0 to 100) some additional 123 visual optimizations (like: segmentation map re-enforcement). This option 124 will balance the bit allocation differently. It tries to take bits from the 125 "easy" parts of the picture and use them in the "difficult" ones instead. 126 Usually, raising the sns value (at fixed -q value) leads to larger files, 127 but with better quality. Typical value is around '75'. 128 * `f` option directly links to the filtering strength used by the codec's 129 in-loop processing. The higher the value, the smoother the highly-compressed 130 area will look. This is particularly useful when aiming at very small files. 131 Typical values are around 20-30. Note that using the option 132 -strong/-nostrong will change the type of filtering. Use "-f 0" to turn 133 filtering off. 134 * `m` controls the trade-off between encoding speed and quality. Default is 4. 135 You can try -m 5 or -m 6 to explore more (time-consuming) encoding 136 possibilities. A lower value will result in faster encoding at the expense 137 of quality. 138 139 ## Decoding tool 140 141 There is a decoding sample in examples/dwebp.c which will take a .webp file and 142 decode it to a PNG image file (amongst other formats). This is simply to 143 demonstrate the use of the API. You can verify the file test.webp decodes to 144 exactly the same as test_ref.ppm by using: 145 146 ```shell 147 cd examples 148 ./dwebp test.webp -ppm -o test.ppm 149 diff test.ppm test_ref.ppm 150 ``` 151 152 The full list of options is available using -h: 153 154 ```shell 155 > dwebp -h 156 Usage: dwebp in_file [options] [-o out_file] 157 ``` 158 159 Decodes the WebP image file to PNG format [Default]. Note: Animated WebP files 160 are not supported. 161 162 Use following options to convert into alternate image formats: 163 164 ``` 165 -pam ......... save the raw RGBA samples as a color PAM 166 -ppm ......... save the raw RGB samples as a color PPM 167 -bmp ......... save as uncompressed BMP format 168 -tiff ........ save as uncompressed TIFF format 169 -pgm ......... save the raw YUV samples as a grayscale PGM 170 file with IMC4 layout 171 -yuv ......... save the raw YUV samples in flat layout 172 ``` 173 174 Other options are: 175 176 ``` 177 -version ..... print version number and exit 178 -nofancy ..... don't use the fancy YUV420 upscaler 179 -nofilter .... disable in-loop filtering 180 -nodither .... disable dithering 181 -dither <d> .. dithering strength (in 0..100) 182 -alpha_dither use alpha-plane dithering if needed 183 -mt .......... use multi-threading 184 -crop <x> <y> <w> <h> ... crop output with the given rectangle 185 -resize <w> <h> ......... resize output (*after* any cropping) 186 -flip ........ flip the output vertically 187 -alpha ....... only save the alpha plane 188 -incremental . use incremental decoding (useful for tests) 189 -h ........... this help message 190 -v ........... verbose (e.g. print encoding/decoding times) 191 -quiet ....... quiet mode, don't print anything 192 -noasm ....... disable all assembly optimizations 193 ``` 194 195 ## WebP file analysis tool 196 197 `webpinfo` can be used to print out the chunk level structure and bitstream 198 header information of WebP files. It can also check if the files are of valid 199 WebP format. 200 201 Usage: 202 203 ```shell 204 webpinfo [options] in_files 205 ``` 206 207 Note: there could be multiple input files; options must come before input files. 208 209 Options: 210 211 ``` 212 -version ........... Print version number and exit. 213 -quiet ............. Do not show chunk parsing information. 214 -diag .............. Show parsing error diagnosis. 215 -summary ........... Show chunk stats summary. 216 -bitstream_info .... Parse bitstream header. 217 ``` 218 219 ## Visualization tool 220 221 There's a little self-serve visualization tool called 'vwebp' under the 222 examples/ directory. It uses OpenGL to open a simple drawing window and show a 223 decoded WebP file. It's not yet integrated in the automake build system, but you 224 can try to manually compile it using the recommendations below. 225 226 Usage: 227 228 ```shell 229 vwebp in_file [options] 230 ``` 231 232 Decodes the WebP image file and visualize it using OpenGL 233 234 Options are: 235 236 ``` 237 -version ..... print version number and exit 238 -noicc ....... don't use the icc profile if present 239 -nofancy ..... don't use the fancy YUV420 upscaler 240 -nofilter .... disable in-loop filtering 241 -dither <int> dithering strength (0..100), default=50 242 -noalphadither disable alpha plane dithering 243 -usebgcolor .. display background color 244 -mt .......... use multi-threading 245 -info ........ print info 246 -h ........... this help message 247 ``` 248 249 Keyboard shortcuts: 250 251 ``` 252 'c' ................ toggle use of color profile 253 'b' ................ toggle background color display 254 'i' ................ overlay file information 255 'd' ................ disable blending & disposal (debug) 256 'q' / 'Q' / ESC .... quit 257 ``` 258 259 ### Building 260 261 Prerequisites: 262 263 1. OpenGL & OpenGL Utility Toolkit (GLUT) 264 265 Linux: `sudo apt-get install freeglut3-dev mesa-common-dev` 266 267 Mac + Xcode: These libraries should be available in the OpenGL / GLUT 268 frameworks. 269 270 Windows: http://freeglut.sourceforge.net/index.php#download 271 272 2. (Optional) qcms (Quick Color Management System) 273 274 1. Download qcms from Mozilla / Chromium: 275 https://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms 276 https://source.chromium.org/chromium/chromium/src/+/main:third_party/qcms/;drc=d4a2f8e1ed461d8fc05ed88d1ae2dc94c9773825 277 2. Build and archive the source files as libqcms.a / qcms.lib 278 3. Update makefile.unix / Makefile.vc 279 1. Define WEBP_HAVE_QCMS 280 2. Update include / library paths to reference the qcms directory. 281 282 Build using makefile.unix / Makefile.vc: 283 284 ```shell 285 $ make -f makefile.unix examples/vwebp 286 > nmake /f Makefile.vc CFG=release-static \ 287 ../obj/x64/release-static/bin/vwebp.exe 288 ``` 289 290 ## Animation creation tool 291 292 The utility `img2webp` can turn a sequence of input images (PNG, JPEG, ...) into 293 an animated WebP file. It offers fine control over duration, encoding modes, 294 etc. 295 296 Usage: 297 298 ```shell 299 img2webp [file_options] [[frame_options] frame_file]... [-o webp_file] 300 ``` 301 302 File-level options (only used at the start of compression): 303 304 ``` 305 -min_size ............ minimize size 306 -kmax <int> .......... maximum number of frame between key-frames 307 (0=only keyframes) 308 -kmin <int> .......... minimum number of frame between key-frames 309 (0=disable key-frames altogether) 310 -mixed ............... use mixed lossy/lossless automatic mode 311 -near_lossless <int> . use near-lossless image preprocessing 312 (0..100=off), default=100 313 -sharp_yuv ........... use sharper (and slower) RGB->YUV conversion 314 (lossy only) 315 -loop <int> .......... loop count (default: 0, = infinite loop) 316 -v ................... verbose mode 317 -h ................... this help 318 -version ............. print version number and exit 319 ``` 320 321 Per-frame options (only used for subsequent images input): 322 323 ``` 324 -d <int> ............. frame duration in ms (default: 100) 325 -lossless ............ use lossless mode (default) 326 -lossy ............... use lossy mode 327 -q <float> ........... quality 328 -m <int> ............. compression method (0=fast, 6=slowest), default=4 329 -exact, -noexact ..... preserve or alter RGB values in transparent area 330 (default: -noexact, may cause artifacts 331 with lossy animations) 332 ``` 333 334 example: `img2webp -loop 2 in0.png -lossy in1.jpg -d 80 in2.tiff -o out.webp` 335 336 Note: if a single file name is passed as the argument, the arguments will be 337 tokenized from this file. The file name must not start with the character '-'. 338 339 ## Animated GIF conversion 340 341 Animated GIF files can be converted to WebP files with animation using the 342 gif2webp utility available under examples/. The files can then be viewed using 343 vwebp. 344 345 Usage: 346 347 ```shell 348 gif2webp [options] gif_file -o webp_file 349 ``` 350 351 Options: 352 353 ``` 354 -h / -help ............. this help 355 -lossy ................. encode image using lossy compression 356 -mixed ................. for each frame in the image, pick lossy 357 or lossless compression heuristically 358 -near_lossless <int> ... use near-lossless image preprocessing 359 (0..100=off), default=100 360 -sharp_yuv ............. use sharper (and slower) RGB->YUV conversion 361 (lossy only) 362 -q <float> ............. quality factor (0:small..100:big) 363 -m <int> ............... compression method (0=fast, 6=slowest), default=4 364 -min_size .............. minimize output size (default:off) 365 lossless compression by default; can be 366 combined with -q, -m, -lossy or -mixed 367 options 368 -kmin <int> ............ min distance between key frames 369 -kmax <int> ............ max distance between key frames 370 -f <int> ............... filter strength (0=off..100) 371 -metadata <string> ..... comma separated list of metadata to 372 copy from the input to the output if present 373 Valid values: all, none, icc, xmp (default) 374 -loop_compatibility .... use compatibility mode for Chrome 375 version prior to M62 (inclusive) 376 -mt .................... use multi-threading if available 377 378 -version ............... print version number and exit 379 -v ..................... verbose 380 -quiet ................. don't print anything 381 ``` 382 383 ### Building 384 385 With the libgif development files installed, gif2webp can be built using 386 makefile.unix: 387 388 ```shell 389 $ make -f makefile.unix examples/gif2webp 390 ``` 391 392 or using autoconf: 393 394 ```shell 395 $ ./configure --enable-everything 396 $ make 397 ``` 398 399 ## Comparison of animated images 400 401 Test utility anim_diff under examples/ can be used to compare two animated 402 images (each can be GIF or WebP). 403 404 Usage: 405 406 ```shell 407 anim_diff <image1> <image2> [options] 408 ``` 409 410 Options: 411 412 ``` 413 -dump_frames <folder> dump decoded frames in PAM format 414 -min_psnr <float> ... minimum per-frame PSNR 415 -raw_comparison ..... if this flag is not used, RGB is 416 premultiplied before comparison 417 -max_diff <int> ..... maximum allowed difference per channel 418 between corresponding pixels in subsequent 419 frames 420 -h .................. this help 421 -version ............ print version number and exit 422 ``` 423 424 ### Building 425 426 With the libgif development files installed, anim_diff can be built using 427 makefile.unix: 428 429 ```shell 430 $ make -f makefile.unix examples/anim_diff 431 ``` 432 433 or using autoconf: 434 435 ```shell 436 $ ./configure --enable-everything 437 $ make 438 ``` 439 440 ## WebP Mux tool 441 442 The examples/ directory contains a tool (webpmux) for manipulating WebP files. 443 The webpmux tool can be used to create an extended format WebP file and also to 444 extract or strip relevant data from such a file. 445 446 A list of options is available using the -help command line flag: 447 448 ```shell 449 > webpmux -help 450 Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT 451 webpmux -set SET_OPTIONS INPUT -o OUTPUT 452 webpmux -duration DURATION_OPTIONS [-duration ...] 453 INPUT -o OUTPUT 454 webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT 455 webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT] 456 [-bgcolor BACKGROUND_COLOR] -o OUTPUT 457 webpmux -info INPUT 458 webpmux [-h|-help] 459 webpmux -version 460 webpmux argument_file_name 461 462 GET_OPTIONS: 463 Extract relevant data: 464 icc get ICC profile 465 exif get EXIF metadata 466 xmp get XMP metadata 467 frame n get nth frame 468 469 SET_OPTIONS: 470 Set color profile/metadata/parameters: 471 loop LOOP_COUNT set the loop count 472 bgcolor BACKGROUND_COLOR set the animation background color 473 icc file.icc set ICC profile 474 exif file.exif set EXIF metadata 475 xmp file.xmp set XMP metadata 476 where: 'file.icc' contains the ICC profile to be set, 477 'file.exif' contains the EXIF metadata to be set 478 'file.xmp' contains the XMP metadata to be set 479 480 DURATION_OPTIONS: 481 Set duration of selected frames: 482 duration set duration for all frames 483 duration,frame set duration of a particular frame 484 duration,start,end set duration of frames in the 485 interval [start,end]) 486 where: 'duration' is the duration in milliseconds 487 'start' is the start frame index 488 'end' is the inclusive end frame index 489 The special 'end' value '0' means: last frame. 490 491 STRIP_OPTIONS: 492 Strip color profile/metadata: 493 icc strip ICC profile 494 exif strip EXIF metadata 495 xmp strip XMP metadata 496 497 FRAME_OPTIONS(i): 498 Create animation: 499 file_i +di[+xi+yi[+mi[bi]]] 500 where: 'file_i' is the i'th animation frame (WebP format), 501 'di' is the pause duration before next frame, 502 'xi','yi' specify the image offset for this frame, 503 'mi' is the dispose method for this frame (0 or 1), 504 'bi' is the blending method for this frame (+b or -b) 505 506 LOOP_COUNT: 507 Number of times to repeat the animation. 508 Valid range is 0 to 65535 [Default: 0 (infinite)]. 509 510 BACKGROUND_COLOR: 511 Background color of the canvas. 512 A,R,G,B 513 where: 'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying 514 the Alpha, Red, Green and Blue component values respectively 515 [Default: 255,255,255,255] 516 517 INPUT & OUTPUT are in WebP format. 518 519 Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be 520 valid. 521 522 Note: if a single file name is passed as the argument, the arguments will be 523 tokenized from this file. The file name must not start with the character '-'. 524 ```