Provides a reader for the PBRT file format.

## PBRT file format

The scene description files used by pbrt are text files. A file consists of statements. There is a set of statements at the beginning of the file which sets up options for the renderer, and a set enclosed in `BeginWorld` and `EndWorld` which creates scene primitives and lights. A detailed description of the format is given in Appendix C of the first edition of the book.

Here is an example of a typical PBRT file:

    # Set up rendering options

    Film "image"
         "integer xresolution" [400] "integer yresolution" [400]
         "string filename" "02-kon-tiki.tga"

    Sampler "stratified"
            "integer xsamples" [2] "integer ysamples" [2]
            "bool jitter" ["false"]

    PixelFilter "mitchell"

    Accelerator "grid"

    LookAt 15 7.5 -15 0 0 0 0 1 0
    Camera "perspective"
           "float fov" [60]

    SurfaceIntegrator "whitted"
            "integer maxdepth" [5]

    #
    BeginWorld
    #
    ## Add lights to the scene
    AttributeBegin
    	Translate 0 20 -20
    	LightSource "point" "color I" [1200 1200 1200]
    AttributeEnd
    #
    ## Add geometry to the scene
    AttributeBegin
    	Rotate -10 1 0 0
    	Translate 0 1 0
    	Scale 1 1.2 1
    	Material "matte" "color Kd" [0.8 0.1 0.1]
    	Shape "cylinder" "float radius" [2] "float zmin" [-3]  "float zmax" [3] "float phimax" [200]
    AttributeEnd

    EndWorld

The PBRT file format supports the following statement types:

- Scene File Structure
- Transformations
- Scene-wide Rendering Options
  - Cameras
  - Samplers
  - Film
  - Filters
  - Renderers
  - Accelerators
  - Surface Integrators
  - Volume Integrators
- Scene definition
  - Attributes
  - Lights
  - Shapes
  - Volumes
  - Object instancing
  - Textures

### Scene File Structure

`AttributeBegin```

> Saves the current transformation and current attributes.
> Partially supported by JPBRT.

```AttributeEnd```

> Restores the previously saved transformation and attributes``.
> Partially supported by JPBRT.

```Include``"filename.pbrt"`

> Includes another PBRT file.

`SearchPath``"path:path:&:path"`

> Specifies one or more directory names into which the scene reader looks for referenced files.
> Search paths are separated by colons (semicolons in Windows). The previously defined search patch can be specified with `&`.
> Not yet supported by JPBRT.

`TransformBegin```

> Saves the current transformation``.
> Not yet supported by JPBRT.

```TransformEnd```

> Restores the current transformation``.
> Not yet supported by JPBRT.

`WorldBegin`

> Marks the end of the options specification and the start of the description of the lights and geometry in the scene.
> Sets the current transformation to identity.

```WorldEnd```

> Marks the end of the scene description. The scene is rendered when this statement is encountered.

### Transformations

The following set of statements update the current transformation matrix of the scene reader.

`Identity`

> Sets the current transformation to identity.

`Translate` `x y z`

> Translates the current transformation by `x y z`.

`Scale` `x y z`

> Scales the current transformation by `x y z`.

`Rotate` `angle x y z`

> Rotates the current transformation by `angle` degrees along the axis given by vector `x y z`.

`LookAt` `ex ey ez lx ly lz ux uy uz`

> Applies a look-at-transformation to the current transformation. The eye position is given by `ex ey ez`, the look-at position is given by `lx ly lz`, the up vector is given by `ux uy uz`.

```CoordinateSystem``"name"`

> Stores the current transformation as `name`.
> Note: the Camera statement stores the current transfomration under the name "camera".

```CoordSysTransform``"name"`

> Applies the previously stored transformation `name` to the current transformation.

`Transform` `m00 ... m33`

> Sets the current transformation to the specified transformation matrix.

`ConcatTransform` `m00 ... m33`

> Applies the specified transformation matrix to the current transformation.

### Scene-wide rendering options

The following set of statements specify rendering options that must be specified before the WorldBegin statement.

`Camera``"name" parameter-list`

> Sets the camera used for viewing the scene using the current transformation.
> Stores the current transformation under the name "camera".
> See Cameras for more information.
> Partially supported by JPBRT.

```Sampler``"name" parameter-list`

> Sets the sampler used for generating samples.
> See Samplers for more information.
> Partially supported by JPBRT.

```PixelFilter``"name" parameter-list`

> Sets the filter used for converting image samples into pixels.
> See Filters for more information.

```Film``"name" parameter-list`

> Specifies the film used for storing pixels.
> See Film for more information.
> Partially supported by JPBRT.

```Accelerator``"name" parameter-list`

> Specifies the structure used for accelerating ray-scene intersection tests``.
> See Accelerators for more information.
> Partially supported by JPBRT.

```SurfaceIntegrator``"name" parameter-list`

> Specifies the integrator used for surfaces.
> If this statement is not specified, a direct lighting integrator is used.
> See Surface Integrators for more information.
> Partially supported by JPBRT.

