package imagelib

The imagelib library

The imagelib library implements image formats such as PNG and PPM in OCaml, relying on only one external dependency: decompress.

Supported image formats:

• PNG (full implementation of RFC 2083),

• PPM, PGM, PBM, ... (fully supported),

• BMP (mostly supported),

• JPG (only image size natively, conversion to PNG otherwise),

• GIF (only image size natively, conversion to PNG otherwise),

  • There is an experimental native implementation available in the pure ImageLib module.

• XCF (only image size natively, conversion to PNG otherwise),

• Other formats rely on convert (imagemagick).

As imagelib only requires decompress, it is suitable for compilation to javascript using js_of_ocaml (only for operations not requiring the convert binary).

Dependencies

List of dependencies:

• OCaml (at least 4.03.0)

• dune (at least 1.2.0)

• decompress (version 0.8.1)

• GNU Make (build)

Additional packages:

• ImageMagick (convert) for handling some formats.

• Crowbar, Alcotest, afl-persistent (for the test suite)

Installation

Imagelib is available on opam (run opam install imagelib). It can also be installed from source as follows.

make
make install

Imagetool

app/imagetool.ml contains an example binary that acts as a command-line interface to many of the functions in the library. It will be installed as imagetool or imagetool.exe if you use opam to install the library, and otherwise it will be in _build/default/app/imagetool.exe

usage: /home/user/ocaml/imagelib/_build/default/app/imagetool.exe [args] INPUT-FILE [OUTPUT-FILE]
Displays a picture in the terminal, or convert it (if OUTPUT-FILE is specified)
The OUTPUT-FILE is a template; any '#' will be replaced with
the frame number (useful if the image has multiple frames)
Options:
--irc | --vt100   Output to terminal using escape codes
 \--character     Fill character(s) for text-mode output
--resize          Set output dimensions. Syntax: '80x25' | '10%'
  \--gamma        Adjust/reinterpret gamma
--crop-x WIDTH    Crop final output to WIDTH pixels
--crop-y HEIGHT   Crop final output to HEIGHT pixels
--frames RANGE    Only operate on RANGE frames from a multi-frame file format
                  (like an animated GIF). The format is comma-separated with '-' separating each range
                    example: --frames 1-10,20-30,50-
                    example: --frames -200,300-400
--background      Set background color for transparency using RGB,
                  e.g. '0xFF0000' is red. Defaults to black.

Example: Displaying an animated GIF in the terminal with a pink background color:

imagetool --background 0xff00ff turtle.gif

Example: Resizing specific frames from a GIF file and exporting them to individual PNG files:

$ imagetool --resize '50%' --frames -2,3-4,6- turtle.gif small-\#.png
$ ls
small-1.png small-2.png small-3.png small-4.png small-6.png small-7.png

Fuzzing

This section is primarily of use for developers of the library.

To exectute crowbar tests, it is enough to run make slowtest.

The aflrunner.exe target can be used to fuzz test the image parsers with AFL. The parser is selected using the filename extension.

Here is an example, requiring at least one valid BMP file in a folder called sample-bmps/:

imagelib $ dune build tests/aflrunner.exe
imagelib $ afl-fuzz \
  -i sample-bmps/ \
  -o bmp-results/ \
  -f /dev/shm/my.bmp -- ./_build/default/tests/aflrunner.exe x /dev/shm/my.bmp

Once one or more crashes have been identified, you can inspect them like this:

imagelib/bmpfuzz/crashes $ export OCAMLRUNPARAM=b
imagelib/bmpfuzz/crashes $ for x in id\:*
    do echo ":: $x"
    cp "$x" x.bmp
    ../../_build/default/tests/aflrunner.exe x x.bmp
    echo "// $x"
  done

:: id:000015,sig:06,src:000110,op:havoc,rep:8
Fatal error: exception Invalid_argument("Bytes.create")
Raised by primitive operation at file "stdlib.ml", line 432, characters 10-26
Called from file "unix/imageUtil_unix.ml", line 60, characters 17-52
Re-raised at file "unix/imageUtil_unix.ml", line 68, characters 8-15
Called from file "src/imageBMP.ml", line 37, characters 10-34
Called from file "src/imageBMP.ml", line 369, characters 6-40
Called from file "src/imageBMP.ml", line 376, characters 4-53
Called from file "src/imageBMP.ml", line 556, characters 20-43
Called from file "tests/aflrunner.ml", line 13, characters 21-62
Called from file "tests/aflrunner.ml", line 21, characters 9-34
// id:000015,sig:06,src:000110,op:havoc,rep:8