Scene file format 0.9

Basics

An .lxs file is an ASCII text file with a full description of the scene to be rendered. As scene descriptions can get quite large, there is a mechanism to break the scene description down into more manageable pieces: the description can be spread over several text files. The suggested organization is the following:

• A main scene file with extension '.lxs'. For example: 'scene.lxs'
• An included Material file with suffif '-mat' and extension '.lxm'. For example: 'scene-mat.lxm'
• An included Geometry file with suffix '-geom' and extension '.lxo'. For example: 'scene-geom.lxo'
• An optional Volume file with suffix '-vol' and extension '.lxv'. For example: 'scene-vol.lxv'

You can include each additional file into the scene file via the "Include" statement:

Include "scene-geom.lxo"

Coordinate System

LuxRender uses a 3D coordinate system where the Z axis points upward and where positive increments of the Y coordinate move away from the camera. This is consistent with Blender's coordinate system. If you need to write an exporter from a program that uses a Y-up system, you need to swap the Y value with the Z value when writing the LuxRender file. In addition, if positive values of the original Z axis move the object toward the camera, you will need to multiply that value by -1 when exporting to Lux.

Basic Structure

While the contents of .lxs files may vary considerably, even the simplest scenes will have the following: a camera specification, at least one light source, a film specification, transformations, primitives, materials, textures and so on...

The following example .lxs file will be the example used in all following explanation:

#This is an example of a comment!

#Global Information
LookAt 0 10 100 0 -1 0 0 1 0
Camera "perspective" "float fov" [30]

Film "fleximage"
        "integer xresolution" [200]
        "integer yresolution" [200]

PixelFilter "mitchell"
        "float xwidth" [2]
        "float ywidth" [2]

Sampler "lowdiscrepancy"
        "string pixelsampler" ["lowdiscrepancy"]

#Scene Specific Information
WorldBegin

AttributeBegin
        CoordSysTransform "camera"
        LightSource "distant"
                "point from" [0 0 0] "point to" [0 0 1]
                "color L" [3 3 3]
AttributeEnd

AttributeBegin
        Rotate 135 1 0 0

        Texture "checks" "float" "checkerboard"
                "float uscale" [4]
                "float vscale" [4]
                "float tex1" [1.0]
                "float tex2" [0.0]

        Texture "kd:checks" "color" "mix"
                "texture amount" ["checks"]
                "color tex1" [1 0 0]
                "color tex2" [0 0 1]

        Material "matte"
                "texture Kd" "kd:checks"

        Shape "disk"
                "float radius" [20]
                "float height" [-1]
AttributeEnd

WorldEnd

Comments

Any text on a line beginning with a # is ignored by the parser. Often these are useful to give readable descriptions of what you are doing!

Statements

'WorldBegin' and 'AttributeEnd' are examples of statements. These are important in describing the properties of whole blocks of data.

Identifiers

'Camera', 'Sampler', 'Texture' and 'Material' are some examples of identifiers. These indicate what aspect of the scene is being described.

Types

These are given in quotes, often after an identifier to specify an implementation to use. For example, by giving the type "perspective" after the 'Camera' identifier, the renderer can use the intended camera model.

Parameters

Parameters typically consist of two parts: the type of parameter followed by the parameter name in given in quotes, followed by the actual value of the parameter given. The type of a parameter can be an integer, a float, a point, a normal, a color, a bool or a string. Continuing our example, the field of view ('fov') needs to be passed to our camera and as this parameter is of type float, we type "float fov" [30]. Note that as 'Rotate' and 'LookAt' take a predetermined amount of numbers and types of arguments they do not need parameter types or quotes.

Importance of parameter types

It is important to explain why you need to specify whether you are giving an integer or float every single time you give a parameter. It may seem like that tedium should be taken care of automatically, but LuxRender would be far less flexible if that were the case. LuxRender is based on plugins, functional sections of code that the core renderer does not need to know anything about. By specifying the parameter type, LuxRender can handle new plugins in a uniform way, allowing developers to realise new features quicker. To reiterate, the parameter types are:

Arrays are created by specifying more than one value inside brackets, separated by space. So a point or a vector is actually an array of floats. In this document we will indicate this by using [n] after the type name, where n is the number of elements required. For example, a valid float[4] would be [0 1 2 3].

WorldBegin

The WorldBegin attribute indicates the end of the global information and the beginning of the scene specific information.

WorldEnd

The WorldEnd attribute indicates the end of the scene specific information and marks the end of the file (if no comments follow).

AttributeBegin

The AttributeBegin attribute indicates the beginning of the description of an unnamed object. In case the object needs to be referenced (for example by instances), use ObjectBegin instead.

AttributeEnd

AttributeEnd marks the end of the description of an unnamed object.

TransformBegin

Indicates the beginning of a named coordinate system. Usually within this block you will write Indentity, Transform, and CoordinateSystem. Identity is used to reset the coordinate system to zero, the Transform defines the transform of the coordinate-system you wish to name, and CoordinateSystem followed by a string names the transform defined in this block.

TransformEnd

TransformEnd marks the end of a named coordinate system.

ObjectBegin

The ObjectBegin attribute indicates the beginning of the description of a named object, which is useful for creating instances. It must be followed by a string, indicating the name of the object.

ObjectEnd

ObjectEnd marks the end of the description of a named object.

ObjectInstance

If a named object is created, it can be referenced in multiple objects. These objects can be ordinary unnamed objects that use an ObjectInstance line instead of a shape definition. It must be followed by a string with the name of the object to instance.

MotionInstance

Deprecated

This works similarly to ObjectInstace but also takes three further parameters: start-time (float), end-time (float) and coordinate-system (string). This allows for rendering motion blur on object transformations. The coordinate-system string should match an already defined CoordinateSystem in a TransformBegin..*TransformEnd* block.

PortalInstance

Works in a similar manner to ObjectInstance but is a substitute for PortalShape. This allows instancing of portal geometry.

Renderer

This identifies which rendering method to use. Currently supported renderers are:

• sampler
• hybridsampler
• sppm

The hybridsppm renderer from 0.8 is gone and has been replaced with the "sppm" renderer. "hybridsppm" never did anything anyway. "hybridsampler" is also known as simply "hybrid". Either works.

Here are the renderer-specific parameters (sppm and sampler have no parameters of their own, all params come from the surface integrator):

Camera

The following camera types are available. The default camera type is 'perspective'.

• perspective (default)

  The most common camera, resemble most closely what is seen by the human eye or a pinhole camera.

• environment

  Denotes a type of camera which maps the whole of the environment around the camera to an image.

• orthographic

  The standard orthographic camera: parallel lines stay parallel and a sense of depth is lost.

• realistic

  A physically-based camera model that loads lens descriptions files to realistically generate camera rays and weights.

The current transformation is used as the camera transform. Thus one usually has a LookAt or Transform statement before

Sampler

LuxRender supports these sampler types:

• random
• lowdiscrepancy
• metropolis
• erpt

Film

There is currently only one film type: fleximage

PixelFilter

Specifies the pixel filter used for image reconstruction. LuxRender supports these pixel filters:

• box
• triangle
• gaussian
• mitchell (default)
• sinc

Accelerator

LuxRender supports the following accelerator structures.

• kdtree (default)
• qbvh
• sqbvh
• unsafekdtree (not thread-safe)
• none

Note: BVH and Grid are no longer preset as of version 0.8. While kdtree is currently the default, qbvh is often a better choice. kdtree is primarily the default to avoid issues when compiling for non-x86 architectures, as QBVH and SQBVH are dependent on SSE. Generally, only KD Tree, SQBVH and QBVH should be exposed to the user.

qbvh/sqbvh
%%%%

SurfaceIntegrator

Here are the surface integrator types.

• bidirectional (default)
• path
• exphotonmap
• directlighting
• igi
• distributedpath
• sppm

Volume Integrator

The following volume integrators are available. They work only with the path integrator and uses only the bounding volumes, not the mediums.

• emission (default, only computes volumetric absorption and emission but no scattering)
• single (computes volumetric absorption, emission and single scattering)
• multi (computes volumetric absorption, emission and multiple scattering)