Convert Zeiss Confocal Files to PGM or PPM with zeisstopnm

You will convert a readable Zeiss confocal file into a PNM image without changing the source file. zeisstopnm writes the image to standard output, so the practical workflow is to redirect that output to a new file and then inspect the result.

Allow about ten minutes if the input file is ready. You need a shell, the netpbm package, and a Zeiss confocal file that the installed program recognises. These examples use Netpbm 11.5.2 from Ubuntu package version 2:11.05.02-1.1build1. The manual page is dated 15 June 1993, so treat the installed command as the authority for this machine.

1. Check the installed command

Confirm that the shell will run the expected binary:

$ command -v zeisstopnm
/usr/bin/zeisstopnm

The command has no useful built-in version flag. Running zeisstopnm --version on this installation prints the Netpbm library and build information, then exits successfully:

$ zeisstopnm --version
zeisstopnm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
zeisstopnm: Built from source dated 2024-03-31 09:09:47

Your build date can differ. The documented help path is the manual page, and zeisstopnm --help exits with status 1 after saying to use man zeisstopnm.

2. Keep the source and destination separate

Choose an output name that is different from the input. The converter reads the Zeiss file and writes PNM data; it does not provide an in-place conversion mode. A relative path is fine when you are already in the working directory:

$ zeisstopnm /path/to/sample.zeiss > sample.pnm

Do not use sudo for an ordinary conversion. Reading a research file and writing a result in a directory you own should be unprivileged. Use elevated privileges only if your system administrator has deliberately granted access to the input or destination, and check the path carefully before doing so.

$ cp --preserve=all sample.pnm sample.pnm.bak
$ zeisstopnm /path/to/sample.zeiss > sample.pnm.new
$ test -s sample.pnm.new && mv -- sample.pnm.new sample.pnm

The mv command changes the destination only after the converter has produced a non-empty file. If conversion fails, inspect or remove the incomplete sample.pnm.new manually. Keep the backup until you have checked the replacement; deleting it is irreversible.

3. Let zeisstopnm choose the PNM type

With no output-format option, the program chooses from the input. Grayscale input produces PGM; non-grayscale input produces PPM. The program also tells you which type it is writing. Capture diagnostics separately if you want to keep the terminal clean:

$ zeisstopnm /path/to/greyscale.zeiss > greyscale.pgm 2> greyscale.log
$ sed -n '1,5p' greyscale.log
Writing a PGM file

The diagnostic wording can vary by build, so the filename extension is only a label you chose. Check the actual PNM header with a tool such as file:

$ file greyscale.pgm
greyscale.pgm: Netpbm image data, ...

The exact dimensions and description depend on the input. A successful file check is useful evidence that the redirected output is an image rather than an error message.

4. Force grayscale output with -pgm

Use -pgm when you specifically require PGM output:

$ zeisstopnm -pgm /path/to/sample.zeiss > sample.pgm

This selects the PGM output format. It does not resize the image or repair an input file that is not a valid Zeiss confocal file. Check both the exit status and the header:

$ status=$?
$ printf 'zeisstopnm status: %s\n' "$status"
zeisstopnm status: 0
$ file sample.pgm
sample.pgm: Netpbm image data, ...

Capture $? immediately after the conversion if you need the status in a script. Any later command replaces it.

5. Force colour output with -ppm

Use -ppm when the next tool expects PPM:

$ zeisstopnm -ppm /path/to/sample.zeiss > sample.ppm
$ status=$?
$ printf 'zeisstopnm status: %s\n' "$status"
zeisstopnm status: 0
$ file sample.ppm
sample.ppm: Netpbm image data, ...

Again, the option selects the output representation; it is not a general image-editing or colour-management operation. If you need a PNG or another delivery format, pass the verified PPM or PGM file to a separate converter such as one installed on your system.

6. Diagnose a failed conversion

A failed conversion returns a non-zero status and may leave an empty or partial redirected file. Preserve the diagnostic before running another command:

$ zeisstopnm /path/to/sample.zeiss > sample.pnm 2> sample.zeisstopnm.err
$ status=$?
$ printf 'status: %s\n' "$status"
$ sed -n '1,10p' sample.zeisstopnm.err
status: 1

On this installation, an empty test file produces Input file not in Zeiss format (too small) and status 1. That is a format or input problem, not a reason to add sudo. Check the path, size and permissions without altering the source:

$ ls -lh -- /path/to/sample.zeiss
$ file -- /path/to/sample.zeiss
$ test -r /path/to/sample.zeiss; printf 'readable: %s\n' "$?"
$ sed -n '1,10p' sample.zeisstopnm.err

If the source is readable but still rejected, obtain the file again from the instrument workflow or ask the person who exported it which Zeiss confocal format it uses. Do not rename an unrelated image and expect the extension to change its contents. If the input is valuable, do not edit it with a text editor while troubleshooting.