The imagelib library
The imagelib library implements image formats such as PNG, BMP, and PPM in OCaml, relying on only one external dependency: 'decompress'.
Unix-dependent functionality such as reading or writing to files in the filesystem are packaged in the
imagelib.unix findlib module inside this OPAM package; to use it you need to include
imagelib.unix specifically in your project's dependencies, for instance
(libraries imagelib.unix) in your Dune file.
Supported image formats:
PNG (full implementation of RFC 2083),
PPM, PGM, PBM, ... (fully supported),
JPG (only image size natively),
GIF (only image size natively),
There is an experimental native implementation available in the pure
XCF (only image size natively),
Utility functions for handling unimplemented formats are available in the 'imagelib.unix' findlib package and handle conversion from unsupported image formats like JPG, GIF, XCF by converting them to PNG using the
convertcommandline utility from
As imagelib only requires
decompress, it is suitable (excluding operations requiring the
js_of_ocaml, or inclusion in MirageOS unikernels.
List of dependencies:
OCaml (at least 4.03.0)
dune (at least 1.2.0)
decompress (version 0.8.1)
GNU Make (build)
convert) for handling some formats.
Crowbar, Alcotest, afl-persistent (for the test suite)
Imagelib is available on
opam install imagelib). It can also be installed from source as follows.
make make install
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.exe if you use opam to install the library, and otherwise it will be in
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
This section is primarily of use for developers of the library.
crowbar tests, it is enough to run
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
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