Convert a PPM Image to an Atari Neochrome File with ppmtoneo

You will finish with an Atari Neochrome .neo file produced from a PPM image, plus a check that can read the result back. 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 does not need elevated privileges. Work in a directory where you can write the output.

1. Check the input before converting

Inspect the image first. Replace the example path with the PPM you actually intend to convert:

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

The second command is part of Netpbm and reports the 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 that a file named .ppm is valid merely because its extension looks right.

ppmtoneo accepts an image no larger than 320 by 200 pixels. Smaller images are accepted by the installed program and are placed into the fixed-size Neochrome output. An input wider than 320 pixels or taller than 200 pixels fails with a diagnostic such as image is larger than 320x200 - sorry.

Checkpoint: continue only when pamfile identifies a readable PPM and both dimensions are at most 320 by 200.

2. Convert the image and capture binary standard output

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

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

The colour-count line varies with the input. It is diagnostic output, not the file itself. The Neochrome bytes go to standard output, which is why the redirection is essential. Without it, binary data is sent to your terminal and the intended file is not created.

For an image supplied by another Netpbm command, the filename can be omitted and standard input is used:

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

This example uses ppmmake only to create a simple test image. It is not a substitute for preparing a useful Atari graphic.

Checkpoint: if the command exits successfully, verify that the output is not empty:

$ 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 as a promise about 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 check 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. The useful parts are the Atari DEGAS/Neochrome identification and the 320 by 200 geometry. The output 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 the input values to the range it needs.

Do not confuse a successful conversion with faithful colour reproduction. The source PPM may contain more colours than the target format can represent. Inspect the result on the target software or hardware when exact appearance matters.

4. Read the file back as a verification pass

neotoppm is the companion Netpbm converter. Use it to prove that the file can be parsed and that 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 shown above are expected from this installed toolchain. The round trip does not restore colours that were discarded during conversion, and it does not prove that a particular emulator or Atari program accepts every file. It does establish that 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. If you need to replace an older file, compare or test the new file first, then move it over the old one in a separate, deliberate step. A move such as mv ./output.neo ./archive.neo changes the filesystem and can overwrite an existing destination, so do not run it until you have confirmed both paths.

5. Handle common failures without guessing

• No output file appears: check that you used > ./output.neo. The converter writes the binary result to standard output.
• Binary noise appears in the terminal: stop the command if it is still running and repeat it with redirection. Do not paste terminal output into another file.
• The 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 is reversible.
• The output looks wrong: inspect the source dimensions and colour range, then use neotoppm for a round trip. The target has a limited 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 copy options from a different converter.

If you need to discard a failed test, remove only the exact generated file after checking its path, for example rm -- ./output.neo. That is destructive and has no recovery once the file is gone, so prefer a new output name while testing. No service restart, configuration edit or sudo command is part of this workflow.