Send a PPM Image to an NCSA ICR Display with ppmtoicr

ppmtoicr is a relic of NCSA Telnet's inline image display protocol, and it still works if you happen to have an ICR-capable terminal on the other end. It turns a PPM into a stream of terminal control data, not a file you can open elsewhere. Allow about ten minutes if the PPM and the destination display are already sorted.

1. Check the installed command and input

This guide covers the Netpbm package installed on this machine, version 11.5.2. The installed manual page is dated 17 July 2022. You need a readable PPM file and a terminal or connection that understands the NCSA ICR protocol. Ordinary conversion work does not need sudo.

$ command -v ppmtoicr
/usr/bin/ppmtoicr
$ dpkg-query -W -f='${Version}\n' netpbm
2:11.05.02-1.1build1
$ test -r /path/to/image.ppm && echo readable
readable

The program has no useful standalone help screen: its installed command reports that you should read man ppmtoicr. Read that page when working on another Netpbm release, because option details belong to the installed version.

2. Send a PPM file to the display

With an ICR-capable destination connected to the terminal session, run the input file as the final argument:

$ ppmtoicr /path/to/image.ppm

The command writes the ICR stream to standard output. It emits diagnostic messages such as palette and picture-data progress on standard error, while the display data goes to the terminal. The program creates a window matching the input image dimensions, downloads a palette of up to 256 colours, and loads the picture.

A normal terminal that does not implement ICR may show escape sequences or other unreadable output. That is not a safe way to preview the result. Interrupting the command stops the transfer, but it does not repair a terminal left in an unusual display state; reconnect or reset the terminal through your normal, environment-specific procedure if needed.

3. Set the window name

Use -windowname when the display should show a label other than the input filename:

$ ppmtoicr -windowname=inspection /path/to/image.ppm

The name must contain printable characters and must not contain the caret character, ^. If you omit the option, the default is the input filename. When input comes from standard input, the default is untitled. In a filename-derived window name, unprintable characters and ^ are changed to full stops.

4. Expand the image on screen

Use -expand for a display-side scale factor. A value of 2 displays four screen pixels for each input pixel, because both dimensions are doubled:

$ ppmtoicr -windowname=large-preview -expand=2 /path/to/image.ppm

This option does not rewrite the PPM file and does not improve its resolution. It only asks the ICR display to show the image larger. Start with a small value on a constrained display, since the resulting window can exceed the available screen area.

5. Choose a numbered display

If the ICR environment exposes more than one screen, select the destination with -display:

$ ppmtoicr -display=1 -windowname=monitor-1 /path/to/image.ppm

The option takes the screen number used by the ICR environment. The manual does not define a universal numbering scheme or a discovery command, so use the numbering documented by the terminal or host setup rather than guessing.

6. Use standard input and capture carefully

The filename is optional. Without it, ppmtoicr reads a PPM stream from standard input:

$ pnmtoppm /path/to/source-image.png | ppmtoicr -windowname=converted

This example assumes pnmtoppm is installed and that its input format is supported by that command. The ICR output still goes to standard output, while the pipeline supplies the PPM input. If the display needs the stream saved first, redirect it explicitly:

$ ppmtoicr /path/to/image.ppm > image.icr
$ cat image.icr

Saving and replaying is slower because the program normally flushes frequently to speed up a live display. It also saves terminal control data, not a portable image file. Do not open image.icr in an editor or treat it as reversible image storage. There is no icrtoppm tool for converting the stream back to PPM.

Common traps and recovery

• Input will not open. Check the path and permissions with ls -l /path/to/image.ppm and test -r /path/to/image.ppm. Fix access or choose another readable copy; do not grant broad permissions just to make a test pass.
• Display shows nothing. Verify that the endpoint actually supports NCSA ICR and that the selected -display number is correct. A successful process exit only means the local conversion and write completed.
• Redirecting to an existing file. The shell truncates that file with > before ppmtoicr starts. Use a new destination such as image.icr.new, inspect the transfer, then rename it deliberately.
• Skip the old -rle option. Netpbm removed it from the documentation after 10.71; an option-processing bug made it ineffective anyway.