| 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)` |
| 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. |
| 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`. |
