Turn Netpbm Images into Octave Matrices with pamtooctaveimg

You will convert a PNM or PAM image into GNU Octave's indexed image format, load the result as an image and colormap, and verify the output without changing the source file. Allow about 15 minutes for a first run. You need the netpbm package, a readable image, and GNU Octave if you want to display or manipulate the result.

The examples below use Netpbm 11.5.2, supplied here by Debian package netpbm version 2:11.05.02-1.1build1. The installed manual page is older than the binary, so treat the command output and checks here as the useful reference for this machine.

1. Check the installed command

Confirm that the command is on your path and ask the linked Netpbm library for its version. This is a read-only check and does not require elevated privileges:

$ command -v pamtooctaveimg
/usr/bin/pamtooctaveimg
$ pamtooctaveimg -version
pamtooctaveimg: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pamtooctaveimg: Built from source dated 2024-03-31 09:09:47
...

The command has no pamtooctaveimg-specific conversion switches. It accepts an optional input filename and also understands options common to libnetpbm programs, including -version, -quiet and -plain where applicable. Do not assume that a familiar option from another Netpbm program belongs here.

2. Convert an image to an Octave file

Pass a PNM or PAM filename and redirect standard output to a new file. Replace the placeholder path with your own readable image:

$ pamtooctaveimg /path/to/input.ppm > /path/to/output.img

The output is ASCII Octave data, not a raster image that an ordinary image viewer will open. A small two-colour PPM produces content shaped like this:

# Created from '/path/to/input.ppm' by pamtooctave
# name: img
# type: matrix
# rows: 1
# columns: 2
 1 2
# name: map
# type: matrix
# rows: 2
# columns: 3
 1.0000000000 0.0000000000 0.0000000000
 0.0000000000 1.0000000000 0.0000000000

The img matrix contains palette indexes. The map matrix contains one red, green and blue triplet per row, with channel values from 0 to 1. In the example, the pixels select the first and second rows of the map.

Messages about the palette go to standard error. For example, the installed program reports a palette count while the Octave data continues to standard output. That separation makes redirection safe for scripts.

3. Read from standard input when a pipeline is clearer

The filename is optional. A filename of -, or no filename at all, tells the program to read the first image from standard input:

$ pamtooctaveimg - < /path/to/input.pam > /path/to/output.img
$ test -s /path/to/output.img && echo 'Octave file written'
Octave file written

This is useful when another Netpbm command produces the input:

$ pnmtoppm /path/to/source.pbm | pamtooctaveimg - > /path/to/output.img

Only the first image in an input stream is converted. If a file contains multiple Netpbm images, split or select the intended image before this step. A successful exit status means the conversion completed; it does not prove that you selected the image you meant.

4. Load and inspect the result in Octave

Start Octave in the directory containing the output, then load both variables:

$ octave
octave:1> [img, map] = loadimage("output.img");
octave:2> size(img)
ans =

   1   2
octave:3> size(map)
ans =

   2   3

For a normal image, img has one row per image row and one column per image column. map has three columns because each palette entry stores red, green and blue levels. The exact matrix dimensions depend on the source image and its colours.

Display the indexed image with its matching palette:

imshow(img, map);

Do not call imshow(img) and then assume Octave will recover the intended colours. The palette is part of this file format, so pass map with img.

5. Convert indexed data back to RGB values

Use ind2rgb when later Octave code needs separate red, green and blue matrices rather than palette indexes:

[r, g, b] = ind2rgb(img, map);
size(r)
size(g)
size(b)

Each returned matrix has the same image dimensions as img. Keep the original img and map if you want to preserve the indexed representation. Converting to three matrices can be convenient for calculations, but it is not required merely to display the image.

6. Protect existing output and diagnose failures

$ pamtooctaveimg /path/to/input.ppm > /path/to/output.img.new
$ test -s /path/to/output.img.new
$ sed -n '1,12p' /path/to/output.img.new
$ mv /path/to/output.img.new /path/to/output.img

The mv command changes the destination, so run it only after the inspection succeeds. If conversion fails, leave the old output in place and remove the incomplete .new file after checking its contents. Do not delete the source image as part of cleanup.

A missing-file error is normally a path or permission problem:

$ test -r /path/to/input.ppm && echo readable
readable
$ pamtooctaveimg /path/to/input.ppm > /path/to/output.img

If the image is valid but its colours look wrong, check that the consumer loaded both variables and that the source was not a multi-image stream. Use -quiet when a clean standard error stream matters. There is no reason to run this converter as root unless the input or output location is itself restricted, and changing permissions is usually safer than granting a broad privileged shell.