| 1 |
+ |
# RCSid $Id$ |
| 2 |
|
# *Radiance* File Formats |
| 3 |
|
This chapter discusses the standard file formats specific to *Radiance*, and gives their internal structure, with pointers to routines for reading and writing them. The following file formats (listed with their conventional suffixes) are covered: |
| 4 |
|
|
| 50 |
|
|
| 51 |
|
!xform -n chair1 -t 10 5 8 chair.rad |
| 52 |
|
|
| 53 |
< |
The command is executed during file parsing, and its output is read as more input. Long commands may be continued on multiple lines by escaping the newline character with a backslash ('\'): |
| 53 |
> |
The command is executed during file parsing, and its output is read as more input. Long commands may be continued on multiple lines by escaping the newline character with a backslash ('\\'): |
| 54 |
|
|
| 55 |
|
!gensurf marble sink '15.5+x(theta(s),phi(t))' \ |
| 56 |
|
'10.5+y(theta(s),phi(t))' \ |
| 153 |
|
y(th,p) = R(th,p)*sin(th)*sin(p); |
| 154 |
|
z(th,p) = R(th,p)*cos(th); |
| 155 |
|
|
| 156 |
< |
In contrast to the usual semantics in programs where each statement corresponds to an evaluation, statements in function files correspond to *definitions*. Once a function or variable has been defined, it may be used in later definitions, along with predefined functions such as `sin(x)` and `cos(x)` and constants such as PI [^2]. (All math functions use standard C conventions, hence trigonometry is done in radians rather than degrees.) |
| 156 |
> |
In contrast to the usual semantics in programs where each statement corresponds to an evaluation, statements in function files correspond to *definitions*. Once a function or variable has been defined, it may be used in later definitions, along with predefined functions such as `sin(x)` and `cos(x)` and constants such as `PI`[^2]. (All math functions use standard C conventions, hence trigonometry is done in radians rather than degrees.) |
| 157 |
|
|
| 158 |
|
[^2]: TBD - There once was a footnote here |
| 159 |
|
|
| 229 |
|
|
| 230 |
|
The following are sometimes defined, depending on the program: |
| 231 |
|
|
| 232 |
< |
PI |
| 232 |
> |
`PI` |
| 233 |
|
: The ratio of a circle's circumference to its diameter. |
| 234 |
|
|
| 235 |
|
`erf(z), erfc(z)` |
| 258 |
|
: surface normal |
| 259 |
|
|
| 260 |
|
`Px, Py, Pz` |
| 261 |
< |
:intersection point |
| 261 |
> |
: intersection point |
| 262 |
|
|
| 263 |
|
`T` |
| 264 |
|
: distance from start |
| 523 |
|
**Table 4.** Programs in the *Radiance* distribution that read and write font files. |
| 524 |
|
|
| 525 |
|
### *Radiance* C Library |
| 526 |
< |
Similar to data files, font files are usually read and stored in a lookup table. The data structures for fonts are in src/common/font.h, and the routines for reading and spacing them are in `src/common/font.c`. The main structure type is `FONT`. The routine `getfont(fname)` loads a font file from the *Radiance* library (set by the `RAYPATH` environment variable), and returns a pointer to the resulting `FONT` structure. If the file has been previously loaded, a pointer to the stored structure is returned. The `freefont(fname)` routine frees memory associated with the named font file and deletes it from the table, or frees all font data if `fname` is `NULL`. |
| 526 |
> |
Similar to data files, font files are usually read and stored in a lookup table. The data structures for fonts are in `src/common/font.h`, and the routines for reading and spacing them are in `src/common/font.c`. The main structure type is `FONT`. The routine `getfont(fname)` loads a font file from the *Radiance* library (set by the `RAYPATH` environment variable), and returns a pointer to the resulting `FONT` structure. If the file has been previously loaded, a pointer to the stored structure is returned. The `freefont(fname)` routine frees memory associated with the named font file and deletes it from the table, or frees all font data if `fname` is `NULL`. |
| 527 |
|
|
| 528 |
|
Three different routines are available for text spacing. The `uniftext(sp,tp,f`) function takes the nul-terminated string `tp` and computes uniform per-character spacing for the font `f`, returned in the short integer array `sp`. (This is a fairly simple process, and all spacing values will be 255 unless a character has no corresponding glyph.) The `squeeztext(sp,tp,f,cis)` performs a similar function, but puts only `ci`s units between adjacent characters, based on the actual width of each font glyph. The most sophisticated spacing function is `proptext(sp,tp,f,cis,nsi)`, which produces a total line length equal to what it would be with uniform spacing, while maintaining equal inter-character spacing throughout (i.e., proportional spacing). The `nsi` argument is the number of spaces (zero-vertex glyphs) considered as an indent. That is, if this many or more adjacent spaces occur in `tp`, the indented text following will appear at the same point as it would have had the spacing been uniform. This maintains columns in tabulated text despite the proportional spacing. Tabs are not understood or interpreted by any of these routines, and must be expanded to the appropriate number of spaces via **expand**. |
| 529 |
|
|
| 609 |
|
**Table 5.** Programs in the *Radiance* distribution that read and write octree files. |
| 610 |
|
|
| 611 |
|
### *Radiance* C Library |
| 612 |
< |
Since reading an octree file also may involve reading a *Radiance* scene description, some of the same library routines are called indirectly. The header file `src/common/octree.h` is needed in addition to the `src/common/object.`h file. The module `src/ot/writeoct.c` contains the main routines for writing an octree to stdout, while `src/common/readoct.c` contains the corresponding routines for reading an octree from a file. Both modules access routines in `src/common/portio.c` for reading and writing portable binary data. |
| 612 |
> |
Since reading an octree file also may involve reading a *Radiance* scene description, some of the same library routines are called indirectly. The header file `src/common/octree.h` is needed in addition to the `src/common/object.h` file. The module `src/ot/writeoct.c` contains the main routines for writing an octree to stdout, while `src/common/readoct.c` contains the corresponding routines for reading an octree from a file. Both modules access routines in `src/common/portio.c` for reading and writing portable binary data. |
| 613 |
|
|
| 614 |
|
Here is the main call for writing out an octree: |
| 615 |
|
|
| 622 |
|
: Read the octree file fname into scene, saving scene file names in the ofn array. What is loaded depends on the flags in load,which may be one or more of `IO_CHECK`, `IO_INFO`, `IO_SCENE`, `IO_TREE`, `IO_FILES` and `IO_BOUNDS`. These correspond to checking file type and consistency, transferring the information header to stdout, loading the scene data, loading the octree structure, assigning the scene file names to ofn, and assigning the octree cube boundaries. The macro `IO_ALL` includes all of these flags, for convenience. |
| 623 |
|
|
| 624 |
|
## Picture File Format (.hdr suffix) |
| 625 |
< |
*Radiance* pictures[^pic] differ from standard computer graphics images inasmuch as they contain real physical data, namely radiance values at each pixel. To do this, it is necessary to maintain floating point information, and we use a 4-byte/pixel encoding described in Chapter II.5 of Graphics Gems II [Arvo91,p.80]. The basic idea is to store a 1-byte mantissa for each of three primaries, and a common 1-byte exponent. The accuracy of these values will be on the order of 1% (±1 in 200) over a dynamic range from 10^-38^ to 10^38^. |
| 625 |
> |
*Radiance* pictures[^pic] differ from standard computer graphics images inasmuch as they contain real physical data, namely radiance values at each pixel. To do this, it is necessary to maintain floating point information, and we use a 4-byte/pixel encoding described in Chapter II.5 of *Graphics Gems II* [Arvo91,p.80]. The basic idea is to store a 1-byte mantissa for each of three primaries, and a common 1-byte exponent. The accuracy of these values will be on the order of 1% (±1 in 200) over a dynamic range from 10^-38^ to 10^38^. |
| 626 |
|
|
| 627 |
|
[^pic]: The picture filename extension used to be .pic, but that conflicted with too many other programs. It was replaced with .hdr, an abbreviation of "high dynamic range." |
| 628 |
|
|
| 635 |
|
The information header begins with the usual `#?RADIANCE` identifier, followed by one or more lines containing the programs used to produce the picture. These commands may be interspersed with variables describing relevant information such as the view, exposure, color correction, and so on. Variable assignments begin on a new line, and the variable name (usually all upper case) is followed by an equals sign ('='), which is followed by the assigned value up until the end of line. Some variable assignments override previous assignments in the same header, where other assignments are cumulative. Here are the most important variables for *Radiance* pictures: |
| 636 |
|
|
| 637 |
|
`FORMAT` |
| 638 |
< |
: A line indicating the file's format. At most one `FORMAT` line is allowed, and it must be assigned a value of either `32- bit_rle_rgbe` or `32-bit_rle_xyze` to be a valid *Radiance* picture. |
| 638 |
> |
: A line indicating the file's format. At most one `FORMAT` line is allowed, and it must be assigned a value of either `32-bit_rle_rgbe` or `32-bit_rle_xyze` to be a valid *Radiance* picture. |
| 639 |
|
|
| 640 |
|
`EXPOSURE` |
| 641 |
|
: A single floating point number indicating a multiplier that has been applied to all the pixels in the file. `EXPOSURE` values are cumulative, so the original pixel values (i.e., radiances in w/sr/m^2^) must be derived by taking the values in the file and dividing by all the `EXPOSURE` settings multiplied together. No `EXPOSURE` setting implies that no exposure changes have taken place. |
| 653 |
|
: The *Radiance* view parameters used to create this picture. Multiple assignments are cumulative inasmuch as new view options add to or override old ones. |
| 654 |
|
|
| 655 |
|
`PRIMARIES` |
| 656 |
< |
The CIE (x,y) chromaticity coordinates of the three (RGB) primaries and the white point used to standardize the picture's color system. This is used mainly by the **ra_xyze** program to convert between color systems. If no `PRIMARIES` line appears, we assume the standard primaries defined in `src/common/color.h`, namely `0.640 0.330 0.290 0.600 0.150 0.060 0.333 0.333` for red, green, blue and white, respectively. |
| 656 |
> |
: The CIE (x,y) chromaticity coordinates of the three (RGB) primaries and the white point used to standardize the picture's color system. This is used mainly by the **ra_xyze** program to convert between color systems. If no `PRIMARIES` line appears, we assume the standard primaries defined in `src/common/color.h`, namely `0.640 0.330 0.290 0.600 0.150 0.060 0.333 0.333` for red, green, blue and white, respectively. |
| 657 |
|
|
| 658 |
|
As always, the end of the header is indicated by an empty line. |
| 659 |
|
|
| 705 |
|
: Repeated pixel values are indicated by an illegal (i.e., unnormalized) pixel that has 1's for all three mantissas, and an exponent that corresponds to the number of times the previous pixel is repeated. Consecutive repeat indicators contain higher-order bytes of the count. |
| 706 |
|
|
| 707 |
|
New run-length encoded |
| 708 |
< |
: In this format, the four scanline components (three primaries and exponent) are separated for better compression using adaptive run-length encoding (described by Glassner in Chapter II.8 of Graphics Gems II [Arvo91,p.89]). The record begins with an unnormalized pixel having two bytes equal to 2, followed by the upper byte and the lower byte of the scanline length (which must be less than 32768). A run is indicated by a byte with its high-order bit set, corresponding to a count with excess 128. A non-run is indicated with a byte less than 128. The maximum compression ratio using this scheme is better than 100:1, but typical performance for *Radiance* pictures is more like 2:1. |
| 708 |
> |
: In this format, the four scanline components (three primaries and exponent) are separated for better compression using adaptive run-length encoding (described by Glassner in Chapter II.8 of *Graphics Gems II* [Arvo91,p.89]). The record begins with an unnormalized pixel having two bytes equal to 2, followed by the upper byte and the lower byte of the scanline length (which must be less than 32768). A run is indicated by a byte with its high-order bit set, corresponding to a count with excess 128. A non-run is indicated with a byte less than 128. The maximum compression ratio using this scheme is better than 100:1, but typical performance for *Radiance* pictures is more like 2:1. |
| 709 |
|
|
| 710 |
|
The physical values these scanlines correspond to depend on the format and other information contained in the information header. If the `FORMAT` string indicates RGB data, then the units for each primary are spectral radiances over the corresponding waveband, such that a pixel value of $(1,1,1)$ corresponds to a total energy of 1 w/sr/m^2^ over the visible spectrum. The actual luminance value (in lm/sr/m^2^) can be computed from the following formula for the standard *Radiance* RGB primaries: |
| 711 |
|
|
| 713 |
|
|
| 714 |
|
The value of 179 lm/w is the standard *luminous efficacy* of equal-energy white light that is defined and used by *Radiance* specifically for this conversion. This and the other values above are defined in `src/common/color.h`, and the above formula is given as a macro, `luminance(col)`. |
| 715 |
|
|
| 716 |
< |
If the `FORMAT` string indicates XYZ data, then the units of the Y primary are already lm/st/m^2^, so the above conversion is unnecessary. |
| 716 |
> |
If the `FORMAT` string indicates XYZ data, then the units of the Y primary are already lm/sr/m^2^, so the above conversion is unnecessary. |
| 717 |
|
|
| 718 |
|
### *Radiance* programs |
| 719 |
|
Table 6 shows the many programs that read and write *Radiance* pictures. |
| 768 |
|
Information headers are manipulated with the routines in `src/common/header.c` and the macros in `color.h`. Features for handing views are defined in `src/common/view.h` with routines in `src/common/image.c`. Here are the relevant calls for reading and copying information headers: |
| 769 |
|
|
| 770 |
|
`int checkheader(FILE *fin, char *fmt, FILE *fout);` |
| 771 |
< |
: Read the header information from `fin`, copying to `fou`t (unless fout is `NULL`), checking any `FORMAT` line against the string `fmt`. The `FORMAT` line (if it exists) will not be copied to `fout`. The function returns 1 if the header was OK and the format matched, 0 if the header was OK but there was no format line, and -1 if the format line did not match or there was some problem reading the header. Wildcard characters ('\*' and '?') may appear in `fmt`, in which case a globbing match is applied, and the matching format value will be copied to fmt upon success. The normal `fmt` values for pictures are `COLRFMT` for *Radiance* RGB, `CIEFMT` for 4-byte XYZ pixels, or a copy of `PICFMT` for glob matches to either. (Do not pass `PICFMT` directly, as this will cause an illegal memory access on systems that store static strings in read-only memory.) |
| 771 |
> |
: Read the header information from `fin`, copying to `fout` (unless fout is `NULL`), checking any `FORMAT` line against the string `fmt`. The `FORMAT` line (if it exists) will not be copied to `fout`. The function returns 1 if the header was OK and the format matched, 0 if the header was OK but there was no format line, and -1 if the format line did not match or there was some problem reading the header. Wildcard characters ('\*' and '?') may appear in `fmt`, in which case a globbing match is applied, and the matching format value will be copied to fmt upon success. The normal `fmt` values for pictures are `COLRFMT` for *Radiance* RGB, `CIEFMT` for 4-byte XYZ pixels, or a copy of `PICFMT` for glob matches to either. (Do not pass `PICFMT` directly, as this will cause an illegal memory access on systems that store static strings in read-only memory.) |
| 772 |
|
|
| 773 |
|
`int getheader(FILE *fp, int (*f)(), char *p);` |
| 774 |
|
: For those who need more control, `getheader` reads the header from `fp`, calling the function `f` (if not` NULL`) with each input line and the client data pointer `p`. A simple call to skip the header is `getheader(fp,NULL,NULL)`. To copy the header unconditionally to `stdout`, call `getheader(fp,fputs,stdout)`. More often, `getheader` is called with a client function, which checks each line for specific variable settings. |
| 793 |
|
: Macro** | puts real exposure value `ex` to stream `fp`. |
| 794 |
|
|
| 795 |
|
`iscolcor(s)` |
| 796 |
< |
:Macro returns non-zero if the line `s` is a `COLORCORR` setting. |
| 796 |
> |
: Macro returns non-zero if the line `s` is a `COLORCORR` setting. |
| 797 |
|
|
| 798 |
|
`colcorval(cc,s)` |
| 799 |
|
: Macro assign color correction value from line `s` in the `COLOR` |
| 841 |
|
stream fp. |
| 842 |
|
|
| 843 |
|
`scanlen(rs)` |
| 844 |
< |
: Macro to get the scanline length from the `RESOL`U structure |
| 844 |
> |
: Macro to get the scanline length from the `RESOLU` structure |
| 845 |
|
pointed to by `rs`. |
| 846 |
|
|
| 847 |
|
`numscans(rs)` |
| 849 |
|
structure pointed to by `rs`. |
| 850 |
|
|
| 851 |
|
`fscnresolu(slp,nsp,fp)` |
| 852 |
< |
: Macro to read in a resolution string from `f`p and assign the scanline length and number of scanlines to the integers pointed to by `slp` and `nsp`, respectively. This call expects standard English-text ordered scanlines, and returns non-zero only if the resolution string agrees. |
| 852 |
> |
: Macro to read in a resolution string from `fp` and assign the scanline length and number of scanlines to the integers pointed to by `slp` and `nsp`, respectively. This call expects standard English-text ordered scanlines, and returns non-zero only if the resolution string agrees. |
| 853 |
|
|
| 854 |
|
`fprtresolu(sl,ns,fp)` |
| 855 |
|
: Macro to print out a resolution string for `ns` scanlines of length `sl` in standard English-text ordering to `fp`. |
| 968 |
|
**Table 8.** Programs in the *Radiance* distribution that read and write ambient files. |
| 969 |
|
|
| 970 |
|
### *Radiance* C Library |
| 971 |
< |
The `src/rt/ambient.h` file contains definitions of the `AMBVAL` structure and certain details of the ambient file format. The `src/rt/ambio.c` module contains the specialized routines for reading and writing ambient files, and these functions in turn access routines in `src/common/portio.c` for reading and writing portable binary data. The information header is handled by the routines in s`rc/common/header.c`, similar to the method described for *Radiance* picture files. Here are the main calls from `src/rt/ambio.c`: |
| 971 |
> |
The `src/rt/ambient.h` file contains definitions of the `AMBVAL` structure and certain details of the ambient file format. The `src/rt/ambio.c` module contains the specialized routines for reading and writing ambient files, and these functions in turn access routines in `src/common/portio.c` for reading and writing portable binary data. The information header is handled by the routines in `src/common/header.c`, similar to the method described for *Radiance* picture files. Here are the main calls from `src/rt/ambio.c`: |
| 972 |
|
|
| 973 |
|
`putambmagic(FILE *fp);` |
| 974 |
|
: Put out the appropriate two-byte magic number for a *Radiance* ambient file to the stream `fp`. |
