Convert an Atari Neochrome NEO File to PPM with neotoppm

Found an old Atari ST .neo file and no modern viewer will touch it? neotoppm turns a Neochrome image into a PPM that every other Netpbm tool can read, and from there you can get to PNG or anything else. It writes to standard output, so the normal workflow is redirect to a file, then inspect what you got. Ten minutes if the input file is already sitting there ready.

You need Linux, a readable Neochrome file and the netpbm package. This guide uses the installed Netpbm 11.5.2 command. The neotoppm(1) manual page is dated 24 April 2001, so treat these examples as verified for this installed version rather than assuming an older or newer package behaves identically.

1. Check the installed command

Confirm which executable your shell will actually run. Ordinary, read-only, no elevated privileges needed:

$ command -v neotoppm
/usr/bin/neotoppm
$ neotoppm --version
neotoppm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...

The build-information lines can vary, but the version line should name the linked Netpbm library. Worth recording the package too, in case you ever need it for a bug report:

$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

Checkpoint: If command -v finds nothing, stop and install netpbm through your normal package-management process. A missing package is not a reason to reach for sudo on the converter itself.

2. Convert one file

Pass the input path as the only argument it takes, and redirect standard output to a new destination:

$ neotoppm /path/to/example.neo > example.ppm

neotoppm has no command-specific options of its own: it reads one Neochrome file and writes a PPM image, and the input is never edited. Any informational messages go to standard error separately, so they never end up inside your redirected image.

There is no success message to wait for, so a zero exit status is the first thing worth checking:

$ printf 'conversion status: %s\n' "$?"
conversion status: 0
$ file example.ppm
example.ppm: Netpbm image data, ... pixmap

Check the status immediately after neotoppm runs; anything else in between and you are no longer checking the command you meant to. What file reports depends on its own version, but it should name a Netpbm image, not an empty or generic data file.

3. Make the output easier to look at

For a second, independent check, ask another Netpbm reader to parse the file if one is installed. pnmfile reports the format and dimensions without touching the image itself:

$ pnmfile example.ppm
example.ppm:	PPM raw, ...

Those dimensions come straight from the NEO image; the manual defines no width or height flags, so do not invent one. If the dimensions or colours look wrong, keep the original file and go investigate the source image, or open it in a viewer that reads PPM natively.

PPM is an interchange format, not necessarily where you want to end up. Once the output passes your checks, hand it to a separate tool such as pnmtopng:

$ pnmtopng example.ppm > example.png
$ file example.png
example.png: PNG image data, ...

That conversion is pnmtopng's job, not neotoppm's. Keep the PPM around until you have checked the PNG too.

4. Use the shared Netpbm options on purpose

The program also recognises the common options every Netpbm tool shares. --quiet suppresses informational messages on standard error, useful in a script:

$ neotoppm --quiet /path/to/example.neo > example.ppm
$ test -s example.ppm && echo 'non-empty PPM written'
non-empty PPM written

--plain asks for the plain, ASCII form of PPM instead of the normal raw form:

$ neotoppm --plain /path/to/example.neo > example-plain.ppm
$ file example-plain.ppm
example-plain.ppm: Netpbm image data, ... pixmap

Plain output is usually bigger, and it earns its keep only when a downstream tool specifically needs ASCII PPM, not as some general quality setting. Both two-hyphen spellings work here; the manual also documents the one-hyphen forms if you prefer those.

5. Do not clobber an existing output file

> truncates its destination the instant the converter starts, before it has produced anything. If example.ppm already matters, write to a temporary name first and only replace the original once the conversion and checks have both succeeded:

$ neotoppm /path/to/example.neo > example.ppm.new
$ test -s example.ppm.new
$ file example.ppm.new
example.ppm.new: Netpbm image data, ... pixmap
$ mv -- example.ppm.new example.ppm

mv is the point of no return here: it replaces the old output, so do not run it until the new file is genuinely the one you want to keep. If conversion fails partway, remove the incomplete new file instead and the old output is still sitting there untouched:

$ rm -- example.ppm.new

That removal cannot be undone. Either way, the original .neo file stays untouched throughout, so it remains your recovery copy no matter which path you took.

6. Diagnose a failed conversion

If the command cannot open the input, check its path and readability without touching it:

$ ls -l -- /path/to/example.neo
$ test -r /path/to/example.neo && echo readable

A missing file, a typo in the path, and a permissions problem are three different things, all separate from a genuinely invalid image. If the input is readable but conversion still fails, capture the full error from standard error and confirm the file really is an Atari Neochrome image before digging further. Do not silence errors with --quiet while you are still trying to diagnose them.

An empty or unparseable output means discard it and rerun to a new destination. A clean process exit is useful evidence, but it is not the same as actually looking at the image: check it with file, pnmfile or a trusted viewer before you delete the source.

Done means