-
Notifications
You must be signed in to change notification settings - Fork 344
/
Copy pathfileformat.html
4301 lines (4228 loc) · 153 KB
/
fileformat.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>The pbrt Input File Format</title>
<style type="text/css">
/*
:Author: David Goodger ([email protected])
:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left {
clear: left }
img.align-right {
clear: right }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="the-pbrt-input-file-format">
<h1 class="title">The pbrt Input File Format</h1>
<!-- ..image:: images/biohazard.png -->
<p>This document is a reference to the file format used in the <tt class="docutils literal"><span class="pre">pbrt</span></tt>
rendering system described in the "Physically Based Rendering" book; see
the <a class="reference external" href="http://pbrt.org/">pbrt website</a> for more information about <tt class="docutils literal"><span class="pre">pbrt</span></tt>. Note that this
document serves as a comprehensive reference; the pbrt User's Guide (which
is still yet to be written) will document how to use <tt class="docutils literal"><span class="pre">pbrt</span></tt> with more
focus on how to achieve certain tasks or how to address various issues in
the results it renders.</p>
<p><strong>Note: this document is still in draft form and sections are still, unfortunately, incomplete. The text is currently complete up to the "Materials"; in that section and beyond, the parameters to the various object implementations are listed correctly, but the accompanying text hasn't been written yet. I will try to have this all finished in the next few days.</strong></p>
<p>Contents:</p>
<ul class="simple">
<li><a class="reference internal" href="#general-structure-of-a-pbrt-input-file">General structure of a pbrt input file</a><ul>
<li><a class="reference internal" href="#parameter-lists">Parameter Lists</a></li>
<li><a class="reference internal" href="#specifying-transformations">Specifying Transformations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#specifying-scene-wide-rendering-options">Specifying Scene-Wide Rendering Options</a><ul>
<li><a class="reference internal" href="#cameras">Cameras</a></li>
<li><a class="reference internal" href="#samplers">Samplers</a></li>
<li><a class="reference internal" href="#film">Film</a></li>
<li><a class="reference internal" href="#filters">Filters</a></li>
<li><a class="reference internal" href="#renderers">Renderers</a></li>
<li><a class="reference internal" href="#surface-integrators">Surface Integrators</a></li>
<li><a class="reference internal" href="#volume-integrators">Volume Integrators</a></li>
<li><a class="reference internal" href="#accelerators">Accelerators</a></li>
</ul>
</li>
<li><a class="reference internal" href="#specifying-the-world">Specifying the World</a><ul>
<li><a class="reference internal" href="#attributes">Attributes</a></li>
<li><a class="reference internal" href="#shapes">Shapes</a></li>
<li><a class="reference internal" href="#object-instancing">Object Instancing</a></li>
<li><a class="reference internal" href="#lights">Lights</a></li>
<li><a class="reference internal" href="#area-lights">Area Lights</a></li>
<li><a class="reference internal" href="#materials">Materials</a></li>
<li><a class="reference internal" href="#textures">Textures</a></li>
<li><a class="reference internal" href="#scattering-volumes">Scattering Volumes</a></li>
</ul>
</li>
</ul>
<p>The scene description files used by <tt class="docutils literal"><span class="pre">pbrt</span></tt> are plain text files. The
file format was designed so that it would be both easy to parse and easy
for applications to generate from their own internal representations of
scenes. While a binary file format would result in smaller files and
faster parsing, a human-readable format is far easier to edit by hand. The
input file parser is very simple. It contains no logic about the validity
of any statement beyond its basic syntax; it just calls the corresponding
API function. (There was no reason for the parsers to duplicate all of the
error-checking logic in the API implementation.)</p>
<p>A <tt class="docutils literal"><span class="pre">pbrt</span></tt> scene file consists of a series of statements; different
statements specify the geometry and light sources in the scene and set
overall rendering parameters (such as which light transport algorithm to
use or the image resolution.) Each statement in these files corresponds
directly to a <tt class="docutils literal"><span class="pre">pbrt</span></tt> API function from Appendix B in the "Physically
Based Rendering" book. For example, when the <tt class="docutils literal"><span class="pre">WorldBegin</span></tt> statement
appears in the input, the <tt class="docutils literal"><span class="pre">pbrtWorldBegin()</span></tt> function is called. To best
understand this document, you should already be familiar with the concepts
introduced in Appendix B, though we will try to re-introduce some key
concepts from that appendix here.</p>
<p>Here is a short example of a <tt class="docutils literal"><span class="pre">pbrt</span></tt> input file: Between the start of the
file and the <tt class="docutils literal"><span class="pre">WorldBegin</span></tt> statement, overall options for rendering the
scene are specified, including the camera type and position, the sampler
definition, and information about the image to be generated. After
<tt class="docutils literal"><span class="pre">WorldBegin</span></tt>, the lights, geometry, and scattering volumes (if any) in
the scene are defined, up until the <tt class="docutils literal"><span class="pre">WorldEnd</span></tt> statement, which causes
the image to be rendered. The hash character <tt class="docutils literal"><span class="pre">#</span></tt> denotes that the rest
of the line is a comment and should be ignored by the parser.</p>
<pre class="literal-block">
LookAt 0 10 100 0 -1 0 0 1 0
Camera "perspective" "float fov" [30]
PixelFilter "mitchell" "float xwidth" [2] "float ywidth" [2]
Sampler "bestcandidate"
Film "image" "string filename" ["simple.exr"]
"integer xresolution" [200] "integer yresolution" [200]
WorldBegin
AttributeBegin
CoordSysTransform "camera"
LightSource "distant"
"point from" [0 0 0] "point to" [0 0 1]
"rgb L" [3 3 3]
AttributeEnd
AttributeBegin
Rotate 135 1 0 0
Texture "checks" "spectrum" "checkerboard"
"float uscale" [4] "float vscale" [4]
"rgb tex1" [1 0 0] "rgb tex2" [0 0 1]
Material "matte"
"texture Kd" "checks"
Shape "disk" "float radius" [20] "float height" [-1]
AttributeEnd
WorldEnd
</pre>
<div class="section" id="general-structure-of-a-pbrt-input-file">
<h1>General structure of a pbrt input file</h1>
<p>A scene description file starts with a series of directives that describe
the camera, film, and sampling and light transport algorithms to use in
rendering the scene. These are followed by the <tt class="docutils literal"><span class="pre">WorldBegin</span></tt> directive;
after <tt class="docutils literal"><span class="pre">WorldBegin</span></tt>, the world definition block starts, and it is no
longer legal to specify different definitions of any of the objects defined
in the initial section of the file. However, lights, materials, textures,
shapes, and volumetric scattering regions can be defined inside the world
block (and can only be defined inside the world block). The world block
ends with the <tt class="docutils literal"><span class="pre">WorldEnd</span></tt> directive; when this is encountered, the
<tt class="docutils literal"><span class="pre">Renderer</span></tt> defined to render the scene takes control and does the
required rendering computation.</p>
<p>The following section, <a class="reference internal" href="#specifying-scene-wide-rendering-options">Specifying Scene-Wide Rendering Options</a>,
documents the directives that are valid outside of the world definition
block. The subsequent section, <a class="reference internal" href="#specifying-the-world">Specifying the World</a>, documents the
directives for defining the shapes, materials, lights, etc., that define
the scene.</p>
<p>Some of the statements in the input file, such as <tt class="docutils literal"><span class="pre">WorldBegin</span></tt>,
<tt class="docutils literal"><span class="pre">AttributeEnd</span></tt>, and so on, have no additional arguments. Others, such as
those related to specifying transformations, such as <tt class="docutils literal"><span class="pre">Rotate</span></tt> and
<tt class="docutils literal"><span class="pre">LookAt</span></tt>, take a predetermined number of arguments of predetermined
type. (For example, <tt class="docutils literal"><span class="pre">Translate</span></tt> is followed by three floating-point
values that give the x, y, and z components of the translation vector. The
remainder of the statements take a variable number of arguments and are of
the form</p>
<blockquote>
<em>identifier</em> "<em>type</em>" <em>parameter-list</em></blockquote>
<p>For example, the <tt class="docutils literal"><span class="pre">Shape</span></tt> identifier describes a shape to be added to the
scene, where the type of shape to create is given by a string
(e.g. "sphere") and is followed a list of shape-specific parameters that
define the shape. For example,</p>
<pre class="literal-block">
Shape "sphere" "float radius" [5]
</pre>
<p>defines a sphere of radius 5. (See <a class="reference internal" href="#shapes">Shapes</a> for documentation of the
parmeters taken by the various shapes implemented in <tt class="docutils literal"><span class="pre">pbrt</span></tt>.)</p>
<p>Here, the "type" string gives the name of the particular shape, etc.,
implementation to use, and <em>parameter-list</em> gives the parameters to pass to
the plug-in. With this design, the parser doesn't need to know anything
about the semantics of the parameters; it just needs to know how to parse
parameter lists and how to initialize a <tt class="docutils literal"><span class="pre">ParamSet</span></tt> from them (The
<tt class="docutils literal"><span class="pre">ParamSet</span></tt> class is described on page 1047 of the PBR book).</p>
<p>Almost all directives in a <tt class="docutils literal"><span class="pre">pbrt</span></tt> input file have a direct correspondence
with a function in the <tt class="docutils literal"><span class="pre">pbrt</span></tt> API, defined in the files <tt class="docutils literal"><span class="pre">core/api.h</span></tt>
and <tt class="docutils literal"><span class="pre">core/api.cpp</span></tt>. The only input file directive that does not directly
correspond to a function in the API is the <tt class="docutils literal"><span class="pre">Include</span></tt> statement, which
allows other input files to be parsed. <tt class="docutils literal"><span class="pre">Include</span></tt> behaves similarly to
the <tt class="docutils literal"><span class="pre">#include</span></tt> directive in C++, except that only the directory that the
currently-being-processed input file is searched for matching filenames.
Of course, a complete pathname or a path relative to the current directory
can be specified if appropriate.</p>
<pre class="literal-block">
Include "geometry/car.pbrt"
</pre>
<div class="section" id="parameter-lists">
<h2>Parameter Lists</h2>
<p>Variable-length lists of named parameters and their values are the key
meeting ground between the parsing system and the objects that are created
to represent the scene. Each of these lists holds an arbitrary number of
name/value pairs, with the name in quotation marks and the value or values
in square brackets:</p>
<blockquote>
"<em>type</em> <em>name</em>" <tt class="docutils literal"><span class="pre">[</span></tt> <em>value or values</em> <tt class="docutils literal"><span class="pre">]</span></tt></blockquote>
<p>For example,</p>
<pre class="literal-block">
"float fov" [30]
</pre>
<p>specifies a parameter "fov" that is a single floating-point
value, with value 30. Or,</p>
<pre class="literal-block">
"float cropwindow" [0 .5 0 .25]
</pre>
<p>specifies that "cropwindow" is a floating-point array with the given four
values. Notice that values are enclosed in square brackets. Single values
(such as the "30" in the "fov" example above) may be provided with or
without square brackets enclosing them, though arrays of values always must
be enclosed in square brackets.</p>
<p>The type of each parameter must always be given along with its name;
<tt class="docutils literal"><span class="pre">pbrt</span></tt> has no built-in knowledge of any parameter names. This simplifies
the parsing system, although it does create a small extra burden for the
creator of the input file.</p>
<p><tt class="docutils literal"><span class="pre">pbrt</span></tt> supports seven basic parameter types: <tt class="docutils literal"><span class="pre">integer</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>,
<tt class="docutils literal"><span class="pre">point</span></tt>, <tt class="docutils literal"><span class="pre">vector</span></tt>, <tt class="docutils literal"><span class="pre">normal</span></tt>, <tt class="docutils literal"><span class="pre">spectrum</span></tt>, <tt class="docutils literal"><span class="pre">bool</span></tt>, and <tt class="docutils literal"><span class="pre">string</span></tt>.
The <tt class="docutils literal"><span class="pre">point</span></tt>, <tt class="docutils literal"><span class="pre">vector</span></tt>, and <tt class="docutils literal"><span class="pre">normal</span></tt> types all take three
floating-point values to specify each value. <tt class="docutils literal"><span class="pre">string</span></tt> parameters must be
inside quotation marks, and <tt class="docutils literal"><span class="pre">bool</span></tt> parameters are set with the strings
<tt class="docutils literal"><span class="pre">"true"</span></tt> and <tt class="docutils literal"><span class="pre">"false"</span></tt>, quotation marks included.</p>
<pre class="literal-block">
"string filename" "foo.exr"
"point origin" [ 0 1 2 ]
"normal N" [ 0 1 0 0 0 1 ] # array of 2 normal values
"bool renderquickly" "true"
</pre>
<p><tt class="docutils literal"><span class="pre">pbrt</span></tt> provides a number of ways of specifying spectral values in scene
description files. RGB values are commonly used, though see Section 5.2.2
on page 273 of the second edition of "Physically Based Rendering" for
discussion of the shortcomings of this representation. RGB color values
can be specified with the <tt class="docutils literal"><span class="pre">rgb</span></tt> type. (<tt class="docutils literal"><span class="pre">color</span></tt> is also supported as a
synonym for this):</p>
<pre class="literal-block">
"rgb Kd" [ .2 .5 .3 ]
</pre>
<p>specifies the RGB color with red equal to 0.2 and so forth. The
<tt class="docutils literal"><span class="pre">FromRGB()</span></tt> method of the <tt class="docutils literal"><span class="pre">Spectrum</span></tt> implementation being used is used
to convert the given RGB colors to the current spectral representation.</p>
<p>Alternatively, XYZ colors can be used to specify a spectrum:</p>
<pre class="literal-block">
"xyz Kd" [ .4 .6 .7 ]
</pre>
<p>General sampled SPDs are specified with a series of (wavelength, value)
pairs, where wavelengths are specified in nm. These SPDs are resampled to
the current spectral representation with its <tt class="docutils literal"><span class="pre">FromSampled()</span></tt> method. For
example,</p>
<pre class="literal-block">
"spectrum Kd" [ 300 .3 400 .6 410 .65 415 .8 500 .2 600 .1 ]
</pre>
<p>specifies a piecewise-linar SPD with a value of 0.3 at 300nm, 0.6 and
400nm, and so forth. Since complex sampled SPDs may have many values, they
can also be provided through a separate file:</p>
<pre class="literal-block">
"spectrum Kd" "filename"
</pre>
<p>Where the filename specifies the path to a plain text file with pairs of
floating-point (wavelength, value) as above. The parser for these files
allows uses <tt class="docutils literal"><span class="pre">#</span></tt> to denote a comment that goes to the end of the current
line. See the directory <tt class="docutils literal"><span class="pre">scenes/spds</span></tt> in the <tt class="docutils literal"><span class="pre">pbrt</span></tt> distribution for
examples.</p>
<p>Finally, SPDs of blackbody emitters can be specified with two
floating-point values, one giving the blackbody temperature in Kelvin, and
the second giving a scale factor. See the <a class="reference external" href="http://en.wikipedia.org/wiki/Black_body">Wikipedia article</a> on blackbody
emitters for more information and the formula used to compute the SPD from
the blackbody temperature:</p>
<pre class="literal-block">
"blackbody L" [ 6500 1 ] # daylight, approximately
</pre>
</div>
<div class="section" id="specifying-transformations">
<h2>Specifying Transformations</h2>
<p>A series of directives modify the current transformation marix (CTM). (See
Section B.2.2 on page 1053 for more information about how the CTM is
maintined during scene description.) When the scene's camera is specified,
the CTM gives the world to camera transformation; when a light or shape is
created, the CTM specifies the transformation from object space to world
space.</p>
<p>When parsing begins, the CTM is the identity transformation; furthermore,
it is is reset to the identity when the <tt class="docutils literal"><span class="pre">WorldBegin</span></tt> directive is
encountered. The following directives change the CTM; they are shown with
the corresponding <tt class="docutils literal"><span class="pre">pbrt</span></tt> API call:</p>
<table border="1" class="docutils">
<colgroup>
<col width="59%" />
<col width="41%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Input File Syntax</th>
<th class="head">API Call</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">Identity</span></tt></td>
<td><tt class="docutils literal"><span class="pre">pbrtIdentity()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">Translate</span></tt> <em>x y z</em></td>
<td><tt class="docutils literal"><span class="pre">pbrtTranslate()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">Scale</span></tt> <em>x y z</em></td>
<td><tt class="docutils literal"><span class="pre">pbrtScale()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">Rotate</span></tt> <em>angle x y z</em></td>
<td><tt class="docutils literal"><span class="pre">pbrtRotate()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">LookAt</span></tt> <em>ex ey ez lx ly lz ux uy uz</em></td>
<td><tt class="docutils literal"><span class="pre">pbrtLookAt()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">CoordinateSystem</span></tt> "<em>name</em>"</td>
<td><tt class="docutils literal"><span class="pre">pbrtCoordinateSystem()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">CoordSysTransform</span></tt> "<em>name</em>"</td>
<td><tt class="docutils literal"><span class="pre">pbrtCoordSysTransform()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">Transform</span></tt> <em>m00 ... m33</em></td>
<td><tt class="docutils literal"><span class="pre">pbrtTransform()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">ConcatTransform</span></tt> <em>m00 .. m33</em></td>
<td><tt class="docutils literal"><span class="pre">pbrtConcatTransform()</span></tt></td>
</tr>
</tbody>
</table>
<p>For example, <tt class="docutils literal"><span class="pre">Translate</span></tt> takes three floating-point values, <em>x</em>, <em>y</em>, and
<em>z</em>, and the corresponding values are passed to the <tt class="docutils literal"><span class="pre">pbrtTranslate()</span></tt> API
call, which in turn modifies the CTM by setting it to the product of the
CTM with the matrix representing the given translation.</p>
<p><tt class="docutils literal"><span class="pre">pbrt</span></tt> supports animated transformations by allowing two transformation
matrices to be specified at different times. The <tt class="docutils literal"><span class="pre">TransformTimes</span></tt>
directive, which must be outside of the world definition block, defines these
two times with floating-point vaues:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">TransformTimes</span></tt> <em>start</em> <em>end</em></blockquote>
<p>Then, the <tt class="docutils literal"><span class="pre">ActiveTransform</span></tt> directive indicates whether subsequent
directives that modify the CTM should apply to the transformation at the
starting time, the transformation at the ending time, or both. The default
is that both matrices should be updated:</p>
<pre class="literal-block">
Translate 1 0 0 # applies to both, by default
ActiveTransform StartTime
Rotate 90 1 0 0
ActiveTransform EndTime
Rotate 120 0 1 0
ActiveTransform All
</pre>
</div>
</div>
<div class="section" id="specifying-scene-wide-rendering-options">
<h1>Specifying Scene-Wide Rendering Options</h1>
<p>This section describes rendering options that must be specified before the
<tt class="docutils literal"><span class="pre">WorldBegin</span></tt> statement. The following sub-sections describe how options
related to each of the following are set:</p>
<ul class="simple">
<li><a class="reference internal" href="#cameras">Cameras</a></li>
<li><a class="reference internal" href="#samplers">Samplers</a></li>
<li><a class="reference internal" href="#film">Film</a></li>
<li><a class="reference internal" href="#filters">Filters</a></li>
<li><a class="reference internal" href="#renderers">Renderers</a></li>
<li><a class="reference internal" href="#surface-integrators">Surface Integrators</a></li>
<li><a class="reference internal" href="#volume-integrators">Volume Integrators</a></li>
<li><a class="reference internal" href="#accelerators">Accelerators</a></li>
</ul>
<div class="section" id="cameras">
<h2>Cameras</h2>
<p>The <tt class="docutils literal"><span class="pre">Camera</span></tt> directive specifies the camera used for viewing the scene. <a class="footnote-reference" href="#id2" id="id1">[1]</a>
For example,</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>The camera is used when <tt class="docutils literal"><span class="pre">pbrt</span></tt> is used to render an actual image. However, some of <tt class="docutils literal"><span class="pre">pbrt</span></tt>'s <tt class="docutils literal"><span class="pre">Renderer</span></tt> implementations compute other quantities--for example, <tt class="docutils literal"><span class="pre">AggregateTest</span></tt> tests ray tracing acceleration structures and <tt class="docutils literal"><span class="pre">CreateRadianceProbes</span></tt> computes spherical harmonic radiance probes at a grid of locations--neither one of these uses the camera. See the section on <a class="reference internal" href="#renderers">Renderers</a> for more discussion.</td></tr>
</tbody>
</table>
<pre class="literal-block">
Camera "perspective" "float fov" [60]
</pre>
<p>When the <tt class="docutils literal"><span class="pre">Camera</span></tt> directive is encountered in an input file, the current
transformation matrix is used to initialize the world-to-camera
transformation.</p>
<p><tt class="docutils literal"><span class="pre">pbrt</span></tt> provides three camera implementations:</p>
<table border="1" class="docutils">
<colgroup>
<col width="49%" />
<col width="51%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Implementation Class</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>"environment"</td>
<td><tt class="docutils literal"><span class="pre">EnvironmentCamera</span></tt></td>
</tr>
<tr><td>"orthographic"</td>
<td><tt class="docutils literal"><span class="pre">OrthoCamera</span></tt></td>
</tr>
<tr><td>"perspective"</td>
<td><tt class="docutils literal"><span class="pre">PerspectiveCamera</span></tt></td>
</tr>
</tbody>
</table>
<p>The default camera is a <tt class="docutils literal"><span class="pre">PerspectiveCamera</span></tt> with the default values
listed below (90 degree field of view, etc.)</p>
<p>A number of parameters are common to all cameras in <tt class="docutils literal"><span class="pre">pbrt</span></tt>:</p>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="16%" />
<col width="13%" />
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head">Name</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>float</td>
<td>shutteropen</td>
<td>0</td>
<td>The time at which the virtual camera shutter opens.</td>
</tr>
<tr><td>float</td>
<td>shutterclose</td>
<td>1</td>
<td>The time at which the virtual camera shutter closes.</td>
</tr>
<tr><td>float</td>
<td>frameaspectratio</td>
<td>(see description)</td>
<td>The aspect ratio of the film. By default, this is computed from
the x and y resolutions of the film, but it can be overridden if desired.</td>
</tr>
<tr><td>float[4]</td>
<td>screenwindow</td>
<td>(see description)</td>
<td>The bounds of the film plane in screen space. By default, this
is [-1,1] along the shorter image axis and is set proportionally along the
longer axis.</td>
</tr>
</tbody>
</table>
<p>(The <tt class="docutils literal"><span class="pre">EnvironmentCamera</span></tt> takes no additional parameters beyond these.)</p>
<p><tt class="docutils literal"><span class="pre">PerspectiveCamera</span></tt> and <tt class="docutils literal"><span class="pre">OrthoCamera</span></tt> support images rendered with
depth of field. They both use the following two parmaeters to set the lens
focus, etc.</p>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="16%" />
<col width="13%" />
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head">Name</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>float</td>
<td>lensradius</td>
<td>0</td>
<td>The radius of the lens. Used to render scenes with depth of field
and focus effects. The default value yields a pinhole camera.</td>
</tr>
<tr><td>float</td>
<td>focaldistance</td>
<td>10^30</td>
<td>The focal distance of the lens. If "lensradius" is zero, this has
no effect. Otherwise, it specifies the distance from the camera origin
to the focal plane.</td>
</tr>
</tbody>
</table>
<p>Finally, the perspective camera has two (semi-redundant) parameters for
setting the camera's field of view.</p>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="16%" />
<col width="13%" />
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head">Name</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>float</td>
<td>fov</td>
<td>90</td>
<td>Specifies the field of view for the perspective camera. This is
the spread angle of the viewing frustum along the narrower of the
image's width and height.</td>
</tr>
<tr><td>float</td>
<td>halffov</td>
<td>n/a</td>
<td>For convenience to some programs that export from modeling systems, the
camera's field of view can also be specified via the half-angle between
the view direction and the edge of the viewing frustum. If this parameter
isn't provided, then <tt class="docutils literal"><span class="pre">fov</span></tt> is used to set the field of view instead.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="samplers">
<h2>Samplers</h2>
<p>The <tt class="docutils literal"><span class="pre">Sampler</span></tt> generates samples for the image, time, lens, and Monte
Carlo integration. A number of implementations are provided; the default
is "lowdiscrepancy"--the <tt class="docutils literal"><span class="pre">LDSampler</span></tt>. Note that the sampler is only used
if <tt class="docutils literal"><span class="pre">SamplerRenderer</span></tt> is the <tt class="docutils literal"><span class="pre">Renderer</span></tt> being used to render the scene;
other renderers have their own sample generation mechanisms internally
and/or don't need samples in this manner (e.g. <tt class="docutils literal"><span class="pre">AggregateTest</span></tt>).</p>
<table border="1" class="docutils">
<colgroup>
<col width="37%" />
<col width="63%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Implementation Class</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>"adaptive"</td>
<td><tt class="docutils literal"><span class="pre">AdaptiveSampler</span></tt></td>
</tr>
<tr><td>"bestcandidate"</td>
<td><tt class="docutils literal"><span class="pre">BestCandidateSampler</span></tt></td>
</tr>
<tr><td>"halton"</td>
<td><tt class="docutils literal"><span class="pre">HaltonSampler</span></tt> <a class="footnote-reference" href="#sososamp" id="id3">[2]</a></td>
</tr>
<tr><td>"lowdiscrepancy"</td>
<td><tt class="docutils literal"><span class="pre">LDSampler</span></tt></td>
</tr>
<tr><td>"random"</td>
<td><tt class="docutils literal"><span class="pre">RandomSampler</span></tt> <a class="footnote-reference" href="#badsamp" id="id4">[3]</a></td>
</tr>
<tr><td>"stratified"</td>
<td><tt class="docutils literal"><span class="pre">StratifiedSampler</span></tt> <a class="footnote-reference" href="#sososamp" id="id5">[2]</a></td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="sososamp" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id5">2</a>)</em> The <tt class="docutils literal"><span class="pre">HaltonSampler</span></tt> and <tt class="docutils literal"><span class="pre">StratifiedSampler</span></tt> are not as effective as the <tt class="docutils literal"><span class="pre">LDSampler</span></tt>, <tt class="docutils literal"><span class="pre">AdaptiveSampler</span></tt>, or <tt class="docutils literal"><span class="pre">BestCandidateSampler</span></tt>; the sample points they generate aren't as good and thus more samples will generally be required to get a similar result.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="badsamp" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>The <tt class="docutils literal"><span class="pre">RandomSampler</span></tt> generates particularly ineffective sampling patterns. It is really only useful for comparison against more sophisticated approaches and shouldn't otherwise be used.</td></tr>
</tbody>
</table>
<p>The <tt class="docutils literal"><span class="pre">AdaptiveSampler</span></tt> takes a minimum number of samples in each pixel and
then performs a test to see if, according to some metric, they vary
excessively. If so, it takes a higher number of samples. The underlying
sample generation algorithms are based on the low-discrepancy patterns used
by the <tt class="docutils literal"><span class="pre">LDSampler</span></tt>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="14%" />
<col width="12%" />
<col width="57%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head">Name</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>integer</td>
<td>minsamples</td>
<td>4</td>
<td>This is the initial number of samples taken inside each pixel area.</td>
</tr>
<tr><td>integer</td>
<td>maxsamples</td>
<td>32</td>
<td>If the variation test indicates that this is a complex pixel
area, then this number of samples is taken.</td>
</tr>
<tr><td>string</td>
<td>method</td>
<td>contrast</td>
<td>This parameter sets which test to use to see if a pixel is
varying excessively. The two supported values are "contrast",
which indicates that the color contrast between the sample values
should be compared toa threshold, and "shapeid", which indicates
that if different shapes are visible in the pixel area, additional
samples should be taken.</td>
</tr>
</tbody>
</table>
<p>The "bestcandidate", "lowdiscrepancy", "halton", and "random" samplers all take a single parameter, "pixelsamples",
which sets the number of samples to take in each pixel area.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="15%" />
<col width="13%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head">Name</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>integer</td>
<td>pixelsamples</td>
<td>4</td>
<td>The number of samples to take, per pixel. Note that the
number of samples is taken per pixel on average; depending on
the actual sampling algorithm being used, individual
pixel areas may have slightly more or slightly fewer.</td>
</tr>
</tbody>
</table>
<p>The "stratified" sampler has three parameters that control its behavior.</p>
<table border="1" class="docutils">
<colgroup>
<col width="16%" />
<col width="13%" />
<col width="11%" />
<col width="60%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head">Name</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>bool</td>
<td>jitter</td>
<td>"true"</td>
<td>Whether or not the generated samples should be jittered inside each stratum;
this is generally only worth setting to "false" for comparisons
between jittered and uniform sampling--uniform sampling will
almost always give a worse result.</td>
</tr>
<tr><td>integer</td>
<td>xsamples</td>
<td>2</td>
<td>The number of samples per pixel to take in the x direction.</td>
</tr>
<tr><td>integer</td>
<td>ysamples</td>
<td>2</td>
<td>The number of samples per pixel to take in the y direction.
In general, "xsamples" and "ysamples" should be set to the
same value for best results.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="film">
<h2>Film</h2>
<p>The <tt class="docutils literal"><span class="pre">Film</span></tt> directive specifies the characteristics of the image being generated by the renderer.
Note that only the <tt class="docutils literal"><span class="pre">SamplerRenderer</span></tt> and the <tt class="docutils literal"><span class="pre">MetropolisRenderer</span></tt> use the film; the other
renderers don't generate an image per se and thus ignore the film definition.</p>
<p>The only <tt class="docutils literal"><span class="pre">Film</span></tt> implementation currently available in <tt class="docutils literal"><span class="pre">pbrt</span></tt> is
<tt class="docutils literal"><span class="pre">ImageFilm</span></tt> which is specified as <tt class="docutils literal"><span class="pre">"image"</span></tt> in input files. For example:</p>
<pre class="literal-block">
Film "image" "string filename" ["out.exr"]
"float cropwindow" [ .2 .5 .3 .8 ]
</pre>
<p>The "image" film takes a handful of parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="14%" />
<col width="12%" />
<col width="58%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head">Name</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>integer</td>
<td>xresolution</td>
<td>640</td>
<td>The number of pixels in the x direction.</td>
</tr>
<tr><td>integer</td>
<td>yresolution</td>
<td>480</td>
<td>The number of pixels in the y direction.</td>
</tr>
<tr><td>float[4]</td>
<td>cropwindow</td>
<td>[ 0 1 0 1 ]</td>
<td>The subregion of the image to render. The four values specified
should be fractions in the range [0,1], and they represent x_min,
x_max, y_min, and y_max, respectively.
These values are in normalized device coordinates, with (0,0) in the
upper-left corner of the image.</td>
</tr>
<tr><td>string</td>
<td>filename</td>
<td>"pbrt.exr"</td>
<td>The output filename. The <tt class="docutils literal"><span class="pre">ImageFilm</span></tt> uses the suffix of the
given filename to determine the image file format to use. All builds
of <tt class="docutils literal"><span class="pre">pbrt</span></tt> support PFM and TGA format images; those configured to use
the OpenEXR libraries support EXR as well.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="filters">
<h2>Filters</h2>
<p>The implementation of <tt class="docutils literal"><span class="pre">ImageFilm</span></tt> uses an instance of the abstract
<tt class="docutils literal"><span class="pre">Filter</span></tt> class to filter sample values to compute final pixel values.
(Thus, as only the <tt class="docutils literal"><span class="pre">SamplerRenderer</span></tt> and the <tt class="docutils literal"><span class="pre">MetropolisRenderer</span></tt> use
<tt class="docutils literal"><span class="pre">ImageFilm</span></tt>, the filter setting is only relevant when one of those
renderers is being used.</p>
<p><tt class="docutils literal"><span class="pre">pbrt</span></tt> provides a number of filter implementations, listed below. The
default is "box"; while the box filter has a number of known shortcomings,
it is the most effective filter when the low-discrepancy sampler is being
used (recall the illustration in Figure 7.37 on page 392 of PBR).</p>
<table border="1" class="docutils">
<colgroup>
<col width="49%" />
<col width="51%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Implementation Class</th>
</tr>
</thead>
<tbody valign="top">