```VolumeIntegrator``"name" parameter-list`

> Specifies the integrator used for volumes.
> See Volume Integrators for more information.
> Partially supported by JPBRT.

#### ``Cameras

    Camera "environment"
           "float hither" [0.001] "float yon" [10e30]

           "float shutteropen" [0] "float shutterclose" [1]
           "float frameaspectratio" [frameaspectratio]
           "float screenwindow" [-1 1 -1 1]

> Sets an environment camera.
> Not yet supported by JPBRT.

    Camera "orthographic"
           "float hither" [0.001] "float yon" [10e30]

           "float shutteropen" [0] "float shutterclose" [1]
           "float lensradius" [0] "float focaldistance" [10e30]
           "float frameaspectratio" [frameaspectratio]
           "float screenwindow" [-1 1 -1 1]

> Sets an orthographic camera.
> The camera uses the current transform.
> Stores the current transform under the name "camera".

    Camera "perspective"
           "float fov" [90]
           "float hither" [0.001] "float yon" [10e30]

           "float shutteropen" [0] "float shutterclose" [1]
           "float lensradius" [0] "float focaldistance" [10e30]
           "float frameaspectratio" [frameaspectratio]
           "float screenwindow" [-1 1 -1 1]

> Sets a perspective camera.
> The camera uses the current transform.
> Stores the current transform under the name "camera".

#### ``Samplers

    Sampler "bestcandidate"
            "integer pixelsamples" [4]

> Sets the best-candidate sampler.

    Sampler "lowdiscrepancy"
            "integer pixelsamples" [4]

> Not yet supported by JPBRT.

    Sampler "stratified"
            "integer xsamples" [2] "integer ysamples" [2]
            "bool jitter" ["true"]

> Sets the stratified sampler.

#### Film

    Film "image"
         "integer xresolution" [640] "integer yresolution" [480]
         "string filename" "pbrt.exr"
         "float cropwindow" [0 1 0 1]
         "integer writefrequency" [-1]
         "bool premultiplyalpha" ["true"]

> Partially supported by JPBRT.

#### Filters

    Filter "box"
         "float xwidth" [0.5] "float ywidth" [0.5]

> Sets the box filter.

    Filter "gaussian"
         "float xwidth" [2] "float ywidth" [2]
         "float alpha" [2]

> Sets the gaussian filter.

    Filter "mitchell"
         "float xwidth" [2] "float ywidth" [2]
         "float B" [0.333333] "float C" [0.333333]

> Sets the Mitchell filter.

    Filter "sinc"
         "float xwidth" [4] "float ywidth" [4]
         "float tau" [3]

> Sets the Lanczos sinc filter.

    Filter "triangle"
         "float xwidth" [2] "integer ywidth" [2]

> Sets the triangle filter.

#### Accelerators

    Accelerator "none"

> Sets no accelerator.
> This is a unique feature of JPBRT.

    Accelerator "grid"
         "boolean refineimmediately" [false]

> Sets the grid accelerator.

    Accelerator "kdtree"
         "integer intersectcost" [80] "integer traversalcost" [1]
         "float emptybonus" [0.2]
         "integer maxprims" [1] "integer maxdepth" [-1]

> Sets the kd-tree accelerator.
> Not yet supported by JPBRT.

### Surface Integrators

    SurfaceIntegrator "directlighting"
             "integer maxdepth" [5]
             "string strategy" ["all" or "one"]

> Creates the direct lighting surface integrator.

    SurfaceIntegrator "whitted"
             "integer maxdepth" [5]

> Creates the Whitted surface integrator.

### Volume Integrators

    VolumeIntegrator "none"

> Creates the null volume integrator which ignores all volume regions in a scene.
> Compatbility Warning: "none" is not supported by pbrt.

    VolumeIntegrator "emission"
             "float stepsize" [1]

> Creates the emission volume integrator.

    VolumeIntegrator "single"
             "float stepsize" [1]

> Creates the single volume integrator.

### ``Scene Definition

#### Attributes

`Material``"name" parameter-list`

> Sets the current material attribute.
> See Materials for more information.
> Partially supported by JPBRT.

```Texture``"name" parameter-list`

> Sets the current texture attribute.
> See Textures for more information.
> Not yet supported by JPBRT.

```ReverseOrientation`

> Flips the current reverse orientation attribute``.
> Not yet supported by JPBRT.

#### ``Lights, shapes and volumes

`Shape``"name" parameter-list`

> Creates a shape object using the current transformation and attributes.
> See Shapes for more information.
> Partially supported by JPBRT.

```LightSource``"name" parameter-list`

> Creates a light source object using the current transformation and attributes``.
> See Lights for more information.
> Partially supported by JPBRT.

```AreaLightSource``"name" parameter-list`

> Sets the current area light attribute.
> See Lights for more information.
> Not yet supported by JPBRT.

```Volume``"name" parameter-list`

> Creates a volume object.
> See Volumes for more information.
> Not yet supported by JPBRT.

