Convert FIASCO Images to PGM or PPM with fiascotopnm

You will finish with a repeatable way to decode a FIASCO image into a PGM or PPM file, send one image to another program, and split a video stream into numbered frames. The examples target Netpbm 11.5.2, provided by the Debian package netpbm 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a shell, a readable FIASCO file such as INPUT.wfa, and enough disk space for the decoded image or frames. The examples only read the input and create output files. They do not need sudo.

1. Check the installed command

Start with the binary and its version. This is a normal, read-only check:

$ command -v fiascotopnm
/usr/bin/fiascotopnm
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ fiascotopnm --version
fiascotopnm 1.0
fiascotopnm: Using libnetpbm from Netpbm Version: 11.5.2

Keep the installed help nearby as you work:

$ fiascotopnm --help

There is a documentation mismatch worth checking before you copy an older example. The installed help calls the fast option --fast, the frame-rate option --framerate, and the verbosity option --verbose. The local manpage also documents older spellings such as --fps. On this installation, --framerate=12 is accepted but --fps=12 is rejected. Prefer the syntax printed by the installed command.

2. Decode one image to a named file

Use --output with a basename, not a complete PGM or PPM filename. fiascotopnm adds .pgm for a black-and-white image or .ppm for a colour image:

$ fiascotopnm --output=decoded INPUT.wfa
$ ls -lh decoded.pgm decoded.ppm 2>/dev/null

Only one of those files should exist. The ls command may report an error for the other extension; that is expected. Verify the file type and dimensions with Netpbm's pamfile if it is installed:

$ pamfile decoded.pgm
decoded.pgm: PGM raw, 640 by 480 pixels

The exact type, dimensions and maximum value depend on the input. If you omit the output name, fiascotopnm uses the input filename as the basename, so INPUT.wfa normally produces INPUT.wfa.pgm or INPUT.wfa.ppm. That extra suffix is easy to miss when a later command expects a particular filename.

3. Send a single image through standard output

Use --output=- when another program should receive the PNM bytes. Redirect the bytes to a file or pipe them directly:

$ fiascotopnm --output=- INPUT.wfa > decoded.ppm
$ pamfile decoded.ppm
decoded.ppm: PPM raw, 640 by 480 pixels

The extension in this example is a promise you are making to yourself, not a conversion request. A monochrome source still produces PGM data, so inspect the result before handing it to a program that requires PPM. Do not mix diagnostic output into the redirected stream. If you need a named result with the correct extension, let fiascotopnm choose the suffix instead.

This standard-output form is for a single image. The manpage says that video streams cannot be written to standard output because they produce multiple files.

4. Decode a video stream into numbered frames

For a FIASCO video, give --output a basename. Frames are written as numbered files such as frames.00.ppm and frames.14.ppm:

$ mkdir -p decoded-frames
$ fiascotopnm --output=decoded-frames/frame VIDEO.wfa
$ find decoded-frames -maxdepth 1 -type f -name 'frame.*.ppm' -print | sort | head

Creating the directory changes state, but it is reversible. If it contains only output from this example, remove it with rmdir decoded-frames after deleting or moving the files. Before rerunning a conversion, choose a fresh directory or inspect existing names: the command can overwrite an output path, and that would be irreversible unless you have a copy.

Do not assume the frame count or padding width. The actual stream determines both. Check the result with:

$ find decoded-frames -maxdepth 1 -type f -printf '%f\n' | sort -V | tail

5. Trade quality or size for speed

On a slow machine, --fast selects 4:2:0 decoding. Chroma channels are decoded at half width and height, so quality is slightly lower. --magnify=-1 reduces the decoded image, while --double enlarges it by replacing each pixel with four identical pixels. The combination below is intended for a quick, low-quality preview:

$ fiascotopnm --fast --magnify=-1 --double INPUT.wfa > preview.ppm

Do not treat this as a lossless conversion. Keep the original FIASCO file and use ordinary decoding for an archive or any output where detail matters. The display-related options, including --panel and frame rate, are mainly useful for video playback workflows; they are not needed for a normal file conversion.

6. Troubleshoot without guessing

A missing file is usually a path or current-directory problem. Confirm both before changing permissions:

$ pwd
$ test -r INPUT.wfa && echo 'input is readable'
$ fiascotopnm --output=decoded INPUT.wfa

If the input is supplied by another command, use standard input explicitly. A lone hyphen means standard input according to the manpage:

$ producer-that-outputs-fiasco | fiascotopnm --output=decoded -

Do not run fiascotopnm with no input in an interactive terminal unless you intend to provide bytes manually: it reads standard input and may appear to hang while waiting. Use Ctrl-C to stop that waiting process. For a repeatable diagnosis, capture the installed help and version, then test with a known-good FIASCO file.

Configuration can also affect the result. fiascotopnm reads /etc/system.fiascorc and $HOME/.fiascorc before command-line options, then applies a file supplied with --config=FILE. Do not edit either global or personal file just to make one conversion work. First use explicit command-line options, and inspect a supplied configuration file before using it. The FIASCO_DATA and FIASCO_IMAGES environment variables can change where input data is searched for and where relative output is saved.