Using the fif tool

The command-line tool fif converts pictures to FIF2 and back and inspects FIF2 files. This page first shows common tasks and how to find the best quality for the size, then lists every command and option and explains the error messages.

Every command follows the same pattern: first the command, then the input and output files, then the options.

fif <command> <input> [<output>] [options]

fif help lists the commands with examples; fif help decode (or fif decode --help) lists all options of one command, grouped by what they are for.

Options must come after the file names. fif encode in.png out.fif -q 80 works; fif encode -q 80 in.png out.fif does not.

Common tasks

Compress a photograph

fif encode holiday.jpg holiday.fif -q 70

The tool prints the size of the result and the bits per pixel. Quality 70 gives a good picture for most photographs; lower values give smaller files.

Make a small file for the web

fif encode holiday.jpg web.fif --max-dim 1600 -q 50 --thumbnail 200

--max-dim 1600 reduces the picture so that its longer edge is at most 1600 pixels before it is encoded. --thumbnail 200 adds a JPEG preview of 200 pixels, which a viewer can show before it has decoded the picture. The original file name, the original size and the reduction factor are recorded in the file.

Add author and copyright

fif encode holiday.jpg holiday.fif --meta author="Ada Lovelace" --text copyright="(c) 2026 Ada Lovelace"

The camera's own data comes along by itself: from the EXIF block of a JPEG or PNG the tool takes the camera, lens, date taken, exposure, author, copyright and description, and it turns the picture upright if the camera stored it sideways. The GPS position is never taken over. A --meta or --text value with the same name replaces the camera's; --no-exif ignores the EXIF data altogether.

Each --meta and --text option stores one named value. You can use them as often as you like. The values may contain any characters, including accents and non-Latin scripts.

Decode at a larger size

fif decode holiday.fif poster.png --scale 3

The decoder carries out the fractal reconstruction at three times the coded resolution. This gives sharper edges than enlarging the normal decode in an image editor. Factors of 2 to 3 give the best results; up to 16 is possible.

Decode to an exact size

fif decode holiday.fif wallpaper.png --size 2560x1440

The picture fills the box completely. If its shape differs from the box, the excess is cut off equally on both sides; the picture is never stretched. To keep the whole picture, give only one dimension:

fif decode holiday.fif wide.png --width 2560

Decode only part of a picture

fif info holiday.fif --tiles                              # the tile map
fif decode holiday.fif detail.png --region 400x300+600+200
fif decode holiday.fif detail.png --region 400x300+600+200 --scale 4
fif decode holiday.fif some.png --tiles 0,5-6

A FIF2 picture is made of tiles that decode independently, so a part of it costs only the tiles it touches. --region takes the rectangle in the usual geometry notation: widthxheight+left+top, in the pixels of the picture as fif info reports them. The result is exactly the same as cutting the rectangle out of a full decode, only much faster: on a 3840 × 2160 picture, a 512 × 512 region decoded four times larger took 0.09 s instead of 0.62 s for the whole picture. --region combines with --scale, --width, --height and --size, which then refer to the region.

--tiles picks tiles by number, with ranges as in a print dialog. The picture keeps its full size; tiles that are not listed stay grey. fif info … --tiles shows where each tile is and which bytes of the file it needs.

Get a quick preview

fif thumbnail holiday.fif preview.jpg        # the largest stored preview, if there is one
fif thumbnail holiday.fif small.jpg 0        # preview number 0
fif decode holiday.fif preview.png --scale 1/4    # fast reduced decode

A reduced decode with 1/2, 1/4 or 1/8 is much faster than a full decode, because the reconstruction itself runs at the smaller size. The result is an approximation: 1/2 is almost indistinguishable from a properly reduced picture, 1/8 is good enough for a preview only.

Look inside a file

fif info holiday.fif

Example output:

file        holiday.fif
format      FIF2 v3.0
dimensions  1000 x 560, 3 channel(s)
size        102.3 KiB  (1.4965 bpp)
source      holiday.jpg, 1749 x 980, reduced by 1.749 before encoding
blocks      4..32, tile 256
chroma      4:2:0, shared
base layer  first 52.9 KiB of 102.3 KiB (51.7%) decodes at DC resolution
tiles       12 (4 x 3), independently decodable
sections    chunks 488 B, thumbnail 16.6 KiB, fic 85.2 KiB, raw 0 B
checksums   fic ok, chunks ok, thumbnail ok
thumbnails  1
  [0] 333 x 186 JPEG, 16.6 KiB
chunks      10
  ENCO  encoder        "libfif v3.2"
  ENCO  source_name    "holiday.jpg"
  ENCO  credits        "libfif v3.2 - (c) 2026 Oskar Behzadpour
                        FIF2 format v3.0 by Rezar Behzad
                        More info: www.FractalImageCompression.com"
  COLR  transfer       "sRGB"
  COLR  primaries      "sRGB"
  META  author         "Ada Lovelace"
  TEXT  copyright      "(c) 2026 Ada Lovelace"
  ENCO  quality        70
  ENCO  effort         5
  DECO  deblock        60

