Convert a Biorad Confocal File to PGM with bioradtopgm

bioradtopgm pulls a single frame out of a Biorad confocal microscope file and writes it as a plain greyscale PGM you can actually open. You will finish with that image extracted, or with a clear report of how many frames the file holds before you pick one. The examples use Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

Allow about ten minutes for a single file. You need a readable Biorad confocal file, a shell, and the Netpbm package. The conversion normally runs as your ordinary user: you only need elevated privileges if your input or output directory deliberately denies your account access, and sudo will not fix a bad file path.

1. Check the installed converter

Confirm which executable will run and record its Netpbm version. These are read-only commands:

$ command -v bioradtopgm
/usr/bin/bioradtopgm
$ bioradtopgm --version
bioradtopgm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version probe prints build details as well as the library version, so the remaining lines can differ between distributions. If command -v finds nothing, install Netpbm through your normal package-management process before continuing.

2. Ask how many images are present

A Biorad file can contain more than one image. Run the converter without an image number to inspect the file rather than produce pixels:

$ bioradtopgm /path/to/sample.biorad
image size: 512 x 512
number of images: 8

The exact wording and dimensions come from the file; the useful result is the image count and size. This inspection mode produces no PGM output, so redirecting it to a file is unnecessary. Replace /path/to/sample.biorad with your real path: the suffix is only a placeholder, since the converter accepts a Biorad file rather than requiring a specific filename extension.

If the command reports an open or read error, check the path and permissions without changing anything:

$ ls -l /path/to/sample.biorad
$ test -r /path/to/sample.biorad && echo readable

A non-zero status here means you have not yet established that the input is readable. Do not interpret an empty or damaged file as an image with zero frames.

3. Extract one image by its zero-based number

Choose one image number from zero through one less than the reported count. The first image is number zero, and the number is attached directly to -image, as in -image0, not supplied as a separate argument:

$ bioradtopgm -image0 /path/to/sample.biorad > sample-000.pgm
$ file sample-000.pgm
sample-000.pgm: Netpbm image data, size 512 x 512, rawbits, greymap

bioradtopgm writes the PGM image to standard output; the converter does not choose an output filename for you. Use a new destination name while testing, and confirm it is non-empty:

$ test -s sample-000.pgm && echo 'PGM output is non-empty'
PGM output is non-empty

The file description can vary slightly. It should identify a Netpbm image, and the dimensions should match the inspection result. PGM is greyscale, so do not expect colour channels in this output.

4. Extract a different frame without overwriting the first

For the eighth image in the example inspection, use image number seven and a separate output path:

$ bioradtopgm -image7 /path/to/sample.biorad > sample-007.pgm
$ file sample-007.pgm
sample-007.pgm: Netpbm image data, size 512 x 512, rawbits, greymap

Image numbering is zero-based, a common source of an off-by-one error: if the file reports eight images, -image8 is outside that range. Re-run the inspection command if you lose track of the count.

$ cp --preserve=all sample-000.pgm sample-000.pgm.bak
$ bioradtopgm -image0 /path/to/sample.biorad > sample-000.pgm.new
$ test -s sample-000.pgm.new && mv sample-000.pgm.new sample-000.pgm

5. Correct an upside-down image

If the extracted image is upside down, pass the PGM through pamflip -tb, which flips it top to bottom:

$ pamflip -tb sample-000.pgm > sample-000-fixed.pgm
$ file sample-000-fixed.pgm
sample-000-fixed.pgm: Netpbm image data, size 512 x 512, rawbits, greymap

This is a second, separate command. It leaves the original PGM untouched and writes the corrected image to a new file. Inspect the corrected result before replacing anything. If pamflip is not installed, keep the PGM and use the image-processing package your system provides rather than changing the source file.

6. Diagnose the likely mistakes

• Usage output usually means the option shape is wrong. The documented form is bioradtopgm [-image#] [imagedata]: use -image0, not -image 0.
• A missing image number is valid, not an error. It selects inspection mode and deliberately produces no PGM.
• An empty output file usually means the wrong argument shape, not a broken install. Check the exit status and rerun without overwriting a good destination.

$ bioradtopgm -image0 /path/to/sample.biorad > sample-check.pgm
$ printf 'converter exit status: %s\n' "$?"
converter exit status: 0
$ test -s sample-check.pgm && echo valid-size
valid-size

A successful exit status means the conversion completed; it does not confirm that you selected the intended frame or that the orientation is correct. Keep the original input until the PGM has been checked in an image viewer or passed to the next trusted processing step.