pbrt-v3 Input File Format (2024)

This document is a reference to the file format used inpbrt-v3, the version of the system correspondingto the third edition of Physically Based Rendering; it serves as acomprehensive reference. The pbrt User'sGuide documents how to use pbrt with morefocus on how to achieve certain tasks or how to address various issues inthe results it renders.

The scene description files used by pbrt areplain text files. The file format was designed so that it would be botheasy to parse and easy for applications to generate from their own internalrepresentations of scenes.

A pbrt scene file consists of a series ofstatements; different statements specify the geometry and lightsources in the scene and set overall rendering parameters (such as whichlight transport algorithm to use or the image resolution). Each statementin these files corresponds directly to a pbrt APIfunction from Appendix B in the Physically Based Rendering book.For example, when the WorldBegin statement appearsin the input, the pbrtWorldBegin() function iscalled. To best understand this document, you should already be familiarwith the concepts introduced in Appendix B, though we will try tore-introduce some key concepts from that appendix here.

We tried to minimize changes to the file format in order to make it aseasy as possible to use existing scene description fileswith pbrt-v3. A number of changes were necessaryfor new functionality or changes in the system's implementation. Thebiggest resulting change to input files is thatthe Renderer, SurfaceIntegrator,and VolumeIntegrator directives have all beenunified under Integrator; only a singleintegrator now needs to be specified.

Some functionality was removed:

  • Accelerator "grid": use "bvh" or "kdtree"instead.
  • Material "measured": the new "fourier"material should now be used for measured BRDFs. Note that it uses adifferent representation of BRDFs than "measured" did.
  • Material "shinymetal": use the "uber"material in place of "shinymetal".
  • VolumeRegion: use the new participatingmedia representation: NamedMedium and MediumInterface.
  • SurfaceIntegrator: the "photonmap","irradiancecache", "igi", "dipolesubsurface", "ambientocclusion","useprobes", "diffuseprt" and "glossyprt" integrators have been removed.
    • Use "sppm" for the "photonmap".
    • The "path" integrator now handles subsurface scattering directly.
    • The others aren't as good as path tracing anyway. :-)
  • VolumeIntegrator"single"and emission: use the "volpath" path tracingintegrator.
  • Sampler "bestcandidate": use any other sampler.
  • Renderer: use Integrator, as described above.
  • Texture "image" "float gamma": image maptextures now take a "bool" value to enable or disable conversion fromsRGB to linear texture values; it is true by default for 8-bit textureformats like TGA and false by default for floating-point formats likeOpenEXR.

The documentation on the pbrt-v2 fileformat is still available.

Here is a short example of a pbrt input file:Between the start of the file and the WorldBeginstatement, overall options for rendering the scene are specified, includingthe camera type and position, the sampler definition, and information aboutthe image to be generated. AfterWorldBegin, the lights, geometry, and scatteringvolumes (if any) in the scene are defined, up untilthe WorldEnd statement, which causes the image tobe rendered.

LookAt 3 4 1.5 # eye .5 .5 0 # look at point 0 0 1 # up vectorCamera "perspective" "float fov" 45Sampler "halton" "integer pixelsamples" 128Integrator "path"Film "image" "string filename" "simple.png" "integer xresolution" [400] "integer yresolution" [400]WorldBegin# uniform blue-ish illumination from all directionsLightSource "infinite" "rgb L" [.4 .45 .5]# approximate the sunLightSource "distant" "point from" [ -30 40 100 ] "blackbody L" [3000 1.5]AttributeBegin Material "glass" Shape "sphere" "float radius" 1AttributeEndAttributeBegin Texture "checks" "spectrum" "checkerboard" "float uscale" [8] "float vscale" [8] "rgb tex1" [.1 .1 .1] "rgb tex2" [.8 .8 .8] Material "matte" "texture Kd" "checks" Translate 0 0 -1 Shape "trianglemesh" "integer indices" [0 1 2 0 2 3] "point P" [ -20 -20 0 20 -20 0 20 20 0 -20 20 0 ] "float st" [ 0 0 1 0 1 1 0 1 ]AttributeEndWorldEnd

When rendered with pbrt, this image isgenerated: pbrt-v3 Input File Format (1)

A scene description file starts with a series of directives thatdescribe the camera, film, and sampling and light transport algorithms touse in rendering the scene. These are followed bythe WorldBegin directive;after WorldBegin, the world definition blockstarts, and it is no longer legal to specify different definitions of anyof the objects defined in the initial section of the file. However,lights, materials, textures, shapes, and volumetric scattering regions canbe defined inside the world block (and can only be defined inside the worldblock). The world block ends with the WorldEnddirective; when this is encountered, theIntegrator defined takes control and does therequired rendering computation.

The hash character # denotes that the rest ofthe line is a comment and should be ignored by the parser.

The followingsection, Scene-widerendering options, documents the directives that are valid outside ofthe world definition block. The subsequentsection, Describing the scene,documents the directives for defining the shapes, materials, lights, etc.,that define the scene.

Some of the statements in the input file, such as WorldBegin,AttributeEnd, and so on, have no additional arguments. Others, such asthose related to specifying transformations, such as Rotate andLookAt, take a predetermined number of argumentsof predetermined type. (For example, Translateis followed by three floating-point values that give the x, y, and zcomponents of the translation vector.) The remainder of the statements takea variable number of arguments and are of the form

identifier "type" parameter-list

For example, the Shape identifier describes a shape to be added to thescene, where the type of shape to create is given by a string(e.g. "sphere") and is followed a list of shape-specific parameters thatdefine the shape. For example,

Shape "sphere" "float radius" [5]

defines a sphere of radius 5. (See Shapes for documentation of theparameters taken by the various shapes implemented in pbrt.)

Here, the "type" string gives the name of the particular shape, etc.,implementation to use, and parameter-list gives the parameters to pass tothe implementation. With this design, the parser doesn't need to know anythingabout the semantics of the parameters; it just needs to know how to parseparameter lists and how to initialize a ParamSet from them (TheParamSet class is described starting on page 1105of the third edition of the Physically Based Rendering book).

Almost all directives in a pbrt input file have a direct correspondencewith a function in the pbrt API, defined in the files core/api.hand core/api.cpp. The only input file directive that does not directlycorrespond to a function in the API is the Include statement, whichallows other input files to be parsed. Include behaves similarly tothe #include directive in C++, except that only the directory that thecurrently-being-processed input file is searched for matching filenames.Of course, a complete pathname or a path relative to the current directorycan be specified if appropriate.

Include "geometry/car.pbrt"

Parameter Lists

Variable-length lists of named parameters and their values are the keymeeting ground between the parsing system and the objects that are createdto represent the scene. Each of these lists holds an arbitrary number ofname/value pairs, with the name in quotation marks and the value or valuesin square brackets:

"type name" [ value or values ]

For example,

"float fov" [30]

specifies a parameter "fov" that is a single floating-pointvalue, with value 30. Or,

"float cropwindow" [0 .5 0 .25]

specifies that "cropwindow" is a floating-point array with the given fourvalues. Notice that values are enclosed in square brackets. Single values(such as the "30" in the "fov" example above) may be provided with orwithout square brackets enclosing them, though arrays of values always mustbe enclosed in square brackets.

The type of each parameter must always be given along with its name;pbrt has no built-in knowledge of any parameter names. This simplifiesthe parsing system, although it does create a small burden for thecreator of the input file.

pbrt supports nine basic parameter types: integer, float,point2, vector2,point3, vector3,normal3, spectrum, bool,and string. Alternatively, point, vector,normal, can be used as synonyms for theirthree-dimensional equivalents.

The point2and vector2 types take two floating-point valuesto specify each value (and similarly for their 3Dequivalents). string parameters must be insidequotation marks, and bool parameters are set withthe strings"true" and "false", quotation marks included.

"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"

pbrt provides a number of ways of specifying spectral values in scenedescription files. RGB values are commonly used, though see the discussionin Section 5.2.2on page 325 of the third edition of "Physically Based Rendering" fordiscussion of the shortcomings of this representation. RGB color valuescan be specified with the rgb type. (color is also supported as asynonym for this):

"rgb Kd" [ .2 .5 .3 ]

specifies the RGB color with red equal to 0.2 and so forth. TheFromRGB() method of the Spectrum implementation being used is usedto convert the given RGB colors to the current spectral representation.

Alternatively, XYZ colors can be used to specify a spectrum:

"xyz Kd" [ .4 .6 .7 ]

General sampled SPDs are specified with a series of (wavelength, value)pairs, where wavelengths are specified in nm. These SPDs are resampled tothe current spectral representation with its FromSampled() method. Forexample,