#### ``Object instancing

`ObjectBegin``"name"`

> Denotes the start of a name assignment.
> Assigns the given name to the object surrounded by ObjectBegin and ObjectEnd``.
> Not yet supported by JPBRT.

```ObjectEnd`

> Denotes the end of a name assignment``.
> Not yet supported by JPBRT.

```ObjectInstance``"name"`

> Instantiates a previously named object.
> Not yet supported by JPBRT.

#### ``Shapes

    Shape "box"
         "point p1" [-1 -1 -1] "point p2" [1 1 1]

> Creates a box.
> Compatbility Warning: "box" is not supported by pbrt. If you want your scene to be compatible with pbrt, use a "trianglemesh" shape instead.

    Shape "cone"
         "float radius" [1]
         "float height" [0]
         "float phimax" [360]

> Creates a cone.

    Shape "cylinder"
         "float radius" [1]
         "float zmin" [-1] "float zmax" [1]
         "float phimax" [360]

> Creates a cylinder.

    Shape "disk"
         "float radius" [1] "float innerradius" [0]
         "float height" [0]
         "float phimax" [360]

> Creates a disk.

    Shape "hyperboloid"
         "point p1" [0 0 0] "point p2" [1 1 1]
         "float phimax" [360]

> Creates a hyperboloid.

    Shape "loopsubdiv"
         "integer nlevels" [3]
         "integer indices" [n integers]
         "point P" [n points]

> Creates a loop-subdivided triangle mesh.
> Not yet supported by JPBRT.

    Shape "nurbs"
         "integer nu" [must be specified] "integer nv" [must be specified]
         "integer uorder" [0] "integer vorder" [0]
         "float u0" [0] "float v0" [0]
         "float u1" [0] "float v1" [0]
         "float uknots" [nu+uorder floats]
         "float vknots" [nv+vorder floats]
         "point P" [nu*nv points]
         "float Pw" [4*nu*nv floats]

> Creates a nurbs shape.
> Not yet supported by JPBRT.

    Shape "paraboloid"
         "float radius" [1]
         "float zmin" [-1] "float zmax" [1]
         "float phimax" [360]

> Creates a paraboloid.

    Shape "sphere"
         "float radius" [1]
         "float zmin" [-1] "float zmax" [1]
         "float phimax" [360]

> Creates a sphere.

    Shape "trianglemesh"
         "integer indices" [n integers]
         "point P" [n points]

         "normal N" [n normals]
         "vector S" [vector]
         "float st" [n*2 floats]
         "float uv" [n*2 floats]

> Creates a triangle mesh.

    Shape "mesh"
         "integer triindices" [n integers]
         "point P" [n points]

         "normal N" [n normals]
         "vector S" [vector]
         "float st" [n*2 floats]
         "float uv" [n*2 floats]

> Creates a triangle mesh using the alternative syntax used by Luxrender.
> Compatibility warning: "mesh" is not supported by pbrt. If you want your scene to be compatible with pbrt, use a "trianglemesh" shape instead.

#### Materials

    Material "matte"
             "color/texture Kd" []
             "float/texture sigma" []
             "float/texture bumpmap" []

> Sets the material attribute to matte.
> Textures not yet supported by JPBRT.

#### Textures

Not yet supported by JPBRT.

#### Volumes

Not yet supported by JPBRT.

#### Lights

    AreaLightSource "area"
             "color L" [1 1 1]
             "integer nsamples" [1]

> Sets an area light as the current area light attribute.
> Not yet supported by JPBRT.

    LightSource "distant"
             "color L" [1 1 1]
             "color scale" [1 1 1]
             "point from" [0 0 0] "point to" [0 0 1]

> Creates a distant light source.

    LightSource "goniometric"
             "color I" [1 1 1]
             "string mapname" "mapname"

> Creates a goniometric light source.
> Not yet supported by JPBRT.

    LightSource "infinite"
             "color L" [1 1 1]
             "color scale" [1 1 1]
             "integer nsamples" [1]
             "string mapname" "mapname"

> Creates an infinite light source.
> mapname not yet supported by JPBRT.

    LightSource "point"
             "color I" [1 1 1]
             "color scale" [1 1 1]
             "point from" [0 0 0]

> Creates a point light source.

    LightSource "projection"
             "color I" [1 1 1]
             "float fov" [45]
             "string mapname" "mapname"

> Creates a projection light source.
> Not yet supported by JPBRT.

    LightSource "spot"
             "color I" [1 1 1]
             "point from" [0 0 0] "point to" [0 0 1]
             "float coneangle" [30] "float conedeltaangle" [5]

> Creates a spot light source.
> Not yet supported by JPBRT.

## References

- M. Pharr, G. Humphreys. (2010). Physically Based Rendering, 2nd Edition. Morgan Kaufmann.
  APPENDIX B.
- M. Pharr, G. Humphreys. (2004). Physically Based Rendering. Morgan Kaufmann.
  APPENDIX C.