| __ __ ____ ____ ____ |
| / \\/ \/ _ \/ _ )/ _ \ |
| \ / __/ _ \ __/ |
| \__\__/\____/\_____/__/ ____ ___ |
| / _/ / \ \ / _ \/ _/ |
| / \_/ / / \ \ __/ \__ |
| \____/____/\_____/_____/____/v0.1.3 |
| |
| Description: |
| ============ |
| |
| WebP codec: library to encode and decode images in WebP format. This package |
| contains the library that can be used in other programs to add WebP support, |
| as well as the command line tools 'cwebp' and 'dwebp'. |
| |
| See http://code.google.com/speed/webp |
| |
| Latest sources are available from http://www.webmproject.org/code/ |
| |
| It is released under the same license as the WebM project. |
| See http://www.webmproject.org/license/software/ or the |
| file "COPYING" file for details. An additional intellectual |
| property rights grant can be found in the file PATENTS. |
| |
| Building: |
| ========= |
| |
| Windows build: |
| -------------- |
| |
| By running: |
| |
| nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output |
| |
| the directory output\release-static\(x64|x86)\bin will contain the tools |
| cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will |
| contain the libwebp static library. |
| The target architecture (x86/x64) is detected by Makefile.vc from the Visual |
| Studio compiler (cl.exe) available in the system path. |
| |
| Unix build using makefile.unix: |
| ------------------------------- |
| |
| On platforms with GNU tools installed (gcc and make), running |
| |
| make -f makefile.unix |
| |
| will build the binaries examples/cwebp and examples/dwebp, along |
| with the static library src/libwebp.a. No system-wide installation |
| is supplied, as this is a simple alternative to the full installation |
| system based on the autoconf tools (see below). |
| Please refer the makefile.unix for additional details and customizations. |
| |
| Using autoconf tools: |
| --------------------- |
| ./autogen.sh |
| ./configure |
| make |
| make install |
| |
| should be all you need to have the following files |
| |
| /usr/local/include/webp/decode.h |
| /usr/local/include/webp/decode_vp8.h |
| /usr/local/include/webp/encode.h |
| /usr/local/include/webp/types.h |
| /usr/local/lib/libwebp.* |
| /usr/local/bin/cwebp |
| /usr/local/bin/dwebp |
| |
| installed. |
| |
| Note: The encoding and decoding libraries are compiled separately |
| (as src/dec/libwebpdecode.* and src/dec/libwebpencode.*). They |
| can be installed independently using a minor modification in the |
| corresponding Makefile.am configure files (see comments there). |
| |
| SWIG bindings: |
| -------------- |
| |
| To generate language bindings from swig/libwebp.i swig-1.3 |
| (http://www.swig.org) is required. 2.0 may work, but has not been tested. |
| |
| Currently the following functions are mapped: |
| Decode: |
| WebPGetDecoderVersion |
| WebPGetInfo |
| WebPDecodeRGB |
| WebPDecodeRGBA |
| WebPDecodeARGB |
| WebPDecodeBGR |
| WebPDecodeBGRA |
| Encode: |
| WebPGetEncoderVersion |
| WebPEncodeRGB |
| WebPEncodeRGBA |
| WebPEncodeBGR |
| WebPEncodeBGRA |
| |
| Java bindings: |
| |
| To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent) |
| is necessary for enum support. The output is intended to be a shared object / |
| DLL that can be loaded via System.loadLibrary("webp_jni"). |
| |
| Encoding tool: |
| ============== |
| |
| The examples/ directory contains tools for encoding (cwebp) and |
| decoding (dwebp) images. |
| |
| The easiest use should look like: |
| cwebp input.png -q 80 -o output.webp |
| which will convert the input PNG or JPEG file to a WebP file using a |
| quality factor of 80 on a 0->100 scale (0 being the lowest quality, |
| 100 being the best. Default value is 75). |
| |
| A longer list of options is available using the -longhelp command line flag: |
| |
| > cwebp -longhelp |
| Usage: |
| cwebp [-preset <...>] [options] in_file [-o out_file] |
| |
| If input size (-s) for an image is not specified, it is assumed to be a |
| PNG or JPEG file. |
| options: |
| -h / -help ............ short help |
| -H / -longhelp ........ long help |
| -q <float> ............. quality factor (0:small..100:big) |
| -alpha_q <int> ......... Transparency-compression quality (0..100). |
| -preset <string> ....... Preset setting, one of: |
| default, photo, picture, |
| drawing, icon, text |
| -preset must come first, as it overwrites other parameters. |
| -m <int> ............... compression method (0=fast, 6=slowest) |
| -segments <int> ........ number of segments to use (1..4) |
| -size <int> ............ Target size (in bytes) |
| -psnr <float> .......... Target PSNR (in dB. typically: 42) |
| |
| -s <int> <int> ......... Input size (width x height) for YUV |
| -sns <int> ............. Spatial Noise Shaping (0:off, 100:max) |
| -f <int> ............... filter strength (0=off..100) |
| -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp) |
| -strong ................ use strong filter instead of simple. |
| -partition_limit <int> . limit quality to fit the 512k limit on |
| the first partition (0=no degradation ... 100=full) |
| -pass <int> ............ analysis pass number (1..10) |
| -crop <x> <y> <w> <h> .. crop picture with the given rectangle |
| -resize <w> <h> ........ resize picture (after any cropping) |
| -map <int> ............. print map of extra info. |
| -print_ssim ............ prints averaged SSIM distortion. |
| -print_psnr ............ prints averaged PSNR distortion. |
| -d <file.pgm> .......... dump the compressed output (PGM file). |
| -alpha_method <int> .... Transparency-compression method (0..1) |
| -alpha_filter <string> . predictive filtering for alpha plane. |
| One of: none, fast (default) or best. |
| -alpha_cleanup ......... Clean RGB values in transparent area. |
| -noalpha ............... discard any transparency information. |
| |
| -short ................. condense printed message |
| -quiet ................. don't print anything. |
| -version ............... print version number and exit. |
| -noasm ................. disable all assembly optimizations. |
| -v ..................... verbose, e.g. print encoding/decoding times |
| -progress .............. report encoding progress |
| |
| Experimental Options: |
| -af .................... auto-adjust filter strength. |
| -pre <int> ............. pre-processing filter |
| |
| |
| The main options you might want to try in order to further tune the |
| visual quality are: |
| -preset |
| -sns |
| -f |
| -m |
| |
| Namely: |
| * 'preset' will set up a default encoding configuration targeting a |
| particular type of input. It should appear first in the list of options, |
| so that subsequent options can take effect on top of this preset. |
| Default value is 'default'. |
| * 'sns' will progressively turn on (when going from 0 to 100) some additional |
| visual optimizations (like: segmentation map re-enforcement). This option |
| will balance the bit allocation differently. It tries to take bits from the |
| "easy" parts of the picture and use them in the "difficult" ones instead. |
| Usually, raising the sns value (at fixed -q value) leads to larger files, |
| but with better quality. |
| Typical value is around '75'. |
| * 'f' option directly links to the filtering strength used by the codec's |
| in-loop processing. The higher, the smoother will highly-compressed area |
| look. This is particularly useful when aiming at very small files. |
| Typical values are around 20-30. Note that using the option -strong will |
| change the type of filtering. Use "-f 0" to turn filtering off. |
| * 'm' controls the trade-off between encoding speed and quality. Default is 4. |
| You can try -m 5 or -m 6 to explore more (time-consuming) encoding |
| possibilities. A lower value will result in faster encoding at the expense |
| of quality. |
| |
| Decoding tool: |
| ============== |
| |
| There is a decoding sample in examples/dwebp.c which will take |
| a .webp file and decode it to a PNG image file (amongst other formats). |
| This is simply to demonstrate the use of the API. You can verify the |
| file test.webp decodes to exactly the same as test_ref.ppm by using: |
| |
| cd examples |
| ./dwebp test.webp -ppm -o test.ppm |
| diff test.ppm test_ref.ppm |
| |
| The full list of options is available using -h: |
| |
| > dwebp -h |
| Usage: dwebp in_file [options] [-o out_file] |
| |
| Decodes the WebP image file to PNG format [Default] |
| Use following options to convert into alternate image formats: |
| -ppm ......... save the raw RGB samples as color PPM |
| -pgm ......... save the raw YUV samples as a grayscale PGM |
| file with IMC4 layout. |
| Other options are: |
| -version .... print version number and exit. |
| -nofancy ..... don't use the fancy YUV420 upscaler. |
| -nofilter .... disable in-loop filtering. |
| -mt .......... use multi-threading |
| -crop <x> <y> <w> <h> ... crop output with the given rectangle |
| -scale <w> <h> .......... scale the output (*after* any cropping) |
| -h ....... this help message. |
| -v ....... verbose (e.g. print encoding/decoding times) |
| -noasm ....... disable all assembly optimizations. |
| |
| Visualization tool: |
| =================== |
| |
| There's a little self-serve visualization tool called 'vwebp' under the |
| examples/ directory. It uses OpenGL to open a simple drawing window and show |
| a decoded WebP file. It's not yet integrated in the automake or makefile.unix |
| build system, but you can try to manually compile it using the recommendations |
| at the top of the source file. |
| |
| Usage: 'vwebp my_picture.webp' |
| |
| |
| Encoding API: |
| ============= |
| |
| The main encoding functions are available in the header src/webp/encode.h |
| The ready-to-use ones are: |
| size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride, |
| float quality_factor, uint8_t** output); |
| size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride, |
| float quality_factor, uint8_t** output); |
| size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride, |
| float quality_factor, uint8_t** output); |
| size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride, |
| float quality_factor, uint8_t** output); |
| |
| They will convert raw RGB samples to a WebP data. The only control supplied |
| is the quality factor. |
| |
| Advanced encoding API: |
| ---------------------- |
| |
| A more advanced API is based on the WebPConfig and WebPPicture structures. |
| |
| WebPConfig contains the encoding settings and is not tied to a particular |
| picture. |
| WebPPicture contains input data, on which some WebPConfig will be used for |
| compression. |
| The encoding flow looks like: |
| |
| -------------------------------------- BEGIN PSEUDO EXAMPLE |
| |
| #include <webp/encode.h> |
| |
| // Setup a config, starting form a preset and tuning some additional |
| // parameters |
| WebPConfig config; |
| if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor)) |
| return 0; // version error |
| } |
| // ... additional tuning |
| config.sns_strength = 90; |
| config.filter_sharpness = 6; |
| config_error = WebPValidateConfig(&config); // not mandatory, but useful |
| |
| // Setup the input data |
| WebPPicture pic; |
| if (!WebPPictureInit(&pic)) { |
| return 0; // version error |
| } |
| pic.width = width; |
| pic.height = height; |
| // allocated picture of dimension width x height |
| if (!WebPPictureAllocate(&pic)) { |
| return 0; // memory error |
| } |
| // at this point, 'pic' has been initialized as a container, |
| // and can receive the Y/U/V samples. |
| // Alternatively, one could use ready-made import functions like |
| // WebPPictureImportRGB(), which will take care of memory allocation. |
| // In any case, past this point, one will have to call |
| // WebPPictureFree(&pic) to reclaim memory. |
| |
| // Set up a byte-output write method. WebPMemoryWriter, for instance. |
| WebPMemoryWriter wrt; |
| pic.writer = MyFileWriter; |
| pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work; |
| // initialize 'wrt' here... |
| |
| // Compress! |
| int ok = WebPEncode(&config, &pic); // ok = 0 => error occurred! |
| WebPPictureFree(&pic); // must be called independently of the 'ok' result. |
| |
| // output data should have been handled by the writer at that point. |
| |
| -------------------------------------- END PSEUDO EXAMPLE |
| |
| Decoding API: |
| ============= |
| |
| This is mainly just one function to call: |
| |
| #include "webp/decode.h" |
| uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size, |
| int *width, int *height); |
| |
| Please have a look at the file src/webp/decode.h for the details. |
| There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with |
| decoding to raw Y'CbCr samples. One can also decode the image directly into a |
| pre-allocated buffer. |
| |
| To detect a WebP file and gather picture's dimensions, the function: |
| int WebPGetInfo(const uint8_t* data, size_t data_size, |
| int *width, int *height); |
| is supplied. No decoding is involved when using it. |
| |
| A lower-level API is available from the header file <webp/decode_vp8.h> |
| |
| Incremental decoding API: |
| ========================= |
| |
| In the case when data is being progressively transmitted, pictures can still |
| be incrementally decoded using a slightly more complicated API. Decoder state |
| is stored into an instance of the WebPIDecoder object. This object can be |
| created with the purpose of decoding either RGB or Y'CbCr samples. |
| For instance: |
| |
| WebPDecBuffer buffer; |
| WebPInitDecBuffer(&buffer); |
| buffer.colorspace = MODE_BGR; |
| ... |
| WebPIDecoder* idec = WebPINewDecoder(&buffer); |
| |
| As data is made progressively available, this incremental-decoder object |
| can be used to decode the picture further. There are two (mutually exclusive) |
| ways to pass freshly arrived data: |
| |
| either by appending the fresh bytes: |
| |
| WebPIAppend(idec, fresh_data, size_of_fresh_data); |
| |
| or by just mentioning the new size of the transmitted data: |
| |
| WebPIUpdate(idec, buffer, size_of_transmitted_buffer); |
| |
| Note that 'buffer' can be modified between each calls to WebPIUpdate, in |
| particular when the buffer is resized to accommodate larger data. |
| |
| These functions will return the decoding status: either VP8_STATUS_SUSPENDED if |
| decoding is not finished yet, or VP8_STATUS_OK when decoding is done. |
| Any other status is an error condition. |
| |
| The idec object must always be released (even upon an error condition) |
| by calling: WebPDelete(idec). |
| |
| To retrieve partially decoded picture samples, one must use the corresponding |
| method: WebPIDecGetRGB or WebPIDecGetYUV. |
| It will return the last displayable pixel row. |
| |
| Lastly, note that decoding can also be performed into a pre-allocated pixel |
| buffer. This buffer must be passed when creating a WebPIDecoder, calling |
| WebPINewRGB() or WebPINewYUV(). |
| |
| Please have a look at the src/webp/decode.h header for further details. |
| |
| Advanced Decoding API: |
| ====================== |
| |
| WebP decoding supports an advanced API which provides on-the-fly cropping and |
| rescaling, something of great usefulness on memory-constrained environments like |
| mobile phones. Basically, the memory usage will scale with the output's size, |
| not the input's, when one only needs a quick preview or a zoomed in portion of |
| an otherwise too-large picture. Some CPU can be saved too, incidentally. |
| |
| -------------------------------------- BEGIN PSEUDO EXAMPLE |
| // A) Init a configuration object |
| WebPDecoderConfig config; |
| CHECK(WebPInitDecoderConfig(&config)); |
| |
| // B) optional: retrieve the bitstream's features. |
| CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK); |
| |
| // C) Adjust 'config' options, if needed |
| config.options.no_fancy_upsampling = 1; |
| config.options.use_scaling = 1; |
| config.options.scaled_width = scaledWidth(); |
| config.options.scaled_height = scaledHeight(); |
| // etc. |
| |
| // D) Specify 'config' output options for specifying output colorspace. |
| // Optionally the external image decode buffer can also be specified. |
| config.output.colorspace = MODE_BGRA; |
| // Optionally, the config.output can be pointed to an external buffer as |
| // well for decoding the image. This externally supplied memory buffer |
| // should be big enough to store the decoded picture. |
| config.output.u.RGBA.rgba = (uint8_t*) memory_buffer; |
| config.output.u.RGBA.stride = scanline_stride; |
| config.output.u.RGBA.size = total_size_of_the_memory_buffer; |
| config.output.is_external_memory = 1; |
| |
| // E) Decode the WebP image. There are two variants w.r.t decoding image. |
| // The first one (E.1) decodes the full image and the second one (E.2) is |
| // used to incrementally decode the image using small input buffers. |
| // Any one of these steps can be used to decode the WebP image. |
| |
| // E.1) Decode full image. |
| CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK); |
| |
| // E.2) Decode image incrementally. |
| WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config); |
| CHECK(idec != NULL); |
| while (bytes_remaining > 0) { |
| VP8StatusCode status = WebPIAppend(idec, input, bytes_read); |
| if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) { |
| bytes_remaining -= bytes_read; |
| } else { |
| break; |
| } |
| } |
| WebPIDelete(idec); |
| |
| // F) Decoded image is now in config.output (and config.output.u.RGBA). |
| // It can be saved, displayed or otherwise processed. |
| |
| // G) Reclaim memory allocated in config's object. It's safe to call |
| // this function even if the memory is external and wasn't allocated |
| // by WebPDecode(). |
| WebPFreeDecBuffer(&config.output); |
| |
| -------------------------------------- END PSEUDO EXAMPLE |
| |
| Bugs: |
| ===== |
| |
| Please report all bugs to our issue tracker: |
| http://code.google.com/p/webp/issues |
| Patches welcome! See this page to get started: |
| http://www.webmproject.org/code/contribute/submitting-patches/ |
| |
| Discuss: |
| ======== |
| |
| Email: webp-discuss@webmproject.org |
| Web: http://groups.google.com/a/webmproject.org/group/webp-discuss |