Make PPM Colours Legal for NTSC or PAL with ppmntsc

ppmntsc checks each pixel in a PPM image and adjusts colours that fall outside the range an NTSC or PAL video system can represent. This avoids leaving a video workflow to clip those values later. The command writes the resulting PPM to standard output, so you can inspect it, save it under a new name or pass it to another Netpbm tool.

Allow about five minutes for a first conversion. You need the Netpbm package and a PPM input file. The examples use ordinary user permissions and deliberately write a new output file. No command here needs sudo.

1. Check the installed command and input

Confirm which executable will run and check that your input is a PPM file before converting it:

$ command -v ppmntsc
/usr/bin/ppmntsc
$ file source.ppm
source.ppm: Netpbm image data

The installed command on this system reports Netpbm 11.5.2 when asked for its version information. The local manual is dated 19 April 2000, while the Debian package is newer, so treat the installed binary as the authority for diagnostics and the manual for the option contract:

$ ppmntsc --version
ppmntsc: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

If command -v finds nothing, stop and install Netpbm through your normal package-management process. Do not work around a missing executable by downloading an unrelated copy into a shared directory.

2. Convert an image using the default NTSC transform

The default is NTSC. Give the input path as the final argument and redirect standard output to a new file:

$ ppmntsc source.ppm > source-ntsc.ppm

The original file is read but not changed. The output is always standard output, not a file selected by an option. This distinction matters: without the redirection, binary PPM data will be sent to your terminal. If you accidentally did that, press Ctrl-C; the source file is still untouched.

Checkpoint: confirm that the new file has a PPM header and is not empty:

$ head -n 3 source-ntsc.ppm
P6
1920 1080
255
$ test -s source-ntsc.ppm && echo "output exists"
output exists

The header values will match your image, not this example. ppmntsc handles multi-image PPM input and emits the corresponding multi-image PPM output.

3. Use PAL when that is the delivery system

For PAL output, add --pal. The input remains unchanged and the corrected image is written to standard output in the same way:

$ ppmntsc --pal source.ppm > source-pal.ppm
$ head -n 3 source-pal.ppm
P6
1920 1080
255

Do not choose PAL merely because the source was created on a PAL-region computer. Choose the transform for the video system that will receive the image. NTSC is the default when --pal is absent.

4. Count illegal pixels without producing a separate report

Add --verbose when you want a grand total of illegal pixels. Its diagnostic text is printed on standard error, leaving standard output available for the converted image:

$ ppmntsc --verbose source.ppm > source-ntsc.ppm
ppmntsc: 1 images processed.
ppmntsc: 2 pixels were above the saturation limit.
ppmntsc: 1 pixels were below the saturation limit.

The counts depend on the input. A count of zero means every pixel passed the legality test; it does not mean that the command failed to read the image. To keep diagnostics in a log while preserving the image file, use separate redirections:

$ ppmntsc --verbose source.ppm > source-ntsc.ppm 2> source-ntsc.log

Check the log with sed -n '1,20p' source-ntsc.log. Avoid using a single >& redirection here, because it would mix diagnostic text into the binary output.

5. Produce a diagnostic view instead of the normal corrected image

Three filters replace pixels that do not belong to the selected set with black. They are useful for finding where a correction would occur:

• --legalonly keeps already legal pixels and makes illegal pixels black.
• --illegalonly keeps illegal pixels uncorrected and makes already legal pixels black.
• --correctedonly keeps corrected versions of illegal pixels and makes already legal pixels black.

For example, make a review image without replacing the normal delivery file:

$ ppmntsc --illegalonly source.ppm > source-illegal.ppm
$ ppmntsc --correctedonly source.ppm > source-corrected.ppm

These are PPM images, not masks with a special format. Black can therefore mean "not in the selected category", rather than an original black pixel. Keep the original input if you need to distinguish those cases.

6. Investigate a surprising result safely

--debug prints a very large listing of illegal colours and their legal counterparts. Use it on a small test image or redirect it to a file. Do not send it to a terminal for a large photograph:

$ ppmntsc --debug source.ppm > source-ntsc.ppm 2> source-debug.log
$ sed -n '1,20p' source-debug.log

If the output is unexpectedly empty, check that you used a valid PPM file and that the shell redirection points to the intended directory. A missing input path reads standard input, so a command waiting without a prompt may simply be waiting for more PPM data. Press Ctrl-D only when you deliberately supplied the input interactively; otherwise press Ctrl-C and rerun with an explicit filename.

For a repeatable check, compare headers and let a PPM-aware viewer or downstream tool read the new file. Do not compare binary PPM files with a text editor. If you need to discard a test output, remove only the named derived file, for example rm -- source-ntsc.ppm; that cannot restore an overwritten file, which is why the examples never redirect over the source.