"spectrum Kd" [ 300 .3 400 .6 410 .65 415 .8 500 .2 600 .1 ]

specifies a piecewise-linear SPD with a value of 0.3 at 300nm, 0.6 and400nm, and so forth. Since complex sampled SPDs may have many values, theycan also be provided through a separate file:

"spectrum Kd" "filename"

Where the filename specifies the path to a plain text file with pairs offloating-point (wavelength, value) as above. The parser for these filesallows uses # to denote a comment that goes to the end of the currentline. See the directory scenes/spds in thepbrt scenes distribution forexamples.

Finally, SPDs of blackbody emitters can be specified with twofloating-point values, one giving the blackbody temperature in Kelvin, andthe second giving a scale factor. (Blackbody emitters are discussed inSection 12.1.1 of the book.)

"blackbody L" [ 6500 1 ] # daylight, approximately

Transformations

A series of directives modify the current transformation matrix (CTM).(See Section B.2.2 on page 1111 for more information about how the CTM ismaintained during scene description.) When the scene's camera is specifiedwith a Camera directive, the CTM defines theworld to camera transformation; when a light or shape is created, the CTMspecifies the transformation from object space to world space.

When parsing begins, the CTM is the identity transformation; furthermore,it is is reset to the identity when the WorldBegin directive isencountered. The following directives change the CTM; they are shown withthe corresponding pbrt API call:

Input File SyntaxAPI Call
IdentitypbrtIdentity()
Translate x y zpbrtTranslate()
Scale x y zpbrtScale()
Rotate angle x y zpbrtRotate()
LookAt eye_x eye_y eye_z look_x look_y look_z up_x up_y up_zpbrtLookAt()
CoordinateSystem "name"pbrtCoordinateSystem()
CoordSysTransform "name"pbrtCoordSysTransform()
Transform m00 ... m33pbrtTransform()
ConcatTransform m00 .. m33pbrtConcatTransform()

For example, Translate takes three floating-point values, x, y, andz, and the corresponding values are passed to the pbrtTranslate() APIcall, which in turn modifies the CTM by setting it to the product of theCTM with the matrix representing the given translation.

pbrt supports animated transformations by allowing two transformationmatrices to be specified at different times. The TransformTimesdirective, which must be outside of the world definition block, defines thesetwo times with floating-point values:

TransformTimes start end

Then, the ActiveTransform directive indicates whether subsequentdirectives that modify the CTM should apply to the transformation at thestarting time, the transformation at the ending time, or both. The defaultis that both matrices should be updated:

Translate 1 0 0 # applies to both, by defaultActiveTransform StartTimeRotate 90 1 0 0ActiveTransform EndTimeRotate 120 0 1 0ActiveTransform All

This section describes rendering options that must be specified before theWorldBegin statement.

Cameras

The Camera directive specifies the camera usedfor viewing the scene.

The default camera is a PerspectiveCamera witha 90 degree field of view:

Camera "perspective" "float fov" [90]

When the Camera directive is encountered in an input file, the currenttransformation matrix is used to initialize the world-to-cameratransformation.

pbrt provides four camera implementations:

NameImplementation Class
"environment"EnvironmentCamera
"orthographic"OrthographicCamera
"perspective"PerspectiveCamera
"realistic"RealisticCamera

Two parameters that set the camera's shutter open times are common toall cameras in pbrt.

TypeNameDefault ValueDescription
floatshutteropen0The time at which the virtual camera shutter opens.
floatshutterclose1The time at which the virtual camera shutter closes.

The PerspectiveCamera,OrthographicCamera,and EnvironmentCamera share two additionalparameters that describe the imaging area:

TypeNameDefault ValueDescription
floatframeaspectratio(see description)The aspect ratio of the film. By default, this is computed fromthe x and y resolutions of the film, but it can be overridden if desired.
floatscreenwindow(see description)The bounds of the film plane in screen space. By default, thisis [-1,1] along the shorter image axis and is set proportionally along thelonger axis.

PerspectiveCameraand OrthographicCamera support images rendered withdepth of field. They both use the following two parameters to setparameters related to lens focus.

TypeNameDefault ValueDescription
floatlensradius0The radius of the lens. Used to render scenes with depth of fieldand focus effects. The default value yields a pinhole camera.
floatfocaldistance10^30The focal distance of the lens. If "lensradius" is zero, this hasno effect. Otherwise, it specifies the distance from the camera originto the focal plane.

The perspective camera has two (semi-redundant) parameters forsetting the camera's field of view.

TypeNameDefault ValueDescription
floatfov90Specifies the field of view for the perspective camera. This isthe spread angle of the viewing frustum along the narrower of theimage's width and height.
floathalffovn/aFor convenience to some programs that export from modeling systems, thecamera's field of view can also be specified via the half-angle betweenthe view direction and the edge of the viewing frustum. If this parameterisn't provided, then fov is used to set the field of view instead.

The RealisticCamera simulates imaging from light rays passing throughcomplex lens systems. It takes a number of additional parameters.

TypeNameDefault ValueDescription
stringlensfile""Specifies the name of a lens description file that gives the collectionof lens elements in the lens system. A number of such lenses areavailable in the lenses directory in thepbrt-v3 scenes distribution.
floataperturediameter1.0Diameter of the lens system's aperture, specified in mm. The smallerthe aperture, the less light reaches the film plane, but the greater therange of distances that are in focus.
floatfocusdistance10.0Distance in meters at which the lens system is focused.
boolsimpleweightingtrueIndicates whether incident radiance at the film plane should just beweighted by the cosine-to-the-4th term, or whether it should alsoinclude the additional weighting terms that account for the shutter opentime and the projected area of the exit pupil are included so that theimage records incident energy on the film plane.

Samplers

The Sampler generates samples for the image,time, lens, and Monte Carlo integration. A number of implementations areprovided; the default "halton"—is an instance ofthe HaltonSampler that takes 16 samples perpixel.

NameImplementation Class
"02sequence" (or, for backwards compatibility, "lowdiscrepancy")ZeroTwoSequenceSampler
"halton"HaltonSampler
"maxmindist"MaxMinDistSampler
"random"RandomSampler
"sobol"SobolSampler
"stratified"StratifiedSampler

The HaltonSamplerand SobolSampler are generally the mosteffective samplers for Monte Carlointegration. The RandomSampler generatesparticularly ineffective sampling patterns and is really only useful forcomparison against more sophisticated approaches and shouldn't otherwisebe used.

The ZeroTwoSequenceSampler, HaltonSampler, MaxMinDistSampler, RandomSampler,and SobolSampler all take a single parameter, "pixelsamples",which sets the number of samples to take in each pixel area. (ForZeroTwoSequenceSampler, MaxMinDistSampler,and SobolSampler, this value must be a power oftwo. If a non-power-of-two value is provided, it is rounded up to thenext power of two.)

TypeNameDefault ValueDescription
integerpixelsamples16The number of samples to take, per pixel. Note that thenumber of samples is taken per pixel on average; depending onthe actual sampling algorithm being used, individualpixel areas may have slightly more or slightly fewer.

The StratifiedSampler has three parametersthat control its behavior.

TypeNameDefault ValueDescription
booljitter"true"Whether or not the generated samples should be jittered inside each stratum;this is generally only worth setting to "false" for comparisonsbetween jittered and uniform sampling—uniform sampling willalmost always give a worse result.
integerxsamples2The number of samples per pixel to take in the x direction.
integerysamples2The number of samples per pixel to take in the y direction.In general, "xsamples" and "ysamples" should be set to thesame value for best results.

Film

The Film directive specifies the characteristics of the image being generated by the renderer.

The only Film implementation currentlyavailable in pbrt isImageFilm which is specified as "image" in input files. For example:

Film "image" "string filename" ["out.exr"] "float cropwindow" [ .2 .5 .3 .8 ]

The "image" film takes a handful of parameters:

TypeNameDefault ValueDescription
integerxresolution640The number of pixels in the x direction.
integeryresolution480The number of pixels in the y direction.
float[4]cropwindow[ 0 1 0 1 ]The subregion of the image to render. The four values specifiedshould 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 theupper-left corner of the image.
floatscale1Scale factor to apply to film pixel values before saving the image.
floatmaxsampleluminanceinfiniteImage sample values with luminance greater than this value are clampedto have this luminance. (This is a hack, but can be useful foreliminating large variance spikes in scenes with difficult light transport.)
floatdiagonal35Diagonal length of the film, in mm. (This value is only used when theRealisticCamera is used.)
stringfilename"pbrt.exr"The output filename.

