1 |
.EQ |
2 |
delim @@ |
3 |
.EN |
4 |
.SH 1 |
5 |
\f[BI]Radiance\f[B] File Formats |
6 |
.pdfhref O 1 "Radiance File Formats" |
7 |
.pdfhref M "radiance-file-formats" |
8 |
.LP |
9 |
This chapter discusses the standard file formats specific to |
10 |
\f[I]Radiance\f[R], and gives their internal structure, with pointers to |
11 |
routines for reading and writing them. |
12 |
The following file formats (listed with their conventional suffixes) are |
13 |
covered: |
14 |
.IP "\f[B]Scene Description (.rad suffix)\f[R]" 3 |
15 |
This is the main input file type, describing materials and geometry for |
16 |
the rendering programs, and must be compiled into an octree by oconv |
17 |
prior to ray-tracing. |
18 |
It is an ASCII text format, and is often translated from a CAD |
19 |
description, but may be created or edited by a text editor as well. |
20 |
.RS 3 |
21 |
.RE |
22 |
.IP "\f[B]Function File (.cal suffix)\f[R]" 3 |
23 |
Also a text format, these files describe mathematical patterns, |
24 |
textures, and surface shapes. |
25 |
In the case of patterns and textures, the functions serve as input |
26 |
directly to the rendering programs. |
27 |
In the case of surfaces, the functions serve as input to one of the |
28 |
generator programs, \f[B]gensurf\f[R], \f[B]genrev\f[R] or |
29 |
\f[B]genworm\f[R]. |
30 |
Additionally, \f[B]pcomb\f[R] may be used to perform math on |
31 |
\f[I]Radiance\f[R] pictures and the \f[B]rcalc\f[R] utility may be used |
32 |
in creative ways to manipulate data for scene generation and data |
33 |
analysis. |
34 |
.RS 3 |
35 |
.RE |
36 |
.IP "\f[B]Data File (.dat suffix)\f[R]" 3 |
37 |
Another ASCII format, data files are used directly by the rendering |
38 |
programs to interpolate values for luminaire photometry, among other |
39 |
things. |
40 |
.RS 3 |
41 |
.RE |
42 |
.IP "\f[B]Font File (.fnt suffix)\f[R]" 3 |
43 |
A simple, polygonal font representation for rendering text patterns. |
44 |
This ASCII format describes each character \[lq]glyph\[rq] as a sequence |
45 |
of vertices in rectangular, integer coordinates ranging from 0 to 255. |
46 |
.RS 3 |
47 |
.RE |
48 |
.IP "\f[B]Octree (.oct suffix)\f[R]" 3 |
49 |
A binary data structure computed from one or more scene description |
50 |
files by the oconv program. |
51 |
It may contain frozen scene data in binary form, or merely references to |
52 |
the original scene files. |
53 |
.RS 3 |
54 |
.RE |
55 |
.IP "\f[B]Picture (.hdr suffix)\f[R]" 3 |
56 |
A binary image file containing calibrated, real radiance values at each |
57 |
pixel. |
58 |
\f[I]Radiance\f[R] pictures may be displayed, analyzed, and converted to |
59 |
other image formats. |
60 |
.RS 3 |
61 |
.RE |
62 |
.IP "\f[B]Z-buffer (.zbf suffix)\f[R]" 3 |
63 |
A binary file with the distances to each pixel in a corresponding |
64 |
picture. |
65 |
.RS 3 |
66 |
.RE |
67 |
.IP "\f[B]Ambient File (.amb suffix)\f[R]" 3 |
68 |
A binary file used to store diffuse interreflection values, which are |
69 |
shared between cooperating rendering processes running sequentially or |
70 |
in parallel. |
71 |
Since these values are view-independent, sharing this information across |
72 |
multiple runs is highly economical. |
73 |
.RS 3 |
74 |
.RE |
75 |
.LP |
76 |
We will discuss each of these formats in turn, giving examples and |
77 |
pointers to routines in the source code for reading and writing them, |
78 |
and the programs that use them. |
79 |
In general, the ASCII text formats have no standard routines for writing |
80 |
them, since they generally originate outside of \f[I]Radiance\f[R] or |
81 |
are created with simple \f[I]printf(3)\f[R] statements. |
82 |
Most binary file formats are machine and system independent, meaning |
83 |
they can be moved safely from one place to another and |
84 |
\f[I]Radiance\f[R] will still understand them (provided no unintentional |
85 |
character translation takes place along the way)\**. |
86 |
.FS |
87 |
The single exception to this rule is the Z-buffer file, whose contents |
88 |
are dictated by the floating point representation and byte order of the |
89 |
originating machine. |
90 |
This choice was made for economic reasons, and is rarely a problem. |
91 |
.FE |
92 |
Most binary files also include a standard ASCII header at their |
93 |
beginning that may be read by the \f[B]getinfo\f[R] program. |
94 |
This offers a convenient method for identifying the file contents when |
95 |
the file name is ambiguous. |
96 |
.SH 2 |
97 |
Scene Description Format (.rad suffix) |
98 |
.pdfhref O 2 "Scene Description Format \(.rad suffix\)" |
99 |
.pdfhref M "scene-description-format-.rad-suffix" |
100 |
.LP |
101 |
The semantics of the \f[I]Radiance\f[R] scene description format are |
102 |
covered in the Reference Manual. |
103 |
We will therefore focus on the file syntax and structure, which are |
104 |
simple and straightforward. |
105 |
In fact, some would say that the \f[I]Radiance\f[R] scene description |
106 |
format is brain-dead, in the sense that it offers few language amenities |
107 |
and requires the awkward counting of string and real arguments (not to |
108 |
mention those non-existent integer arguments). |
109 |
We have little to offer in its defense. |
110 |
.PP |
111 |
The truth is, the scene format was designed to grow with |
112 |
\f[I]Radiance\f[R], and we wanted to keep it as simple as possible so as |
113 |
to encourage others to write translators to and from it. |
114 |
Specifically, we wanted to be able to read files using the |
115 |
\f[I]scanf(3)\f[R] library function and write files using |
116 |
\f[I]printf(3)\f[R]. |
117 |
Furthermore, we wanted everyone\[cq]s parsers to be stable over time, |
118 |
which meant no primitive-specific syntax. |
119 |
We also decided that a flat file structure was most practical, since |
120 |
hierarchies are typically lost on the first translation, and sufficient |
121 |
structure could be provided by the file system itself. |
122 |
Since we did not intend text editing to be the primary input method, we |
123 |
felt the effects of these programming decisions on the human readability |
124 |
and writability of the format were less important. |
125 |
.PP |
126 |
Even so, the format is relatively easy to read and write once you get |
127 |
used to it, and with the \f[I]Radiance\f[R] generator programs and |
128 |
in-line command expansion, the text editor becomes a powerful modeling |
129 |
tool in the hands of an experienced user. |
130 |
Together with the need for editing material descriptions, our assumption |
131 |
that users would rarely edit these files turned out to be mistaken. |
132 |
Consequently, it is a good idea for all users to familiarize themselves |
133 |
with the scene description format, awkward or not. |
134 |
.SH 3 |
135 |
Basic File Structure |
136 |
.pdfhref O 3 "Basic File Structure" |
137 |
.pdfhref M "basic-file-structure" |
138 |
.LP |
139 |
There are four statement types in a scene description file: comments, |
140 |
commands, primitives and aliases. |
141 |
These may be interspersed in the file, and the only structural |
142 |
requirement is that modifiers precede the primitives they modify. |
143 |
.SH 4 |
144 |
Comments |
145 |
.pdfhref O 4 "Comments" |
146 |
.pdfhref M "comments" |
147 |
.LP |
148 |
The simplest statement type is a comment statement begins with a pound |
149 |
sign (`#') and continues to the end of line: |
150 |
.IP |
151 |
.nf |
152 |
\f[C] |
153 |
# This is a comment. |
154 |
\f[] |
155 |
.fi |
156 |
.SH 4 |
157 |
Commands |
158 |
.pdfhref O 4 "Commands" |
159 |
.pdfhref M "commands" |
160 |
.LP |
161 |
An in-line command, which begins with an exclamation mark (`!') and |
162 |
continues to the end of line: |
163 |
.IP |
164 |
.nf |
165 |
\f[C] |
166 |
!xform -n chair1 -t 10 5 8 chair.rad |
167 |
\f[] |
168 |
.fi |
169 |
.LP |
170 |
The command is executed during file parsing, and its output is read as |
171 |
more input. |
172 |
Long commands may be continued on multiple lines by escaping the newline |
173 |
character with a backslash (`\[rs]'): |
174 |
.IP |
175 |
.nf |
176 |
\f[C] |
177 |
!gensurf marble sink \[aq]15.5+x(theta(s),phi(t))\[aq] \[rs] |
178 |
\[aq]10.5+y(theta(s),phi(t))\[aq] \[rs] |
179 |
\[aq]30.75+z(theta(s),phi(t))\[aq] \[rs] |
180 |
8 29 -f basin.cal -s |
181 |
\f[] |
182 |
.fi |
183 |
.LP |
184 |
Since the command is executed by the shell, pipes and other facilities |
185 |
are available as well. |
186 |
The following command creates a counter with a precisely cut hole for |
187 |
the sink basin just given: |
188 |
.IP |
189 |
.nf |
190 |
\f[C] |
191 |
!( echo marble polygon sink_top 0 0 108 31 \[rs] |
192 |
10.5 30.75 31 22 30.75 0 22 30.75 0 0 \[rs] |
193 |
30.75 31 0 30.75 31 10.5 30.75 ; \[rs] |
194 |
cnt 30 | rcalc \[rs] |
195 |
-e \[aq]$1=15.5+x(theta(0),phi(1-$1/29))\[aq] \[rs] |
196 |
-e \[aq]$2=10.5+y(theta(0),phi(1-$1/29))\[aq] \[rs] |
197 |
-e \[aq]$3=30.75\[aq] -f basin.cal ) |
198 |
\f[] |
199 |
.fi |
200 |
.LP |
201 |
Note in the above example that two commands are executed in sequence. |
202 |
The first creates the counter perimeter, and the second cuts the hole. |
203 |
The two commands are enclosed in parentheses, so if a final |
204 |
transformation is added by \f[B]xform\f[R] with the \f[B]-c\f[R] option, |
205 |
it will be applied to both commands, not just the last one. |
206 |
.SH 4 |
207 |
Primitives |
208 |
.pdfhref O 4 "Primitives" |
209 |
.pdfhref M "primitives" |
210 |
.LP |
211 |
A primitive can be thought of as an indivisible unit of scene |
212 |
information. |
213 |
It can be a surface, material, pattern, texture or mixture. |
214 |
The basic structure of a primitive is as follows: |
215 |
.IP |
216 |
.nf |
217 |
\f[C] |
218 |
modifier type identifier |
219 |
n S1 S2 S3 ..Sn |
220 |
0 |
221 |
m R1 R2 R3 ..Rm |
222 |
\f[] |
223 |
.fi |
224 |
.LP |
225 |
The \f[C]modifier\f[R] is the \f[C]identifier\f[R] of a previously |
226 |
defined primitive, or \f[C]void\f[R] if no modifier is appropriate. |
227 |
The type is one of the supported \f[I]Radiance\f[R] primitive keywords, |
228 |
such as \f[I]polygon\f[R] or \f[I]plastic\f[R]. |
229 |
Following the \f[C]modifier\f[R], type and identifier are the string |
230 |
arguments, preceded by the number of string arguments and separated by |
231 |
white space. |
232 |
If there are no string arguments, then 0 should be given for |
233 |
\f[C]n\f[R]. |
234 |
The string arguments are followed by the integer arguments in the same |
235 |
fashion. |
236 |
(Since there are no \f[I]Radiance\f[R] primitives currently using |
237 |
integer arguments, the count is always 0.) |
238 |
Finally, the number of real arguments is given, followed by the real |
239 |
arguments. |
240 |
.PP |
241 |
The location of the primitive in the scene description has no |
242 |
importance, except that its modifier refers to the most recently defined |
243 |
primitive with that identifier. |
244 |
If no such modifier was defined, an error results. |
245 |
In fact, \[lq]undefined modifier\[rq] is the most frequently reported |
246 |
error when parsing an invalid scene description, since any random bit of |
247 |
junk encountered where a statement is expected will be interpreted as a |
248 |
modifier. |
249 |
One final note about modifiers \[em] since surfaces never modify |
250 |
anything, their identifiers are neither stored nor referenced in the |
251 |
parser\[cq]s modifier list, and serve only for debugging purposes during |
252 |
editing and rendering. |
253 |
.PP |
254 |
Within a primitive, white space serves only to separate words, and |
255 |
multiple spaces, tabs, form feeds, returns, and newlines are all |
256 |
considered as one separator. |
257 |
Consequently, it is not possible for a string argument to contain any |
258 |
white space, which is OK because no \f[I]Radiance\f[R] primitive needs |
259 |
this. |
260 |
.SH 4 |
261 |
Aliases |
262 |
.pdfhref O 4 "Aliases" |
263 |
.pdfhref M "aliases" |
264 |
.LP |
265 |
An alias simply associates a new modifier and identifier with a |
266 |
previously defined primitive. |
267 |
The syntax is as follows: |
268 |
.IP |
269 |
.nf |
270 |
\f[C] |
271 |
modifier alias new_identifier old_identifier |
272 |
\f[] |
273 |
.fi |
274 |
.LP |
275 |
The \f[C]old_identifier\f[R] should be associated with some modifier |
276 |
primitive (i.e., non-surface) given earlier. |
277 |
The \f[C]modifier\f[R], if different from the original, will be used |
278 |
instead in later applications of \f[C]new_identifier\f[R]. |
279 |
.PP |
280 |
Aliases are most often used to give new names to previously defined |
281 |
materials. |
282 |
They may also be used to associate different patterns or textures with |
283 |
the same material. |
284 |
.SH 3 |
285 |
Scene Hierarchy |
286 |
.pdfhref O 3 "Scene Hierarchy" |
287 |
.pdfhref M "scene-hierarchy" |
288 |
.LP |
289 |
Hierarchical scene descriptions are achieved through expansion of |
290 |
in-line \f[B]xform\f[R] commands. |
291 |
The \f[B]xform\f[R] command is used to read and place other |
292 |
\f[I]Radiance\f[R] scene description files in the calling file, and |
293 |
these other descriptions may in turn read others, and so on down the |
294 |
tree. |
295 |
No check is made to assure that none of the calling files is called |
296 |
again, even by itself. |
297 |
If this happens, commands open commands until the system runs out of |
298 |
processes, which is a very nasty business and to be avoided. |
299 |
.SH 3 |
300 |
\f[BI]Radiance\f[B] Programs |
301 |
.pdfhref O 3 "Radiance Programs" |
302 |
.pdfhref M "radiance-programs" |
303 |
.LP |
304 |
The following table shows programs in the main \f[I]Radiance\f[R] |
305 |
distribution that read and write scene description files. |
306 |
Additionally, there are other translators that write scene files, which |
307 |
are available separately as free contributions or as part of other (CAD) |
308 |
programs. |
309 |
.PP |
310 |
.na |
311 |
.TS |
312 |
delim(@@) tab( ); |
313 |
l l l l. |
314 |
T{ |
315 |
Program |
316 |
T} T{ |
317 |
Read |
318 |
T} T{ |
319 |
Write |
320 |
T} T{ |
321 |
Function |
322 |
T} |
323 |
_ |
324 |
T{ |
325 |
\f[B]arch2rad\f[R] |
326 |
T} T{ |
327 |
T} T{ |
328 |
X |
329 |
T} T{ |
330 |
Convert Architrion text file to \f[I]Radiance\f[R] |
331 |
T} |
332 |
T{ |
333 |
\f[B]genblinds\f[R] |
334 |
T} T{ |
335 |
T} T{ |
336 |
X |
337 |
T} T{ |
338 |
Generate curved venetian blinds |
339 |
T} |
340 |
T{ |
341 |
\f[B]genbox\f[R] |
342 |
T} T{ |
343 |
T} T{ |
344 |
X |
345 |
T} T{ |
346 |
Generate parallelepiped |
347 |
T} |
348 |
T{ |
349 |
\f[B]genclock\f[R] |
350 |
T} T{ |
351 |
T} T{ |
352 |
X |
353 |
T} T{ |
354 |
Generate analog clock |
355 |
T} |
356 |
T{ |
357 |
\f[B]genprism\f[R] |
358 |
T} T{ |
359 |
T} T{ |
360 |
X |
361 |
T} T{ |
362 |
Generate extruded polygon |
363 |
T} |
364 |
T{ |
365 |
\f[B]genrev\f[R] |
366 |
T} T{ |
367 |
T} T{ |
368 |
X |
369 |
T} T{ |
370 |
Generate surface of revolution |
371 |
T} |
372 |
T{ |
373 |
\f[B]gensky\f[R] |
374 |
T} T{ |
375 |
T} T{ |
376 |
X |
377 |
T} T{ |
378 |
Generate CIE sky distribution |
379 |
T} |
380 |
T{ |
381 |
\f[B]gensurf\f[R] |
382 |
T} T{ |
383 |
T} T{ |
384 |
X |
385 |
T} T{ |
386 |
Generate arbitrary surface patch |
387 |
T} |
388 |
T{ |
389 |
\f[B]genworm\f[R] |
390 |
T} T{ |
391 |
T} T{ |
392 |
X |
393 |
T} T{ |
394 |
Generate varying diameter curved path |
395 |
T} |
396 |
T{ |
397 |
\f[B]ies2rad\f[R] |
398 |
T} T{ |
399 |
T} T{ |
400 |
X |
401 |
T} T{ |
402 |
Convert IES luminaire file to \f[I]Radiance\f[R] |
403 |
T} |
404 |
T{ |
405 |
\f[B]mgf2rad\f[R] |
406 |
T} T{ |
407 |
T} T{ |
408 |
X |
409 |
T} T{ |
410 |
Convert MGF file to \f[I]Radiance\f[R] |
411 |
T} |
412 |
T{ |
413 |
\f[B]mkillum\f[R] |
414 |
T} T{ |
415 |
X |
416 |
T} T{ |
417 |
X |
418 |
T} T{ |
419 |
Compute \f[I]illum\f[R] secondary sources |
420 |
T} |
421 |
T{ |
422 |
\f[B]nff2rad\f[R] |
423 |
T} T{ |
424 |
T} T{ |
425 |
X |
426 |
T} T{ |
427 |
Convert NFF file to \f[I]Radiance\f[R] |
428 |
T} |
429 |
T{ |
430 |
\f[B]objline\f[R] |
431 |
T} T{ |
432 |
T} T{ |
433 |
X |
434 |
T} T{ |
435 |
Generate line drawing of \f[I]Radiance\f[R] file |
436 |
T} |
437 |
T{ |
438 |
\f[B]objview\f[R] |
439 |
T} T{ |
440 |
T} T{ |
441 |
X |
442 |
T} T{ |
443 |
Quick view of \f[I]Radiance\f[R] object |
444 |
T} |
445 |
T{ |
446 |
\f[B]oconv\f[R] |
447 |
T} T{ |
448 |
T} T{ |
449 |
X |
450 |
T} T{ |
451 |
Compile \f[I]Radiance\f[R] scene description |
452 |
T} |
453 |
T{ |
454 |
\f[B]obj2rad\f[R] |
455 |
T} T{ |
456 |
T} T{ |
457 |
X |
458 |
T} T{ |
459 |
Convert Wavefront .OBJ file to \f[I]Radiance\f[R] |
460 |
T} |
461 |
T{ |
462 |
\f[B]rad\f[R] |
463 |
T} T{ |
464 |
X |
465 |
T} T{ |
466 |
T} T{ |
467 |
Render \f[I]Radiance\f[R] scene |
468 |
T} |
469 |
T{ |
470 |
\f[B]rad2mgf\f[R] |
471 |
T} T{ |
472 |
X |
473 |
T} T{ |
474 |
T} T{ |
475 |
Convert \f[I]Radiance\f[R] file to MGF |
476 |
T} |
477 |
T{ |
478 |
\f[B]raddepend\f[R] |
479 |
T} T{ |
480 |
X |
481 |
T} T{ |
482 |
T} T{ |
483 |
Determine scene file dependencies |
484 |
T} |
485 |
T{ |
486 |
\f[B]replmarks\f[R] |
487 |
T} T{ |
488 |
X |
489 |
T} T{ |
490 |
X |
491 |
T} T{ |
492 |
Replace triangular markers with objects |
493 |
T} |
494 |
T{ |
495 |
\f[B]rpict\f[R] |
496 |
T} T{ |
497 |
X |
498 |
T} T{ |
499 |
T} T{ |
500 |
Batch rendering program |
501 |
T} |
502 |
T{ |
503 |
\f[B]rtrace\f[R] |
504 |
T} T{ |
505 |
X |
506 |
T} T{ |
507 |
T} T{ |
508 |
Customizable ray-tracer |
509 |
T} |
510 |
T{ |
511 |
\f[B]rview\f[R] |
512 |
T} T{ |
513 |
X |
514 |
T} T{ |
515 |
T} T{ |
516 |
Interactive renderer |
517 |
T} |
518 |
T{ |
519 |
\f[B]thf2rad\f[R] |
520 |
T} T{ |
521 |
T} T{ |
522 |
X |
523 |
T} T{ |
524 |
Convert GDS things file to \f[I]Radiance\f[R] |
525 |
T} |
526 |
T{ |
527 |
\f[B]tmesh2rad\f[R] |
528 |
T} T{ |
529 |
T} T{ |
530 |
X |
531 |
T} T{ |
532 |
Convert triangle mesh file to \f[I]Radiance\f[R] |
533 |
T} |
534 |
T{ |
535 |
\f[B]xform\f[R] |
536 |
T} T{ |
537 |
X |
538 |
T} T{ |
539 |
X |
540 |
T} T{ |
541 |
Transform Radiance objects |
542 |
T} |
543 |
.TE |
544 |
.ad |
545 |
.LP |
546 |
\f[B]Table 1.\f[R] Radiance programs that read and write scene |
547 |
descriptions. |
548 |
.SH 3 |
549 |
\f[BI]Radiance\f[B] C Library |
550 |
.pdfhref O 3 "Radiance C Library" |
551 |
.pdfhref M "radiance-c-library" |
552 |
.LP |
553 |
The principal library function for reading scene description files is |
554 |
\f[C]readobj(inpspec)\f[R], defined in \f[C]src/common/readobj.c\f[R]. |
555 |
This routine takes the name of a file, or command beginning with `!', or |
556 |
\f[C]NULL\f[R] if standard input is to be read, and loads the |
557 |
\f[I]Radiance\f[R] data structures defined in |
558 |
\f[C]src/common/object.h\f[R]. |
559 |
If loading \f[I]Radiance\f[R] data structures is not the action desired, |
560 |
then a more custom approach is necessary, such as that used in |
561 |
\f[C]src/gen/xform.c\f[R]. |
562 |
If using \f[I]Radiance\f[R] data structures is acceptable, but the data |
563 |
need not remain resident in memory, then follow the lead in |
564 |
\f[C]src/ot/getbbox.c\f[R] and use \f[C]src/ot/readobj2.c\f[R] instead. |
565 |
In any case, the list of defined primitive types in |
566 |
\f[C]src/common/otypes.h\f[R] is crucial. |
567 |
.SH 2 |
568 |
Function File Format (.cal suffix) |
569 |
.pdfhref O 2 "Function File Format \(.cal suffix\)" |
570 |
.pdfhref M "function-file-format-.cal-suffix" |
571 |
.LP |
572 |
Function files are used throughout \f[I]Radiance\f[R] to specify |
573 |
mathematical formulas and relations for procedural textures, patterns |
574 |
and surfaces. |
575 |
They are also used by filter programs such as rcalc to manipulate data, |
576 |
and pcomb to manipulate pictures. |
577 |
.PP |
578 |
Function file syntax is simple and should be familiar to most |
579 |
programmers, as it is based on fairly standard algebraic expressions. |
580 |
Here is an example, which corresponds to the in-line commands given in |
581 |
the previous section: |
582 |
.IP |
583 |
.nf |
584 |
\f[C] |
585 |
{ |
586 |
basin.cal - calculate coordinates for basin sink. |
587 |
} |
588 |
|
589 |
theta(s) = PI*(0.5+0.5*s); |
590 |
phi(t) = 2*PI*t; |
591 |
|
592 |
R(th,p) = 5 + ( 3.25*cos(p)\[ha]2 + |
593 |
1.75*sin(p)\[ha]2 ) * sin(th)\[ha]2; |
594 |
|
595 |
x(th,p) = R(th,p)*sin(th)*cos(p); |
596 |
y(th,p) = R(th,p)*sin(th)*sin(p); |
597 |
z(th,p) = R(th,p)*cos(th); |
598 |
\f[] |
599 |
.fi |
600 |
.LP |
601 |
In contrast to the usual semantics in programs where each statement |
602 |
corresponds to an evaluation, statements in function files correspond to |
603 |
\f[I]definitions\f[R]. |
604 |
Once a function or variable has been defined, it may be used in later |
605 |
definitions, along with predefined functions such as \f[C]sin(x)\f[R] |
606 |
and \f[C]cos(x)\f[R] and constants such as PI \**. |
607 |
.FS |
608 |
TBD - There once was a footnote here |
609 |
.FE |
610 |
(All math functions use standard C conventions, hence trigonometry is |
611 |
done in radians rather than degrees.) |
612 |
.PP |
613 |
Evaluation order (operator precedence) follows standard rules of |
614 |
algebra. |
615 |
Exponentiation is performed first \f[C](x\[ha]y)\f[R], followed by |
616 |
multiplication and division \f[C](x*y, x/y)\f[R], then addition and |
617 |
subtraction \f[C](x+y, x-y)\f[R]. |
618 |
Unary minus is most tightly associated \f[C](-x)\f[R], and parentheses |
619 |
override operator precedence in the usual way. |
620 |
Semicolons separate statements, and white space is generally ignored. |
621 |
Comments are enclosed by curly braces, which may be nested. |
622 |
.PP |
623 |
The above file does not actually \f[I]do\f[R] anything, it merely |
624 |
defines functions that are useful by a program that does. |
625 |
Taking our \f[B]gensurf\f[R] example from the previous section: |
626 |
.IP |
627 |
.nf |
628 |
\f[C] |
629 |
!gensurf marble sink \[aq]15.5+x(theta(s),phi(t))\[aq] \[rs] |
630 |
\[aq]10.5+y(theta(s),phi(t))\[aq] \[rs] |
631 |
\[aq]30.75+z(theta(s),phi(t))\[aq] \[rs] |
632 |
8 29 -f basin.cal -s |
633 |
\f[] |
634 |
.fi |
635 |
.LP |
636 |
The \f[B]-f\f[R] option loads in our file, which is then used to |
637 |
evaluate expressions such as \f[C]15.5+x(theta(s),phi(t))\f[R] for |
638 |
specific values of \f[C]s\f[R] and \f[C]t\f[R]. |
639 |
These variables range from 0 to 1 over the surface patch in increments |
640 |
of @1 / 8@ and @1 / 29@, respectively. |
641 |
(See the \f[B]gensurf\f[R] manual page for details.) |
642 |
The entire expression for each evaluation could have been written in the |
643 |
command line, but it is much more convenient to create a function file. |
644 |
.SH 3 |
645 |
Language Features |
646 |
.pdfhref O 3 "Language Features" |
647 |
.pdfhref M "language-features" |
648 |
.LP |
649 |
Subtle features of the functional language provide much greater power |
650 |
than first meets the eye. |
651 |
One of these is the ability to define recursive functions. |
652 |
The following example defines the factorial function (\f[I]n!\f[R]): |
653 |
.IP |
654 |
.nf |
655 |
\f[C] |
656 |
fact(n) : if(n-1.5, n*fact(n-1), 1); |
657 |
\f[] |
658 |
.fi |
659 |
.LP |
660 |
This uses the library function \f[C]if(cond,e1,e0)\f[R], which returns |
661 |
\f[C]e1\f[R] if cond is greater than zero, and \f[C]e0\f[R] otherwise. |
662 |
Since only one of these expressions is evaluated, \f[C]fact(n)\f[R] will |
663 |
call itself until \f[C]n\f[R] is less than 2, when the \f[C]if\f[R] |
664 |
expression returns 1\**. |
665 |
.FS |
666 |
Note that we compare \f[C]n\f[R] to 1.5, so as to avoid any round-off |
667 |
problems caused by floating point math. |
668 |
Caution is advised because all expressions are evaluated as |
669 |
double-precision real, and comparisons to zero are unreliable. |
670 |
.FE |
671 |
The colon (`:') is used in place of the usual equals assignment (`=') |
672 |
because we want this function to have the constant attribute, which |
673 |
means any later appearance in an expression of \f[C]fact(ce)\f[R] where |
674 |
ce is also a constant expression will be replaced by its value. |
675 |
This can be an important savings in cases where an expression or |
676 |
subexpression is expensive to evaluate, and only needs to be computed |
677 |
once. |
678 |
All of the standard library functions have the constant attribute. |
679 |
(See the following section for a complete list.) |
680 |
.PP |
681 |
Another handy language feature is the ability to pass function names as |
682 |
arguments. |
683 |
A simple example of this is the following function, which computes the |
684 |
numerical derivative of a function given as its first argument: |
685 |
.IP |
686 |
.nf |
687 |
\f[C] |
688 |
FTINY : 1e-7; |
689 |
d1(f,x) = (f(x+FTINY)-f(x-FTINY))/FTINY/2; |
690 |
\f[] |
691 |
.fi |
692 |
.LP |
693 |
Evaluating \f[C]d1(sin,1.1)\f[R] using this formula yields 0.4536, which |
694 |
is fairly close to the true derivative, which is \f[C]cos(1.1)\f[R]. |
695 |
.PP |
696 |
A third language feature, which is normally transparent to the user, is |
697 |
the notion of \f[I]contexts\f[R]. |
698 |
Identifiers may be composed of parts, starting with a name and |
699 |
continuing with one or more context names. |
700 |
Each name is delimited by a back-quote (`\[ga]'). |
701 |
Names themselves begin with a letter and continue with any sequence of |
702 |
letters, digits, underscores and decimal points. |
703 |
The following are examples of valid identifiers: |
704 |
.IP |
705 |
.nf |
706 |
\f[C] |
707 |
v1, V.W, x_rand\[ga]local, \[ga]A_, Qa_5\[ga] |
708 |
\f[] |
709 |
.fi |
710 |
.LP |
711 |
If a context mark appears at the beginning of the identifier, then its |
712 |
reference must be local. |
713 |
If it appears at the end, then its reference must be global. |
714 |
A local reference must be resolved in the local context, i.e., no |
715 |
contexts above this one will be searched. |
716 |
A global reference must correspond to the original context, ignoring any |
717 |
local redefinitions. |
718 |
.PP |
719 |
The reason that contexts are normally transparent is that they are |
720 |
controlled by the calling program \[em] there are no explicit language |
721 |
features for establishing contexts. |
722 |
A new context is established automatically for each function file loaded |
723 |
by the rendering programs. |
724 |
That way, it is safe to reuse variable names that have been used in |
725 |
other files, and even in the main initialization file, |
726 |
\f[C]rayinit.cal\f[R]. |
727 |
.PP |
728 |
Although not strictly necessary, there are two good reasons to define |
729 |
variables and functions before referencing them in a function file. |
730 |
One is related to contexts. |
731 |
If a previous definition of a variable name is given in an enclosing |
732 |
context (e.g., \f[C]rayinit.cal\f[R]), then that reference will be used |
733 |
rather than a later one in the current context, unless the reference is |
734 |
made explicitly local by starting the identifier with a context mark. |
735 |
The second reason for defining before referencing is constant |
736 |
expressions. |
737 |
If a variable or function has the constant attribute (i.e., defined with |
738 |
`:' instead of `='), then a later subexpression referencing it can be |
739 |
replaced by its evaluated result during compilation. |
740 |
If the constant is not defined until after it is referenced, it remains |
741 |
as a reference, which takes time to evaluate each time. |
742 |
.PP |
743 |
Other features of the language are truly transparent, but knowledge of |
744 |
them can help one to write more efficient function files: |
745 |
.IP \[bu] 3 |
746 |
Once a variable has been evaluated, the result is cached and it is not |
747 |
reevaluated unless the client program changes an internal counter |
748 |
(\f[C]eclock\f[R]), which indicates that something has changed. |
749 |
This means that using variables to hold frequently used values will not |
750 |
only simplify the function file, it will save time during evaluation. |
751 |
.IP \[bu] 3 |
752 |
An argument passed in a function call is not evaluated until the |
753 |
function calls for it specifically, and the result is also cached to |
754 |
avoid redundant calculation. |
755 |
The conditional evaluation feature is actually a requirement for |
756 |
recursive functions to work, but caching is not. |
757 |
Argument value caching means it is more efficient to pass an |
758 |
expensive-to-compute expression than to have the function compute it |
759 |
internally if it appears more than once in the function definition. |
760 |
This is especially true for recursive functions with deep call trees. |
761 |
.SH 3 |
762 |
Standard Definitions (Library) |
763 |
.pdfhref O 3 "Standard Definitions \(Library\)" |
764 |
.pdfhref M "standard-definitions-library" |
765 |
.LP |
766 |
The following are always defined: |
767 |
.IP "\f[B]\f[CB]if(a, b, c)\f[B]\f[R]" 3 |
768 |
Conditional expression. |
769 |
If a is positive, return b, else return c. |
770 |
.RS 3 |
771 |
.RE |
772 |
.IP "\f[B]\f[CB]select(N, a1, a2, ..)\f[B]\f[R]" 3 |
773 |
Return Nth argument. |
774 |
If N is 0, then return the count of arguments excluding the first. |
775 |
This provides basic array functionality. |
776 |
.RS 3 |
777 |
.RE |
778 |
.IP "\f[B]\f[CB]sqrt(x)\f[B]\f[R]" 3 |
779 |
Return square root of \f[C]x\f[R], where \f[C]x >= 0\f[R]. |
780 |
.RS 3 |
781 |
.RE |
782 |
.IP "\f[B]\f[CB]sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x)\f[B]\f[R]" 3 |
783 |
Standard trigonometry functions. |
784 |
.RS 3 |
785 |
.RE |
786 |
.IP "\f[B]\f[CB]floor(x), ceil(x)\f[B]\f[R]" 3 |
787 |
Greatest lower bound and least upper bound (integer). |
788 |
.RS 3 |
789 |
.RE |
790 |
.IP "\f[B]\f[CB]exp(x), log(x), log10(x)\f[B]\f[R]" 3 |
791 |
Exponent and logarithm functions. |
792 |
.RS 3 |
793 |
.RE |
794 |
.IP "\f[B]\f[CB]rand(x)\f[B]\f[R]" 3 |
795 |
Return pseudo-random number in the range [0,1) for any argument x. |
796 |
The same return value is guaranteed for the same argument. |
797 |
.RS 3 |
798 |
.RE |
799 |
.LP |
800 |
The following are sometimes defined, depending on the program: |
801 |
.IP "\f[B]PI\f[R]" 3 |
802 |
The ratio of a circle\[cq]s circumference to its diameter. |
803 |
.RS 3 |
804 |
.RE |
805 |
.IP "\f[B]\f[CB]erf(z), erfc(z)\f[B]\f[R]" 3 |
806 |
Error function and complimentary error function. |
807 |
.RS 3 |
808 |
.RE |
809 |
.IP "\f[B]\f[CB]j0(x), j1(x), jn(n,x), y0(x), y1(x), yn(n,x)\f[B]\f[R]" 3 |
810 |
Bessel functions. |
811 |
.RS 3 |
812 |
.RE |
813 |
.IP "\f[B]\f[CB]hermite(p0,p1,r0,r1,t)\f[B]\f[R]" 3 |
814 |
One-dimensional Hermite polynomial. |
815 |
.RS 3 |
816 |
.RE |
817 |
.LP |
818 |
The rendering programs also define the following noise functions: |
819 |
.IP "\f[B]\f[CB]noise3(x,y,z), noise3x(x,y,z), noise3y(x,y,z), noise3z(x,y,z)\f[B]\f[R]" 3 |
820 |
Perlin noise function and its gradient [Perlin85][Arvo91,p.396]. |
821 |
.RS 3 |
822 |
.RE |
823 |
.IP "\f[B]\f[CB]fnoise3(x,y,z)\f[B]\f[R]" 3 |
824 |
Fractal noise function, ranging from -1 to 1. |
825 |
.RS 3 |
826 |
.RE |
827 |
.LP |
828 |
Interaction with the renderer is achieved via special purpose variables |
829 |
and functions whose values correspond to the current ray intersection |
830 |
and the calling primitive. |
831 |
Unlike the above functions, none of these have the constant attribute |
832 |
since their values change from one ray to the next: |
833 |
.IP "\f[B]\f[CB]Dx, Dy, Dz\f[B]\f[R]" 3 |
834 |
ray direction |
835 |
.RS 3 |
836 |
.RE |
837 |
.IP "\f[B]\f[CB]Nx, Ny, Nz\f[B]\f[R]" 3 |
838 |
surface normal |
839 |
.RS 3 |
840 |
.RE |
841 |
.LP |
842 |
\f[C]Px, Py, Pz\f[R] :intersection point |
843 |
.IP "\f[B]\f[CB]T\f[B]\f[R]" 3 |
844 |
distance from start |
845 |
.RS 3 |
846 |
.RE |
847 |
.IP "\f[B]\f[CB]Ts\f[B]\f[R]" 3 |
848 |
single ray (shadow) distance |
849 |
.RS 3 |
850 |
.RE |
851 |
.IP "\f[B]\f[CB]Rdot\f[B]\f[R]" 3 |
852 |
ray dot product |
853 |
.RS 3 |
854 |
.RE |
855 |
.IP "\f[B]\f[CB]S\f[B]\f[R]" 3 |
856 |
world scale |
857 |
.RS 3 |
858 |
.RE |
859 |
.IP "\f[B]\f[CB]Tx, Ty, Tz\f[B]\f[R]" 3 |
860 |
world origin |
861 |
.RS 3 |
862 |
.RE |
863 |
.IP "\f[B]\f[CB]Ix, Iy, Iz\f[B]\f[R]" 3 |
864 |
world i unit vector |
865 |
.RS 3 |
866 |
.RE |
867 |
.IP "\f[B]\f[CB]Jx, Jy, Jz\f[B]\f[R]" 3 |
868 |
world j unit vector |
869 |
.RS 3 |
870 |
.RE |
871 |
.IP "\f[B]\f[CB]Kx, Ky, Kz\f[B]\f[R]" 3 |
872 |
world k unit vector |
873 |
.RS 3 |
874 |
.RE |
875 |
.IP "\f[B]\f[CB]arg(n)\f[B]\f[R]" 3 |
876 |
real arguments, arg(0) is count |
877 |
.RS 3 |
878 |
.RE |
879 |
.LP |
880 |
For BRDF primitives, the following variables are also available: |
881 |
.IP "\f[B]\f[CB]NxP, NyP, NzP\f[B]\f[R]" 3 |
882 |
perturbed surface normal |
883 |
.RS 3 |
884 |
.RE |
885 |
.IP "\f[B]\f[CB]RdotP\f[B]\f[R]" 3 |
886 |
perturbed ray dot product |
887 |
.RS 3 |
888 |
.RE |
889 |
.IP "\f[B]\f[CB]CrP, CgP, CbP\f[B]\f[R]" 3 |
890 |
perturbed material color |
891 |
.RS 3 |
892 |
.RE |
893 |
.LP |
894 |
For prism1 and prism2 primitives, the following are available: |
895 |
.IP "\f[B]\f[CB]DxA, DyA, DzA\f[B]\f[R]" 3 |
896 |
direction to target light source |
897 |
.RS 3 |
898 |
.RE |
899 |
.LP |
900 |
Other functions, variables and constants are defined as well in the file |
901 |
\f[C]src/rt/rayinit.cal\f[R], which gets installed in the standard |
902 |
\f[I]Radiance\f[R] library directory and can be modified or appended as |
903 |
desired\**. |
904 |
.FS |
905 |
It is usually a good idea to store any such customized files in a |
906 |
personal library location and set the \f[C]RAYPATH\f[R] environment |
907 |
variable to search there first. |
908 |
This way, it does not affect other users or get overwritten during the |
909 |
next system installation. |
910 |
.FE |
911 |
.SH 3 |
912 |
\f[BI]Radiance\f[B] Programs |
913 |
.pdfhref O 3 "Radiance Programs" |
914 |
.pdfhref M "radiance-programs-1" |
915 |
.LP |
916 |
Table 2 shows \f[I]Radiance\f[R] programs that read and write function |
917 |
files. |
918 |
.PP |
919 |
.na |
920 |
.TS |
921 |
delim(@@) tab( ); |
922 |
l l l l. |
923 |
T{ |
924 |
Program |
925 |
T} T{ |
926 |
Read |
927 |
T} T{ |
928 |
Write |
929 |
T} T{ |
930 |
Function |
931 |
T} |
932 |
_ |
933 |
T{ |
934 |
\f[B]calc\f[R] |
935 |
T} T{ |
936 |
X |
937 |
T} T{ |
938 |
X |
939 |
T} T{ |
940 |
Interactive calculator |
941 |
T} |
942 |
T{ |
943 |
\f[B]genrev\f[R] |
944 |
T} T{ |
945 |
X |
946 |
T} T{ |
947 |
T} T{ |
948 |
Generate surface of revolution |
949 |
T} |
950 |
T{ |
951 |
\f[B]gensurf\f[R] |
952 |
T} T{ |
953 |
X |
954 |
T} T{ |
955 |
T} T{ |
956 |
Generate arbitrary surface patch |
957 |
T} |
958 |
T{ |
959 |
\f[B]genworm\f[R] |
960 |
T} T{ |
961 |
X |
962 |
T} T{ |
963 |
T} T{ |
964 |
Generate varying diameter curved path |
965 |
T} |
966 |
T{ |
967 |
\f[B]macbethcal\f[R] |
968 |
T} T{ |
969 |
T} T{ |
970 |
X |
971 |
T} T{ |
972 |
Compute image color & contrast correction |
973 |
T} |
974 |
T{ |
975 |
\f[B]pcomb\f[R] |
976 |
T} T{ |
977 |
X |
978 |
T} T{ |
979 |
T} T{ |
980 |
Perform arbitrary math on picture(s) |
981 |
T} |
982 |
T{ |
983 |
\f[B]rcalc\f[R] |
984 |
T} T{ |
985 |
X |
986 |
T} T{ |
987 |
T} T{ |
988 |
Record stream calculator |
989 |
T} |
990 |
T{ |
991 |
\f[B]rpict\f[R] |
992 |
T} T{ |
993 |
X |
994 |
T} T{ |
995 |
T} T{ |
996 |
Batch rendering program |
997 |
T} |
998 |
T{ |
999 |
\f[B]rtrace\f[R] |
1000 |
T} T{ |
1001 |
X |
1002 |
T} T{ |
1003 |
T} T{ |
1004 |
Customizable ray-tracer |
1005 |
T} |
1006 |
T{ |
1007 |
\f[B]rview\f[R] |
1008 |
T} T{ |
1009 |
X |
1010 |
T} T{ |
1011 |
T} T{ |
1012 |
Interactive renderer |
1013 |
T} |
1014 |
T{ |
1015 |
\f[B]tabfunc\f[R] |
1016 |
T} T{ |
1017 |
T} T{ |
1018 |
X |
1019 |
T} T{ |
1020 |
Create function file from tabulated data |
1021 |
T} |
1022 |
.TE |
1023 |
.ad |
1024 |
.LP |
1025 |
\f[B]Table 2.\f[R] Programs in the \f[I]Radiance\f[R] distribution that |
1026 |
read and write function files. |
1027 |
.PP |
1028 |
In addition, the program \f[B]ev\f[R] evaluates expressions given as |
1029 |
command line arguments, though it does not handle function files or |
1030 |
definitions. |
1031 |
There are also a number of 2-d plotting routines that use a slightly |
1032 |
modified statement syntax, called \f[B]bgraph\f[R], \f[B]dgraph\f[R], |
1033 |
\f[B]gcomp\f[R], and \f[B]igraph\f[R]. |
1034 |
Additional utility programs are useful in combination with rcalc for |
1035 |
data analysis and scene generation. |
1036 |
The program \f[B]cnt\f[R] generates simple records to drive |
1037 |
\f[B]rcalc\f[R], and the \f[B]total\f[R] program is handy for adding up |
1038 |
results. |
1039 |
The \f[B]histo\f[R] program computes histograms needed for certain types |
1040 |
of statistical analysis. |
1041 |
The \f[B]lam\f[R] program concatenates columns from multiple input |
1042 |
files, and \f[B]neat\f[R] neatens up columns for better display. |
1043 |
.SH 3 |
1044 |
\f[BI]Radiance\f[B] C Library |
1045 |
.pdfhref O 3 "Radiance C Library" |
1046 |
.pdfhref M "radiance-c-library-1" |
1047 |
.LP |
1048 |
The standard routines for loading and evaluating function files are |
1049 |
divided into three modules, \f[C]src/common/calexpr.c\f[R] for |
1050 |
expression parsing and evaluation, \f[C]src/common/caldefn.c\f[R] for |
1051 |
variable and function storage and lookup, and |
1052 |
\f[C]src/common/calfunc.c\f[R] for library function storage and function |
1053 |
evaluation. |
1054 |
There is a fourth module for writing out expressions called |
1055 |
\f[C]src/common/calprnt.c\f[R], which we will not discuss. |
1056 |
They all use the header file \f[C]src/common/calcomp.h\f[R], which |
1057 |
defines common data structures and evaluation macros. |
1058 |
Of these, the three most often used declarations for external routines |
1059 |
are: |
1060 |
.IP "\f[B]\f[CB]typedef struct epnode EPNODE;\f[B]\f[R]" 3 |
1061 |
Expression parse tree node. |
1062 |
Some routines return pointers to this structure type, and the main |
1063 |
evaluation macro, \f[C]evalue(ep)\f[R], takes an argument of this type. |
1064 |
.RS 3 |
1065 |
.RE |
1066 |
.IP "\f[B]\f[CB](double) evalue(ep);\f[B]\f[R]" 3 |
1067 |
Evaluate an expression parse tree. |
1068 |
Uses node type table to access appropriate function depending on root |
1069 |
node type. |
1070 |
(E.g., an addition node calls \f[C]eadd(ep)\f[R].) |
1071 |
.RS 3 |
1072 |
.RE |
1073 |
.IP "\f[B]\f[CB]extern unsigned long eclock;\f[B]\f[R]" 3 |
1074 |
This is a counter used to determine when variable values need updating. |
1075 |
The initial value is 0, which tells the routines always to reevaluate |
1076 |
variables. |
1077 |
Once incremented to 1, variable evaluations are cached and not |
1078 |
recomputed until \f[C]eclock\f[R] is incremented again. |
1079 |
Usually, client programs increment \f[C]eclock\f[R] each time |
1080 |
definitions or internal states affecting returned values change. |
1081 |
This assures the quickest evaluation of correct results. |
1082 |
.RS 3 |
1083 |
.RE |
1084 |
.LP |
1085 |
The usual approach to handling definitions is to compile them into the |
1086 |
central lookup table; variable and function references are later |
1087 |
evaluated by traversing the stored parse trees. |
1088 |
Syntax errors and undefined symbol errors during evaluation result in |
1089 |
calls to the user-definable routine \f[C]eputs(s)\f[R] to report the |
1090 |
error and \f[C]quit(status)\f[R] to exit the program. |
1091 |
Domain and range errors during evaluation set \f[C]errno\f[R], then call |
1092 |
the user-definable routine \f[C]wputs(s)\f[R] to report the error and |
1093 |
return zero as the expression result. |
1094 |
Following are standard routines provided for parsing from a file and |
1095 |
parsing from a string: |
1096 |
.IP "\f[B]\f[CB]EPNODE *eparse(char *expr);\f[B]\f[R]" 3 |
1097 |
Compile the string expr into a parse tree for later evaluation with |
1098 |
evalue(ep). |
1099 |
.RS 3 |
1100 |
.RE |
1101 |
.IP "\f[B]\f[CB]epfree(EPNODE *ep);\f[B]\f[R]" 3 |
1102 |
Free memory associated with ep, including any variables referenced if |
1103 |
they are no longer defined. |
1104 |
.RS 3 |
1105 |
.RE |
1106 |
.IP "\f[B]\f[CB]double eval(char *expr);\f[B]\f[R]" 3 |
1107 |
Immediately parse, evaluate and free the given string expression. |
1108 |
.RS 3 |
1109 |
.RE |
1110 |
.IP "\f[B]\f[CB]fcompile(char *fname);\f[B]\f[R]" 3 |
1111 |
Compile definitions from the given file, or standard input if fname is |
1112 |
NULL. |
1113 |
.RS 3 |
1114 |
.RE |
1115 |
.IP "\f[B]\f[CB]scompile(char *str, char *fn, int ln);\f[B]\f[R]" 3 |
1116 |
Compile definitions from the string str, taken from file fn at line |
1117 |
number ln. |
1118 |
If no file is associated, fn can be NULL, and ln can be 0. |
1119 |
.RS 3 |
1120 |
.RE |
1121 |
.LP |
1122 |
The following routines allow one to control the current context for |
1123 |
definition lookup and storage: |
1124 |
.IP "\f[B]\f[CB]char *setcontext(char *ctx);\f[B]\f[R]" 3 |
1125 |
Set the current context to ctx. |
1126 |
If ctx is NULL, then simply return the current context. |
1127 |
An empty string sets the global context. |
1128 |
.RS 3 |
1129 |
.RE |
1130 |
.IP "\f[B]\f[CB]char *pushcontext(char *name);\f[B]\f[R]" 3 |
1131 |
Push another context onto the stack. |
1132 |
Return the new (full) context. |
1133 |
.RS 3 |
1134 |
.RE |
1135 |
.IP "\f[B]\f[CB]char *popcontext();\f[B]\f[R]" 3 |
1136 |
Pop the top context name off the stack. |
1137 |
Return the new (full) context. |
1138 |
.RS 3 |
1139 |
.RE |
1140 |
.LP |
1141 |
The following functions permit the explicit setting of variable and |
1142 |
function values: |
1143 |
.IP "\f[B]\f[CB]varset(char *vname, int assign, double val);\f[B]\f[R]" 3 |
1144 |
Set the specified variable to the given value, using a constant |
1145 |
assignment if assign is `:' or a regular one if it is `='. |
1146 |
This is always faster than compiling a string to do the same thing. |
1147 |
.RS 3 |
1148 |
.RE |
1149 |
.IP "\f[B]\f[CB]funset(char *fname, int nargs, int assign, double (*fptr)(char *fn));\f[B]\f[R]" 3 |
1150 |
Assign the specified library function, which takes a minimum of nargs |
1151 |
arguments. |
1152 |
The function will have the constant attribute if assign is `:', or not |
1153 |
if it is `='. |
1154 |
The only argument to the referenced function pointer is the function |
1155 |
name, which will equal fname. |
1156 |
(This string must therefore be declared static.) |
1157 |
This offers a convenient method to identify calls to an identical |
1158 |
function assigned multiple tasks. |
1159 |
Argument values are obtained with calls back to the argument(n) library |
1160 |
function. |
1161 |
.RS 3 |
1162 |
.RE |
1163 |
.LP |
1164 |
The following functions are provided for evaluating a function or |
1165 |
variable in the current definition set: |
1166 |
.IP "\f[B]\f[CB]double varvalue(char *vname);\f[B]\f[R]" 3 |
1167 |
Evaluate the given variable and return the result. |
1168 |
Since a hash lookup is necessary to resolve the reference, this is |
1169 |
slightly less efficient than evaluating a compiled expression via |
1170 |
evalue(ep), which uses soft links generated and maintained during |
1171 |
compilation. |
1172 |
.RS 3 |
1173 |
.RE |
1174 |
.IP "\f[B]\f[CB]double funvalue(char *fn, int n, double a);\f[B]\f[R]" 3 |
1175 |
Evaluate the function fn, passing n real arguments in the array a. |
1176 |
There is currently no mechanism for passing functions or function name |
1177 |
arguments from client programs. |
1178 |
.RS 3 |
1179 |
.RE |
1180 |
.LP |
1181 |
These routines can be used to check the existence of a specific function |
1182 |
or variable: |
1183 |
.IP "\f[B]\f[CB]int vardefined(char *vname);\f[B]\f[R]" 3 |
1184 |
Return non-zero if the named variable is defined. |
1185 |
(If the symbol is defined as a function, zero is returned.) |
1186 |
.RS 3 |
1187 |
.RE |
1188 |
.IP "\f[B]\f[CB]int fundefined(char *fname);\f[B]\f[R]" 3 |
1189 |
Return the number of required arguments for the named function if it is |
1190 |
defined, or zero if it is not defined. |
1191 |
(If the symbol is defined as a variable, zero is returned.) |
1192 |
.RS 3 |
1193 |
.RE |
1194 |
.LP |
1195 |
These routines allow definitions to be cleared: |
1196 |
.IP "\f[B]\f[CB]dclear(char *dname);\f[B]\f[R]" 3 |
1197 |
Clear the given variable or function, unless it is a constant |
1198 |
expression. |
1199 |
.RS 3 |
1200 |
.RE |
1201 |
.IP "\f[B]\f[CB]dremove(char *dname);\f[B]\f[R]" 3 |
1202 |
Clear the given variable or function, even if it is a constant |
1203 |
expression. |
1204 |
Library definitions cannot be removed, except by calling funset with a |
1205 |
\f[C]NULL\f[R] pointer for the function argument. |
1206 |
.RS 3 |
1207 |
.RE |
1208 |
.IP "\f[B]\f[CB]dcleanup(int level);\f[B]\f[R]" 3 |
1209 |
Clear definitions. |
1210 |
If level is 0, then just clear variable definitions. |
1211 |
If level is 2, then clear constants as well. |
1212 |
If the current context is local, then only local definitions will be |
1213 |
affected. |
1214 |
If global, all definitions in all contexts will be affected. |
1215 |
.RS 3 |
1216 |
.RE |
1217 |
.LP |
1218 |
These routines may be used during library function evaluation: |
1219 |
.IP "\f[B]\f[CB]int nargum();\f[B]\f[R]" 3 |
1220 |
Determine the number of arguments available in the current function |
1221 |
evaluation context. |
1222 |
.RS 3 |
1223 |
.RE |
1224 |
.IP "\f[B]\f[CB]double argument(int n);\f[B]\f[R]" 3 |
1225 |
Evaluate and return the nth argument. |
1226 |
.RS 3 |
1227 |
.RE |
1228 |
.IP "\f[B]\f[CB]char *argfun(n);\f[B]\f[R]" 3 |
1229 |
Get the name of the function passed as argument n.\ (Generates an error |
1230 |
if the nth argument is not a function.) |
1231 |
.RS 3 |
1232 |
.RE |
1233 |
.LP |
1234 |
Other, even more specialized routines are provided for controlling the |
1235 |
parsing process, printing out expressions and sifting through stored |
1236 |
definitions, but these are not accessed by most client programs. |
1237 |
Worth noting are the various compile flags that affect which features of |
1238 |
the expression language are included. |
1239 |
The standard library sets the flags \f[C]-DVARIABLE\f[R], |
1240 |
\f[C]-DFUNCTION\f[R], \f[C]-DRCONST\f[R], and \f[C]-DBIGLIB\f[R]. |
1241 |
Here is a list of compile flags and their meanings: |
1242 |
.IP "\f[B]\f[CB]-DVARIABLE\f[B]\f[R]" 3 |
1243 |
Allow user-defined variables and (if \f[C]-DFUNCTION\f[R]) user- defined |
1244 |
functions. |
1245 |
.RS 3 |
1246 |
.RE |
1247 |
.IP "\f[B]\f[CB]-DFUNCTION\f[B]\f[R]" 3 |
1248 |
Compile in library functions and (if \f[C]-DVARIABLE\f[R]) allow |
1249 |
user-supplied function definitions. |
1250 |
.RS 3 |
1251 |
.RE |
1252 |
.IP "\f[B]\f[CB]-DBIGLIB\f[B]\f[R]" 3 |
1253 |
Include larger library of standard functions, i.e., standard C math |
1254 |
library. |
1255 |
Otherwise, only minimal library is compiled in, and other functions may |
1256 |
be added using \f[C]funset\f[R]. |
1257 |
.RS 3 |
1258 |
.RE |
1259 |
.IP "\f[B]\f[CB]-DRCONST\f[B]\f[R]" 3 |
1260 |
Reduce constant subexpressions during compilation. |
1261 |
This can result in substantial savings during later evaluation, but the |
1262 |
original user-supplied expressions are lost. |
1263 |
.RS 3 |
1264 |
.RE |
1265 |
.IP "\f[B]\f[CB]-DREDEFW\f[B]\f[R]" 3 |
1266 |
Issue a warning via \f[C]wputs(s)\f[R] if a new definition hides a |
1267 |
constant definition or library function, or replaces an existing, |
1268 |
distinct definition for the same symbol. |
1269 |
(The \f[C]varset\f[R] routine never generates warnings, however.) |
1270 |
.RS 3 |
1271 |
.RE |
1272 |
.IP "\f[B]\f[CB]-DINCHAN\f[B]\f[R]" 3 |
1273 |
Provide for \f[C]\[rs]$N\f[R] syntax for input channels, which result in |
1274 |
callbacks to client-supplied chanvalue(n) routine on each evaluation. |
1275 |
.RS 3 |
1276 |
.RE |
1277 |
.IP "\f[B]\f[CB]-DOUTCHAN\f[B]\f[R]" 3 |
1278 |
Provide for \f[C]\[rs]$N\f[R] lvalue syntax for output channels, which |
1279 |
are evaluated via the chanout(cs) library function, which calls |
1280 |
\f[C](*cs)(n, value)\f[R]for each assigned channel definition. |
1281 |
.RS 3 |
1282 |
.RE |
1283 |
.SH 2 |
1284 |
Data File Format (.dat suffix) |
1285 |
.pdfhref O 2 "Data File Format \(.dat suffix\)" |
1286 |
.pdfhref M "data-file-format-.dat-suffix" |
1287 |
.LP |
1288 |
Although it is possible to store tabular data in a function file using |
1289 |
the select library function, it is more convenient and efficient to |
1290 |
devote a special file format to this purpose. |
1291 |
\f[I]Radiance\f[R] data files store scalar values on an N-dimensional |
1292 |
rectangular grid. |
1293 |
Grid (independent) axes may be regularly or irregularly divided, as |
1294 |
shown in Figure 1. |
1295 |
This data is interpolated during rendering (using N-dimensional linear |
1296 |
interpolation) to compute the desired values. |
1297 |
.PSPIC "figure1.eps" |
1298 |
.ce 1000 |
1299 |
Division of axes in .dat file |
1300 |
.ce 0 |
1301 |
.PP |
1302 |
\f[B]Figure 1.\f[R] A 2-dimensional grid with one regularly divided axis |
1303 |
and one irregularly divided axis. |
1304 |
Each intersection corresponds to a data value that appears in the file. |
1305 |
.PP |
1306 |
Data files are broken into two sections, the header and the body. |
1307 |
The header specifies the grid, and the body contains the data values in |
1308 |
a standard order. |
1309 |
The first value in the file is a positive integer indicating the number |
1310 |
of dimensions. |
1311 |
Next comes that number of axis specifications, in one of two formats. |
1312 |
For a regularly divided axis, the starting and ending value is given, |
1313 |
followed by the number of divisions. |
1314 |
For an irregularly divided axis, two zeros are followed by the number of |
1315 |
divisions then that number of division values. |
1316 |
The two zeros are merely there to indicate an irregular spacing is being |
1317 |
specified. |
1318 |
Once all the axes have been given, the header is done and the body of |
1319 |
the file begins, which consists of one data value after another. |
1320 |
The ordering of the data is such that the last axis given is the one |
1321 |
being traversed most rapidly, similar to a static array assignment in C. |
1322 |
.PP |
1323 |
A file corresponding to the topology shown in Figure 1 is: |
1324 |
.IP |
1325 |
.nf |
1326 |
\f[C] |
1327 |
######### Header ######## |
1328 |
2 # Two-dimensional data array |
1329 |
0.5 0.1 5 # The regularly spaced axis |
1330 |
0 0 5 3 5 10 16 20 # The irregularly spaced axis |
1331 |
########## Body ######### |
1332 |
# The data values, starting with the |
1333 |
# upper left, moving right then down: |
1334 |
19.089 7.001 14.647 6.3671 8.0003 |
1335 |
3.8388 11.873 19.294 16.605 2.7435 |
1336 |
16.699 6.387 2.8123 16.195 17.615 |
1337 |
14.36 14.413 16.184 15.635 4.5403 |
1338 |
3.6740 14.550 10.332 15.932 1.2678 |
1339 |
\f[] |
1340 |
.fi |
1341 |
.LP |
1342 |
Comments begin with a pound sign (`#') and continue to the end of the |
1343 |
line. |
1344 |
White space is ignored except as a data separator, thus the position of |
1345 |
header and data values on each line is irrelevant except to improve |
1346 |
readability. |
1347 |
.SH 3 |
1348 |
\f[BI]Radiance\f[B] Programs |
1349 |
.pdfhref O 3 "Radiance Programs" |
1350 |
.pdfhref M "radiance-programs-2" |
1351 |
.LP |
1352 |
Table 3 shows \f[I]Radiance\f[R] programs that read and write data |
1353 |
files. |
1354 |
.PP |
1355 |
.na |
1356 |
.TS |
1357 |
delim(@@) tab( ); |
1358 |
l l l l. |
1359 |
T{ |
1360 |
Program |
1361 |
T} T{ |
1362 |
Read |
1363 |
T} T{ |
1364 |
Write |
1365 |
T} T{ |
1366 |
Function |
1367 |
T} |
1368 |
_ |
1369 |
T{ |
1370 |
\f[B]ies2rad\f[R] |
1371 |
T} T{ |
1372 |
T} T{ |
1373 |
X |
1374 |
T} T{ |
1375 |
Convert IES luminaire file to \f[I]Radiance\f[R] |
1376 |
T} |
1377 |
T{ |
1378 |
\f[B]mgf2rad\f[R] |
1379 |
T} T{ |
1380 |
T} T{ |
1381 |
X |
1382 |
T} T{ |
1383 |
Convert MGF file to \f[I]Radiance\f[R] |
1384 |
T} |
1385 |
T{ |
1386 |
\f[B]rpict\f[R] |
1387 |
T} T{ |
1388 |
X |
1389 |
T} T{ |
1390 |
T} T{ |
1391 |
Batch rendering program |
1392 |
T} |
1393 |
T{ |
1394 |
\f[B]rtrace\f[R] |
1395 |
T} T{ |
1396 |
X |
1397 |
T} T{ |
1398 |
T} T{ |
1399 |
Customizable ray-tracer |
1400 |
T} |
1401 |
T{ |
1402 |
\f[B]rview\f[R] |
1403 |
T} T{ |
1404 |
X |
1405 |
T} T{ |
1406 |
T} T{ |
1407 |
Interactive renderer |
1408 |
T} |
1409 |
.TE |
1410 |
.ad |
1411 |
.LP |
1412 |
\f[B]Table 3.\f[R] Programs in the \f[I]Radiance\f[R] distribution that |
1413 |
read and write data files. |
1414 |
.SH 3 |
1415 |
\f[BI]Radiance\f[B] C Library |
1416 |
.pdfhref O 3 "Radiance C Library" |
1417 |
.pdfhref M "radiance-c-library-2" |
1418 |
.LP |
1419 |
The header file \f[C]src/rt/data.h\f[R] gives the standard data |
1420 |
structures used by the routines in \f[C]src/rt/data.c\f[R] for reading |
1421 |
and interpolating data files. |
1422 |
The main data type is \f[C]DATARRAY\f[R], which is a structure |
1423 |
containing the grid specification and a pointer to the data array, which |
1424 |
is of the type \f[C]DATATYPE\f[R] (normally \f[B]float\f[R] to save |
1425 |
space). |
1426 |
.PP |
1427 |
The main routine for reading data files is \f[C]getdata(dname)\f[R], |
1428 |
which searches the standard \f[I]Radiance\f[R] library locations set by |
1429 |
the \f[C]RAYPATH\f[R] environment variable. |
1430 |
The return value is a pointer to the loaded \f[C]DATARRAY\f[R], which |
1431 |
may have been loaded by a previous call. |
1432 |
(The routine keeps a hash table of loaded files to minimize time and |
1433 |
memory requirements.) |
1434 |
The \f[C]freedata(dname)\f[R] routine frees memory associated with the |
1435 |
named data file, or all data arrays if \f[C]dname\f[R] is |
1436 |
\f[C]NULL\f[R]. |
1437 |
.PP |
1438 |
The routine that interpolates data values is \f[C]datavalue(dp,pt)\f[R], |
1439 |
which takes a \f[C]DATARRAY\f[R] pointer and an array of |
1440 |
\f[B]double\f[R]s of the appropriate length (the number of dimensions in |
1441 |
\f[C]dp\f[R]). |
1442 |
The \f[B]double\f[R] returned is the interpolated value at that point in |
1443 |
the scalar field. |
1444 |
If the requested point lies outside the data\[cq]s grid, it is |
1445 |
extrapolated from the perimeter values up to a distance of one division |
1446 |
in each dimension, and falls off harmonically to zero outside of that. |
1447 |
This was selected as the most robust compromise, but to be safe it is |
1448 |
generally best to avoid giving out-of-domain points to |
1449 |
\f[C]datavalue\f[R]. |
1450 |
.SH 2 |
1451 |
Font File Format (.fnt suffix) |
1452 |
.pdfhref O 2 "Font File Format \(.fnt suffix\)" |
1453 |
.pdfhref M "font-file-format-.fnt-suffix" |
1454 |
.LP |
1455 |
Font files are used for text patterns and mixtures, and by the |
1456 |
\f[B]psign\f[R] program to generate simple text labels. |
1457 |
Each character glyph is set up on a simple rectangular coordinate system |
1458 |
running from [0,255] in x and y, and the glyph itself is a polygon. |
1459 |
Figure 2 shows an example of the letter \[lq]A\[rq]. |
1460 |
.PSPIC "figure2.eps" |
1461 |
.ce 1000 |
1462 |
Drawing of an A, based on coordinates |
1463 |
.ce 0 |
1464 |
.PP |
1465 |
\f[B]Figure 2.\f[R] A glyph for an \[lq]A\[rq] character in standard |
1466 |
font coordinates. |
1467 |
Note that the hole is made via a seam, just as with \f[I]Radiance\f[R] |
1468 |
scene polygons. |
1469 |
The actual aspect and spacing of the character will be determined by the |
1470 |
client program. |
1471 |
.PP |
1472 |
Each glyph begins with the decimal value of that character\[cq]s index, |
1473 |
which is 65 for \[lq]A\[rq] according to the ASCII standard. |
1474 |
This is followed by the number of vertices, then the vertices themselves |
1475 |
in @left ( x sub 1 , y sub 1 right ) , left ( x sub 2 , y sub 2 right )@ |
1476 |
order. |
1477 |
White space again serves as a separator, and comments may begin with a |
1478 |
pound sign (`#') and continue to the end of line. |
1479 |
Here is the glyph entry for the letter \[lq]A\[rq] corresponding to |
1480 |
Figure 2: |
1481 |
.IP |
1482 |
.nf |
1483 |
\f[C] |
1484 |
65 15 # Helvetica \[dq]A\[dq] |
1485 |
155 222 242 48 185 48 168 86 |
1486 |
83 86 65 48 12 48 101 222 |
1487 |
155 222 128 179 126 179 97 116 |
1488 |
155 116 128 179 155 222 |
1489 |
\f[] |
1490 |
.fi |
1491 |
.LP |
1492 |
If the number of vertices given is zero, then the character is a space. |
1493 |
This is not the same as no entry, which means there is no valid glyph |
1494 |
for that character. |
1495 |
Glyphs may appear in any order, with indices ranging from 0 to 255. |
1496 |
The maximum number of vertices for a single glyph is 32767. |
1497 |
.PP |
1498 |
Two standard font files are provided, \f[C]helvet.fnt\f[R] and |
1499 |
\f[C]hexbit4x1.fnt\f[R]. |
1500 |
The former is a Helvetica font from the public domain Hershey font set. |
1501 |
The second is a simple bit pattern font for hexadecimal encodings of |
1502 |
bitmaps. |
1503 |
.SH 3 |
1504 |
\f[BI]Radiance\f[B] Programs |
1505 |
.pdfhref O 3 "Radiance Programs" |
1506 |
.pdfhref M "radiance-programs-3" |
1507 |
.LP |
1508 |
Table 4 shows \f[I]Radiance\f[R] programs that read and write font |
1509 |
files. |
1510 |
.PP |
1511 |
.na |
1512 |
.TS |
1513 |
delim(@@) tab( ); |
1514 |
l l l l. |
1515 |
T{ |
1516 |
Program |
1517 |
T} T{ |
1518 |
Read |
1519 |
T} T{ |
1520 |
Write |
1521 |
T} T{ |
1522 |
Function |
1523 |
T} |
1524 |
_ |
1525 |
T{ |
1526 |
\f[B]pcompos\f[R] |
1527 |
T} T{ |
1528 |
X |
1529 |
T} T{ |
1530 |
T} T{ |
1531 |
Compose \f[I]Radiance\f[R] pictures |
1532 |
T} |
1533 |
T{ |
1534 |
\f[B]psign\f[R] |
1535 |
T} T{ |
1536 |
X |
1537 |
T} T{ |
1538 |
T} T{ |
1539 |
Generate \f[I]Radiance\f[R] picture label |
1540 |
T} |
1541 |
T{ |
1542 |
\f[B]rpict\f[R] |
1543 |
T} T{ |
1544 |
X |
1545 |
T} T{ |
1546 |
T} T{ |
1547 |
Batch rendering program |
1548 |
T} |
1549 |
T{ |
1550 |
\f[B]rtrace\f[R] |
1551 |
T} T{ |
1552 |
X |
1553 |
T} T{ |
1554 |
T} T{ |
1555 |
Customizable ray-tracer |
1556 |
T} |
1557 |
T{ |
1558 |
\f[B]rview\f[R] |
1559 |
T} T{ |
1560 |
X |
1561 |
T} T{ |
1562 |
T} T{ |
1563 |
Interactive renderer |
1564 |
T} |
1565 |
.TE |
1566 |
.ad |
1567 |
.LP |
1568 |
\f[B]Table 4.\f[R] Programs in the \f[I]Radiance\f[R] distribution that |
1569 |
read and write font files. |
1570 |
.SH 3 |
1571 |
\f[BI]Radiance\f[B] C Library |
1572 |
.pdfhref O 3 "Radiance C Library" |
1573 |
.pdfhref M "radiance-c-library-3" |
1574 |
.LP |
1575 |
Similar to data files, font files are usually read and stored in a |
1576 |
lookup table. |
1577 |
The data structures for fonts are in src/common/font.h, and the routines |
1578 |
for reading and spacing them are in \f[C]src/common/font.c\f[R]. |
1579 |
The main structure type is \f[C]FONT\f[R]. |
1580 |
The routine \f[C]getfont(fname)\f[R] loads a font file from the |
1581 |
\f[I]Radiance\f[R] library (set by the \f[C]RAYPATH\f[R] environment |
1582 |
variable), and returns a pointer to the resulting \f[C]FONT\f[R] |
1583 |
structure. |
1584 |
If the file has been previously loaded, a pointer to the stored |
1585 |
structure is returned. |
1586 |
The \f[C]freefont(fname)\f[R] routine frees memory associated with the |
1587 |
named font file and deletes it from the table, or frees all font data if |
1588 |
\f[C]fname\f[R] is \f[C]NULL\f[R]. |
1589 |
.PP |
1590 |
Three different routines are available for text spacing. |
1591 |
The \f[C]uniftext(sp,tp,f\f[R]) function takes the nul-terminated string |
1592 |
\f[C]tp\f[R] and computes uniform per-character spacing for the font |
1593 |
\f[C]f\f[R], returned in the short integer array \f[C]sp\f[R]. |
1594 |
(This is a fairly simple process, and all spacing values will be 255 |
1595 |
unless a character has no corresponding glyph.) |
1596 |
The \f[C]squeeztext(sp,tp,f,cis)\f[R] performs a similar function, but |
1597 |
puts only \f[C]ci\f[R]s units between adjacent characters, based on the |
1598 |
actual width of each font glyph. |
1599 |
The most sophisticated spacing function is |
1600 |
\f[C]proptext(sp,tp,f,cis,nsi)\f[R], which produces a total line length |
1601 |
equal to what it would be with uniform spacing, while maintaining equal |
1602 |
inter-character spacing throughout (i.e., proportional spacing). |
1603 |
The \f[C]nsi\f[R] argument is the number of spaces (zero-vertex glyphs) |
1604 |
considered as an indent. |
1605 |
That is, if this many or more adjacent spaces occur in \f[C]tp\f[R], the |
1606 |
indented text following will appear at the same point as it would have |
1607 |
had the spacing been uniform. |
1608 |
This maintains columns in tabulated text despite the proportional |
1609 |
spacing. |
1610 |
Tabs are not understood or interpreted by any of these routines, and |
1611 |
must be expanded to the appropriate number of spaces via |
1612 |
\f[B]expand\f[R]. |
1613 |
.SH 3 |
1614 |
Octree Format (.oct suffix) |
1615 |
.pdfhref O 3 "Octree Format \(.oct suffix\)" |
1616 |
.pdfhref M "octree-format-.oct-suffix" |
1617 |
.LP |
1618 |
In \f[I]Radiance\f[R], octrees are used to accelerate ray intersection |
1619 |
calculations as described by Glassner [Glassner84]. |
1620 |
This data structure is computed by the \f[B]oconv\f[R] program, which |
1621 |
produces a binary file as its output. |
1622 |
An octree file contains a list of \f[I]Radiance\f[R] scene description |
1623 |
files (which may be empty), some information to guarantee portability |
1624 |
between systems and different versions of the code, followed by the |
1625 |
octree data itself. |
1626 |
If the octree file is \[lq]frozen,\[rq] then it will also contain the |
1627 |
scene data, compiled into a binary format for quick loading. |
1628 |
This is most convenient for octrees that are used in \f[I]instance\f[R] |
1629 |
primitives, which may be moved to a different (library) location from |
1630 |
the originating scene files. |
1631 |
.PP |
1632 |
An octree recursively subdivides 3-dimensional space into 8 subtrees, |
1633 |
hence its name. |
1634 |
Each \[lq]leaf\[rq] node contains between zero and \f[C]MAXSET\f[R] |
1635 |
surface primitives, indicating that section of space contains part or |
1636 |
all of those surfaces. |
1637 |
(Surface primitives may appear more than once in the octree.) |
1638 |
The goal of \f[B]oconv\f[R] is to build an octree that contains no more |
1639 |
than N surfaces in each leaf node, where N is set by the \f[B]-n\f[R] |
1640 |
option (5 by default). |
1641 |
It may allow more surfaces in places where the octree has reached its |
1642 |
maximum resolution (depth), set by the \f[B]-r\f[R] option (1024 \[em] |
1643 |
depth 10 by default). |
1644 |
Figure 3 shows a quadtree dividing 2-dimensional space, analogous to our |
1645 |
3-dimensional octree. |
1646 |
.PSPIC "figure3.eps" |
1647 |
.ce 1000 |
1648 |
A quadtree dividing two-dimensional space |
1649 |
.ce 0 |
1650 |
.PP |
1651 |
\f[B]Figure 3.\f[R] An example quadtree divided so that no leaf node |
1652 |
contains more than 2 objects. |
1653 |
A three-dimensional octree works the same way. |
1654 |
Each leaf node is either empty, or contains a list of intersecting |
1655 |
surfaces. |
1656 |
.SH 3 |
1657 |
Basic File Structure |
1658 |
.pdfhref O 3 "Basic File Structure" |
1659 |
.pdfhref M "basic-file-structure-1" |
1660 |
.LP |
1661 |
An octree file is divided into five sections: the information header, |
1662 |
the scene boundaries, the scene file names, the octree data structure, |
1663 |
and the compiled scene data. |
1664 |
If the octree is frozen, then the compiled scene data is included and |
1665 |
the scene file names are not. |
1666 |
Otherwise, the scene data is left off. |
1667 |
.SH 4 |
1668 |
Information Header |
1669 |
.pdfhref O 4 "Information Header" |
1670 |
.pdfhref M "information-header" |
1671 |
.LP |
1672 |
As with other binary \f[I]Radiance\f[R] formats, the beginning of an |
1673 |
octree file is the information header. |
1674 |
The first line is \[lq]#?RADIANCE\[rq] to aid in identification by the |
1675 |
UNIX \f[B]file\f[R] program. |
1676 |
Following this is the \f[B]oconv\f[R] command (or commands) used to |
1677 |
produce the octree, then a line indicating the format, |
1678 |
\f[C]FORMAT=Radiance_octree\f[R]. |
1679 |
The end of the information header is always an empty line. |
1680 |
Here is an example of an octree information header, as reported by |
1681 |
\f[B]getinfo\f[R]: |
1682 |
.IP |
1683 |
.nf |
1684 |
\f[C] |
1685 |
#?RADIANCE |
1686 |
oconv model.b90 desk misc |
1687 |
oconv -f -i modelb.oct window blinds lights lamp |
1688 |
FORMAT=Radiance_octree |
1689 |
\f[] |
1690 |
.fi |
1691 |
.LP |
1692 |
The actual content of this header is ignored when an octree is read |
1693 |
except for the \f[C]FORMAT\f[R] line, which if it appears must match the |
1694 |
one shown above. |
1695 |
.SH 4 |
1696 |
Scene Boundaries |
1697 |
.pdfhref O 4 "Scene Boundaries" |
1698 |
.pdfhref M "scene-boundaries" |
1699 |
.LP |
1700 |
After the information header, there is a magic number indicating the |
1701 |
format version and the size of object indices (in bytes per index). |
1702 |
This is a two-byte quantity, which must be one of the following in the |
1703 |
current release: |
1704 |
.PP |
1705 |
.na |
1706 |
.nr LLold \n[LL] |
1707 |
.TS |
1708 |
delim(@@) tab( ); |
1709 |
lw(35.0n) lw(35.0n). |
1710 |
T{ |
1711 |
.nr LL 35.0n |
1712 |
285 |
1713 |
T} T{ |
1714 |
.nr LL 35.0n |
1715 |
Two-byte object indices. |
1716 |
T} |
1717 |
T{ |
1718 |
.nr LL 35.0n |
1719 |
287 |
1720 |
T} T{ |
1721 |
.nr LL 35.0n |
1722 |
Four-byte object indices. |
1723 |
T} |
1724 |
T{ |
1725 |
.nr LL 35.0n |
1726 |
291 |
1727 |
T} T{ |
1728 |
.nr LL 35.0n |
1729 |
Eight-byte object indices. |
1730 |
(Only supported on architectures with 64-bit \f[B]longs\f[R].) |
1731 |
T} |
1732 |
.TE |
1733 |
.nr LL \n[LLold] |
1734 |
.ad |
1735 |
.LP |
1736 |
Technically, the code will also support odd-sized integers, but they are |
1737 |
not found on any existing machine architectures so we can forget about |
1738 |
them. |
1739 |
.PP |
1740 |
Following the octree magic number, we have the enclosing cube for the |
1741 |
scene, which defines the dimensions of the octree\[cq]s root node. |
1742 |
The cube is aligned along the world coordinate axes, so may be defined |
1743 |
by one corner (the 3-dimensional minimum) and the side length. |
1744 |
For historical reasons, these four values are stored as ASCII-encoded |
1745 |
real values in nul-terminated strings. |
1746 |
(The octree boundaries may also be read using \f[B]getinfo\f[R] with the |
1747 |
\f[B]-d\f[R] option.) |
1748 |
.SH 4 |
1749 |
Scene File Names |
1750 |
.pdfhref O 4 "Scene File Names" |
1751 |
.pdfhref M "scene-file-names" |
1752 |
.LP |
1753 |
Following the octree dimensions, the names of the scene description |
1754 |
files are given, each stored a nul-terminated string. |
1755 |
The end of this file list is indicated by an empty string. |
1756 |
If the octree is \[lq]frozen,\[rq] meaning it contains the compiled |
1757 |
scene information as well, then no file names will be present (i.e., the |
1758 |
first string will be empty). |
1759 |
.SH 4 |
1760 |
Octree Data Structure |
1761 |
.pdfhref O 4 "Octree Data Structure" |
1762 |
.pdfhref M "octree-data-structure" |
1763 |
.LP |
1764 |
After the scene description files, an N-byte integer indicates the total |
1765 |
number of primitives given to \f[B]oconv\f[R], where N is the size |
1766 |
derived from the magic number as we described. |
1767 |
This object count will be used to verify that the files have not changed |
1768 |
significantly since the octree was written\**. |
1769 |
.FS |
1770 |
Small changes that do not affect geometry will not cause problems, but |
1771 |
if the primitive count changes, so does the indexing of surfaces, and |
1772 |
with that the octree data structure becomes invalid. |
1773 |
A second check is made to insure that no non-surface primitives appear |
1774 |
in any leaf nodes, and this at least guarantees that the renderer will |
1775 |
not dump core from an outdated octree, even if the results are wrong. |
1776 |
.FE |
1777 |
.PP |
1778 |
After the primitive count, the actual octree is stored, using the |
1779 |
following recursive procedure: |
1780 |
.IP |
1781 |
.nf |
1782 |
\f[C] |
1783 |
puttree(ot) begin |
1784 |
if ot is a tree then |
1785 |
write the character \[aq]\[rs]002\[aq] |
1786 |
call puttree on each child node (0-7) else if ot is empty then |
1787 |
write the character \[aq]\[rs]000\[aq] |
1788 |
else |
1789 |
write the character \[aq]\[rs]001\[aq] |
1790 |
write out the number of surfaces |
1791 |
write out each surface\[aq]s index |
1792 |
end |
1793 |
end puttree |
1794 |
\f[] |
1795 |
.fi |
1796 |
.LP |
1797 |
The number of surfaces and the surface indices are each N-byte integers, |
1798 |
and the tree node types are single bytes. |
1799 |
Reading the octree is accomplished with a complementary procedure. |
1800 |
.SH 4 |
1801 |
Compiled Scene Data |
1802 |
.pdfhref O 4 "Compiled Scene Data" |
1803 |
.pdfhref M "compiled-scene-data" |
1804 |
.LP |
1805 |
If the octree is frozen, then this data structure is followed by a |
1806 |
compiled version of the scene. |
1807 |
This avoids the problems of changes to scene files, and allows an octree |
1808 |
to be moved conveniently from one location and one system to another |
1809 |
without worrying about the associated scene files. |
1810 |
.PP |
1811 |
The scene data begins with a listing of the defined primitive types. |
1812 |
This list consists of the name of each type as a nul-terminated string, |
1813 |
followed by an empty string once the list has been exhausted. |
1814 |
This permits the indexing of primitive types with a single byte later |
1815 |
on, without concern about changes to \f[I]Radiance\f[R] involving |
1816 |
\f[C]src/common/otypes.h\f[R]. |
1817 |
.PP |
1818 |
The scene primitives are written one at a time. |
1819 |
First is a single byte with the primitive type index, as determined from |
1820 |
the list given above. |
1821 |
Second is the N-byte modifier index, followed by the primitive\[cq]s |
1822 |
identifier as a nul-terminated string. |
1823 |
String arguments start with a 2-byte integer indicating the argument |
1824 |
count, followed by the strings themselves, which are nul-terminated. |
1825 |
Real arguments next have a 2-byte count followed by the real values, |
1826 |
each stored as a 4-byte mantissa followed by a 1-byte (signed) exponent. |
1827 |
(The mantissa is the numerator of a fraction of @2 sup 31 \[u2212] 1@.) |
1828 |
The end of data is indicated with a -1 value for the object type |
1829 |
(byte=255). |
1830 |
.SH 3 |
1831 |
\f[BI]Radiance\f[B] Programs |
1832 |
.pdfhref O 3 "Radiance Programs" |
1833 |
.pdfhref M "radiance-programs-4" |
1834 |
.LP |
1835 |
Table 5 shows \f[I]Radiance\f[R] programs that read and write octree |
1836 |
files. |
1837 |
.PP |
1838 |
.na |
1839 |
.TS |
1840 |
delim(@@) tab( ); |
1841 |
l l l l. |
1842 |
T{ |
1843 |
Program |
1844 |
T} T{ |
1845 |
Read |
1846 |
T} T{ |
1847 |
Write |
1848 |
T} T{ |
1849 |
Function |
1850 |
T} |
1851 |
_ |
1852 |
T{ |
1853 |
\f[B]getinfo\f[R] |
1854 |
T} T{ |
1855 |
X |
1856 |
T} T{ |
1857 |
T} T{ |
1858 |
Print information header from binary file |
1859 |
T} |
1860 |
T{ |
1861 |
\f[B]oconv\f[R] |
1862 |
T} T{ |
1863 |
X |
1864 |
T} T{ |
1865 |
X |
1866 |
T} T{ |
1867 |
Compile \f[I]Radiance\f[R] scene description |
1868 |
T} |
1869 |
T{ |
1870 |
\f[B]rad\f[R] |
1871 |
T} T{ |
1872 |
X |
1873 |
T} T{ |
1874 |
X |
1875 |
T} T{ |
1876 |
Render \f[I]Radiance\f[R] scene |
1877 |
T} |
1878 |
T{ |
1879 |
\f[B]rpict\f[R] |
1880 |
T} T{ |
1881 |
X |
1882 |
T} T{ |
1883 |
T} T{ |
1884 |
Batch rendering program |
1885 |
T} |
1886 |
T{ |
1887 |
\f[B]rpiece\f[R] |
1888 |
T} T{ |
1889 |
X |
1890 |
T} T{ |
1891 |
T} T{ |
1892 |
Parallel batch rendering program |
1893 |
T} |
1894 |
T{ |
1895 |
\f[B]rtrace\f[R] |
1896 |
T} T{ |
1897 |
X |
1898 |
T} T{ |
1899 |
T} T{ |
1900 |
Customizable ray-tracer |
1901 |
T} |
1902 |
T{ |
1903 |
\f[B]rview\f[R] |
1904 |
T} T{ |
1905 |
X |
1906 |
T} T{ |
1907 |
T} T{ |
1908 |
Interactive renderer |
1909 |
T} |
1910 |
.TE |
1911 |
.ad |
1912 |
.LP |
1913 |
\f[B]Table 5.\f[R] Programs in the \f[I]Radiance\f[R] distribution that |
1914 |
read and write octree files. |
1915 |
.SH 3 |
1916 |
\f[BI]Radiance\f[B] C Library |
1917 |
.pdfhref O 3 "Radiance C Library" |
1918 |
.pdfhref M "radiance-c-library-4" |
1919 |
.LP |
1920 |
Since reading an octree file also may involve reading a |
1921 |
\f[I]Radiance\f[R] scene description, some of the same library routines |
1922 |
are called indirectly. |
1923 |
The header file \f[C]src/common/octree.h\f[R] is needed in addition to |
1924 |
the \f[C]src/common/object.\f[R]h file. |
1925 |
The module \f[C]src/ot/writeoct.c\f[R] contains the main routines for |
1926 |
writing an octree to stdout, while \f[C]src/common/readoct.c\f[R] |
1927 |
contains the corresponding routines for reading an octree from a file. |
1928 |
Both modules access routines in \f[C]src/common/portio.c\f[R] for |
1929 |
reading and writing portable binary data. |
1930 |
.PP |
1931 |
Here is the main call for writing out an octree: |
1932 |
.IP "\f[B]\f[CB]writeoct(int store, CUBE *scene, char *ofn[]);\f[B]\f[R]" 3 |
1933 |
Write the octree stored in scene to stdout, assuming the header has |
1934 |
already been written. |
1935 |
The flags in store determine what will be included. |
1936 |
Normally, this variable is one of \f[C]IO_ALL\f[R] or |
1937 |
\f[C](IO_ALL & \[ti]IO_FILES)\f[R] correspondingto writing a normal or a |
1938 |
frozen octree, respectively. |
1939 |
.RS 3 |
1940 |
.RE |
1941 |
.LP |
1942 |
Here is the main call for reading in an octree: |
1943 |
.IP "\f[B]\f[CB]readoct(char *fname, int load, CUBE *scene, char *ofn[]);\f[B]\f[R]" 3 |
1944 |
Read the octree file fname into scene, saving scene file names in the |
1945 |
ofn array. |
1946 |
What is loaded depends on the flags in load,which may be one or more of |
1947 |
\f[C]IO_CHECK\f[R], \f[C]IO_INFO\f[R], \f[C]IO_SCENE\f[R], |
1948 |
\f[C]IO_TREE\f[R], \f[C]IO_FILES\f[R] and \f[C]IO_BOUNDS\f[R]. |
1949 |
These correspond to checking file type and consistency, transferring the |
1950 |
information header to stdout, loading the scene data, loading the octree |
1951 |
structure, assigning the scene file names to ofn, and assigning the |
1952 |
octree cube boundaries. |
1953 |
The macro \f[C]IO_ALL\f[R] includes all of these flags, for convenience. |
1954 |
.RS 3 |
1955 |
.RE |
1956 |
.SH 2 |
1957 |
Picture File Format (.hdr suffix) |
1958 |
.pdfhref O 2 "Picture File Format \(.hdr suffix\)" |
1959 |
.pdfhref M "picture-file-format-.hdr-suffix" |
1960 |
.LP |
1961 |
\f[I]Radiance\f[R] pictures\** |
1962 |
.FS |
1963 |
The picture filename extension used to be .pic, but that conflicted with |
1964 |
too many other programs. |
1965 |
It was replaced with .hdr, an abbreviation of \[lq]high dynamic |
1966 |
range.\[rq] |
1967 |
.FE |
1968 |
differ from standard computer graphics images inasmuch as they contain |
1969 |
real physical data, namely radiance values at each pixel. |
1970 |
To do this, it is necessary to maintain floating point information, and |
1971 |
we use a 4-byte/pixel encoding described in Chapter II.5 of Graphics |
1972 |
Gems II [Arvo91,p.80]. |
1973 |
The basic idea is to store a 1-byte mantissa for each of three |
1974 |
primaries, and a common 1-byte exponent. |
1975 |
The accuracy of these values will be on the order of 1% (±1 in 200) over |
1976 |
a dynamic range from 10\*{-38\*} to 10\*{38\*}. |
1977 |
.PP |
1978 |
Although \f[I]Radiance\f[R] pictures \f[I]may\f[R] contain physical |
1979 |
data, they do not \f[I]necessarily\f[R] contain physical data. |
1980 |
If the rendering did not use properly modeled light sources, or the |
1981 |
picture was converted from some other format, or custom filtering was |
1982 |
applied, then the physical data will be invalid. |
1983 |
Table 6 lists programs that read and write \f[I]Radiance\f[R] pictures, |
1984 |
with pluses next to the X-marks indicating where physical data is |
1985 |
preserved (or at least understood). |
1986 |
Specifically, if the picture file read or written by a program has an |
1987 |
\[lq]X+\[rq], then it has maintained the physical validity of the pixels |
1988 |
by keeping track of any exposure or color corrections in the appropriate |
1989 |
header variables, described below. |
1990 |
.SH 3 |
1991 |
Basic File Structure |
1992 |
.pdfhref O 3 "Basic File Structure" |
1993 |
.pdfhref M "basic-file-structure-2" |
1994 |
.LP |
1995 |
\f[I]Radiance\f[R] picture files are divided into three sections: the |
1996 |
information header, the resolution string, and the scanline records. |
1997 |
All of these must be present or the file is incomplete. |
1998 |
.SH 4 |
1999 |
Information Header |
2000 |
.pdfhref O 4 "Information Header" |
2001 |
.pdfhref M "information-header-1" |
2002 |
.LP |
2003 |
The information header begins with the usual \f[C]#?RADIANCE\f[R] |
2004 |
identifier, followed by one or more lines containing the programs used |
2005 |
to produce the picture. |
2006 |
These commands may be interspersed with variables describing relevant |
2007 |
information such as the view, exposure, color correction, and so on. |
2008 |
Variable assignments begin on a new line, and the variable name (usually |
2009 |
all upper case) is followed by an equals sign (`='), which is followed |
2010 |
by the assigned value up until the end of line. |
2011 |
Some variable assignments override previous assignments in the same |
2012 |
header, where other assignments are cumulative. |
2013 |
Here are the most important variables for \f[I]Radiance\f[R] pictures: |
2014 |
.IP "\f[B]\f[CB]FORMAT\f[B]\f[R]" 3 |
2015 |
A line indicating the file\[cq]s format. |
2016 |
At most one \f[C]FORMAT\f[R] line is allowed, and it must be assigned a |
2017 |
value of either \f[C]32- bit_rle_rgbe\f[R] or \f[C]32-bit_rle_xyze\f[R] |
2018 |
to be a valid \f[I]Radiance\f[R] picture. |
2019 |
.RS 3 |
2020 |
.RE |
2021 |
.IP "\f[B]\f[CB]EXPOSURE\f[B]\f[R]" 3 |
2022 |
A single floating point number indicating a multiplier that has been |
2023 |
applied to all the pixels in the file. |
2024 |
\f[C]EXPOSURE\f[R] values are cumulative, so the original pixel values |
2025 |
(i.e., radiances in w/sr/m\*{2\*}) must be derived by taking the values |
2026 |
in the file and dividing by all the \f[C]EXPOSURE\f[R] settings |
2027 |
multiplied together. |
2028 |
No \f[C]EXPOSURE\f[R] setting implies that no exposure changes have |
2029 |
taken place. |
2030 |
.RS 3 |
2031 |
.RE |
2032 |
.IP "\f[B]\f[CB]COLORCORR\f[B]\f[R]" 3 |
2033 |
A color correction multiplier that has been applied to this picture. |
2034 |
Similar to the \f[C]EXPOSURE\f[R] variable except given in three parts |
2035 |
for the three primaries. |
2036 |
In general, the value should have a brightness of unity, so that it does |
2037 |
not affect the actual brightness of pixels, which should be tracked by |
2038 |
\f[C]EXPOSURE\f[R] changes instead. |
2039 |
(This variable is also cumulative.) |
2040 |
.RS 3 |
2041 |
.RE |
2042 |
.IP "\f[B]\f[CB]SOFTWARE\f[B]\f[R]" 3 |
2043 |
The software version used to create the picture, usually something like |
2044 |
\f[C]RADIANCE 3.04 official release July 16, 1996\f[R]. |
2045 |
.RS 3 |
2046 |
.RE |
2047 |
.IP "\f[B]\f[CB]PIXASPECT\f[B]\f[R]" 3 |
2048 |
The pixel aspect ratio, expressed as a decimal fraction of the height of |
2049 |
each pixel to its width. |
2050 |
This is not to be confused with the image aspect ratio, which is the |
2051 |
total height over width. |
2052 |
(The image aspect ratio is actually equal to the height in pixels over |
2053 |
the width in pixels, \f[I]multiplied\f[R] by the pixel aspect ratio.) |
2054 |
These assignments are cumulative, so the actual pixel aspect ratio is |
2055 |
all ratios multiplied together. |
2056 |
If no \f[C]PIXASPECT\f[R] assignment appears, the ratio is assumed to be |
2057 |
1. |
2058 |
.RS 3 |
2059 |
.RE |
2060 |
.IP "\f[B]\f[CB]VIEW\f[B]\f[R]" 3 |
2061 |
The \f[I]Radiance\f[R] view parameters used to create this picture. |
2062 |
Multiple assignments are cumulative inasmuch as new view options add to |
2063 |
or override old ones. |
2064 |
.RS 3 |
2065 |
.RE |
2066 |
.LP |
2067 |
\f[C]PRIMARIES\f[R] The CIE (x,y) chromaticity coordinates of the three |
2068 |
(RGB) primaries and the white point used to standardize the |
2069 |
picture\[cq]s color system. |
2070 |
This is used mainly by the \f[B]ra_xyze\f[R] program to convert between |
2071 |
color systems. |
2072 |
If no \f[C]PRIMARIES\f[R] line appears, we assume the standard primaries |
2073 |
defined in \f[C]src/common/color.h\f[R], namely |
2074 |
\f[C]0.640 0.330 0.290 0.600 0.150 0.060 0.333 0.333\f[R] for red, |
2075 |
green, blue and white, respectively. |
2076 |
.PP |
2077 |
As always, the end of the header is indicated by an empty line. |
2078 |
.SH 4 |
2079 |
Resolution String |
2080 |
.pdfhref O 4 "Resolution String" |
2081 |
.pdfhref M "resolution-string" |
2082 |
.LP |
2083 |
All \f[I]Radiance\f[R] pictures have a standard coordinate system, which |
2084 |
is shown in Figure 4. |
2085 |
The origin is always at the lower left corner, with the X coordinate |
2086 |
increasing to the right, and the Y coordinate increasing in the upward |
2087 |
direction. |
2088 |
The actual ordering of pixels in the picture file, however, is addressed |
2089 |
by the resolution string. |
2090 |
.PSPIC "figure4.eps" |
2091 |
.ce 1000 |
2092 |
Radiance picture coordinate system |
2093 |
.ce 0 |
2094 |
.PP |
2095 |
\f[B]Figure 4.\f[R] The standard coordinate system for an MxN picture. |
2096 |
.PP |
2097 |
The resolution string is given as one of the following: |
2098 |
.IP "\f[B]\f[CB]-Y N +X M\f[B]\f[R]" 3 |
2099 |
The standard orientation produced by the renderers, indicating that Y is |
2100 |
decreasing in the file, and X is increasing. |
2101 |
X positions are increasing in each scanline, starting with the upper |
2102 |
left position in the picture and moving to the upper right initially, |
2103 |
then on down the picture. |
2104 |
Some programs will only handle pictures with this ordering. |
2105 |
.RS 3 |
2106 |
.RE |
2107 |
.IP "\f[B]\f[CB]-Y N -X M\f[B]\f[R]" 3 |
2108 |
The X ordering has been reversed, effectively flipping the image left to |
2109 |
right from the standard ordering. |
2110 |
.RS 3 |
2111 |
.RE |
2112 |
.IP "\f[B]\f[CB]+Y N -X M\f[B]\f[R]" 3 |
2113 |
The image has been flipped left to right and also top to bottom, which |
2114 |
is the same as rotating it by 180 degrees. |
2115 |
.RS 3 |
2116 |
.RE |
2117 |
.IP "\f[B]\f[CB]+Y N +X M\f[B]\f[R]" 3 |
2118 |
The image has been flipped top to bottom from the standard ordering. |
2119 |
.RS 3 |
2120 |
.RE |
2121 |
.IP "\f[B]\f[CB]+X M +Y N\f[B]\f[R]" 3 |
2122 |
The image has been rotated 90 degrees clockwise. |
2123 |
.RS 3 |
2124 |
.RE |
2125 |
.IP "\f[B]\f[CB]-X M +Y N\f[B]\f[R]" 3 |
2126 |
The image has been rotated 90 degrees clockwise, then flipped top to |
2127 |
bottom. |
2128 |
.RS 3 |
2129 |
.RE |
2130 |
.IP "\f[B]\f[CB]-X M -Y N\f[B]\f[R]" 3 |
2131 |
The image has been rotated 90 degrees counter-clockwise. |
2132 |
.RS 3 |
2133 |
.RE |
2134 |
.IP "\f[B]\f[CB]+X M -Y N\f[B]\f[R]" 3 |
2135 |
The image has been rotate 90 degrees counter-clockwise, then flipped top |
2136 |
to bottom. |
2137 |
.RS 3 |
2138 |
.RE |
2139 |
.LP |
2140 |
The reason for tracking all these changes in picture orientation is so |
2141 |
programs that compute ray origin and direction from the \f[C]VIEW\f[R] |
2142 |
variable in the information header will work despite such changes. |
2143 |
Also, it can reduce memory requirements on converting from other image |
2144 |
formats that have a different scanline ordering, such as Targa. |
2145 |
.SH 4 |
2146 |
Scanline Records |
2147 |
.pdfhref O 4 "Scanline Records" |
2148 |
.pdfhref M "scanline-records" |
2149 |
.LP |
2150 |
\f[I]Radiance\f[R] scanlines come in one of three flavors, described |
2151 |
below: |
2152 |
.IP "\f[B]Uncompressed\f[R]" 3 |
2153 |
Each scanline is represented by M pixels with 4 bytes per pixel, for a |
2154 |
total length of 4xM bytes. |
2155 |
This is the simplest format to read and write, since it has a one-to-one |
2156 |
correspondence to an array of \f[C]COLR\f[R] values. |
2157 |
.RS 3 |
2158 |
.RE |
2159 |
.IP "\f[B]Old run-length encoded\f[R]" 3 |
2160 |
Repeated pixel values are indicated by an illegal (i.e., unnormalized) |
2161 |
pixel that has 1\[cq]s for all three mantissas, and an exponent that |
2162 |
corresponds to the number of times the previous pixel is repeated. |
2163 |
Consecutive repeat indicators contain higher-order bytes of the count. |
2164 |
.RS 3 |
2165 |
.RE |
2166 |
.IP "\f[B]New run-length encoded\f[R]" 3 |
2167 |
In this format, the four scanline components (three primaries and |
2168 |
exponent) are separated for better compression using adaptive run-length |
2169 |
encoding (described by Glassner in Chapter II.8 of Graphics Gems II |
2170 |
[Arvo91,p.89]). |
2171 |
The record begins with an unnormalized pixel having two bytes equal to |
2172 |
2, followed by the upper byte and the lower byte of the scanline length |
2173 |
(which must be less than 32768). |
2174 |
A run is indicated by a byte with its high-order bit set, corresponding |
2175 |
to a count with excess 128. |
2176 |
A non-run is indicated with a byte less than 128. |
2177 |
The maximum compression ratio using this scheme is better than 100:1, |
2178 |
but typical performance for \f[I]Radiance\f[R] pictures is more like |
2179 |
2:1. |
2180 |
.RS 3 |
2181 |
.RE |
2182 |
.LP |
2183 |
The physical values these scanlines correspond to depend on the format |
2184 |
and other information contained in the information header. |
2185 |
If the \f[C]FORMAT\f[R] string indicates RGB data, then the units for |
2186 |
each primary are spectral radiances over the corresponding waveband, |
2187 |
such that a pixel value of @left ( 1 , 1 , 1 right )@ corresponds to a |
2188 |
total energy of 1 w/sr/m\*{2\*} over the visible spectrum. |
2189 |
The actual luminance value (in lm/sr/m\*{2\*}) can be computed from the |
2190 |
following formula for the standard \f[I]Radiance\f[R] RGB primaries: |
2191 |
.PP |
2192 |
.EQ |
2193 |
L sub v = 179 left ( 0.265 r + 0.670 g + 0.065 b right ) |
2194 |
.EN |
2195 |
.PP |
2196 |
The value of 179 lm/w is the standard \f[I]luminous efficacy\f[R] of |
2197 |
equal-energy white light that is defined and used by \f[I]Radiance\f[R] |
2198 |
specifically for this conversion. |
2199 |
This and the other values above are defined in |
2200 |
\f[C]src/common/color.h\f[R], and the above formula is given as a macro, |
2201 |
\f[C]luminance(col)\f[R]. |
2202 |
.PP |
2203 |
If the \f[C]FORMAT\f[R] string indicates XYZ data, then the units of the |
2204 |
Y primary are already lm/st/m\*{2\*}, so the above conversion is |
2205 |
unnecessary. |
2206 |
.SH 3 |
2207 |
\f[BI]Radiance\f[B] programs |
2208 |
.pdfhref O 3 "Radiance programs" |
2209 |
.pdfhref M "radiance-programs-5" |
2210 |
.LP |
2211 |
Table 6 shows the many programs that read and write \f[I]Radiance\f[R] |
2212 |
pictures. |
2213 |
.PP |
2214 |
.na |
2215 |
.TS |
2216 |
delim(@@) tab( ); |
2217 |
l l l l. |
2218 |
T{ |
2219 |
Program |
2220 |
T} T{ |
2221 |
Read |
2222 |
T} T{ |
2223 |
Write |
2224 |
T} T{ |
2225 |
Function |
2226 |
T} |
2227 |
_ |
2228 |
T{ |
2229 |
\f[B]falsecolor\f[R] |
2230 |
T} T{ |
2231 |
X+ |
2232 |
T} T{ |
2233 |
X |
2234 |
T} T{ |
2235 |
Create false color image |
2236 |
T} |
2237 |
T{ |
2238 |
\f[B]findglare\f[R] |
2239 |
T} T{ |
2240 |
X+ |
2241 |
T} T{ |
2242 |
T} T{ |
2243 |
Find sources of discomfort glare |
2244 |
T} |
2245 |
T{ |
2246 |
\f[B]getinfo\f[R] |
2247 |
T} T{ |
2248 |
X |
2249 |
T} T{ |
2250 |
T} T{ |
2251 |
Print information header from binary file |
2252 |
T} |
2253 |
T{ |
2254 |
\f[B]macbethcal\f[R] |
2255 |
T} T{ |
2256 |
X |
2257 |
T} T{ |
2258 |
X |
2259 |
T} T{ |
2260 |
Compute image color & contrast correction |
2261 |
T} |
2262 |
T{ |
2263 |
\f[B]normpat\f[R] |
2264 |
T} T{ |
2265 |
X |
2266 |
T} T{ |
2267 |
X |
2268 |
T} T{ |
2269 |
Normalize picture for use as pattern tile |
2270 |
T} |
2271 |
T{ |
2272 |
\f[B]objpict\f[R] |
2273 |
T} T{ |
2274 |
T} T{ |
2275 |
X |
2276 |
T} T{ |
2277 |
Generate composite picture of object |
2278 |
T} |
2279 |
T{ |
2280 |
\f[B]pcomb\f[R] |
2281 |
T} T{ |
2282 |
X+ |
2283 |
T} T{ |
2284 |
X |
2285 |
T} T{ |
2286 |
Perform arbitrary math on picture(s) |
2287 |
T} |
2288 |
T{ |
2289 |
\f[B]pcond\f[R] |
2290 |
T} T{ |
2291 |
X+ |
2292 |
T} T{ |
2293 |
X |
2294 |
T} T{ |
2295 |
Condition a picture for display |
2296 |
T} |
2297 |
T{ |
2298 |
\f[B]pcompos\f[R] |
2299 |
T} T{ |
2300 |
X |
2301 |
T} T{ |
2302 |
X |
2303 |
T} T{ |
2304 |
Composite pictures |
2305 |
T} |
2306 |
T{ |
2307 |
\f[B]pextrem\f[R] |
2308 |
T} T{ |
2309 |
X+ |
2310 |
T} T{ |
2311 |
T} T{ |
2312 |
Find minimum and maximum pixels |
2313 |
T} |
2314 |
T{ |
2315 |
\f[B]pfilt\f[R] |
2316 |
T} T{ |
2317 |
X+ |
2318 |
T} T{ |
2319 |
X+ |
2320 |
T} T{ |
2321 |
Filter and anti-alias picture |
2322 |
T} |
2323 |
T{ |
2324 |
\f[B]pflip\f[R] |
2325 |
T} T{ |
2326 |
X+ |
2327 |
T} T{ |
2328 |
X+ |
2329 |
T} T{ |
2330 |
Flip picture left-right and/or top-bottom |
2331 |
T} |
2332 |
T{ |
2333 |
\f[B]pinterp\f[R] |
2334 |
T} T{ |
2335 |
X+ |
2336 |
T} T{ |
2337 |
X+ |
2338 |
T} T{ |
2339 |
Interpolate/extrapolate picture views |
2340 |
T} |
2341 |
T{ |
2342 |
\f[B]protate\f[R] |
2343 |
T} T{ |
2344 |
X+ |
2345 |
T} T{ |
2346 |
X+ |
2347 |
T} T{ |
2348 |
Rotate picture 90 degrees clockwise |
2349 |
T} |
2350 |
T{ |
2351 |
\f[B]psign\f[R] |
2352 |
T} T{ |
2353 |
T} T{ |
2354 |
X |
2355 |
T} T{ |
2356 |
Create text picture |
2357 |
T} |
2358 |
T{ |
2359 |
\f[B]pvalue\f[R] |
2360 |
T} T{ |
2361 |
X+ |
2362 |
T} T{ |
2363 |
X+ |
2364 |
T} T{ |
2365 |
Convert picture to/from simpler formats |
2366 |
T} |
2367 |
T{ |
2368 |
\f[B]ra_avs\f[R] |
2369 |
T} T{ |
2370 |
X |
2371 |
T} T{ |
2372 |
X |
2373 |
T} T{ |
2374 |
Convert to/from AVS image format |
2375 |
T} |
2376 |
T{ |
2377 |
\f[B]ra_pict\f[R] |
2378 |
T} T{ |
2379 |
X |
2380 |
T} T{ |
2381 |
X |
2382 |
T} T{ |
2383 |
Convert to/from Macintosh PICT2 format |
2384 |
T} |
2385 |
T{ |
2386 |
\f[B]ra_ppm\f[R] |
2387 |
T} T{ |
2388 |
X |
2389 |
T} T{ |
2390 |
X |
2391 |
T} T{ |
2392 |
Convert to/from Poskanzer Port. |
2393 |
Pixmap |
2394 |
T} |
2395 |
T{ |
2396 |
\f[B]ra_pr\f[R] |
2397 |
T} T{ |
2398 |
X |
2399 |
T} T{ |
2400 |
X |
2401 |
T} T{ |
2402 |
Convert to/from Sun 8-bit rasterfile |
2403 |
T} |
2404 |
T{ |
2405 |
\f[B]ra_pr24\f[R] |
2406 |
T} T{ |
2407 |
X |
2408 |
T} T{ |
2409 |
X |
2410 |
T} T{ |
2411 |
Convert to/from Sun 24-bit rasterfile |
2412 |
T} |
2413 |
T{ |
2414 |
\f[B]ra_ps\f[R] |
2415 |
T} T{ |
2416 |
X |
2417 |
T} T{ |
2418 |
T} T{ |
2419 |
Convert to B&W or color PostScript |
2420 |
T} |
2421 |
T{ |
2422 |
\f[B]ra_rgbe\f[R] |
2423 |
T} T{ |
2424 |
X |
2425 |
T} T{ |
2426 |
X |
2427 |
T} T{ |
2428 |
Convert to/from uncompressed picture |
2429 |
T} |
2430 |
T{ |
2431 |
\f[B]ra_t8\f[R] |
2432 |
T} T{ |
2433 |
X |
2434 |
T} T{ |
2435 |
X |
2436 |
T} T{ |
2437 |
Convert to/from Targa 8-bit format |
2438 |
T} |
2439 |
T{ |
2440 |
\f[B]ra_t16\f[R] |
2441 |
T} T{ |
2442 |
X |
2443 |
T} T{ |
2444 |
X |
2445 |
T} T{ |
2446 |
Convert to/from Targa 16-bit and 24-bit |
2447 |
T} |
2448 |
T{ |
2449 |
\f[B]ra_tiff\f[R] |
2450 |
T} T{ |
2451 |
X |
2452 |
T} T{ |
2453 |
X |
2454 |
T} T{ |
2455 |
Convert to/from TIFF 8-bit and 24-bit |
2456 |
T} |
2457 |
T{ |
2458 |
\f[B]ra_xyze\f[R] |
2459 |
T} T{ |
2460 |
X |
2461 |
T} T{ |
2462 |
X |
2463 |
T} T{ |
2464 |
Convert to/from CIE primary picture |
2465 |
T} |
2466 |
T{ |
2467 |
\f[B]rad\f[R] |
2468 |
T} T{ |
2469 |
T} T{ |
2470 |
X+ |
2471 |
T} T{ |
2472 |
Render Radiance scene |
2473 |
T} |
2474 |
T{ |
2475 |
\f[B]ranimate\f[R] |
2476 |
T} T{ |
2477 |
T} T{ |
2478 |
X+ |
2479 |
T} T{ |
2480 |
Animate Radiance scene |
2481 |
T} |
2482 |
T{ |
2483 |
\f[B]rpict\f[R] |
2484 |
T} T{ |
2485 |
X |
2486 |
T} T{ |
2487 |
X+ |
2488 |
T} T{ |
2489 |
Batch rendering program |
2490 |
T} |
2491 |
T{ |
2492 |
\f[B]rpiece\f[R] |
2493 |
T} T{ |
2494 |
X |
2495 |
T} T{ |
2496 |
X+ |
2497 |
T} T{ |
2498 |
Parallel batch rendering program |
2499 |
T} |
2500 |
T{ |
2501 |
\f[B]rtrace\f[R] |
2502 |
T} T{ |
2503 |
X |
2504 |
T} T{ |
2505 |
X+ |
2506 |
T} T{ |
2507 |
Customizable ray-tracer |
2508 |
T} |
2509 |
T{ |
2510 |
\f[B]rview\f[R] |
2511 |
T} T{ |
2512 |
X |
2513 |
T} T{ |
2514 |
X+ |
2515 |
T} T{ |
2516 |
Interactive renderer |
2517 |
T} |
2518 |
T{ |
2519 |
\f[B]vwright\f[R] |
2520 |
T} T{ |
2521 |
X |
2522 |
T} T{ |
2523 |
T} T{ |
2524 |
Get view parameters and shift them |
2525 |
T} |
2526 |
T{ |
2527 |
\f[B]xglaresrc\f[R] |
2528 |
T} T{ |
2529 |
X |
2530 |
T} T{ |
2531 |
T} T{ |
2532 |
Display glare sources from \f[B]findglare\f[R] |
2533 |
T} |
2534 |
T{ |
2535 |
\f[B]ximage\f[R] |
2536 |
T} T{ |
2537 |
X+ |
2538 |
T} T{ |
2539 |
T} T{ |
2540 |
Display \f[I]Radiance\f[R] picture under \f[I]X11\f[R] |
2541 |
T} |
2542 |
T{ |
2543 |
\f[B]xshowtrace\f[R] |
2544 |
T} T{ |
2545 |
X |
2546 |
T} T{ |
2547 |
T} T{ |
2548 |
Show ray traces on \f[I]X11\f[R] display |
2549 |
T} |
2550 |
.TE |
2551 |
.ad |
2552 |
.LP |
2553 |
\f[B]Table 6.\f[R] \f[I]Radiance\f[R] programs that read and write |
2554 |
picture files. |
2555 |
Pluses indicate when a program makes use of or preserves physical pixel |
2556 |
values. |
2557 |
.SH 3 |
2558 |
\f[BI]Radiance\f[B] C Library |
2559 |
.pdfhref O 3 "Radiance C Library" |
2560 |
.pdfhref M "radiance-c-library-5" |
2561 |
.LP |
2562 |
There are a fair number of routines for reading, writing and |
2563 |
manipulating \f[I]Radiance\f[R] pictures. |
2564 |
If you want to write a converter to or from a 24-bit image format, you |
2565 |
can follow the skeletal example in \f[C]src/px/ra_skel.c\f[R]. |
2566 |
This has all of the basic functionality of the other \f[B]ra_*\f[R] |
2567 |
image conversion programs, with the actual code for the destination type |
2568 |
removed (or simplified). |
2569 |
The method in \f[C]ra_skel\f[R] uses the routines in |
2570 |
\f[C]src/common/colrops.c\f[R] to avoid conversion to machine floating |
2571 |
point, which can slow things down and is not necessary in this case. |
2572 |
.PP |
2573 |
Below we describe routines for reading and writing pictures, which rely |
2574 |
heavily on definitions in \f[C]src/common/color.h\f[R]. |
2575 |
We start with the calls for manipulating information headers, followed |
2576 |
by the calls for resolution strings, then the calls for scanline |
2577 |
records. |
2578 |
.PP |
2579 |
Information headers are manipulated with the routines in |
2580 |
\f[C]src/common/header.c\f[R] and the macros in \f[C]color.h\f[R]. |
2581 |
Features for handing views are defined in \f[C]src/common/view.h\f[R] |
2582 |
with routines in \f[C]src/common/image.c\f[R]. |
2583 |
Here are the relevant calls for reading and copying information headers: |
2584 |
.IP "\f[B]\f[CB]int checkheader(FILE *fin, char *fmt, FILE *fout);\f[B]\f[R]" 3 |
2585 |
Read the header information from \f[C]fin\f[R], copying to |
2586 |
\f[C]fou\f[R]t (unless fout is \f[C]NULL\f[R]), checking any |
2587 |
\f[C]FORMAT\f[R] line against the string \f[C]fmt\f[R]. |
2588 |
The \f[C]FORMAT\f[R] line (if it exists) will not be copied to |
2589 |
\f[C]fout\f[R]. |
2590 |
The function returns 1 if the header was OK and the format matched, 0 if |
2591 |
the header was OK but there was no format line, and -1 if the format |
2592 |
line did not match or there was some problem reading the header. |
2593 |
Wildcard characters (`*' and `?') may appear in \f[C]fmt\f[R], in which |
2594 |
case a globbing match is applied, and the matching format value will be |
2595 |
copied to fmt upon success. |
2596 |
The normal \f[C]fmt\f[R] values for pictures are \f[C]COLRFMT\f[R] for |
2597 |
\f[I]Radiance\f[R] RGB, \f[C]CIEFMT\f[R] for 4-byte XYZ pixels, or a |
2598 |
copy of \f[C]PICFMT\f[R] for glob matches to either. |
2599 |
(Do not pass \f[C]PICFMT\f[R] directly, as this will cause an illegal |
2600 |
memory access on systems that store static strings in read-only memory.) |
2601 |
.RS 3 |
2602 |
.RE |
2603 |
.IP "\f[B]\f[CB]int getheader(FILE *fp, int (*f)(), char *p);\f[B]\f[R]" 3 |
2604 |
For those who need more control, \f[C]getheader\f[R] reads the header |
2605 |
from \f[C]fp\f[R], calling the function \f[C]f\f[R] (if |
2606 |
not\f[C]NULL\f[R]) with each input line and the client data pointer |
2607 |
\f[C]p\f[R]. |
2608 |
A simple call to skip the header is \f[C]getheader(fp,NULL,NULL)\f[R]. |
2609 |
To copy the header unconditionally to \f[C]stdout\f[R], call |
2610 |
\f[C]getheader(fp,fputs,stdout)\f[R]. |
2611 |
More often, \f[C]getheader\f[R] is called with a client function, which |
2612 |
checks each line for specific variable settings. |
2613 |
.RS 3 |
2614 |
.RE |
2615 |
.IP "\f[B]\f[CB]int isformat(char *s);\f[B]\f[R]" 3 |
2616 |
Returns non-zero if the line \f[C]s\f[R] is a \f[C]FORMAT\f[R] |
2617 |
assignment. |
2618 |
.RS 3 |
2619 |
.RE |
2620 |
.IP "\f[B]\f[CB]int formatval(char *r, char *s);\f[B]\f[R]" 3 |
2621 |
Returns the \f[C]FORMAT\f[R] value from line \f[C]s\f[R] in the string |
2622 |
\f[C]r\f[R]. |
2623 |
Returns non-zero if \f[C]s\f[R] is a valid format line. |
2624 |
.RS 3 |
2625 |
.RE |
2626 |
.IP "\f[B]\f[CB]fputformat(char *s, FILE *fp);\f[B]\f[R]" 3 |
2627 |
Put format assignment \f[C]s\f[R] to the stream \f[C]fp\f[R]. |
2628 |
.RS 3 |
2629 |
.RE |
2630 |
.IP "\f[B]\f[CB]isexpos(s)\f[B]\f[R]" 3 |
2631 |
Macro returns non-zero if the line \f[C]s\f[R] is an \f[C]EXPOSURE\f[R] |
2632 |
setting. |
2633 |
.RS 3 |
2634 |
.RE |
2635 |
.IP "\f[B]exposval(s)\f[R]" 3 |
2636 |
Macro returns \f[B]double\f[R] exposure value from line \f[C]s\f[R]. |
2637 |
.RS 3 |
2638 |
.RE |
2639 |
.IP "\f[B]\f[CB]fputexpos(ex,fp)\f[B]\f[R]" 3 |
2640 |
Macro** | puts real exposure value \f[C]ex\f[R] to stream \f[C]fp\f[R]. |
2641 |
.RS 3 |
2642 |
.RE |
2643 |
.LP |
2644 |
\f[C]iscolcor(s)\f[R] :Macro returns non-zero if the line \f[C]s\f[R] is |
2645 |
a \f[C]COLORCORR\f[R] setting. |
2646 |
.IP "\f[B]\f[CB]colcorval(cc,s)\f[B]\f[R]" 3 |
2647 |
Macro assign color correction value from line \f[C]s\f[R] in the |
2648 |
\f[C]COLOR\f[R] variable \f[C]cc\f[R]. |
2649 |
.RS 3 |
2650 |
.RE |
2651 |
.IP "\f[B]\f[CB]fputcolcor(cc,fp)\f[B]\f[R]" 3 |
2652 |
Macro puts correction \f[C]COLOR\f[R] \f[C]cc\f[R] to stream |
2653 |
\f[C]fp\f[R]. |
2654 |
.RS 3 |
2655 |
.RE |
2656 |
.IP "\f[B]\f[CB]isaspect(s)\f[B]\f[R]" 3 |
2657 |
Macro returns non-zero if the line \f[C]s\f[R] is a \f[C]PIXASPECT\f[R] |
2658 |
setting. |
2659 |
.RS 3 |
2660 |
.RE |
2661 |
.IP "\f[B]\f[CB]aspectval(s)\f[B]\f[R]" 3 |
2662 |
Macro returns double pixel aspect value from line \f[C]s\f[R]. |
2663 |
.RS 3 |
2664 |
.RE |
2665 |
.IP "\f[B]\f[CB]fputaspect(pa,fp)\f[B]\f[R]" 3 |
2666 |
Macro puts real pixel aspect value \f[C]pa\f[R] to stream \f[C]fp\f[R]. |
2667 |
.RS 3 |
2668 |
.RE |
2669 |
.IP "\f[B]\f[CB]int isview(char *s);\f[B]\f[R]" 3 |
2670 |
Returns non-zero if header line \f[C]s\f[R] contains view parameters. |
2671 |
Note that \[ga]\f[C]s\f[R] could be either a \f[C]VIEW\f[R] assignment |
2672 |
or a rendering command. |
2673 |
.RS 3 |
2674 |
.RE |
2675 |
.IP "\f[B]\f[CB]int sscanview(VIEW *vp, char *s);\f[B]\f[R]" 3 |
2676 |
Scan view options from the string \f[C]s\f[R] into the \f[C]VIEW\f[R] |
2677 |
structure pointed to by \f[C]vp\f[R]. |
2678 |
.RS 3 |
2679 |
.RE |
2680 |
.IP "\f[B]\f[CB]fprintview(VIEW *vp, FILE *fp);\f[B]\f[R]" 3 |
2681 |
Print view options in \f[C]vp\f[R] to the stream \f[C]fp\f[R]. |
2682 |
Note that this does not print out \[lq]VIEW=\[rq] first, or end the |
2683 |
line. |
2684 |
Therefore, one usually calls \f[C]fputs(VIEWSTR,fp)\f[R] followed by |
2685 |
\f[C]fprintview(vp,fp)\f[R], then \f[C]putc(\[aq]\[rs]n\[aq],fp)\f[R]. |
2686 |
.RS 3 |
2687 |
.RE |
2688 |
.IP "\f[B]\f[CB]isprims(s)\f[B]\f[R]" 3 |
2689 |
Macro returns non-zero if the line \f[C]s\f[R] is a \f[C]PRIMARIES\f[R] |
2690 |
setting. |
2691 |
.RS 3 |
2692 |
.RE |
2693 |
.IP "\f[B]\f[CB]primsval(p,s)\f[B]\f[R]" 3 |
2694 |
Macro assign color primitives from line \f[C]s\f[R] in the |
2695 |
\f[C]RGBPRIMS\f[R] variable \f[C]p\f[R]. |
2696 |
.RS 3 |
2697 |
.RE |
2698 |
.IP "\f[B]\f[CB]fputprims(p,fp)\f[B]\f[R]" 3 |
2699 |
Macro puts color primitives \f[C]p\f[R] to stream \f[C]fp\f[R]. |
2700 |
.RS 3 |
2701 |
.RE |
2702 |
.LP |
2703 |
The header file \f[C]src/common/resolu.h\f[R] has macros for resolution |
2704 |
strings, which are handled by routines in \f[C]src/common/resolu.c\f[R]. |
2705 |
Here are the relevant calls: |
2706 |
.IP "\f[B]\f[CB]fgetsresolu(rs,fp)\f[B]\f[R]" 3 |
2707 |
Macro to get a resolution string from the stream \f[C]fp\f[R] and put it |
2708 |
in the \f[C]RESOLU\f[R] structure pointed to by \f[C]rs\f[R]. |
2709 |
The return value is non-zero if the resolution was successfully loaded. |
2710 |
.RS 3 |
2711 |
.RE |
2712 |
.IP "\f[B]\f[CB]fputsresolu(rs,fp)\f[B]\f[R]" 3 |
2713 |
Macro to write the \f[C]RESOLU\f[R] structure pointed to by rs to the |
2714 |
stream fp. |
2715 |
.RS 3 |
2716 |
.RE |
2717 |
.IP "\f[B]\f[CB]scanlen(rs)\f[B]\f[R]" 3 |
2718 |
Macro to get the scanline length from the \f[C]RESOL\f[R]U structure |
2719 |
pointed to by \f[C]rs\f[R]. |
2720 |
.RS 3 |
2721 |
.RE |
2722 |
.IP "\f[B]\f[CB]numscans(rs)\f[B]\f[R]" 3 |
2723 |
Macro to get the number of scanlines from the \f[C]RESOLU\f[R] structure |
2724 |
pointed to by \f[C]rs\f[R]. |
2725 |
.RS 3 |
2726 |
.RE |
2727 |
.IP "\f[B]\f[CB]fscnresolu(slp,nsp,fp)\f[B]\f[R]" 3 |
2728 |
Macro to read in a resolution string from \f[C]f\f[R]p and assign the |
2729 |
scanline length and number of scanlines to the integers pointed to by |
2730 |
\f[C]slp\f[R] and \f[C]nsp\f[R], respectively. |
2731 |
This call expects standard English-text ordered scanlines, and returns |
2732 |
non-zero only if the resolution string agrees. |
2733 |
.RS 3 |
2734 |
.RE |
2735 |
.IP "\f[B]\f[CB]fprtresolu(sl,ns,fp)\f[B]\f[R]" 3 |
2736 |
Macro to print out a resolution string for \f[C]ns\f[R] scanlines of |
2737 |
length \f[C]sl\f[R] in standard English-text ordering to \f[C]fp\f[R]. |
2738 |
.RS 3 |
2739 |
.RE |
2740 |
.LP |
2741 |
The file \f[C]src/common/color.c\f[R] contains the essential routines |
2742 |
for reading and writing scanline records. |
2743 |
Here are the relevant calls and macros: |
2744 |
.IP "\f[B]\f[CB]int freadcolrs(COLR *scn, int sl, FILE *fp);\f[B]\f[R]" 3 |
2745 |
Read a scanline record of length \f[C]sl\f[R] from stream \f[C]fp\f[R] |
2746 |
into the \f[C]COLR\f[R] array \f[C]scn\f[R]. |
2747 |
Interprets uncompressed, old, and new run-length encoded records. |
2748 |
Returns 0 on success, -1 on failure. |
2749 |
.RS 3 |
2750 |
.RE |
2751 |
.IP "\f[B]\f[CB]int fwritecolrs(COLR *scn, int sl, FILE *fp);\f[B]\f[R]" 3 |
2752 |
Write the scanline record stored in the \f[C]COLR\f[R] array |
2753 |
\f[C]scn\f[R], length \f[C]sl\f[R], to the stream \f[C]fp\f[R]. |
2754 |
Uses the new run-length encoding unless \f[C]sl\f[R] is less than 8 or |
2755 |
greater than 32767, when an uncompressed record is written. |
2756 |
Returns 0 on success, -1 if there was an error. |
2757 |
.RS 3 |
2758 |
.RE |
2759 |
.IP "\f[B]\f[CB]int freadscan(COLOR *fscn, int sl, FILE *fp);\f[B]\f[R]" 3 |
2760 |
Reads a scanline of length \f[C]sl\f[R] from the stream \f[C]fp\f[R] and |
2761 |
converts to machine floating-point format in the array \f[C]fscn\f[R]. |
2762 |
Recognizes all scanline record encodings. |
2763 |
Returns 0 on success, or -1 on failure. |
2764 |
.RS 3 |
2765 |
.RE |
2766 |
.IP "\f[B]\f[CB]int fwritescan(COLOR *fscn, int sl, FILE *fp);\f[B]\f[R]" 3 |
2767 |
Write the floating-point scanline of length \f[C]sl\f[R] stored in the |
2768 |
array fscn to the stream \f[C]fp\f[R]. |
2769 |
Converts to 4-byte/pixel scanline format and calls \f[C]fwritecolrs\f[R] |
2770 |
to do the actual write. |
2771 |
Returns 0 on success, or -1 if there was an error. |
2772 |
.RS 3 |
2773 |
.RE |
2774 |
.IP "\f[B]\f[CB]colval(col,p)\f[B]\f[R]" 3 |
2775 |
Macro to get primary p from the floating-point \f[C]COLOR col\f[R]. |
2776 |
The primary index may be one of \f[C]RED\f[R], \f[C]GRN\f[R] or |
2777 |
\f[C]BLU\f[R] for RGB colors, or CIEX, CIEY or CIEZ for XYZ colors. |
2778 |
This macro is a valid lvalue, so can be used on the left of assignment |
2779 |
statements as well. |
2780 |
.RS 3 |
2781 |
.RE |
2782 |
.IP "\f[B]\f[CB]colrval(clr,p)\f[B]\f[R]" 3 |
2783 |
Macro to get primary \f[C]p\f[R] from the 4-byte \f[C]COLR\f[R] pixel |
2784 |
\f[C]clr\f[R]. |
2785 |
The primary index may be one of RED, GRN or BLU for RGB colors, or CIEX, |
2786 |
CIEY or CIEZ for XYZ colors. |
2787 |
Unless just one primary is needed, it is more efficient to call |
2788 |
\f[C]colr_color\f[R] and use the \f[C]colval\f[R] macro on the result. |
2789 |
.RS 3 |
2790 |
.RE |
2791 |
.IP "\f[B]\f[CB]colr_color(COLOR col, COLR clr);\f[B]\f[R]" 3 |
2792 |
Convert the 4-byte pixel \f[C]clr\f[R] to a machine floating-point |
2793 |
representation and store the result in \f[C]col\f[R]. |
2794 |
.RS 3 |
2795 |
.RE |
2796 |
.IP "\f[B]\f[CB]setcolr(COLR clr, double p1, p2, p3);\f[B]\f[R]" 3 |
2797 |
Assign the 4-byte pixel \f[C]clr\f[R] according to the three primary |
2798 |
values \f[C]p1\f[R], \f[C]p2\f[R] and \f[C]p3\f[R]. |
2799 |
These can be either \f[I]Radiance\f[R] RGB values or CIE XYZ values. |
2800 |
.RS 3 |
2801 |
.RE |
2802 |
.SH 2 |
2803 |
Z-buffer Format (.zbf suffix) |
2804 |
.pdfhref O 2 "Z-buffer Format \(.zbf suffix\)" |
2805 |
.pdfhref M "z-buffer-format-.zbf-suffix" |
2806 |
.LP |
2807 |
The Z-buffer format used in \f[I]Radiance\f[R] hardly qualifies as a |
2808 |
format at all. |
2809 |
It is in fact a straight copy on the 4-byte machine floating point |
2810 |
values of each pixel in standard scanline order. |
2811 |
There is no information header or resolution string that would make the |
2812 |
file independently useful. |
2813 |
This is usually OK, because Z-buffer files are almost always created and |
2814 |
used in conjunction with a picture file, which has this identifying |
2815 |
information. |
2816 |
.PP |
2817 |
The major shortcoming of this format is that the machine representation |
2818 |
and byte ordering is not always the same from one system to another, |
2819 |
which limits the portability of Z-buffer files. |
2820 |
Since they are primarily used for interpolating animation frames, and |
2821 |
this usually occurs on networks with similar architectures, there is |
2822 |
usually no problem. |
2823 |
Also, since the adoption of IEEE standard floating-point calculations, |
2824 |
different machine representations are becoming quite rare. |
2825 |
[TBD: is this necessary at this point?] |
2826 |
.SH 3 |
2827 |
\f[BI]Radiance\f[B] programs |
2828 |
.pdfhref O 3 "Radiance programs" |
2829 |
.pdfhref M "radiance-programs-6" |
2830 |
.LP |
2831 |
Table 7 shows the programs that read and write \f[I]Radiance\f[R] |
2832 |
Z-buffer files. |
2833 |
The pvalue program may be used to convert Z-buffer files to |
2834 |
\f[I]Radiance\f[R] pictures for the purpose of visualizing the values |
2835 |
using falsecolor. |
2836 |
For example, the following command converts the Z-buffer file |
2837 |
\f[C]frame110.zbf\f[R] associated with the picture |
2838 |
\f[C]frame110.hdr\f[R] to a viewable image: |
2839 |
.IP |
2840 |
.nf |
2841 |
\f[C] |
2842 |
% pvalue -h \[ga]getinfo -d < frame110.hdr\[ga] -r -b -df |
2843 |
frame110.zbf | falsecolor -m 1 -s 40 -l Meters > |
2844 |
frame110z.hdr |
2845 |
\f[] |
2846 |
.fi |
2847 |
.LP |
2848 |
The \f[B]getinfo\f[R] program appearing in back-quotes was used to get |
2849 |
the dimensions associated with the Z-buffer from its corresponding |
2850 |
picture file. |
2851 |
.PP |
2852 |
.na |
2853 |
.TS |
2854 |
delim(@@) tab( ); |
2855 |
l l l l. |
2856 |
T{ |
2857 |
Program |
2858 |
T} T{ |
2859 |
Read |
2860 |
T} T{ |
2861 |
Write |
2862 |
T} T{ |
2863 |
Function |
2864 |
T} |
2865 |
_ |
2866 |
T{ |
2867 |
\f[B]pinterp\f[R] |
2868 |
T} T{ |
2869 |
X |
2870 |
T} T{ |
2871 |
X |
2872 |
T} T{ |
2873 |
Interpolate/extrapolate picture views |
2874 |
T} |
2875 |
T{ |
2876 |
\f[B]pvalue\f[R] |
2877 |
T} T{ |
2878 |
X |
2879 |
T} T{ |
2880 |
X |
2881 |
T} T{ |
2882 |
Convert picture to/from simpler formats |
2883 |
T} |
2884 |
T{ |
2885 |
\f[B]rad\f[R] |
2886 |
T} T{ |
2887 |
T} T{ |
2888 |
X |
2889 |
T} T{ |
2890 |
Render Radiance scene |
2891 |
T} |
2892 |
T{ |
2893 |
\f[B]ranimate\f[R] |
2894 |
T} T{ |
2895 |
X |
2896 |
T} T{ |
2897 |
X |
2898 |
T} T{ |
2899 |
Animate Radiance scene |
2900 |
T} |
2901 |
T{ |
2902 |
\f[B]rpict\f[R] |
2903 |
T} T{ |
2904 |
T} T{ |
2905 |
X |
2906 |
T} T{ |
2907 |
Batch rendering program |
2908 |
T} |
2909 |
T{ |
2910 |
\f[B]rtrace\f[R] |
2911 |
T} T{ |
2912 |
T} T{ |
2913 |
X |
2914 |
T} T{ |
2915 |
Customizable ray-tracer |
2916 |
T} |
2917 |
.TE |
2918 |
.ad |
2919 |
.LP |
2920 |
\f[B]Table 7.\f[R] \f[I]Radiance\f[R] programs that read and write |
2921 |
Z-buffer files. |
2922 |
.SH 3 |
2923 |
\f[BI]Radiance\f[B] C Library |
2924 |
.pdfhref O 3 "Radiance C Library" |
2925 |
.pdfhref M "radiance-c-library-6" |
2926 |
.LP |
2927 |
There are no library functions devoted to reading and writing Z-buffer |
2928 |
files in particular. |
2929 |
The normal method is to read and write Z-buffer scanlines with the |
2930 |
standard \f[C]fread\f[R] and \f[C]fwrite\f[R] library functions using an |
2931 |
appropriate float array. |
2932 |
.SH 2 |
2933 |
Ambient File Format (.amb suffix) |
2934 |
.pdfhref O 2 "Ambient File Format \(.amb suffix\)" |
2935 |
.pdfhref M "ambient-file-format-.amb-suffix" |
2936 |
.LP |
2937 |
\f[I]Radiance\f[R] can store its diffuse interreflection cache in an |
2938 |
\f[I]ambient file\f[R] for reuse by other processes. |
2939 |
This file is in a system-independent binary format, similar to an octree |
2940 |
or picture file, with an information header that can be read using |
2941 |
\f[B]getinfo\f[R]. |
2942 |
Following the header, there is a magic number specific to this file |
2943 |
type, then the ambient value records themselves in encoded form. |
2944 |
.SH 4 |
2945 |
Information Header |
2946 |
.pdfhref O 4 "Information Header" |
2947 |
.pdfhref M "information-header-2" |
2948 |
.LP |
2949 |
The information header begins with the usual \[lq]#?RADIANCE\[rq] |
2950 |
identifier, followed by the originating program and the ambient |
2951 |
calculation parameters (and octree name). |
2952 |
After this is the line: |
2953 |
.IP |
2954 |
.nf |
2955 |
\f[C] |
2956 |
FORMAT=Radiance_ambval |
2957 |
\f[] |
2958 |
.fi |
2959 |
.LP |
2960 |
This identifies the general file type, followed by an empty line ending |
2961 |
the header. |
2962 |
As with most information headers, this exact sequence need not be |
2963 |
followed, so long as there is no inconsistent \f[C]FORMAT\f[R] setting. |
2964 |
.SH 4 |
2965 |
Magic Number |
2966 |
.pdfhref O 4 "Magic Number" |
2967 |
.pdfhref M "magic-number" |
2968 |
.LP |
2969 |
Following the information header is the two-byte magic number, which for |
2970 |
the current ambient file format is 557. |
2971 |
This number may change later should the file format be altered in |
2972 |
incompatible ways. |
2973 |
.SH 4 |
2974 |
Ambient Value Records |
2975 |
.pdfhref O 4 "Ambient Value Records" |
2976 |
.pdfhref M "ambient-value-records" |
2977 |
.LP |
2978 |
Ambient values are written to the file in no particular order. |
2979 |
Each diffuse interreflection value in \f[I]Radiance\f[R] has the |
2980 |
following members: |
2981 |
.IP "\f[B]Level\f[R]" 3 |
2982 |
The number of reflections between the primary (eye) ray and this |
2983 |
surface. |
2984 |
A value with fewer reflections may be used in place of one with more, |
2985 |
but not the other way around. |
2986 |
.RS 3 |
2987 |
.RE |
2988 |
.IP "\f[B]Weight\f[R]" 3 |
2989 |
The weighting value associated with this ray or ambient value. |
2990 |
Similar to the level to avoid using inappropriate values from the cache. |
2991 |
.RS 3 |
2992 |
.RE |
2993 |
.IP "\f[B]Position\f[R]" 3 |
2994 |
The origin point of this interreflection calculation. |
2995 |
.RS 3 |
2996 |
.RE |
2997 |
.IP "\f[B]Direction\f[R]" 3 |
2998 |
The surface normal indicating the zenith of the sample hemisphere for |
2999 |
this value. |
3000 |
.RS 3 |
3001 |
.RE |
3002 |
.IP "\f[B]Value\f[R]" 3 |
3003 |
The calculated indirect irradiance at this point, in w/m\*{2\*} (RGB |
3004 |
color). |
3005 |
.RS 3 |
3006 |
.RE |
3007 |
.IP "\f[B]Radius\f[R]" 3 |
3008 |
The cosine-weighted, harmonic mean distance to other surfaces visible |
3009 |
from this point, used to decide point spacing. |
3010 |
.RS 3 |
3011 |
.RE |
3012 |
.IP "\f[B]Posgradient\f[R]" 3 |
3013 |
The position-based gradient vector, indicating how brightness changes as |
3014 |
a function of position in the sample plane. |
3015 |
.RS 3 |
3016 |
.RE |
3017 |
.IP "\f[B]Dirgradient\f[R]" 3 |
3018 |
The direction-based gradient vector, indicating how brightness changes |
3019 |
as a function of surface orientation. |
3020 |
.RS 3 |
3021 |
.RE |
3022 |
.LP |
3023 |
The members are stored one after the other in the above order using |
3024 |
system-independent binary representations. |
3025 |
The Level member takes 1 byte, Weight takes 5, Position takes 15, |
3026 |
Direction another 15, Value is 4 bytes (using the same color format as |
3027 |
\f[I]Radiance\f[R] pictures), Radius takes 5 bytes, and Posgradient and |
3028 |
Dirgradient each take 15 bytes, for a total size of 75 bytes per record. |
3029 |
.SH 3 |
3030 |
\f[BI]Radiance\f[B] Programs |
3031 |
.pdfhref O 3 "Radiance Programs" |
3032 |
.pdfhref M "radiance-programs-7" |
3033 |
.LP |
3034 |
Table 8 shows \f[I]Radiance\f[R] programs that read and write ambient |
3035 |
files. |
3036 |
The program \f[B]lookamb\f[R] is especially useful for examining the |
3037 |
contents of ambient files and debugging problems in the calculation. |
3038 |
.PP |
3039 |
.na |
3040 |
.TS |
3041 |
delim(@@) tab( ); |
3042 |
l l l l. |
3043 |
T{ |
3044 |
Program |
3045 |
T} T{ |
3046 |
Read |
3047 |
T} T{ |
3048 |
Write |
3049 |
T} T{ |
3050 |
Function |
3051 |
T} |
3052 |
_ |
3053 |
T{ |
3054 |
\f[B]getinfo\f[R] |
3055 |
T} T{ |
3056 |
X |
3057 |
T} T{ |
3058 |
T} T{ |
3059 |
Print information header from binary file |
3060 |
T} |
3061 |
T{ |
3062 |
\f[B]lookamb\f[R] |
3063 |
T} T{ |
3064 |
X |
3065 |
T} T{ |
3066 |
X |
3067 |
T} T{ |
3068 |
Convert \f[I]Radiance\f[R] ambient file |
3069 |
T} |
3070 |
T{ |
3071 |
\f[B]rad\f[R] |
3072 |
T} T{ |
3073 |
X |
3074 |
T} T{ |
3075 |
X |
3076 |
T} T{ |
3077 |
Render \f[I]Radiance\f[R] scene |
3078 |
T} |
3079 |
T{ |
3080 |
\f[B]rpict\f[R] |
3081 |
T} T{ |
3082 |
X |
3083 |
T} T{ |
3084 |
X |
3085 |
T} T{ |
3086 |
Batch rendering program |
3087 |
T} |
3088 |
T{ |
3089 |
\f[B]rpiece\f[R] |
3090 |
T} T{ |
3091 |
X |
3092 |
T} T{ |
3093 |
X |
3094 |
T} T{ |
3095 |
Parallel batch rendering program |
3096 |
T} |
3097 |
T{ |
3098 |
\f[B]rtrace\f[R] |
3099 |
T} T{ |
3100 |
X |
3101 |
T} T{ |
3102 |
X |
3103 |
T} T{ |
3104 |
Customizable ray-tracer |
3105 |
T} |
3106 |
T{ |
3107 |
\f[B]rview\f[R] |
3108 |
T} T{ |
3109 |
X |
3110 |
T} T{ |
3111 |
X |
3112 |
T} T{ |
3113 |
Interactive renderer |
3114 |
T} |
3115 |
.TE |
3116 |
.ad |
3117 |
.LP |
3118 |
\f[B]Table 8.\f[R] Programs in the \f[I]Radiance\f[R] distribution that |
3119 |
read and write ambient files. |
3120 |
.SH 3 |
3121 |
\f[BI]Radiance\f[B] C Library |
3122 |
.pdfhref O 3 "Radiance C Library" |
3123 |
.pdfhref M "radiance-c-library-7" |
3124 |
.LP |
3125 |
The \f[C]src/rt/ambient.h\f[R] file contains definitions of the |
3126 |
\f[C]AMBVAL\f[R] structure and certain details of the ambient file |
3127 |
format. |
3128 |
The \f[C]src/rt/ambio.c\f[R] module contains the specialized routines |
3129 |
for reading and writing ambient files, and these functions in turn |
3130 |
access routines in \f[C]src/common/portio.c\f[R] for reading and writing |
3131 |
portable binary data. |
3132 |
The information header is handled by the routines in |
3133 |
s\f[C]rc/common/header.c\f[R], similar to the method described for |
3134 |
\f[I]Radiance\f[R] picture files. |
3135 |
Here are the main calls from \f[C]src/rt/ambio.c\f[R]: |
3136 |
.IP "\f[B]\f[CB]putambmagic(FILE *fp);\f[B]\f[R]" 3 |
3137 |
Put out the appropriate two-byte magic number for a \f[I]Radiance\f[R] |
3138 |
ambient file to the stream \f[C]fp\f[R]. |
3139 |
.RS 3 |
3140 |
.RE |
3141 |
.IP "\f[B]\f[CB]int hasambmagic(FILE *fp);\f[B]\f[R]" 3 |
3142 |
Read the next two bytes from the stream \f[C]fp\f[R] and return non-zero |
3143 |
if they match an ambient file\[cq]s magic number. |
3144 |
.RS 3 |
3145 |
.RE |
3146 |
.IP "\f[B]\f[CB]int writeambval(AMBVAL *av, FILE *fp);\f[B]\f[R]" 3 |
3147 |
Write out the ambient value structure \f[C]av\f[R] to the stream |
3148 |
\f[C]fp\f[R], returning -1 if a file error occurred, or 0 normally. |
3149 |
.RS 3 |
3150 |
.RE |
3151 |
.IP "\f[B]\f[CB]int readambval(AMBVAL *av, FILE *fp);\f[B]\f[R]" 3 |
3152 |
Read in the next ambient value structure from the stream \f[C]fp\f[R] |
3153 |
and put the result in \f[C]av\f[R]. |
3154 |
Return 1 if the read was successful, 0 if the end of file was reached or |
3155 |
there was an error. |
3156 |
The \f[C]ambvalOK\f[R] function is used to check the consistency of the |
3157 |
value read. |
3158 |
.RS 3 |
3159 |
.RE |
3160 |
.IP "\f[B]\f[CB]int ambvalOK(AMBVAL *av);\f[B]\f[R]" 3 |
3161 |
Return non-zero if the member values of the \f[C]av\f[R] structure are |
3162 |
not too outlandish. |
3163 |
This is handy as insurance against a corrupted ambient file. |
3164 |
.RS 3 |
3165 |
.RE |
3166 |
.SH 2 |
3167 |
Conclusion |
3168 |
.pdfhref O 2 "Conclusion" |
3169 |
.pdfhref M "conclusion" |
3170 |
.LP |
3171 |
We have described the main file formats native to \f[I]Radiance\f[R] and |
3172 |
shown how even the binary formats can be reliably shared in |
3173 |
heterogeneous computing environments. |
3174 |
This corresponds to one of the basic philosophies of UNIX software, |
3175 |
which is system independence. |
3176 |
A more detailed understanding of the formats may still require some use |
3177 |
of binary dump programs and delving into the \f[I]Radiance\f[R] source |
3178 |
code. |