The RADIANCE Picture File Format

Radiance is a lighting simulation and rendering system available by
anonymous ftp from hobbes.lbl.gov (128.3.12.38). The picture file
format used by the program uses a floating point representation that
provides greater fidelity and numerical accuracy over a 24-bit
image, without taking much extra space.

At the end of this message I have put a shar file of the routines you
need to read and write Radiance pictures. The format has been
enhanced slightly for the next release (in an upward compatible
way), so you should definitely use these newer routines.

The file format, like most binary files used by Radiance, contains
an ASCII information header that is terminated by an empty line.
This header typically begins with the line "#?RADIANCE", followd
by the commands used to generate the file, along with variables
indicating exposure, view parameters, and so on. Next there is a
single line that indicates the resolution and pixel scanning order of
the image. For Radiance pictures, the pixels are order as English
text, left to right and top to bottom. This is indicated with a line
of the form:

-Y M +X N

Where M and N are the y and x resolutions, respectively. The x and y
image coordinates are always the same, starting with (0,0) at the lower
left corner, (N,0) at the lower right, and (0,M) at the upper left.
The y resolution appears first in our specification because it is the
major sort, and is preceded by a minus sign because it is decreasing in
the file.

Finally, the floating point scanlines follow. Each pixel is represented by
at most 4 bytes. The first three bytes are the red, green and blue mantissas
(in that order), and the fourth byte is a common exponent. The floating point
color (R,G,B)=(1.,.5,.25) would be represented by the bytes (128,64,32,129).
The conversion back to floating point is possible using the ldexp() library
routine, or it's better to use the colr_color() routine included in color.c.

The scanlines are usually run-length encoded. My previous scheme (release 1.4
and earlier) used a simple count for repeated pixels. My new scheme is
more complicated and encodes the four components separately. I don't
recommend writing your own routine to decode it -- use what's in color.c.

A skeletal program to read a Radiance picture file and convert to 24-bit
gamma-corrected color looks like this:

You will find all the routines you need in ray/src/common. The
checkheader() routine is in the module header.c, fgetresolu is in resolu.c,
freadcolrs() is in color.c, and setcolrgam() and colrs_gambs() are
in the module colrops.c.

If you want to convert the file to 8-bit color, the process is quite a
bit more complicated. I suggest you take a look at the ra_t8.c program
in the ray/src/px directory to get a better idea of what is involved.