The ImageFilm uses the suffix of the givenoutput filename to determine the image file format to use.pbrt supportsPFM andEXR for storing images with pixel valuesstored directly as floating-point values;TGA andPNG can also be used, thoughthese only provide 8 bits per color channel of precision.

Filters

The implementation of ImageFilm uses an instance of the abstractFilter class to filter sample values to computefinal pixel values. The filter is specified withthe PixelFilter directive.pbrt provides a number of filter implementations,listed below. The default is "box".

NameImplementation Class
"box"BoxFilter
"gaussian"GaussianFilter
"mitchell"MitchellFilter
"sinc"LanczosSincFilter
"triangle"TriangleFilter

All filter implementations take two parameters that set the filter width in each direction. Typically,these two parameters will have the same value.

TypeNameDefault ValueDescription
floatxwidth2 (0.5 for box, 4 for sinc)The width of the filter in the x direction.
floatywidth2 (0.5 for box, 4 for sinc)The width of the filter in the y direction.

The "gaussian" filter takes an additional parameter that adjusts the rateof Gaussian falloff; see page 478 for more information.

TypeNameDefault ValueDescription
floatalpha2alpha controls the falloff rate of the Gaussian filter. Smallervalues give a blurrier image.

Two parameters set the shape of the "mitchell" filter; see the equation on the top of page 481.

TypeNameDefault ValueDescription
floatB1/3
floatC1/3These parameters control the shape of the Mitchell filter. The bestresults are generally obtained when B+2C=1.

Finally the sinc filter takes a value tau that sets the number of cycles of the sinc function.

TypeNameDefault ValueDescription
floattau3tau controls how many cycles the sinc function passes through beforeit is clamped to zero by the windowing function.

Integrators

The integrator implements the light transport algorithm thatcomputes radiance arriving at the film plane from surfaces andparticipating media in the scene. The default integrator is thePathIntegrator:

Integrator "path" "integer maxdepth" [5]

The PathIntegrator takes a handful ofparameters:

TypeNameDefault ValueDescription
integermaxdepth5Maximum length of a light-carrying path sampled by the integrator.
integer[4]pixelbounds(Entire image)Subset of image to sample during rendering; in order, values givenspecify the starting and ending x coordinates and then starting andending y coordinates. (This functionality is primarily useful fornarrowing down to a few pixels for debugging.)
floatrrthreshold1Determines when Russian roulette is applied to paths: when the maximumspectral component of the path contribution falls beneath this value,Russian roulette starts to be used.
stringlightsamplestrategy"spatial"Technique used for sampling light sources. Options include "uniform",which samples all light sources uniformly, "power", which samples lightsources according to their emitted power, and "spatial", which computeslight contributions in regions of the scene and samples from a relateddistribution.

A number of other surface integrators are available in the system.

NameImplementation Class
"bdpt"BDPTIntegrator
"directlighting"DirectLightingIntegrator
"mlt"MLTIntegrator
"path"PathIntegrator
"sppm"SPPMIntegrator
"volpath"VolPathIntegrator
"whitted"WhittedIntegrator

The DirectLightingIntegrator takes anadditional parameter that controls the light source samplingstrategy.

TypeNameDefault ValueDescription
stringstrategy"all"The strategy to use for sampling direct lighting. Valid options are"all", which samples all the lights uniformly and averages theircontributions, and "one", which chooses a single light uniformly at random.
integermaxdepth5Maximum length of a light-carrying path sampled by the integrator.
integer[4]pixelbounds(Entire image)Subset of image to sample during rendering; in order, values givenspecify the starting and ending x coordinates and then starting andending y coordinates. (This functionality is primarily useful fornarrowing down to a few pixels for debugging.)

These are the parameters that the BDPTIntegrator takes:

TypeNameDefault ValueDescription
integermaxdepth5Maximum length of a light-carrying path sampled by the integrator.
integer[4]pixelbounds(Entire image)Subset of image to sample during rendering; in order, values givenspecify the starting and ending x coordinates and then starting andending y coordinates. (This functionality is primarily useful fornarrowing down to a few pixels for debugging.)
stringlightsamplestrategy"power"Technique used for sampling light sources. Options include "uniform",which samples all light sources uniformly, "power", which samples lightsources according to their emitted power, and "spatial", which computeslight contributions in regions of the scene and samples from a relateddistribution.
boolvisualizestrategiesfalseIf true, an image is saved for each (s,t) bidirectional path generationstrategy used by the integrator. These images can be helpful forunderstanding which sampling strategies are effective for samplingvarious types of light transport paths.
boolvisualizeweightsfalseIf true, an image is saved with the multiple importance samplingweights for each (s,t) bidirectional path generation strategy. Theseimages can be helpful for understanding which sampling strategies areeffective for sampling various types of light transport paths.

The MLTIntegrator, which implementsthe multiplexed Metropolis light transport algorithm described in Section16.5, takes a number of parameters.

