1 __ __ ____ ____ ____
2 / \\/ \/ _ \/ _ )/ _ \
3 \ / __/ _ \ __/
4 \__\__/\____/\_____/__/ ____ ___
5 / _/ / \ \ / _ \/ _/
6 / \_/ / / \ \ __/ \__
7 \____/____/\_____/_____/____/v0.4.3
8
9Description:
10============
11
12WebP codec: library to encode and decode images in WebP format. This package
13contains the library that can be used in other programs to add WebP support,
14as well as the command line tools 'cwebp' and 'dwebp'.
15
16See http://developers.google.com/speed/webp
17
18Latest sources are available from http://www.webmproject.org/code/
19
20It is released under the same license as the WebM project.
21See http://www.webmproject.org/license/software/ or the
22file "COPYING" file for details. An additional intellectual
23property rights grant can be found in the file PATENTS.
24
25Building:
26=========
27
28Windows build:
29--------------
30
31By running:
32
33 nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output
34
35the directory output\release-static\(x64|x86)\bin will contain the tools
36cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will
37contain the libwebp static library.
38The target architecture (x86/x64) is detected by Makefile.vc from the Visual
39Studio compiler (cl.exe) available in the system path.
40
41Unix build using makefile.unix:
42-------------------------------
43
44On platforms with GNU tools installed (gcc and make), running
45
46 make -f makefile.unix
47
48will build the binaries examples/cwebp and examples/dwebp, along
49with the static library src/libwebp.a. No system-wide installation
50is supplied, as this is a simple alternative to the full installation
51system based on the autoconf tools (see below).
52Please refer to makefile.unix for additional details and customizations.
53
54Using autoconf tools:
55---------------------
56When building from git sources, you will need to run autogen.sh to generate the
57configure script.
58
59./configure
60make
61make install
62
63should be all you need to have the following files
64
65/usr/local/include/webp/decode.h
66/usr/local/include/webp/encode.h
67/usr/local/include/webp/types.h
68/usr/local/lib/libwebp.*
69/usr/local/bin/cwebp
70/usr/local/bin/dwebp
71
72installed.
73
74Note: A decode-only library, libwebpdecoder, is available using the
75'--enable-libwebpdecoder' flag. The encode library is built separately and can
76be installed independently using a minor modification in the corresponding
77Makefile.am configure files (see comments there). See './configure --help' for
78more options.
79
80SWIG bindings:
81--------------
82
83To generate language bindings from swig/libwebp.swig at least swig-1.3
84(http://www.swig.org) is required.
85
86Currently the following functions are mapped:
87Decode:
88 WebPGetDecoderVersion
89 WebPGetInfo
90 WebPDecodeRGBA
91 WebPDecodeARGB
92 WebPDecodeBGRA
93 WebPDecodeBGR
94 WebPDecodeRGB
95
96Encode:
97 WebPGetEncoderVersion
98 WebPEncodeRGBA
99 WebPEncodeBGRA
100 WebPEncodeRGB
101 WebPEncodeBGR
102 WebPEncodeLosslessRGBA
103 WebPEncodeLosslessBGRA
104 WebPEncodeLosslessRGB
105 WebPEncodeLosslessBGR
106
107See swig/README for more detailed build instructions.
108
109Java bindings:
110
111To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent)
112is necessary for enum support. The output is intended to be a shared object /
113DLL that can be loaded via System.loadLibrary("webp_jni").
114
115Python bindings:
116
117To build the swig-generated Python extension code at least Python 2.6 is
118required. Python < 2.6 may build with some minor changes to libwebp.swig or the
119generated code, but is untested.
120
121Encoding tool:
122==============
123
124The examples/ directory contains tools for encoding (cwebp) and
125decoding (dwebp) images.
126
127The easiest use should look like:
128 cwebp input.png -q 80 -o output.webp
129which will convert the input file to a WebP file using a quality factor of 80
130on a 0->100 scale (0 being the lowest quality, 100 being the best. Default
131value is 75).
132You might want to try the -lossless flag too, which will compress the source
133(in RGBA format) without any loss. The -q quality parameter will in this case
134control the amount of processing time spent trying to make the output file as
135small as possible.
136
137A longer list of options is available using the -longhelp command line flag:
138
139> cwebp -longhelp
140Usage:
141 cwebp [-preset <...>] [options] in_file [-o out_file]
142
143If input size (-s) for an image is not specified, it is
144assumed to be a PNG, JPEG, TIFF or WebP file.
145
146Options:
147 -h / -help ............ short help
148 -H / -longhelp ........ long help
149 -q <float> ............. quality factor (0:small..100:big)
150 -alpha_q <int> ......... transparency-compression quality (0..100)
151 -preset <string> ....... preset setting, one of:
152 default, photo, picture,
153 drawing, icon, text
154 -preset must come first, as it overwrites other parameters
155
156 -m <int> ............... compression method (0=fast, 6=slowest)
157 -segments <int> ........ number of segments to use (1..4)
158 -size <int> ............ target size (in bytes)
159 -psnr <float> .......... target PSNR (in dB. typically: 42)
160
161 -s <int> <int> ......... input size (width x height) for YUV
162 -sns <int> ............. spatial noise shaping (0:off, 100:max)
163 -f <int> ............... filter strength (0=off..100)
164 -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp)
165 -strong ................ use strong filter instead of simple (default)
166 -nostrong .............. use simple filter instead of strong
167 -partition_limit <int> . limit quality to fit the 512k limit on
168 the first partition (0=no degradation ... 100=full)
169 -pass <int> ............ analysis pass number (1..10)
170 -crop <x> <y> <w> <h> .. crop picture with the given rectangle
171 -resize <w> <h> ........ resize picture (after any cropping)
172 -mt .................... use multi-threading if available
173 -low_memory ............ reduce memory usage (slower encoding)
174 -map <int> ............. print map of extra info
175 -print_psnr ............ prints averaged PSNR distortion
176 -print_ssim ............ prints averaged SSIM distortion
177 -print_lsim ............ prints local-similarity distortion
178 -d <file.pgm> .......... dump the compressed output (PGM file)
179 -alpha_method <int> .... transparency-compression method (0..1)
180 -alpha_filter <string> . predictive filtering for alpha plane,
181 one of: none, fast (default) or best
182 -alpha_cleanup ......... clean RGB values in transparent area
183 -blend_alpha <hex> ..... blend colors against background color
184 expressed as RGB values written in
185 hexadecimal, e.g. 0xc0e0d0 for red=0xc0
186 green=0xe0 and blue=0xd0
187 -noalpha ............... discard any transparency information
188 -lossless .............. encode image losslessly
189 -hint <string> ......... specify image characteristics hint,
190 one of: photo, picture or graph
191
192 -metadata <string> ..... comma separated list of metadata to
193 copy from the input to the output if present.
194 Valid values: all, none (default), exif, icc, xmp
195
196 -short ................. condense printed message
197 -quiet ................. don't print anything
198 -version ............... print version number and exit
199 -noasm ................. disable all assembly optimizations
200 -v ..................... verbose, e.g. print encoding/decoding times
201 -progress .............. report encoding progress
202
203Experimental Options:
204 -jpeg_like ............. roughly match expected JPEG size
205 -af .................... auto-adjust filter strength
206 -pre <int> ............. pre-processing filter
207
208The main options you might want to try in order to further tune the
209visual quality are:
210 -preset
211 -sns
212 -f
213 -m
214
215Namely:
216 * 'preset' will set up a default encoding configuration targeting a
217 particular type of input. It should appear first in the list of options,
218 so that subsequent options can take effect on top of this preset.
219 Default value is 'default'.
220 * 'sns' will progressively turn on (when going from 0 to 100) some additional
221 visual optimizations (like: segmentation map re-enforcement). This option
222 will balance the bit allocation differently. It tries to take bits from the
223 "easy" parts of the picture and use them in the "difficult" ones instead.
224 Usually, raising the sns value (at fixed -q value) leads to larger files,
225 but with better quality.
226 Typical value is around '75'.
227 * 'f' option directly links to the filtering strength used by the codec's
228 in-loop processing. The higher the value, the smoother the
229 highly-compressed area will look. This is particularly useful when aiming
230 at very small files. Typical values are around 20-30. Note that using the
231 option -strong/-nostrong will change the type of filtering. Use "-f 0" to
232 turn filtering off.
233 * 'm' controls the trade-off between encoding speed and quality. Default is 4.
234 You can try -m 5 or -m 6 to explore more (time-consuming) encoding
235 possibilities. A lower value will result in faster encoding at the expense
236 of quality.
237
238Decoding tool:
239==============
240
241There is a decoding sample in examples/dwebp.c which will take
242a .webp file and decode it to a PNG image file (amongst other formats).
243This is simply to demonstrate the use of the API. You can verify the
244file test.webp decodes to exactly the same as test_ref.ppm by using:
245
246 cd examples
247 ./dwebp test.webp -ppm -o test.ppm
248 diff test.ppm test_ref.ppm
249
250The full list of options is available using -h:
251
252> dwebp -h
253Usage: dwebp in_file [options] [-o out_file]
254
255Decodes the WebP image file to PNG format [Default]
256Use following options to convert into alternate image formats:
257 -pam ......... save the raw RGBA samples as a color PAM
258 -ppm ......... save the raw RGB samples as a color PPM
259 -bmp ......... save as uncompressed BMP format
260 -tiff ........ save as uncompressed TIFF format
261 -pgm ......... save the raw YUV samples as a grayscale PGM
262 file with IMC4 layout
263 -yuv ......... save the raw YUV samples in flat layout
264
265 Other options are:
266 -version .... print version number and exit
267 -nofancy ..... don't use the fancy YUV420 upscaler
268 -nofilter .... disable in-loop filtering
269 -nodither .... disable dithering
270 -dither <d> .. dithering strength (in 0..100)
271 -mt .......... use multi-threading
272 -crop <x> <y> <w> <h> ... crop output with the given rectangle
273 -scale <w> <h> .......... scale the output (*after* any cropping)
274 -alpha ....... only save the alpha plane
275 -incremental . use incremental decoding (useful for tests)
276 -h ....... this help message
277 -v ....... verbose (e.g. print encoding/decoding times)
278 -noasm ....... disable all assembly optimizations
279
280Visualization tool:
281===================
282
283There's a little self-serve visualization tool called 'vwebp' under the
284examples/ directory. It uses OpenGL to open a simple drawing window and show
285a decoded WebP file. It's not yet integrated in the automake build system, but
286you can try to manually compile it using the recommendations below.
287
288Usage: vwebp in_file [options]
289
290Decodes the WebP image file and visualize it using OpenGL
291Options are:
292 -version .... print version number and exit
293 -noicc ....... don't use the icc profile if present
294 -nofancy ..... don't use the fancy YUV420 upscaler
295 -nofilter .... disable in-loop filtering
296 -dither <int> dithering strength (0..100), default=50
297 -mt .......... use multi-threading
298 -info ........ print info
299 -h ....... this help message
300
301Keyboard shortcuts:
302 'c' ................ toggle use of color profile
303 'i' ................ overlay file information
304 'q' / 'Q' / ESC .... quit
305
306Building:
307---------
308
309Prerequisites:
3101) OpenGL & OpenGL Utility Toolkit (GLUT)
311 Linux:
312 $ sudo apt-get install freeglut3-dev mesa-common-dev
313 Mac + XCode:
314 - These libraries should be available in the OpenGL / GLUT frameworks.
315 Windows:
316 http://freeglut.sourceforge.net/index.php#download
317
3182) (Optional) qcms (Quick Color Management System)
319 i. Download qcms from Mozilla / Chromium:
320 http://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms
321 http://src.chromium.org/viewvc/chrome/trunk/src/third_party/qcms
322 ii. Build and archive the source files as libqcms.a / qcms.lib
323 iii. Update makefile.unix / Makefile.vc
324 a) Define WEBP_HAVE_QCMS
325 b) Update include / library paths to reference the qcms directory.
326
327Build using makefile.unix / Makefile.vc:
328$ make -f makefile.unix examples/vwebp
329> nmake /f Makefile.vc CFG=release-static \
330 ../obj/x64/release-static/bin/vwebp.exe
331
332Animated GIF conversion:
333========================
334Animated GIF files can be converted to WebP files with animation using the
335gif2webp utility available under examples/. The files can then be viewed using
336vwebp.
337
338Usage:
339 gif2webp [options] gif_file -o webp_file
340Options:
341 -h / -help ............ this help
342 -lossy ................. encode image using lossy compression
343 -mixed ................. for each frame in the image, pick lossy
344 or lossless compression heuristically
345 -q <float> ............. quality factor (0:small..100:big)
346 -m <int> ............... compression method (0=fast, 6=slowest)
347 -kmin <int> ............ min distance between key frames
348 -kmax <int> ............ max distance between key frames
349 -f <int> ............... filter strength (0=off..100)
350 -metadata <string> ..... comma separated list of metadata to
351 copy from the input to the output if present
352 Valid values: all, none, icc, xmp (default)
353 -mt .................... use multi-threading if available
354
355 -version ............... print version number and exit
356 -v ..................... verbose
357 -quiet ................. don't print anything
358
359Building:
360---------
361With the libgif development files installed, gif2webp can be built using
362makefile.unix:
363$ make -f makefile.unix examples/gif2webp
364
365or using autoconf:
366$ ./configure --enable-everything
367$ make
368
369Encoding API:
370=============
371
372The main encoding functions are available in the header src/webp/encode.h
373The ready-to-use ones are:
374size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride,
375 float quality_factor, uint8_t** output);
376size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride,
377 float quality_factor, uint8_t** output);
378size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride,
379 float quality_factor, uint8_t** output);
380size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride,
381 float quality_factor, uint8_t** output);
382
383They will convert raw RGB samples to a WebP data. The only control supplied
384is the quality factor.
385
386There are some variants for using the lossless format:
387
388size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height,
389 int stride, uint8_t** output);
390size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height,
391 int stride, uint8_t** output);
392size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height,
393 int stride, uint8_t** output);
394size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height,
395 int stride, uint8_t** output);
396
397Of course in this case, no quality factor is needed since the compression
398occurs without loss of the input values, at the expense of larger output sizes.
399
400Advanced encoding API:
401----------------------
402
403A more advanced API is based on the WebPConfig and WebPPicture structures.
404
405WebPConfig contains the encoding settings and is not tied to a particular
406picture.
407WebPPicture contains input data, on which some WebPConfig will be used for
408compression.
409The encoding flow looks like:
410
411-------------------------------------- BEGIN PSEUDO EXAMPLE
412
413#include <webp/encode.h>
414
415 // Setup a config, starting form a preset and tuning some additional
416 // parameters
417 WebPConfig config;
418 if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor))
419 return 0; // version error
420 }
421 // ... additional tuning
422 config.sns_strength = 90;
423 config.filter_sharpness = 6;
424 config_error = WebPValidateConfig(&config); // not mandatory, but useful
425
426 // Setup the input data
427 WebPPicture pic;
428 if (!WebPPictureInit(&pic)) {
429 return 0; // version error
430 }
431 pic.width = width;
432 pic.height = height;
433 // allocated picture of dimension width x height
434 if (!WebPPictureAllocate(&pic)) {
435 return 0; // memory error
436 }
437 // at this point, 'pic' has been initialized as a container,
438 // and can receive the Y/U/V samples.
439 // Alternatively, one could use ready-made import functions like
440 // WebPPictureImportRGB(), which will take care of memory allocation.
441 // In any case, past this point, one will have to call
442 // WebPPictureFree(&pic) to reclaim memory.
443
444 // Set up a byte-output write method. WebPMemoryWriter, for instance.
445 WebPMemoryWriter wrt;
446 WebPMemoryWriterInit(&wrt); // initialize 'wrt'
447
448 pic.writer = MyFileWriter;
449 pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work;
450
451 // Compress!
452 int ok = WebPEncode(&config, &pic); // ok = 0 => error occurred!
453 WebPPictureFree(&pic); // must be called independently of the 'ok' result.
454
455 // output data should have been handled by the writer at that point.
456 // -> compressed data is the memory buffer described by wrt.mem / wrt.size
457
458 // deallocate the memory used by compressed data
459 WebPMemoryWriterClear(&wrt);
460
461-------------------------------------- END PSEUDO EXAMPLE
462
463Decoding API:
464=============
465
466This is mainly just one function to call:
467
468#include "webp/decode.h"
469uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size,
470 int* width, int* height);
471
472Please have a look at the file src/webp/decode.h for the details.
473There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with
474decoding to raw Y'CbCr samples. One can also decode the image directly into a
475pre-allocated buffer.
476
477To detect a WebP file and gather the picture's dimensions, the function:
478 int WebPGetInfo(const uint8_t* data, size_t data_size,
479 int* width, int* height);
480is supplied. No decoding is involved when using it.
481
482Incremental decoding API:
483=========================
484
485In the case when data is being progressively transmitted, pictures can still
486be incrementally decoded using a slightly more complicated API. Decoder state
487is stored into an instance of the WebPIDecoder object. This object can be
488created with the purpose of decoding either RGB or Y'CbCr samples.
489For instance:
490
491 WebPDecBuffer buffer;
492 WebPInitDecBuffer(&buffer);
493 buffer.colorspace = MODE_BGR;
494 ...
495 WebPIDecoder* idec = WebPINewDecoder(&buffer);
496
497As data is made progressively available, this incremental-decoder object
498can be used to decode the picture further. There are two (mutually exclusive)
499ways to pass freshly arrived data:
500
501either by appending the fresh bytes:
502
503 WebPIAppend(idec, fresh_data, size_of_fresh_data);
504
505or by just mentioning the new size of the transmitted data:
506
507 WebPIUpdate(idec, buffer, size_of_transmitted_buffer);
508
509Note that 'buffer' can be modified between each call to WebPIUpdate, in
510particular when the buffer is resized to accommodate larger data.
511
512These functions will return the decoding status: either VP8_STATUS_SUSPENDED if
513decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other
514status is an error condition.
515
516The 'idec' object must always be released (even upon an error condition) by
517calling: WebPDelete(idec).
518
519To retrieve partially decoded picture samples, one must use the corresponding
520method: WebPIDecGetRGB or WebPIDecGetYUVA.
521It will return the last displayable pixel row.
522
523Lastly, note that decoding can also be performed into a pre-allocated pixel
524buffer. This buffer must be passed when creating a WebPIDecoder, calling
525WebPINewRGB() or WebPINewYUVA().
526
527Please have a look at the src/webp/decode.h header for further details.
528
529Advanced Decoding API:
530======================
531
532WebP decoding supports an advanced API which provides on-the-fly cropping and
533rescaling, something of great usefulness on memory-constrained environments like
534mobile phones. Basically, the memory usage will scale with the output's size,
535not the input's, when one only needs a quick preview or a zoomed in portion of
536an otherwise too-large picture. Some CPU can be saved too, incidentally.
537
538-------------------------------------- BEGIN PSEUDO EXAMPLE
539 // A) Init a configuration object
540 WebPDecoderConfig config;
541 CHECK(WebPInitDecoderConfig(&config));
542
543 // B) optional: retrieve the bitstream's features.
544 CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);
545
546 // C) Adjust 'config' options, if needed
547 config.options.no_fancy_upsampling = 1;
548 config.options.use_scaling = 1;
549 config.options.scaled_width = scaledWidth();
550 config.options.scaled_height = scaledHeight();
551 // etc.
552
553 // D) Specify 'config' output options for specifying output colorspace.
554 // Optionally the external image decode buffer can also be specified.
555 config.output.colorspace = MODE_BGRA;
556 // Optionally, the config.output can be pointed to an external buffer as
557 // well for decoding the image. This externally supplied memory buffer
558 // should be big enough to store the decoded picture.
559 config.output.u.RGBA.rgba = (uint8_t*) memory_buffer;
560 config.output.u.RGBA.stride = scanline_stride;
561 config.output.u.RGBA.size = total_size_of_the_memory_buffer;
562 config.output.is_external_memory = 1;
563
564 // E) Decode the WebP image. There are two variants w.r.t decoding image.
565 // The first one (E.1) decodes the full image and the second one (E.2) is
566 // used to incrementally decode the image using small input buffers.
567 // Any one of these steps can be used to decode the WebP image.
568
569 // E.1) Decode full image.
570 CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);
571
572 // E.2) Decode image incrementally.
573 WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config);
574 CHECK(idec != NULL);
575 while (bytes_remaining > 0) {
576 VP8StatusCode status = WebPIAppend(idec, input, bytes_read);
577 if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) {
578 bytes_remaining -= bytes_read;
579 } else {
580 break;
581 }
582 }
583 WebPIDelete(idec);
584
585 // F) Decoded image is now in config.output (and config.output.u.RGBA).
586 // It can be saved, displayed or otherwise processed.
587
588 // G) Reclaim memory allocated in config's object. It's safe to call
589 // this function even if the memory is external and wasn't allocated
590 // by WebPDecode().
591 WebPFreeDecBuffer(&config.output);
592
593-------------------------------------- END PSEUDO EXAMPLE
594
595Bugs:
596=====
597
598Please report all bugs to our issue tracker:
599 http://code.google.com/p/webp/issues
600Patches welcome! See this page to get started:
601 http://www.webmproject.org/code/contribute/submitting-patches/
602
603Discuss:
604========
605
606Email: webp-discuss@webmproject.org
607Web: http://groups.google.com/a/webmproject.org/group/webp-discuss
608