The line base layer states how much of the file is needed for a complete, coarse picture. The line checksums shows whether the file is intact.

Compare two pictures

fif compare original.png decoded.png

Prints three common quality measures: PSNR in decibels, SSIM and MS-SSIM. For all three, higher means closer to the original.

Finding the best quality for the size

No single setting is best for every picture, but five steps find the best one for yours in a few minutes. The numbers below come from a landscape photograph reduced to 1920×1080. Other pictures give other numbers, but the curve has the same shape.

1. Work at the size the picture will be shown

fif encode photo.jpg photo.fif --max-dim 1920

The number of pixels matters more than any quality setting. Half the width and height means a quarter of the pixels and roughly a third of the file size. Use the same --max-dim in all the following steps, so that what you measure is what you will encode.

2. Measure the quality curve

fif bench encodes and decodes in one step, writes no file and reports the size and the quality. Run it for several quality values:

for q in 20 35 50 65 75 85 95; do
  echo "q=$q"; fif bench photo.jpg --max-dim 1920 -q $q -e 2 --no-progress | grep -E 'size|psnr|ms-ssim'
done

Look for the knee: the point after which more bytes buy hardly any quality. From 35 to 50, 75 KiB more bring 1.5 dB. From 75 to 95, 172 KiB more bring only 0.15 dB. A useful rule: go higher only while 10% more size still brings at least 0.1 dB. Here the knee lies between 50 and 65.

The quality of a fractal code levels off at the top, so above about 75 you mainly buy bytes. The numbers are a guide; look at the two candidates at the knee before you decide. MS-SSIM follows the eye better than PSNR, and values above 0.98 are hard to tell from the original at normal viewing size.

fif encode photo.jpg a.fif --max-dim 1920 -q 50 && fif decode a.fif a.png
fif encode photo.jpg b.fif --max-dim 1920 -q 65 && fif decode b.fif b.png

3. Choose the effort

The effort changes the time much more than the size. At quality 65:

For photographs -e 2 is almost always right: the same result as the default, five times faster. Higher effort pays off for textures, patterns and aerial pictures; compare -e 2 and -e 7 with fif bench to find out.

4. Choose the colour resolution

5. Apply it to one picture or to many

• Fixed quality (-q 55): the same look for every picture; the size depends on the content. Right for most batches.
• Fixed size (--target-bpp 1.0): the file is as large as asked; the quality varies. Right when storage or bandwidth is fixed.
• Fixed minimum quality (--target-psnr 31): the smallest file that reaches it.

A target tries seven qualities, so use -e 2 to keep it fast. The tool tells you which quality it chose, and warns you if the target cannot be reached:

$ fif encode photo.jpg photo.fif --max-dim 1920 --target-psnr 31 -e 2
photo.fif: 1920x1080 -> 198.6 KiB (0.7847 bpp) in 0.933 s
target      31 dB -> quality 54, 31.00 dB

$ fif encode photo.jpg photo.fif --max-dim 1920 --target-psnr 34 -e 2
photo.fif: 1920x1080 -> 583.6 KiB (2.3055 bpp) in 1.121 s
target      34 dB -> quality 100, 31.92 dB
fif: warning: 34 dB is not reachable for this image; the best result has 31.92 dB

The warning is useful in itself: this picture levels off just below 32 dB, and anything above about 31 dB costs a lot of bytes for little gain.

In short: reduce to the display size with --max-dim; measure with fif bench and pick the knee, usually between 50 and 70; use -e 2 for photographs; use --subsampling 444 for graphics and 400 for greyscale; fix -q for batches, or use --target-bpp for a fixed budget.

Command reference

Encode options

Further options for experts adjust the block sizes (--min-block, --max-block, powers of two from 2 to 256, --tile), the search (--local-radius, --kd-candidates, --domain-shift) and the planar mode (--planar). fif help encode lists them. The defaults are chosen from measurements; changing them rarely helps.

Decode options

When something goes wrong

Every message has the same form: one line that says what went wrong, and indented hints that say what to do about it.

fif: error: cannot open 'holiday.png': no such file
  hint: the file is looked for in the current directory; give the full path if it is elsewhere

fif: warning: means the command ran, but perhaps not as you expected. fif: error: means it stopped. All messages go to the error output, so the normal output stays clean for scripts.

Exit codes

Things to know

• Banner. Every run starts with three lines naming the tool, the library, the format and their authors. They go to the error output, like all messages, so the normal output of fif info and fif debug stays clean for scripts.
• Old files. Files written by earlier development versions of FIF2 (container version 2) cannot be read by the current tool. It says so and asks you to encode the picture again from the original.
• Transparency. FIF2 has no transparency. The alpha channel of a PNG is discarded when it is read.
• Colour depth. Pictures with 16 bits per channel are reduced to 8 bits.
• Truncated files. A file that was cut short still decodes, at lower quality. fif info shows truncated in that case.