TypeNameDefault ValueDescription
integermaxdepth5Maximum length of a light-carrying path sampled by the integrator.
integerbootstrapsamples100000Number of samples to take during the "bootstrap" phase; some of thesesamples are used for initial light-carrying paths for the Metropolis algorithm.
integerchains1000Number of unique Markov chains chains to follow with the Metropolisalgorithm. (Each chain starts with a new path from the bootstrap phase.)
integermutationsperpixel100Number of path mutations to apply per pixel in the image. (Note thateach pixel will generally receive more or fewer path contributions,depending on how bright the pixel is. For the most part, this is themost effective parameter to increase to improve image quality.
floatlargestepprobability0.3Probability of discarding the current path and generating a new randompath (versus applying a small mutation to the current path). For sceneswith very difficult-to-sample light transport paths, reducing thisprobability may be worthwhile.
floatsigma0.01Standard deviation of the perturbation applied to random samples in[0,1] used for small path mutations.

Finally, the SPPMIntegrator integrator takes anumber of parameters to control the stochastic progressive photon mappingalgorithm.

TypeNameDefault ValueDescription
integermaxdepth5Maximum length of a light-carrying path sampled by the integrator.
integeriterations64Total number of iterations of photon shooting from lightsources. (After each iteration, photon statistics are updated.)
integerphotonsperiteration-1Number of photons to shoot from light sources in each iteration. Withthe default value, -1, the number is automatically set to be equal tothe number of pixels in the image.
integerimagewritefrequency2^31Frequency at which to write out the current image, in photon shootingiterations. (The default value means that the image will effectivelyonly be written once when rendering has finished.)
floatradius1Initial photon search radius. (This value will be reduced as photonsare accumulated at each pixel.)

Accelerators

The type of aggregate to use for efficiently finding ray-shapeintersections is defined with the Accelerator directive:

Accelerator "kdtree" "float emptybonus" [0.1]

The default accelerator, "bvh", is generally a good choice; it is rarelyworthwhile to specify a different accelerator or to need to change theaccelerator's parameters to improve performance.

Two accelerator implementations are available in pbrt:

NameImplementation Class
"bvh"BVHAccel
"kdtree"KdTreeAccel

The "bvh" accelerator, the default, takes just two parameters. Thisaccelerator is efficiently constructed when the scene description isprocessed, while still providing highly efficient ray-shape intersectiontests.

TypeNameDefault ValueDescription
integermaxnodeprims4Maximum number of primitives to allow in a node in the tree. Once the primitives have been split to groups ofthis size or smaller, a leaf node is created.
stringsplitmethod"sah"Method to use to partition the primitives when building the tree. The default, "sah", denotes the surfacearea heuristic; the default should almost certainly be used. The other options—"middle", which splits eachnode at its midpoint along the split axis, "equal", which splits the current group of primitives intotwo equal-sized sets, and "hlbvh", which selects the HLBVHalgorithm, which parallelizes well—are slightly more efficient to evaluate at tree construction time, but lead tosubstantially lower-quality hierarchies.

The "kdtree" accelerator takes a number of parameters that controlits construction. This accelerator takes substantially longer to createthan "bvh" at scene definition time, but it can be marginally faster atfinding ray-shape intersections. It tends to require less memory than"bvh".

See page 291 of the third edition of the book for the details of the costfunction used for building kd-trees (and thus the use of some of the thevarious parameters below.)

TypeNameDefault ValueDescription
integerintersectcost80The value of the cost function that estimates the expected cost of performing a ray-objectintersection, for use in building the kd-tree.
integertraversalcost1Estimated cost for traversing a ray through a kd-tree node.
floatemptybonus0.2"Bonus" factor for kd-tree nodes that represent empty space.
integermaxprims1Maximum number of primitives to store in kd-tree node. (Not a hard limit; more may be stored if the kd-treecan't find splitting planes that reduce the number of primitives when refining a node.)
integermaxdepth-1Maximum depth of the kd-tree. If negative, the kd-tree chooses a maximum depth based on the number ofprimitives to be stored in it.

The MakeNamedMediumand MediumInterface directives are allowed bothin the initial options before WorldBegin aswell as after WorldBegin. See thedocumentation of participating media in"Describing the scene" for more information. When media specifiedin the scene-wide options, the "outside" medium is used for the mediumthat camera rays start out in.

After the camera, film, and rendering options have been set, theWorldBegin directive marks the start of the scenedefinition (the "world block"). In the world block, the lights,materials, and geometric shapes that make up the scene are defined.After WorldBegin, nearly all of the directivesdescribed in the Scene-widerendering options section are illegal; an error message will be printedif one is encountered. Similarly, nearly all of the directives documentedin this section are illegal outside of the world block. (The twoexceptions are the MakeNamedMediumand MediumInterface directives, which are legalin both places.) The end of the world block is denoted bythe WorldEnd directive; when it is encountered,the chosen Integrator takes over and does therequested rendering computation.

Attributes

A number of directives modify the current graphics state—examples includethe transformation directives (Transformations), and thedirective that sets the current material. The current graphics state(including the current transformation matrix) can be saved and restoredusing the AttributeBegin and AttributeEnd directives:

Material "matte"AttributeBegin Material "plastic" Shape "sphere"AttributeEnd # back to the "matte" materialShape "cone"

The transformation matrix can be saved and restored independently of thegraphics state using TransformBegin and TransformEnd.

Scale 2 2 2TransformBegin Translate 1 0 1 Shape "sphere"TransformEnd # Translate no longer applies here

In addition to the current transformation matrix and material, thereverse-orientation setting, specified by the ReverseOrientationdirective, is part of the graphics state. This directive, when active,flips the surface normal of the shapes that follow it; it can be usefulwhen specifying area light sources, which only emit light from the sidetheir surface normal points from, and when specifying transparentmaterials, where the surface normal is used to determine whether rays areentering or exiting the refractive medium.

Shapes

Shapes are specified with the Shape directive; it takes the name of ashape implementation and a parameter list used to define the shape'sproperties:

Shape "name" parameter-list

For example,

Shape "sphere" "float radius" [0.25]

When a Shape directive is encountered, the current transformationmatrix is used to set the object to world transformation for the shape.

A number of shapes are provided by pbrt; this list shows the mappingfrom shape names to implementation class in the system.

NameImplementation Class
"cone"Cone
"curve"Curve
"cylinder"Cylinder
"disk"Disk
"hyperboloid"Hyperboloid
"paraboloid"Paraboloid
"sphere"Sphere
"trianglemesh"Triangle

A few additional shapes are available for convenience; these immediatelyconvert themselves to instances of the Triangleshape when the scene description is loaded.

Name
"heightfield"
"loopsubdiv"
"nurbs"
"plymesh"

The extent of the "cone" shape is defined by three parameters; note thatthe cone is oriented along the z axis in object space; the currenttransformation matrix can be used to orient it differently in the scene'sworld space.

TypeNameDefault ValueDescription
floatradius1The cone's radius.
floatheight1The height of the cone along the z axis.
floatphimax360The maximum extent of the cone in phi (in spherical coordinates).

The "curve" shape, described in Section 3.7 of the book, is useful formodeling thin objects like hair, fur, and grass. It has a few variants,including a ribbon that's always oriented toward the incident ray, a flatribbon with orientation given by a pair of surface normals, and an(apparent) thin cylinder, where shading normals give the illusion of acurved surface.

After the book's publication, support for degree 2 curves was added, aswas support for curves spcified in the b-spline basis.

TypeNameDefault ValueDescription
point[4]P(none)Control points for the cubic Bezier spline that goes along the centerof the curve shape.
stringbasis"bezier"Curve spline basis. "bspline" is the only other option currentlysupported.
intdegree3Degree of the curve's spline. The only other valid option is 2.
stringtype"flat"Which curve variant is used. The other options are "ribbon" and"cylinder". (Figure 3.18 on page 170 shows the differences betweenthem.)
normal[2]N(none)For "ribbon" curves, these normals are respectively used at the startand end of the curve. Intermediate normals are interpolated usingspherical linear interpolation.
floatwidth1Width of the curve.
floatwidth0/width11Width of the curve at the start and end points. If specified, theseoverride the "width" parameter.
integersplitdepth3Number of times the curve is split in half into sub-curves at startuptime. Splitting curves increases memory use but can improve rayintersection performance, as the sub-curves generally have tighterbounding boxes than the entire curve extent.

Similarly, "cylinder" is oriented along the z axis as well. It takesfour parameters.

TypeNameDefault ValueDescription
floatradius1The cylinder's radius.
floatzmin-1The height of the cylinder's bottom along the z axis.
floatzmax1The height of the cylinder's top along the z axis.
floatphimax360The maximum extent of the cylinder in phi (in spherical coordinates).

The "disk" is perpendicular to the z axis, with its center at x=0 andy=0.

TypeNameDefault ValueDescription
floatheight0The location of the disk along the z axis.
floatradius1The outer radius of the disk.
floatinnerradius0The inner radius of the disk (if nonzero, the disk is an annulus).
floatphimax360The maximum extent of the disk in phi (in spherical coordinates).

The "heightfield" shape isn't described in the pbrt book text; it'sessentially a compact way to describe a regular triangulated mesh. Theuser provides resolutions in the u and v directions and then a seriesof height values. The height values give the z values for a series ofvertices over [0,1]^2 in (x,y).

TypeNameDefault ValueDescription
intnu, nvnoneNumber of sample values in each direction. The total numberof triangles in the mesh is 2 * (nu-1) * (nv-1).
float[nu*nv]PznoneArray of height values to specify the heightfield.

"hyperboloid" takes two points to define the line of revolution that sweeps out its surface.

TypeNameDefault ValueDescription
pointp10 0 0The first end point of the hyperboloid's line of revolution.
pointp21 1 1The second end point of the hyperboloid's line of revolution.
floatphimax360The maximum extent of the hyperboloid in phi (in spherical coordinates).

"loopsubdiv" corresponds to a subdivision surface evaluated with Loop's subdivision rules.

TypeNameDefault ValueDescription
integerlevels3The number of levels of refinement to compute in the subdivision algorithm.
integer[n]indicesrequired—no defaultIndices for the base mesh. Indexing is the same as for the triangle mesh primitive.(See "trianglemesh" below).
point[n]Prequired—no defaultVertex positions for the base mesh. This is the same as for the triangle mesh primitive.(See "trianglemesh" below).

"nurbs" can be used to define a NURBS surface. Theimplementation in pbrt does a fixed-rate tessellation, with tessellationrate provided directly by the user.

TypeNameDefault ValueDescription
integernu, nvnone—must be specifiedNumber of control points for NURBS patch in the u and v parametric directions.
integeruorder, vordersee descriptionOrder of NURBS surface in u and v directions. (Order is equal to one plus the surface's degree.)
float[nu+uorder]uknotsnone—must be specifiedKnot vector for NURBS in the u direction.
float[nv+vorder]vknotsnone—must be specifiedKnot vector for NURBS in the v direction.
floatu0, v0none—must be specifiedStarting u and v parametric coordinates at which to evaluate NURBS.
floatu1, v1none—must be specifiedEnding u and v parametric coordinates at which to evaluate NURBS.
point[nu*nv]PnoneEither the P or Pw parameter must be specified to give the surface's controlpoints. P gives regular control points.
float[4*nu*nv]PwnoneSpecifies rational control points, with an additional per-vertex weight value.

Here are the parameters for "paraboloid".

TypeNameDefault ValueDescription
floatradius1The paraboloid's radius.
floatzmin0The height of the lower clipping plane along the z axis.
floatzmax1The height of the upper clipping plane along the z axis.
floatphimax360The maximum extent of the paraboloid along phi (in spherical coordinates).

And these are the "sphere" parameters.

TypeNameDefault ValueDescription
floatradius1The sphere's radius.
floatzmin-radiusThe height of the lower clipping plane along the z axis.
floatzmaxradiusThe height of the upper clipping plane along the z axis.
floatphimax360The maximum extent of the sphere in phi (in spherical coordinates).

An arbitrary triangle mesh is defined by the "trianglemesh" shape. Themesh's topology is defined by the indices parameter, which is an arrayof integer indices into the vertex arrays. Each successive triplet ofindices defines the offsets to the three vertices of one triangle; thus,the length of the indices array must be a multiple of three.

Here is an example of a small triangle mesh:

Shape "trianglemesh" "integer indices" [0 2 1 0 3 2 ] "point P" [550 0 0 0 0 0 0 0 560 550 0 560 ]

Here, we have an array of four vertices in the P parameter. Theindices array defines two triangles that use these vertices—the firstone has vertex positions (550,0,0), (0,0,560), and (0,0,0). Note that bothtriangles use vertices 0 and 2. Because the triangle mesh is specified ina way that makes this vertex reuse explicit, the in-memory representationof the triangle mesh can be more compact than if each triangle had toexplicitly and privately store all of its per-vertex data.

TypeNameDefault ValueDescription
integer[n]indicesrequired—no defaultThe array of integer offsets into the per-vertex data arrays(P, and any of N, S, or uv that are present.)
point[n]Prequired—no defaultThe vertex positions of the triangle mesh.
normal[n]Nnone—optionalPer-vertex normals. If present, shading normals will be computedfrom these values.
vector[n]Snone—optionalPer-vertex tangents.
float[2*n]uvnone—optionalPer-vertex texture coordinates.
float texturealphanoneOptional "alpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,at any point on the triangle where the alpha texture evaluatesto have the value zero, the triangle is cut away and anyray intersection is ignored.
float textureshadowalphanoneOptional "shadowalpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,intersections at any points on the triangle where the alpha texture evaluatesto zero are ignored.

pbrt can also directly read triangle meshes specified inthe PLY meshfile format, via the "plymesh" shape. The following parameters aresupported:

TypeNameDefault ValueDescription
stringfilenamerequired—no defaultFile from which the PLY-format mesh is loaded.
float texturealphanoneOptional "alpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,at any point on the triangle where the alpha texture evaluatesto have the value zero, the triangle is cut away and anyray intersection is ignored.
float textureshadowalphanoneOptional "shadowalpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,intersections at any points on the triangle where the alpha texture evaluatesto zero are ignored.

Object Instancing

If a complex object is used repeatedly in a scene, object instancing may bedesirable; this lets the system store a single instance of the object inmemory and just record multiple transformations to place it in the scene.Object instances are created via named objects.

To create a named object, its definition should be placed within anObjectBegin/ObjectEnd pair:

ObjectBegin "name" Shape ... Shape ...ObjectEnd

When a named object is defined, the current transformation matrix definesthe transformation from object space to the instance's coordinate space.

After a named object has been defined, it can be instantiated with theObjectInstance directive. The current transformation matrix then definesthe instance space to world space transformation; thus, the finaltransformation for a shape in an object instance definition is thecomposition of the CTM when the instance was defined and the CTM when theinstance was instantiated.

Thus, two instances of an object named "foo" are instantiated in thefollowing:

ObjectInstance "foo"Translate 1 0 0ObjectInstance "foo"

Lights

Light sources cast illumination in the scene.pbrt provides two types of lights: lights that exist in the scenewithout any geometry associated with them, and lights that describeemission from one or more shapes in the scene (area lights).

The first type of light is defined with the LightSource directive.There are 6 light sources of this type that are currently available inpbrt.

NameImplementation Class
"distant"DistantLight
"goniometric"GonioPhotometricLight
"infinite"InfiniteAreaLight
"point"PointLight
"projection"ProjectionLight
"spot"SpotLight

For example, the following defines a point light source with RGB intensityof (0.5, 0.5, 0.5):

LightSource "point" "rgb I" [ .5 .5 .5 ]

When a light source definition is encountered, the current transformationmatrix is used to define the light-to-world transformation. Many of thelight sources also take parameters to place it in the scene; using either atransformation matrix or an explicit position or direction to place alight can be useful.

All lights support a spectrum"scale" parameter that scales the amount of light that the lightemits.

TypeNameDefault ValueDescription
spectrumscalergb (1 1 1)Scale factor that modulates the amount of light that the light sourceemits into the scene.

Distant

The "distant" light source represents a directional light source "atinfinity"; in other words, it illuminates the scene with light arrivingfrom a single direction. It takes these parameters:

TypeNameDefault ValueDescription
spectrumLrgb (1 1 1)The radiance emitted from the light source.
pointfrom(0,0,0)"from" and "to" define the direction vector along which illuminationfrom the light arrives at the scene. The defaults give a light that shinesalong the z axis.
pointto(0,0,1)

Goniometric

The "goniometric" light represents a point light source withdirectionally-varying emission, where the emission distribution isrepresented by a texture map. This representation can be useful formodeling many real-world light sources, where measurements of thisdistribution may be available.

Given a normalized outgoing direction w from the goniometriclight source to a point in the scene, the image coordinates in thegoniometric diagram file are found using a (theta, phi) parameterization inspherical coordinates. Here, the theta angle is measured with respect tothe y axis, and x and z define phi. (Elsewherein pbrt, the z axis is generally used tomeasure theta.) The light-to-world transformation matrix can be used toposition and orient the light.

TypeNameDefault ValueDescription
spectrumIrgb (1 1 1)A radiant intensity scale-factor; the radiant intensity in aparticular direction is computed as the product of this valueand the appropriate value from the goniometric diagram table.
stringmapnamerequired—no defaultThe filename of the image file that stores a goniometricdiagram to use for the lighting distribution.

Infinite

The "infinite" light represents an infinitely far away light source thatpotentially casts illumination from all directions. It is useful formodeling incident light in complex real environments ("HDR lighting"). Ittakes an environment map with a "latitude-longitude" parameterization,where given a direction vector w, the spherical (theta, phi) coordinatesare found, and then the u coordinate of the environment map is indexed bythe phi value and v is indexed by theta. (If needed, the environment mapcan be reoriented with the light to world transformation.)

TypeNameDefault ValueDescription
spectrumLrgb (1 1 1)A radiance scale factor for the light; final emitted radiancevalues for a particular direction are computed as the productof this value and the radiance value found from the environment map.
integersamples1Suggested number of shadow samples to take when computing illumination from the light.Depending on the number of pixel samples being taken, this valuemay need to be increased to reduce noise in the illuminationcomputation for the light. (Note that this value is used only whenthe DirectLightingIntegrator is used.)
stringmapnamenoneThe environment map to use for the infinite area light. If this is notprovided, the light will be a constant color.

Point

"point" defines a simple point light that casts the same amount ofillumination in all directions. It takes two parameters:

TypeNameDefault ValueDescription
spectrumIrgb (1 1 1)The light's emitted radiant intensity.
pointfrom0 0 0The location of the light.

Projection

The "projection" light acts like a slide projector; the given image is usedto define a 2D emission distribution that is projected with a center ofprojection at the light's position. Directions outside the frustum oflight projection receive no emitted illumination. It is positioned usingthe light-to-world transformation matrix.

TypeNameDefault ValueDescription
spectrumIrgb (1 1 1)Radiant intensity scale factor; the intensity in a given directionis the product of this value and the value from the image mapfor the corresponding direction.
floatfov45The spread angle of the projected light, along the shorter image axis.
stringmapnamerequired—no defaultThe image to project into the scene.

Spotlight

A spotlight is defined by the "spot" light source. The spotlight isdefined by a lighting direction and then two angles that specify a cone ofdirections in which light is emitted.

TypeNameDefault ValueDescription
spectrumIrgb (1 1 1)Maximum radiant intensity of the light; this is the emitted radiant intensityin the center of the illumination cone. It falls off to zero outside of thecone.
pointfrom, tosee descriptionTwo points defining the lighting vector. The defaults are(0,0,0) and (0,0,1), respectively. This gives a light that ispointing down the z axis.
floatconeangle30The angle that the spotlight's cone makes with its primary axis. For directionsup to this angle from the main axis, the full radiant intensity given by "I"is emitted. After this angle and up to "coneangle" + "conedeltaangle",illumination falls off until it is zero.
floatconedeltaangle5The angle at which the spotlight intensity begins to fall off at the edges.

Area lights have geometry associated with them; the shape and size ofthe emitting shapes have a substantial effect on the resulting emittedradiance distribution. After an AreaLightSourcedirective, all subsequent shapes emit light from their surfaces accordingto the distribution defined by the given area light implementation.Note that area lights can currently only be used with triangle, sphere,cylinder, and disk shapes; a runtime error is issued if an area light isbound to any other type of shape.

The current area light is saved and restored inside attribute blocks;typically area light definitions are insidean AttributeBegin/AttributeEndpair in order to control the shapes that they are applied to.

AttributeBegin AreaLightSource "diffuse" "rgb L" [ .5 .5 .5 ] Translate 0 10 0 Shape "sphere" "float radius" [.25]AttributeEnd# area light is out of scope, subsequent shapes aren't emitters

pbrt currently only includes a single area light implementation, "diffuse".

NameImplementation Class
"diffuse"DiffuseAreaLight

The "diffuse" area light defines an emitter that emitsradiance uniformly over all directions in the hemisphere around the surfacenormal at each point on the surface. Thus, the orientation of the surfacenormal is meaningful; by default, an emitting sphere emits in thedirections outside the sphere and there's no illumination inside of it. Ifthis is not the desired behavior,the ReverseOrientation directive can be used toflip the orientation of the surface normal of subsequent shapes, or the"twosided" option, described in the list of options below, can beenabled.

AttributeBegin AreaLightSource "diffuse" ReverseOrientation # illuminate inside the sphere Shape "sphere"AttributeEnd

The "diffuse" area light takes these parameters.

TypeNameDefault ValueDescription
spectrumLrgb (1 1 1)The amount of emitted radiance at each point and emitted direction..
booltwosidedfalseDetermines whether the light source emits light from just the side ofthe surface where the surface normal points or both sides.
integersamples1Suggested number of shadow samples to take when computing illuminationfrom the light. (As with the InfintieAreaLight,this value is used only whenthe DirectLightingIntegrator is used.)

Materials

Materials specify the light scattering properties of surfaces in the scene.The Material directive specifies the current material, which thenapplies for all subsequent shape definitions (until the end of the currentattribute scope or until a new material is defined:

Material "matte" "rgb Kd" [ .7 .2 .2 ]

Parameters to materials are distinctive in that textures can be usedto specify spatially-varying values for the parameters. For example, theabove material definition defines diffuse surface with the same reddishcolor at all points. Alternatively, we might want to use an image map todefine the color as a function of (u,v) on the surface. This is done bydefining a texture with a user-defined name (below, "lines-tex"), and thenbinding that to the desired parameter of the material.

For example, thefollowing sets the "Kd" parameter of the "matte" material to be computedvia lookups to the "lines.exr" image map.

Texture "lines-tex" "spectrum" "imagemap" "string filename" "textures/lines.exr"Material "matte" "texture Kd" "lines-tex"

Note that for each parameter (for example, "Kd" in the above), a value forthe parameter can either be bound with a constant value, in which case thegiven type of the parameter should be "float", "rgb", "spectrum", etc., asappropriate, or a texture value, in which case the given type of theparameter should be "texture" and the parameter value bound is the name ofa texture. (The next section of this document, Textures, describes thetextures available in pbrt as well as their parameters.)

Parameters to materials can be overridden by the shapes that they areapplied to. For example, the sphere in the following would be green, not red.

Material "matte" "rgb Kd" [ 1 0 0 ]Shape "sphere" "float radius" [ .5 ] "rgb Kd" [ 0 1 0 ] 

Finally, it is sometimes useful to name a material. A named material is amaterial and a set of parameter bindings (to constant values or totextures). It is defined with the MakeNamedMaterial directive. Anamed material can be set to be the current material with theNamedMaterial directive.

MakeNamedMaterial "myplastic" "string type" "plastic" "float roughness" [0.1]Material "matte" # current material is "matte"NamedMaterial "myplastic" # current material is "plastic" as above

This table lists the materials available in pbrt and the correspondingclass in the source code distribution that implements each of them.

NameImplementation Class
disneyDisneyMaterial
fourierFourierMaterial
glassGlassMaterial
hairHairMaterial
kdsubsurfaceKdSubsurfaceMaterial
matteMatteMaterial
metalMetalMaterial
mirrorMirrorMaterial
mixMixMaterial
noneA special material that signifies that the surface it is associatedwith should be ignored for ray intersections. (This is useful forspecifying regions of space associated withparticipating media.)
plasticPlasticMaterial
substrateSubstrateMaterial
subsurface SubsurfaceMaterial
translucentTranslucentMaterial
uberUberMaterial

All of the above materials take a texture that can be used to specify abump map.

TypeNameDefault ValueDescription
float texturebumpmapNoneThe floating-point texture to be used as a bump map.

Disney

The "disney" material was after the book's publication. Itimplements the "Disney BSDF with subsurface scattering", as described inExtendingthe Disney BRDF to a BSDF with Integrated Subsurface Scattering. (Itbuilds on the model describedin PhysicallyBased Shading at Disney. See those documents for more details about theparameters.

TypeNameDefault ValueDescription
spectrum texturecolor0.5Base color of the material.
float textureanisotropic0Controls degree of anisotropy in the specular highlight. Default,0, is none. Range: [0,1].
float textureclearcoat0Contribution of the clearcoat, which gives isotropic specular highlight thattakes on the light's color. Range: [0,1].
float textureclearcoatgloss1Glossiness of the clearcoat. Larger values give tighterhighglights. Range: [0,1].
float textureeta1.5Object's index of refraction.
float texturemetallic0Controls how "metal" the object appears. Higher values reducediffuse scattering and shift the highlight color towards the material'scolor. Range: [0,1].
float textureroughness0.5Material's roughness. Affects specular reflection andtransmission. Range: [0,1].
spectrum texturescatterdistance0Distance that light travels in the object before scattering. Ifgreater than zero, subsurface scattering is used in place ofdiffuse reflection.
float texturesheen0Contribution of the "sheen" term, which adds retro-reflection atobject edges. Mostly useful for cloth. Range: [0,1].
float texturesheentint0.5Controls how much the sheen term's color is tinted by the basecolor. Range: [0,1].
float texturespectrans0Controls contribution of glossy specular transmission. Range: [0,1].
float texturespeculartint0Controls how much the specular highlight's color is tinted by thebase color. Range: [0,1]..

The Disney BSDF also has a mode for thin surfaces that aren't closedgeometric models (e.g. a sheet of paper). The "thin" parameter to thematerial can be used to enable it.

TypeNameDefault ValueDescription
booleanthinfalseControls whether the thin is enabled surface model.
spectrum texturedifftrans1Controls how much of the diffuse scattering is reflected versustransmitted. Zero causes only diffuse reflection and no diffusetransmission, 1 gives an even split between both, and 2 gives onlydiffuse transmission. Range: [0,2].
spectrum textureflatness0Base color of the material.

Fourier

The "fourier" material is used for the Fourier Basis BSDFsdescribed in Section 8.6 of Physically Based Rendering, startingon page 552. This representation is useful both for measured BSDF dataas well as for BSDFs computed through simulation of scattering inlayered surfaces. (A number of such BSDFs are available in thebsdfs directory in thepbrt scenesdistribution.)

TypeNameDefault ValueDescription
stringbsdffilenoneFile that stores the Fourier BSDF description.

Glass

The "glass" material has parameters that specify the reflectivity andtransmissivity. These values are both modulated by the Fresnel equationsfor dielectric materials, which also ensure energy conservation (as long asneither "Kr" nor "Kt" is ever greater than one.)

TypeNameDefault ValueDescription
spectrum textureKr1The reflectivity of the surface.
spectrum textureKt1The transmissivity of the surface.
float textureeta1.5The index of refraction of the inside of the object.(pbrt implicitly assumes that the exterior of objectsis a vacuum, with IOR of 1.)
float textureuroughness0Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled.
float texturevroughness0Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled.
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Hair

The "hair" material models reflection and transmission fromcylindrical fibers like hair and fur. It's generally only useful with the"curve" shape. Its implementation is described in the supplementaryImplementation of a Hair Scattering Model document.

The color of the hair material can be specified in one of a number ofdifferent ways.

TypeNameDescription
spectrum texturesigma_aAbsorption coefficient of the medium inside the hair. This absorptioncoefficient is normalized such that the value provided should be withrespect to the diameter of the hair.
spectrum texturecolorIf specified, a value of the absorption coefficient is computed usingan approximation that leads to the hair having roughly this color, aftermultiple scattering in the hair during rendering.
float textureeumelaninConcentration of the eumelanin pigment in the hair. Blonde hair hasconcentrations around 0.3, brown around 1.3, and black around 8.
float texturepheomelaninConcentration of the pheomelanin pigment in the hair. Pheomelaninmakes red hair red.

If "sigma_a" is specified, then all other parameters related to haircolor are ignored, if present. Otherwise, if "color" is specified, theeumelanin and pheomelanin parameters are ignored, if present. If no haircolor parameters are specified, a eumelanin concentration of 1.3 is used,giving brown hair.

A number of additional parameters are available to control the hair'sappearance.

TypeNameDefault ValueDescription
float textureeta1.55Index of refraction of the hair medium.
float texturebeta_m0.3Longitudinal roughness of the hair. Should be between 0 and 1. Thisroughness controls the size and shape of the hair highlight.
float texturebeta_n0.3Azimuthal roughness of the hair. Should be between 0 and 1.
float texturealpha2Angle of scales on the hair surface, in degrees.

KdSubsurface

The "kdsubsurface" material provides a convenient way to specify thescattering materials of a material that exhibits subsurface scattering.(The parameters to the "subsurface" material, below, are often difficult toset to achieve a desired visual result.) Here, the user can specify adiffuse reflection color, "Kd", and the mean free path—the averagedistance that light travels in the medium before scattering. (The smallerthe mean free path, the thicker the medium is.) These two values are thenused to derive scattering coefficients for the medium.)

TypeNameDefault ValueDescription
spectrum textureKd0.5Diffuse scattering coefficient used to derive scattering properties.
float texturemfp1The mean free path--the average distance light travels in the mediumbefore scattering.
float textureeta1.3The index of refraction inside the object.
spectrum textureKr1Reflection term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount ofreflection.
spectrum textureKt1Transmission term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount oftransmission.
float textureuroughness0Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled.
float texturevroughness0Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled.
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Matte

The "matte" material defines an object with simple Lambertian scattering. It takes two parameters.

TypeNameDefault ValueDescription
spectrum textureKd0.5The diffuse reflectivity of the surface.
float texturesigma0The sigma parameter for the Oren-Nayar model, in degrees.If this is zero, the surface exhibits pure Lambertian reflection.

Metal

The "metal" material describes scattering from metals, where the index ofrefraction (eta) and the absorption coefficient (k) describe metals'reflectance spectra. These and a roughness parameter, which adjusts themicrofacet distributions roughness, describe the overall material. See thescenes/spds/metals directory inthe pbrt distribution for spectra of the IOR andabsorption coefficients of a variety of metals.

TypeNameDefault ValueDescription
spectrum textureeta(copper)Index of refraction to use in computing the material's reflectance.
spectrum texturek(copper)Absorption coefficient to use in computing the material's reflectance.
float textureroughness0.01Roughness of the material's microfacet distribution. Smaller valuesbecome increasingly close to perfect specular reflection.This value should be between zero and one.
float textureuroughnessn/aMicrofacet roughness in the u direction. If unspecified, the"roughness" parameter is used.
float texturevroughnessn/aMicrofacet roughness in the v direction. If unspecified, the"roughness" parameter is used.
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Mirror

The "mirror" material is a simple specular reflector. The amount ofreflection isn't modified by the Fresnel equations.

TypeNameDefault ValueDescription
spectrum textureKr0.9The reflectivity of the mirror. This value can be used to makecolored or dim reflections.

Mixture

The "mix" material interpolates between two previously-named materialsusing a texture. This allows spatially-varying variation between twomaterials.

TypeNameDefault ValueDescription
spectrum textureamount0.5Weighting factor for the blend between materials. A valueof one corresponds to just "namedmaterial1", a value of zerocorresponds to just "namedmaterial2", and values in betweeninterpolate linearly.
stringnamedmaterial1(none)Name of first material to be interpolated between.
stringnamedmaterial2(none)Name of second material to be interpolated between.

Plastic

"plastic" defines a simple plastic material, described by diffuse andspecular reflection coefficients as well as a roughness value thatdescribes how much variation there is in the microfacet distribution thatmodels glossy specular reflection.

TypeNameDefault ValueDescription
spectrum textureKd0.25The diffuse reflectivity of the surface.
spectrum textureKs0.25The specular reflectivity of the surface.
float textureroughness0.1The roughness of the surface, from 0 to 1. Larger valuesresult in larger, more blurry highlights.
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Substrate

The "substrate" material mixes between diffuse and glossy reflection basedon the viewing angle—this models many realistic materials, which becomeincreasingly specular as the viewing angle approaches grazing. It alsosupports anisotropic microfacet models, with two roughness parameters.

TypeNameDefault ValueDescription
spectrum textureKd0.5The coefficient of diffuse reflection.
spectrum textureKs0.5The coefficient of specular reflection.
float textureuroughness0.1The roughness of the surface in the u direction.
float texturevroughness0.1The roughness of the surface in the v direction.
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Subsurface

The "subsurface" material is another material that describes subsurfacescattering. It allows directly setting the absorption coefficient andreduced scattering coefficient. (These values are generally difficult toset manually to achieve a desired look; the "kdsubsurface" material isusually better for that. However, if measured data is available, thismaterial is the appropriate one.) This material also supports setting thescattering properties using values that have been measured by variousresearchers.

TypeNameDefault ValueDescription
stringnamenoneName of measured subsurface scattering coefficients. See thefile src/core/media.cppin the pbrt distribution for all of themeasurements that are available.
spectrum texturesigma_a(.0011, .0024, .014)Absorption coefficient of the volume, measured in mm^-1.
spectrum texturesigma_prime_s(2.55, 3.12, 3.77)Reduced scattering coefficient of the volume, measured in mm^-1.
floatscale1Scale factor that is applied to sigma_a and sigma_prime_s.This is particularly useful when the scene is not measured inmm and the coefficients need to be scaled accordingly. For example,if the scene is modeled in meters, then a scale factor of 0.001would be appropriate.
float textureeta1.33Index of refraction of the scattering volume.
spectrum textureKr1Specular reflection term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount ofspecular reflection.
spectrum textureKt1Specular reflection term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount ofspecular reflection.
float textureuroughness0Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled.
float texturevroughness0Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled.
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Translucent

The "translucent" material models transmission through thin objects (like leaves).

TypeNameDefault ValueDescription
spectrum textureKd0.25The coefficient of diffuse reflection and transmission.
spectrum textureKs0.25The coefficient of specular reflection and transmission.
spectrum texturereflect0.5Fraction of light reflected.
spectrum texturetransmit0.5Fraction of light transmitted.
float textureroughness0.1The roughness of the surface. (This value should be between0 and 1).
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Uber

Finally, the "uber" material is a "kitchen sink" material that supportsdiffuse, glossy specular, and specular reflection.

TypeNameDefault ValueDescription
spectrum textureKd0.25The coefficient of diffuse reflection.
spectrum textureKs0.25The coefficient of glossy reflection.
spectrum textureKr0The coefficient of specular reflection.
spectrum textureKt0The coefficient of specular transmission.
float textureroughness0.1The roughness of the surface.
float textureuroughness0Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled.
float texturevroughness0Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled.
float textureeta1.5Index of refraction of the surface. This value is used inboth the microfacet model for specular reflection as well as forcomputing a Fresnel reflection term for perfect specular reflection.
spectrum textureopacity1The opacity of the surface. Note that when less than one,the uber material transmits light without refracting it.
boolremaproughnesstrueIf true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function.

Textures

The Texture statement creates a named texture of a particular type.Currently, the only types that are supported are spectrum (colorcan be used a synonym) and float.

Texture "name" "type" "class" [ parameter-list ]

For example,

Texture "mydiffuse" "spectrum" "imagemap" "string filename" "image.tga"Material "matte" "texture Kd" "mydiffuse"

pbrt provides the following texture implementations:

NameImplementation Class
"bilerp"BilerpTexture
"checkerboard"Checkerboard2DTexture
"checkerboard"Checkerboard3DTexture
"constant"ConstantTexture
"dots"DotsTexture
"fbm"FBmTexture
"imagemap"ImageTexture
"marble"MarbleTexture
"mix"MixTexture
"scale"ScaleTexture
"uv"UVTexture
"windy"WindyTexture
"wrinkled"WrinkledTexture

In the below, note that a number of textures (e.g. "mix") themselves taketextures as parameters; thus, one can build up small "trees" of computationto compose a series of texture functions.

Textures can be separated into three categories: any-D, 2D, and 3D.Any-D texturesare ConstantTexture, ScaleTexture,and MixTexture. These kinds of textures do nothave a specific dimensionality and have no common arguments.

2D textures use the (u,v) parametric coordinates on a surfacefor evaluation. Theyare BilerpTexture, ImageTexture, UVTexture,CheckerboardTexture, and DotsTexture. 2D textures have thefollowing common parameters:

TypeNameDefault ValueDescription
stringmapping"uv"A string specifying the kind of texture coordinate mapping to use.Legal values are: "uv", "spherical", "cylindrical", or "planar".
floatuscale, vscale1Scaling factors to be applied to the u and v texture coordinates, respectively.These parameters are only meaningful if the texture coordinate mapping typehas been set to "uv".
floatudelta, vdelta0An offset to be applied to the u and v texture coordinates, respectively.These parameters are only meaningful if the texture coordinate mapping type has beenset to "uv" or "planar".
vectorv1, v2see descriptionv1 and v2 are two vectors that define a planar mapping. The defaults are(1,0,0) and (0,1,0), respectively. These parameters are only meaningful if thetexture coordinate mapping type has been set to "planar".

3D textures use a texture space point location to evaluate themselves. Thecurrent transformation matrix at the time they are created gives thetransformation from object space. They are CheckerboardTexture,FBmTexture, WrinkledTexture,MarbleTexture, andWindyTexture. Notethat CheckerboardTexture is the only texture thatcan be either a 2D or 3D texture (see its plug-in specific parametersettings in the following). 3D textures have no common parameters.

Most of the provided textures can generate either Spectrum orfloat values, which is why many of the followingdescriptions have the spectrum/float type.

Constant

The "constant" texture is just a convenience that always returns a givenconstant value.

TypeNameDefault ValueDescription
spectrum/float texturevalue1The constant value of this texture.

Scale

"scale" takes two textures as parameters, evaluates each of them, andreturns their product. It is often convenient to scale a texture used as abump map by a constant float value to modulate the perceived height ofthe bumps, for example.

TypeNameDefault ValueDescription
spectrum/float texturetex1, tex21These two textures will be multiplied together by the ScaleTexture.

Mix

"mix" takes two textures and linearly interpolates between their valuesaccording to the "amount" parameter (which may itself be a texture).

TypeNameDefault ValueDescription
spectrum/float texturetex10One of the two textures to be mixed.
spectrum/float texturetex21The other texture to be mixed. These two textures must be of the same type.
float textureamount0.5The amount to use when linearly interpolating between the two mix textures.

Bilinear Interpolation

"bilerp" bilinearly interpolates between the four textures using the(u,v) parametric coordinate. The v00 parameter represents thetexture to use at (0,0), and so forth.

TypeNameDefault ValueDescription
spectrum/float texturev00, v01, v10, v11see descriptionThe four values to be bilinearly interpolated between.They default to 0, 1, 0, and 1, respectively.

Image Map

Image maps can be provided with the "imagemap" texture.

TypeNameDefault ValueDescription
stringfilenamerequired—no defaultThe filename of the image to load. Currently pbrt supportsTGA, PFM, and EXR format images.
stringwrap"repeat"What to do with texture coordinates that fall outside the legal [0,1] range.Legal values are "repeat", which simply tiles the texture; "black", whichreturns black when outside the legal range; and "clamp", which always returns thenearest border texel.
floatmaxanisotropy8The maximum elliptical eccentricity for the EWA algorithm.
booltrilinearfalseIf true, perform trilinear interpolation when looking up pixel values.Otherwise, pbrt uses the EWA algorithm for texture filtering. EWAgives much better results, but is slower.
floatscale1Scale factor to apply to value looked up in texture.
boolgamma(depends)Indicates whether texel values should be converted from sRGB gammaspace to linear space. This parameter is "true" by default for texturesstored in 8-bit formats like TGA and PNG, and "false" for floating-pointformats like EXR and PFM.

Checkerboard

The "checkerboard" texture is a simple texture that alternates between two other textures.

TypeNameDefault ValueDescription
integerdimension2Sets the dimension of the checkerboard texture. Legal values are 2 and 3.
spectrum/float texturetex11The texture to use for even checks.
spectrum/float texturetex20The texture to use for odd checks.
stringaamode"closedform"Set the antialiasing mode for the checkerboard texture. Legal valuesare "closedform" or "none". This parameter is only legal for 2D checkerboards.

Dots

The "dots" texture generates a random collection of polka dots.

TypeNameDefault ValueDescription
spectrum/float textureinside, outsidesee descriptionThe textures to use for coloring the dots and the background. The defaultsare 1 and 0, respectively.

Fbm and Wrinkled

"fbm" and "wrinkled" are two textures based on the Perlin noise function.They are 3D textures, so the scale of the features of the texture can beadjusted by setting accordingly the CTM when the texture is defined.

TypeNameDefault ValueDescription
integeroctaves8The maximum number of octaves of noise to use in spectral synthesis.
floatroughness0.5The "bumpiness" of the resulting texture.

Marble

Finally, "marble" is a simple approximation to a layered marble texture,based on using Perlin noise to create stochastic variation in the result.

TypeNameDefault ValueDescription
integeroctaves8The maximum number of octaves of noise to use in spectral synthesis.
floatroughness0.5The "bumpiness" of the resulting texture.
floatscale1A scaling factor to apply to the noise function inputs.
floatvariation0.2A scaling factor to apply to the noise function output.

Participating media can be associated with regions of space in thescene using the MakedNamedMediumand MediumInterface directives. First,MakedNamedMedium associates a user-specified namewith medium scattering characteristics.

MakeNamedMedium "mymedium" "string type" "homogeneous" "rgb sigma_s" [100 100 100]

There are two representations of participating media available in pbrt.One represents spatially-uniform media, and the other represents mediawith varying density specified by a 3D grid of floating-point values.

NameImplementation Class
"homogeneous"HomogeneousMedium
"heterogeneous"GridDensityMedium

Both take a few common parameters. (And for the "homogeneous"medium, these are the only parameters available.)

TypeNameDefault ValueDescription
spectrumsigma_argb (0.0011, 0.0024, 0.014)The absorption cross section.
spectrumsigma_srgb (2.55, 3.21, 3.77)The scattering cross section.
stringpresetnoneIf specified, a named measured scattering medium; see thefile src/core/media.cppin the pbrt distribution for all of themeasurements that are available.
floatg0The phase function asymmetry parameter.
floatscale1Scale factor applied to the absorption and scattering crosssections.

The "heterogeneous" allows specification of a sampled volumedensity on a regular grid. Final scattering properties at points insidethe volume are computed by trilinearly interpolating the adjacent samplevalues and then scaling the sigma_a and sigma_s parameter values by theresult.

TypeNameDefault ValueDescription
pointp0, p1(0,0,0), (1,1,1)The two corners of the bounding box that gives the maximum extent ofthe medium. (It may be smaller depending on the shape or shapes that themedium is enclosed in.)
integernx,ny,nz1The number of voxels in the x, y, and z directions, respectively.
float[nx*ny*nz]density0The array of density values.

Given named media, the MediumInterfacedirective can be used to specify the current "interior" and "exterior"media. A vacuum—no participating media—is represented byempty string "".

MakeNamedMedium "mymedium" "homogeneous" "rgb sigma_s" [100 100 100]MediumInterface "" "mymedium"

Before the world block, the interior medium is ignored, but the exteriormedium specifies the medium that camera rays start out in.

Inside the world block, the current medium interface is maintained likeother attributes; it's saved and restored insideAttributeBegin/AttributeEndblocks, and so forth. When a light source is created, the current exteriormedium is used for rays leaving the light when bidirectional lighttransport algorithms are used. (The user is responsible for specifyingmedia in a way such that rays reaching lights are in the same medium asrays leaving those lights.)

Shapes can be used to determine the spatial extent of participating mediain the scene. When a shape is created, the current interior medium isassumed to be the medium inside the shape (where "inside" is on the sideopposite the one the surface normal is pointing), and the current exteriormedium is assumed to be the medium outside the shape. As with lights, theuser is responsible for defining these consistently. (For example, media'sspatial extents should always be enclosed by closed shapes.)

Depending on the application, it can be useful to use a shape purely todetermine the spatial extent of media, but to not want the shape toappear in the scene. In this case, if "none" is specified for theshape's material, it will be ignored in ray intersection calculations(except for allowing the current medium to be updated.)

pbrt-v3 Input File Format (2024)
Top Articles
Latest Posts
Recommended Articles
Article information

Author: Wyatt Volkman LLD

Last Updated:

Views: 6153

Rating: 4.6 / 5 (46 voted)

Reviews: 93% of readers found this page helpful

Author information

Name: Wyatt Volkman LLD

Birthday: 1992-02-16

Address: Suite 851 78549 Lubowitz Well, Wardside, TX 98080-8615

Phone: +67618977178100

Job: Manufacturing Director

Hobby: Running, Mountaineering, Inline skating, Writing, Baton twirling, Computer programming, Stone skipping

Introduction: My name is Wyatt Volkman LLD, I am a handsome, rich, comfortable, lively, zealous, graceful, gifted person who loves writing and wants to share my knowledge and understanding with you.