Getting started with FIF2

The FIF2 reference implementation consists of a library, libfif, and a command-line tool, fif. This page shows how to build them and how to convert your first picture.

What you get

fif (fif.exe on Windows): A command-line tool. It converts pictures to FIF2 and back, shows what a FIF2 file contains, and extracts its preview image.
libfif: A C library with the encoder and decoder, for programs that want to read or write FIF2 themselves. It has a plain C interface and can be used from C, C++ and any language that can call C functions.

The tool reads PNG, JPEG and PNM pictures and writes PNG, JPEG and PNM. PNG and JPEG support requires the libraries libpng and libjpeg-turbo at build time. Without them, the tool still works, but only with PNM files.

Building

You need a C++20 compiler. The code is written for clang++; g++ works as well on Linux and macOS. Microsoft's own compiler is not supported.

Linux and macOS

# Ubuntu: compiler and optional image libraries
sudo apt install clang make pkg-config libpng-dev libjpeg-turbo8-dev

# Fedora
sudo dnf install clang make pkgconf-pkg-config libpng-devel libjpeg-turbo-devel

# macOS with Homebrew; jpeg-turbo must be made visible to pkg-config
brew install pkg-config libpng jpeg-turbo
export PKG_CONFIG_PATH="$(brew --prefix jpeg-turbo)/lib/pkgconfig:$PKG_CONFIG_PATH"

# in the source directory
make

The result is the tool ./fif and the library ./libfif.a.

Windows

Install the “C++ Clang tools for Windows” component of Visual Studio or of the Visual Studio Build Tools.
For PNG and JPEG support, install the image libraries with vcpkg:
```
vcpkg install libpng libjpeg-turbo --triplet x64-windows-static
```
Run build.bat in the source directory.

The result is fif.exe and libfif.lib. The build prints which image formats it found, for example image i/o png, jpeg, pnm.

Your first FIF2 file

fif encode photo.jpg photo.fif2
fif decode photo.fif2 photo-decoded.png

The first command compresses photo.jpg with the default settings. The second command reconstructs the picture and saves it as PNG. The format of the output follows the file extension: .png, .jpg, .ppm or .pgm.

To see what the file contains:

fif info photo.fif2

Choosing the quality

Two settings control the result:

-q, quality, 0 to 100 (default 75): Higher values give better pictures and larger files. Values between 50 and 85 suit most photographs. FIF2 is at its strongest at low values, where other formats show heavy artefacts.
-e, effort, 0 to 9 (default 5): How hard the encoder searches for matching blocks. Higher values take longer and usually give slightly smaller files. Effort 2 is often almost as good as 5 and much faster.

fif encode photo.jpg small.fif2 -q 40
fif encode photo.jpg best.fif2  -q 90 -e 7

If you need a particular file size or quality instead, let the encoder find the setting:

fif encode photo.jpg web.fif2 --target-bpp 0.5     # 0.5 bits per pixel
fif encode photo.jpg web.fif2 --target-psnr 32     # 32 dB

Decoding at a different size

A FIF2 file can be decoded larger or smaller than it was coded:

fif decode photo.fif2 big.png --scale 2            # twice the size
fif decode photo.fif2 hd.png --size 1920x1080      # fill this box
fif decode photo.fif2 preview.jpg --width 400      # 400 pixels wide

The next page, Using the fif tool, explains these and all other options.