Convert a PPM to an Atari Neochrome File

Getting a modern image onto real (or emulated) Atari ST hardware means shrinking it into Neochrome's fixed format, and ppmtoneo does that conversion. This guide uses Netpbm 11.5.2 from Debian package netpbm 2:11.05.02-1.1build1, installed on the machine used for these examples.

Allow about ten minutes. You need an existing PPM file and the Netpbm utilities ppmtoneo, file and, for the round-trip check, neotoppm. The conversion needs no elevated privileges: just work in a directory where you can write the output.

1. Check the input before converting

Inspect the image first. Swap in the PPM you actually intend to convert:

$ file ./input.ppm
$ pamfile ./input.ppm

The second command is part of Netpbm and reports format, dimensions and maximum channel value. A PPM is a colour pixmap, normally identified as P3 for plain text or P6 for raw data. Do not assume a file named .ppm is valid just because the extension looks right.

ppmtoneo accepts an image no larger than 320 by 200 pixels; smaller ones get placed into the fixed-size Neochrome output. Anything wider than 320 pixels or taller than 200 fails with a diagnostic such as image is larger than 320x200 - sorry.

2. Convert the image and capture binary standard output

The command takes one optional positional argument, the input PPM. The converted file goes to standard output, so redirect it to a deliberately named .neo file:

$ ppmtoneo ./input.ppm > ./output.neo
ppmtoneo: computing colormap...
ppmtoneo: 12 colors found

That colour-count line varies with the input; it is diagnostic output, not the file itself. The Neochrome bytes go to standard output, which is exactly why the redirection matters: skip it and binary data lands on your terminal while no file gets created.

For an image piped in from another Netpbm command, drop the filename and standard input takes over:

$ ppmmake red 320 200 | ppmtoneo > ./red.neo
ppmtoneo: computing colormap...
ppmtoneo: 1 colors found

That example uses ppmmake only to build a simple test image; it is not a substitute for preparing a real Atari graphic.

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ wc -c ./output.neo
32128 ./output.neo

The installed converter produced 32,128 bytes for a normal 320 by 200 output in testing. Treat that as a useful sanity check, not a promise for every build or malformed input. If the command fails, do not use a partial output file: write to a new temporary name, inspect the diagnostic, and only rename a verified result.

3. Check the Neochrome header and dimensions

Use file to see what the output looks like to the system:

$ file ./output.neo
output.neo: Atari DEGAS Elite bitmap 320 x 200 x 16, color palette ...

The exact palette text depends on the image and the installed file database. What matters is the Atari DEGAS/Neochrome identification and the 320 by 200 geometry. The format has a 16-colour palette, so a source image with more colours must be reduced; in normal operation ppmtoneo computes a colour map and may report that it is rescaling input values to the range it needs.

Do not confuse a successful conversion with faithful colour reproduction. Your source PPM may hold more colours than the target format can represent, so inspect the result on the target software or hardware whenever exact appearance matters.

4. Read the file back as a verification pass

neotoppm is the companion converter. Use it to prove the file parses and the round trip has the expected geometry:

$ neotoppm ./output.neo > ./roundtrip.ppm
$ pamfile ./roundtrip.ppm
./roundtrip.ppm: PPM raw, 320 by 200  maxval 7

The raw PPM output and maximum value above are what this installed toolchain produces. The round trip does not restore colours discarded during conversion, and it does not prove any particular emulator or Atari program will accept the file. It does prove neotoppm can parse the bytes and recover the fixed image size.

Keep output.neo until you have checked the round trip or viewed the file where it will be used. To replace an older file, compare or test the new one first, then move it over the old one as a separate, deliberate step: a move such as mv ./output.neo ./archive.neo changes the filesystem and can overwrite an existing destination, so confirm both paths before you run it.

Common traps

• No output file appears. Check you actually used > ./output.neo: the converter writes its binary result to standard output.
• Binary noise fills the terminal. Stop the command if it is still running and repeat it with redirection. Do not paste terminal output into another file.
• Image is too large. Resize or crop the PPM with a separate Netpbm operation, save that as a new input, then rerun the conversion. Keep the original so the change stays reversible.
• Output looks wrong. Inspect the source dimensions and colour range, then use neotoppm for a round trip. The target has only a 16-colour palette, so quantisation can be visible.
• Unknown options fail. This program has no options specific to ppmtoneo. The installed manual says it recognises only common libnetpbm options; do not borrow options from a different converter.