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