Scene file format 0.8 - LuxRender Wiki
Luxrender GPL Physically Based Renderer

Scene file format 0.8

Personal tools

From LuxRender Wiki

Revision as of 19:51, 5 April 2012 by Pciccone (Talk | contribs)
Jump to: navigation, search


Introduction

In order to pass scene data for rendering, either the luxrender API or the .lxs file format can be used. While the API and the .lxs file format are closely related, this document only covers the description of the .lxs file format. This should aid both exporter writers and those wishing to gain more control over the rendering process.

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

Components of an .lxs file

Notice these features occur frequently throughout the .lxs file:

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:

Type Description Examples
integer a whole number 1, 2, 3
float a number with a decimal point [1.67], [2.54] (Note the square brackets given around the values.)
point declares a point, given by three floating point values [45.000 12.000 0.900]
vector a vector, specified the same way as a point [12.000 3.120 1.100]
normal a normal (unit vector) same as a point.
color RGB color [r g b] expressed in decimal notation [0.123 1.0 0.245]
bool Boolean ["true"] , ["false"]
string string, non-escaped, surrounded by quotes "simple.exr", "lux.png"

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].

Transformations

Any number of transformation can be applied to a section of the scene. Unless specified each transformation will be concatenated (right multiplied) with the current transform. To make the transformation "local" it's advisable to enclose them between "TransformBegin" and "TransformEnd". These two commands define a block that is then removed when the TransformEnd command is reached. From that point on, the previously defined, possibly global, transformations will be restored. For example:

Identity
Translate 5 0 0
TransformBegin
        # Rotate in addition to translation.
        Rotate 90 0 1 0
        Shape "cone"
TransformEnd
# Only the translate transformation is current at this point

One can store the current transformation as a named coordinate system using "CoordinateSystem". Using this the above example can be written as:

TransformBegin
        Identity
        Translate 5 0 0
        Rotate 90 0 1 0
        CoordinateSystem "mytransform" # store the current transform as "mytransform"
TransformEnd

...
CoordSysTransform "mytransform"   # set the current transformation to "mytransform"
Shape "cone"

Named coordinate systems are needed for motion blur.

The following transformation commands are available.

Transformation commands
Command Description Example
Identity Replaces the current transformation with the identity transformation.  
Rotate Rotates an entity by a given number of degrees around a given axis.

The first parameter is the rotation in degrees, the following parameters indicate the X, Y and Z axis.

A 0 means to leave the axis unaffected, a 1 means to rotate on that axis.

Rotate 180 1 0 0

Rotates the object around the X-axis 180 degrees
Scale Adjusts the size of an entity by a given factor.

Scale .1 .2 .3

Scales in the X-direction to 10%, the Y-direction to 20%, and the Z-direction to 30%
Translate Moves an entity in a given direction by a vector.

Translate 10.1 20.2 30.3

Moves the center 10.1 units in the X-direction, 20.2 in the Y-direction, and 30.3 in the Z-direction
Transform Replaces the current transformation with the given transform. It takes a single 16-element array as parameter, each element corresponds to an item in a 4x4 matrix, column by column. The last column, and thus last 4 values, typically holds the translation part.

Transform [2.0 0.0 0.0 0.0 0.0 2.0 0.0 0.0 0.0 0.0 2.0 0.0 -3.0 2.0 -1.0 1.0]

Replaces the current transform with one that scales the object by 2 and translates it by -3.0 along the X-direction, 2.0 along the Y-direction and -1.0 along the Z-direction.
ConcatTransform Similar to Transform, except concatenates (right multiplies) the given transform with the current transform. See Transform
LookAt The LookAt transformation takes 3 vectors as parameters. The first vector (0 0 0 in the example) is the position of the camera.

The second vector (0 1 0) is the position of the target of the camera. The last vector (0 0 1) is the up vector. This is quite a simple transformation, which allows you to specify 2 points, one where the camera is located and another point of 'interest'.

The up vector is a unit vector which defines how the camera is help up, it should point upwards of your camera, eg if it is held straight, it will be 0 0 1 (+Z up)

LookAt 0 0 0 0 1 0 0 0 1

Orients the entity such that it is located at the origin and looking in the +Y direction, with +Z as up.
CoordSysTransform Replaces the current transformation by a named transformation defined earlier using CoordinateSystem. CoordSysTransform "mytransform"

Attributes

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

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.

Global vs Scene Specific Information

Notice that in the .lxs file structure, global information is given before scene specific information.

Global information

This is information that describes how the scene is going to be rendered; it includes types of and settings for the camera, sampler and film and so on. While the position and rotation of a camera may be considered part of the specific scene description, the camera defines the final render area and is therefore more important to the rendering process than say, geometry. This data is given at the top of the .lxs file.

The following Indentifiers are all considered as global information:

  • Renderer
  • Camera
  • Sampler
  • Film
  • PixelFilter
  • Accelerator
  • SurfaceIntegrator
  • VolumeIntegrator

Renderer

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

  • sampler
  • hybridsampler
  • hybridsppm

Here are the renderer-specific parameters:

hybridsampler

Name Type Description Default value
configfile string Path to a configuration file containing Renderer settings. This file should have the same format as used by SLG, and reads only the parameters defined in this table. ""
opencl.platform.index integer The OpenCL platform index to use for rendering. 0
opencl.gpu.use bool Tell the renderer to use the OpenCL GPU. true
opencl.gpu.workgroup.size integer Set the work-group size for the OpenCL GPU. The default (0) will attempt to automatically detect the correct size. 0

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

Common Camera Parameters

There are parameters specific to a particular camera implementation and general parameters for all cameras. Here are the common parameters:

Name Type Description Default Value Theoretical range Suggested range
hither float Geometry closer than this distance will not be rendered 10`-3`:sup: 0-infinity 0 - 10000
yon float Geometry further than this distance will not be rendered 10`30`:sup: 0-infinity 0 - 10000 (always bigger than hither)
shutteropen float The time in seconds at which the virtual shutter opens 0.0   0.0 - 1.0
shutterclose float The time in seconds at which the virtual shutter closes 1.0   0.0 - 1.0
lensradius float Default (0) for pinhole camera with whole scene in focus, increase for depth of field and focus effects. Ignored by environment and realistic cameras 0.0 0-infinity 0.0 - 1.0
focaldistance float Focal distance of the virtual lens. Use the control focus in depth of field effects. Ignored by environment and realistic cameras 10`30`:sup: 0-infinity 0.0 - 10000.0
frameaspectratio float This is normally computed from resolution but can be overridden here. Ignored by realistic camera computed from given resolution 0-infinity 1.0 - 10.0
screenwindow float[4] Specifies area in camera that the virtual film occupies - the bounds in screen space. Crops the camera viewport. (Ignored by realistic camera.) Values are: xmin xmax ymin ymax. entire screen space dependent on frame aspect ratio (xresolution/yresolution):

If aspect_ratio > 1: -aspect_ratio aspect_ratio -1 1 Otherwise:

-1 1 -1/aspect_ratio 1/aspect_ratio		  

Specific Camera Parameters

'environment' cameras do not support depth of field parameters lensradius and focaldistance as indicated above. 'realistic' cameras don't support lensradius, focaldistance, frameaspectratio and screenwindow either. However, the 'perspective' and 'realistic' cameras do have some specific parameters:

perspective
Name Type Description Default value Theoretical range Suggested range
fov float This is the field of view for the camera - this specifies the solid angle viewed. The fov value is the angle spanned by the smallest dimension of the image (width/height). An fov of 49.13 is equal to a focal length of 35mm. 90.0 0.0 < x < 180.0 1.0 - 179.0
lensradius float This value defines the lens radius. Values higher than 0 enable DOF and control its amount. To calculate the lensradius based on the f/stop number use the following equation:

lensradius = (focallength_in_mm / 1000.0) / ( 2.0 * fstop )

Example: 0.00625 = (35 / 1 000.0) / (2.0 * 2.8)		 0.00625 x ≥ 0.0 0.0 - 0.4
autofocus bool Enable/disable the autofocus feature. It is useful to automatically calculate the focal distance when lens radius > 0.0 (i.e. depth of field enabled). false    
focaldistance float This value controls the focal point of the scene, the distance from the camera at which objects will be in focus. It has no effect if the Lens Radius is set to 0. It is specified in meters. This value is not needed when using autofocus. 0.0 0.0 < x 0.0 - 200.0
blades integer This value controls the number of blade edges of the aperture, values 0 to 2 defaults to a circle. 6    
distribution string This value controls the lens sampling distribution. Non-uniform distributions allow for ring effects. Valid values include: "uniform", "exponential", "inverse exponential", "gaussian", and "inverse gaussian". uniform    
power integer This value controls the exponent for the expression in exponential distribution. Higher values gives a more pronounced ring effect. 1    
realistic

This camera type is not currently functional and should thus not be present in the user interface.

Name Type Description Default value
specfile string The .dat lens specification file which can be found in the cameras/realistic directory ""
filmdistance float Distance from the film to the backmost lens component (milimeters) 70.0
aperture_diameter float The aperture diameter of the aperture stop 1.0
filmdiag float Film diagonal size 35.0

Sampler

LuxRender supports these sampler types:

  • random
  • lowdiscrepancy
  • metropolis
  • erpt

Samplers Parameters

These samplers accept the parameters below.

Valid values for the pixelsampler algorithm parameter are:

  • hilbert
  • linear
  • vegas
  • lowdiscrepancy
  • tile
  • random

NOTE: The tile pixel sampler is mainly intended for long run rendering with [[Network rendering]]. It is quite important to use this kind of pixel sampler in order to improve the cache coherency and to reduce the network bandwidth usage.

random

Completely random sampler

Name Type Description Default value Theoretical range Suggested range
pixelsamples integer Number of samples per pixel / pass 4 x ≥ 1 1 - 512
pixelsampler string Pixel sampler algorithm to use. vegas    
lowdiscrepancy

Generates a low discrepancy sequence that evenly samples values, given a target number of samples per pixel

Name Type Description Default value Theoretical range Suggested range
pixelsamples integer Number of samples per pixel / pass 4 x ≥ 1 1 - 512
pixelsampler string Pixel sampler algorithm to use. vegas    
metropolis

Generates random values that are then slightly mutated, according to the Metropolis algorithm

Name Type Description Default value Theoretical range Suggested range
maxconsecrejects integer Number of consecutive rejects before a next mutation is forced. Low values can cause bias but slightly faster convergence, high values can help clear up caustics faster. 512 x ≥ 0 0 - 32768
largemutationprob float Probability of generating a large sample mutation 0.4 0.0 ≤ x ≤ 1.0 0.0 - 1.0
mutationrange float Maximum distance in pixel for a small mutation (width + height) / 32.0    
usevariance bool Use the variance hint provided by some integrators to alter sample acceptance false    
erpt

Similar to the Metropolis sampler but the ''Energy Redistribution Path Tracing'' algorithm is used

Name Type Description Default value Theoretical range Suggested range
initsamples integer Number of warm-up samples 100000    
chainlength integer Number of mutations from a given seed 2000 x ≥ 1 1 - 32768
mutationrange float Maximum distance in pixel for a small mutation (width + height) / 50.0    

Film

There is currently only one film type: fleximage

Specific Film Parameters

fleximage

A flexible film, being able to output several buffers, with some image normalization options.

Name Type Description Default value Theoretical range Suggested range
xresolution integer The number of pixels in the xdirection 800 x ≥ 1 1 - 10000
yresolution integer The number of pixels in the ydirection 600 x ≥ 1 1 - 10000
cropwindow float[4] Values describing render region that range from min (0) to max (1) in order xmin, xmax, ymin,ymax. (0,0) is top left [0.0 1.0 0.0 1.0] all values: 0 ≤ x ≤ 1  
gamma float Gamma correction value 2.2 x ≥ 0.0 0.0 ≤ x ≤ 5.0
premultiplyalpha bool Multiplies the pixel colours by the pixel's alpha value before writing the image. Used to encode alpha in images without an alpha channel false    
colorspace_red float[2] The xy chromaticity coordinates of the red primary in the target color space. Used for low dynamic range output (and OpenEXR if write_exr_applyimaging is enabled). Default color space is SMPTE. [0.63 0.34]    
colorspace_green float[2] Same as colorspace_red but for the green primary. [0.31 0.595] both values: 0.0 ≤ x ≤ 1.0 both values: 0.0 ≤ x ≤ 1.0
colorspace_blue float[2] Same as colorspace_red but for the blue primary. [0.155 0.07] both values: 0.0 ≤ x ≤ 1.0 both values: 0.0 ≤ x ≤ 1.0
colorspace_white float[2] Same as colorspace_red but for the white point. [0.314275 0.329411] both values: 0.0 ≤ x ≤ 1.0 both values: 0.0 ≤ x ≤ 1.0
write_exr bool Toggles the .exr (OpenEXR) output false    
write_exr_channels string Which channels to write for OpenEXR output. Valid values are:
  • "RGB"
  • "RGBA"
  • "Y"
  • "YA"
"RGBA" is RGB with alpha, "Y" is luminosity, and "YA" is luminosity with alpha.		 "RGB"    
write_exr_halftype bool Indicates if the half-float (16bit) type should be used for OpenEXR output. true    
write_exr_compressiontype string Which compression scheme to use for OpenEXR output. Valid values are:
  • "RLE (lossless)"
  • "PIZ (lossless)"
  • "ZIP (lossless)"
  • "Pxr24 (lossy)"
  • "None"
 "PIZ (lossless)"    
write_exr_applyimaging bool Specifies if the imaging pipeline (for tone mapping, bloom etc) should be used for OpenEXR output. Use "false" to get the raw HDR output. "true"    
write_exr_gamutclamp bool Specifies if out-of-gamut colors should be clamped for OpenEXR output. "true"    
write_exr_ZBuf bool Specifies if the Z-Buffer should be used for OpenEXR output. Will be added as a separate channel in the OpenEXR file. "false"    
write_exr_zbuf_normalizationtype string Specifies which normalization, if any, is applied to the Z-Buffer before being added to the OpenEXR file. Valid values are:
  • "Camera Start/End clip"
  • "Min/Max"
  • "None"
 "None"    
write_png bool Toggles the .png low dynamic range tonemapped output. true    
write_png_channels string Same as write_exr_channels, but for PNG output. "RGB"    
write_png_16bit bool Toggles 16 bit per channel PNG output. false    
write_png_gamutclamp bool Toggles clamping of out-of-gamut colors for PNG output. true    
write_tga bool Toggles the .tga low dynamic range tonemapped output false    
write_tga_channels string Same as write_exr_channels, but for TGA output. "RGB"    
write_tga_gamutclamp bool Toggles clamping of out-of-gamut colors for TGA output. true    
write_tga_zbuf_normalization string Same as for write_exr_zbuf_normalizationtype "None"    
ldr_clamp_method string Method used to clamp out-of-gammut colors after tonemapping. Valid values are:
  • "lum"
  • "hue"
  • "cut"
First two tries to preserve luminosity and hue, respectively, of the color. "cut" will simply clip large values.		 "lum"    
write_resume_flm bool Toggles the rendering resume output. Luxrender will auto-resume a rendering if the resume file exists.

NOTE1: the resume feature doesn't include any sanity check, do not forget to erase the file if you are starting a new rendering or you have modified the scene description. NOTE2: the resume file is usually read between 10-30 secs after the start of the rendering.

NOTE3: this feature works well only with progressive pixel samplers.		 false    
restart_resume_flm bool Disables starting from an existing flm file, whilst still writing a new one if above param is true. false    
filename string The suffix used for all file output "luxout"    
flmwriteinterval integer The interval in seconds between flm file writes 60 x ≥ 1 1 - 36000
writeinterval integer The interval in seconds between all image writes 60 x ≥ 1 1 - 36000
displayinterval integer The interval in seconds between display updates 12 x ≥ 1 1 - 36000
reject_warmup integer The minimum number of samples per pixel before rejecting samples 12 x ≥ 0 1 - 50000
outlierrejection_k integer The number of nearest neighbors to use for outlier rejection. Higher k values suppresses fireflies better, but consumes more memory and CPU, and introduces more bias. Disabled when k = 0. 0 x ≥ 0 1 - 10
haltspp integer Stop the rendering when the average number of samples per pixel is higher or equal to the chosen value.

The rendering will stop at the next valid Sampler/PixelSampler state in order to not introduce bias (i.e. few more samples can be required to reach that state).

A value less or equal to 0 disables this option.		 0 x ≥ 0 0 - 50000
halttime integer Stop the rendering when the time elapsed form the start is higher or equal to the chosen value (defined in seconds).

The rendering will stop at the next valid Sampler/PixelSampler state in order to not introduce bias (i.e. few more samples can be required to reach that state).

A value less or equal to 0 disables this option.		 0 x ≥ 0 0 - 86400
cameraresponse string Camera response file. File should contain the Camera Response Functions, see distributed CRF files. ""    
tonemapkernel string The tonemapping kernel used for low dynamic range output (and OpenEXR if write_exr_applyimaging is enabled). Valid values are:
  • "reinhard"
  • "linear"
  • "autolinear"
  • "contrast"
  • "maxwhite"
 "reinhard"    
reinhard_prescale float Used by "reinhard" tonemapper. Defines the amount of pre-scale. 1.0 x ≥ 0 0 - 8
reinhard_postscale float Used by "reinhard" tonemapper. Defines the amount of post-scale. 1.0 x ≥ 0 0 - 8
reinhard_burn float Used by "reinhard" tonemapper. Defines the amount of burn. 6.0 x ≥ 0 0 - 8
linear_sensitivity float Used by "linear" tonemapper. Sensitivity of the film (in ISO). 50.0 x ≥ 0 6 - 6400
linear_exposure float Used by "linear" tonemapper. Exposure time of the film in seconds (currently not tied to shutter opening). 1.0 x > 0 0.0005 - 60
linear_fstop float Used by "linear" tonemapper. F-stop value. 2.8 x ≥ 0 0.7 - 96
linear_gamma float Used by "linear" tonemapper. Gamma value. Separate from FlexImageFilm's gamma parameter, but should ideally be set to the same value. 1.0 x ≥ 0 0 - 5
contrast_ywa float Used by "contrast" tonemapper. The world adaption luminance, Ywa. 1.0 x > 0 0 - 20000

PixelFilter

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

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

PixelFilter Parameters

The pixel filters accept the parameters below.

box
Name Type Description Default value Theoretical range Suggested range
xwidth float Half-width (or radius) of the filter in the x direction 0.5 x > 0 0.1 - 2
ywidth float Half-width (or radius) of the filter in the y direction 0.5 x > 0 0.1 - 2
triangle
Name Type Description Default value Theoretical range Suggested range
xwidth float Half-width (or radius) of the filter in the x direction 2.0 x > 0 0.1 - 2
ywidth float Half-width (or radius) of the filter in the y direction 2.0 x > 0 0.1 - 2
gaussian
Name Type Description Default value Theoretical range Suggested range
xwidth float Half-width (or radius) of the filter in the x direction 2.0 x > 0 0.1 - 2
ywidth float Half-width (or radius) of the filter in the y direction 2.0 x > 0 0.1 - 2
alpha float Gaussian rate of falloff. Lower values give blurrier images. 2.0 x > 0 0 - 10
mitchell

In the paper by Mitchell and Netravali where this filter was introduced they suggest that the paramers B and C obey the following relation: B + 2C = 1. When using this relation low values for B will lead to a sharper image but with more pronouced ringing while higher values for B will lead to less ringing but also a more blurred result.

Name Type Description Default value Theoretical range Suggested range
xwidth float Half-width (or radius) of the filter in the x direction 2.0 x > 0 0.1 - 3
ywidth float Half-width (or radius) of the filter in the y direction 2.0 x > 0 0.1 - 3
B float B parameter for the mitchell filter 1/3 0 ≤ x ≤ 1 0 - 1
C float C parameter for the mitchell filter 1/3 0 ≤ x ≤ 1 0 - 1
supersample bool When enabled emulates 2x supersampling followed by reduction, both done using same mitchell filter. false    
sinc
Name Type Description Default value Theoretical range Suggested range
xwidth float Half-width (or radius) of the filter in the x direction 4.0 x > 0 0.1 - 5
ywidth float Half-width (or radius) of the filter in the y direction 4.0 x > 0 0.1 - 5
tau float Width of the filter window. Should not be larger than the radius of the filter. 3.0 x > 0 0.1 - 5

Accelerator

LuxRender supports the following accelerator structures.

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

Accelerator Parameters

There are no common accelerator parameters.

kdtree

Can also be called '''tabreckdtree'''. Based on the "Recursive Ray Traversal Algorithm" presented in Vlastimil Havran's thesis.

Name Type Description Default value
intersectcost integer Computational cost expected for ray-object intersections. This is used to control how the kdtree is built. 80
traversalcost integer Computational cost expected for traversing a ray through the kdtree. This is used to control how the kdtree is built. 1
emptybonus float Bonus that promotes kd-tree nodes that represent empty space. 0.5
maxprims integer Maximum number of primitives in a kdtree node before further splitting of the node occurs. 1
maxdepth integer If positive, the maximum depth of the tree. If negative this value is set automatically. -1
qbvh

This accelerator is a variant of the BVH accelerator that has 4 children per node instead of two and uses SSE instructions to traverse the tree. It uses much less memory than a kd-tree while providing an equivalent or better speed.

Name Type Description Default value
maxprimsperleaf integer The maximum number of primitives in a leaf node. 4
fullsweepthreshold integer The number of primitives that triggers partial scanning to determine the splitting plane 4 * maxprimsperleaf
skipfactor integer How many primitives will be grouped together when partial scanning is done to determine the split plane 1
grid

This accelerator is not thread-safe and must not be used with multiple rendering threads. It subdivides the scene's bounding box into uniform grid cells, with at most 64 cells in any dimension. Each cell keeps a simple list of all primitives that are contained within the cell.

This accelerator is only useful for scenes with a high number of small and uniformly distributed shapes.

Name Type Description Default value
refineimmediately bool Makes the primitive intersectable as soon as it is added to the grid. Otherwise individual shapes aren't intersectable till rays are cast and there is a ray hit with the primitive. false
unsafekdtree

This accelerator is not thread-safe and must not be used with multiple rendering threads. Otherwise identical to the regular kdtree accelerator.

Name Type Description Default value
intersectcost integer Computational cost expected for ray-object intersections. This is used to control how the kdtree is built. 80
traversalcost integer Computational cost expected for traversing a ray through the kdtree. This is used to control how the kdtree is built. 1
emptybonus float Bonus that promotes kd-tree nodes that represent empty space. 0.5
maxprims integer Maximum number of primitives in a kdtree node before further splitting of the node occurs. 1
maxdepth integer If positive, the maximum depth of the tree. If negative this value is set automatically. -1
bvh

This accelerator is not thread-safe and must not be used with multiple rendering threads. A bounding volume hierarchy based accelerator. Uses significantly less memory than a kd-tree with good speed.

Name Type Description Default value
treetype integer Tree type to generate. 2 for binary tree, 4 for quad tree, 8 for octree 4
costsamples integer Number of samples to use for cost minimization when determining optimal split plane. If < 2 use mean position as split plane. 0
intersectcost integer Computational cost expected for ray-object intersections. This is used to control how the bvh is built. 80
traversalcost integer Computational cost expected for traversing a ray through the kdtree. This is used to control how the bvh is built. 10
emptybonus float Bonus that promotes bvh nodes that represent empty space. 0.5

SurfaceIntegrator

Here are the surface integrator types.

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

Common Surface Integrator Parameters

The following parameters are common to all integrators unless specified.

Name Type Description Default value
lightstrategy string Light Strategies define how the light sources are sampled. There are several strategies available:
  • "one" - randomly pick a light to sample;
  • "all" - samples all lights and averages;
  • "auto" - choose to use "one" if there are more than 5 light sources in the scene and "all" otherwise;
  • "importance" - uses user defined light importance to pick lights to sample more;
  • "powerimp" - uses user defined light importance and light power to pick lights to sample more;
  • "allpowerimp" - uses user defined light importance and light power to pick lights to sample more. Traces at least one shadow ray per light source;
  • "logpowerimp" - uses user defined light importance and the logarithm of light power to pick lights to sample more;
Supported by all integrators except bidirectional.		 auto
shadowraycount integer Specifies the number of shadow rays traced at each intersection. Supported by the following surface integrators: directlighting, exphotonmap, path. 1

Specific Surface Integrator Parameters

These parameters are specific to surface integrators.

bidirectional
Name Type Description Default value Theoretical range
eyedepth integer The maximum length of an eye subpath 8 x > 0
lightdepth integer The maximum length of a light subpath 8 x ≥ 0
strategy string Defines how the light sources are sampled. The following strategies are available:
  • one - randomly pick a light to sample;
  • all - samples all lights and averages;
  • auto - choose to use "one" if there are more than 5 light sources in the scene and "all" otherwise;
 auto  
eyerrthreshold float The minimum probability for russian roulette eye subpath termination 0 x ≥ 0
lightrrthreshold float The minimum probability for russian roulette light subpath termination 0 x ≥ 0
path
Name Type Description Default value Theoretical range
maxdepth integer The maximum length of a path. 16 x > 0
rrstrategy string Defines the russian roulette strategy used. Can be one of the following:
  • "none" - no russian roulette is used
  • "probability" - fixed probability defined by rrcontinueprob
  • "efficiency" - adaptive probability
 efficiency  
rrcontinueprob float Continue probability for fixed probability russian roulette strategy. 0.65 0 ≤ x ≤ 1
directlighting
Name Type Description Default value Theoretical range
maxdepth integer The maximum recursion depth for reflections. 5 x > 0
exphotonmap

Photon mapping integrator. Due to its biased nature the parameters are highly scene dependent.

Name Type Description Default value Theoretical range
renderingmode string Select the rendering strategy between "directlighting" and "path". directlighting  
causticphotons integer Set the size of the caustic photonmap. 20000 x > 0
indirectphotons integer Set the size of the indirect photonmap. 200000 x > 0
directphotons integer Set the size of the direct photonmap. 200000 x > 0
radiancephotons integer Set the size of the radiance photonmap. 200000 x > 0
nphotonsused integer Maximum number of photons used in irradiance computation. 50 x > 0
maxphotondist float Maximum distance of photons included in irradiance computation. 0.5 x > 0
maxdepth integer Set the maximum number of specular bounces during rendering. 5 x > 0
maxphotondepth integer Set the maximum number of specular bounces when tracing photons. 10 x > 0
finalgather bool Used by directlighting strategy. Enables/disables final gathering. true  
finalgathersamples integer Used by directlighting strategy. Set the number of samples used during final gathering. Should be multiple of two. 32 x > 1
gatherangle float Used by final gathering. Set photon gathering angle (in degrees). 10.0 0 < x < 90
rrstrategy string Defines the russian roulette strategy used. Can be one of the following:
  • "none" - no russian roulette is used
  • "probability" - fixed probability defined by rrcontinueprob
  • "efficiency" - adaptive probability
 efficiency  
rrcontinueprob float Continue probability for fixed probability russian roulette strategy. 0.65 0 ≤ x ≤ 1
distancethreshold string Used by path strategy. Fallbacks to plain path tracing when rendering corners in order to avoid photon leaks. maxdist * 1.25 x > 0
photonmapsfile string If the file exists load the photon maps from the file otherwise save photon maps to it.    
distributedpath

Variant of the path integrator which can be optimized for faster convergence.

Name Type Description Default value Theoretical range
renderingmode string Select the rendering strategy between "directlighting" and "path". directlighting  
strategy string Strategy to use: "all" samples all lights and averages, "one" which randomly picks a light at each step, "auto" which choose to use "one" if there are more than 5 light sources in the scene and "all" otherwise. "auto"  
directsampleall bool Include diffuse direct light sample at first vertex. true  
directsamples integer The number of direct light samples to take at the eye vertex. 1 x > 0
indirectsampleall bool Include diffuse indirect light sample at first vertex. false  
indirectsamples integer The number of indirect light samples to take at the remaining vertices. 1 x > 0
diffusereflectdepth integer The maximum recursion depth for diffuse reflection ray casting. 3 x > 0
diffusereflectsamples integer The number of diffuse reflection samples to take at the eye vertex. 1 x > 0
diffuserefractdepth integer The maximum recursion depth for diffuse refraction ray casting. 5 x > 0
diffuserefractsamples integer The number of diffuse refraction samples to take at the eye vertex. 1 x > 0
directdiffuse bool Include diffuse direct light sample at first vertex. true  
indirectdiffuse bool Include diffuse indirect light sample at first vertex. true  
glossyreflectdepth integer The maximum recursion depth for glossy reflection ray casting. 2 x > 0
glossyreflectsamples integer The number of glossy reflection samples to take at the eye vertex. 1 x > 0
glossyrefractdepth integer The maximum recursion depth for glossy refraction ray casting. 5 x > 0
glossyrefractsamples integer The number of glossy refraction samples to take at the eye vertex. 1 x > 0
directglossy bool Include glossy direct light sample at first vertex. true  
indirectglossy bool Include glossy indirect light sample at first vertex. true  
specularreflectdepth integer The maximum recursion depth for specular reflection ray casting. 3 x > 0
specularrefractdepth integer The maximum recursion depth for specular refraction ray casting. 5 x > 0
diffusereflectreject bool Enable Rejection for Diffuse Reflection. false  
diffuserefractreject bool Enable Rejection for Diffuse Refraction. false  
diffusereflectreject_threshold integer The Average Threshold to reject. 10.0 x > 0
diffuserefractreject_threshold integer The Average Threshold to reject. 10.0 x > 0
glossyreflectreject bool Enable Rejection for Glossy Reflection. false  
glossyrefractreject bool Enable Rejection for Glossy Refraction. false  
glossyreflectreject_threshold integer The Average Threshold to reject. 10.0 x > 0
glossyrefractreject_threshold integer The Average Threshold to reject. 10.0 x > 0

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)

Common Volume Parameters

Here are the common parameters for volume integrators. There are no specific parameters for the volume integrators.

Name Type Description Default value Theoretical range
stepsize float The stepping distance to use along a ray while performing the ray marching algorithm 1 x > 0

Scene specific information

Geometry, materials, textures - these obviously affect the final image but have no bearing on how the scene is to be rendered. This data is given between the WorldBegin and WorldEnd statements after the global information. More on these statements and the 'Attribute' statements a little later.

The distinction between the global information and the scene specific information is not arbitrary. LuxRender processes and "locks" global information first before looking at scene specific information. This implementation would allow for view-optimized tesselation of geometry, for instance.

In addition to the identifiers described above in the Transformations section and the Attributes section the following identifiers can be included in the scene:

  • AreaLightSource
  • LightSource
  • LightGroup
  • Shape
  • PortalShape
  • Volume
  • Texture
  • Material
  • MakeNamedMaterial
  • NamedMaterial
  • MakeNamedVolume
  • Interior
  • Exterior

Each of these shall be covered in turn.



Contents

Light

General Syntax:

LightSource TYPE <parameters>

Where TYPE in one of the following:

  • area
  • distant
  • goniometric
  • infinite
  • point
  • projection
  • sky
  • spot
  • sun

There is no default type.

For convenience, it's possible to specify the sunsky light which automatically creates a sun and sky light with the same parameters.

Examples

Here are some examples of light declarations:

Type Code
Point Texture "pL" "color" "blackbody" "float temperature" [6500.0]
LightSource "point" "texture L" ["pL"] "float gain" [1.0]
Spot Texture "Spots::L" "color" "blackbody" "float temperature" [3200.00]
LightSource "spot" "point from" [0 0 0] "point to" [0 0 -1] "float coneangle" [70] "float conedeltaangle" [5]
   "texture L" ["Spots::L"] "float gain" [1.50]

Common Light Parameters

These parameters are applicable to all light plugins:

name type description default value
importance float It is part of the Rendering Hints framework. It is a user defined value > 0.0. It can be used by a light strategy as weight for choosing which light source to sample more (available since v0.7). 1.0

Specific Light Parameters

These parameters are specific to individual light plugins:

name type description default value
area::L color The color of the light. 1 1 1
area::nsamples integer The suggested number of shadow samples when computing illumination from the given light. 1
distant::L color The color of the light. 1 1 1
distant::from/to point The two points defining the light direction. Default is down the z axis. 0 0 0 and 0 0 1
goniometric::I color The color of the light 1 1 1
goniometric::mapname string The filename of the goniometric file (goniometric diagram of light distribution) no default
infinite::L color The color of the light. 1 1 1
infinite::nsamples integer The suggested number of shadow samples when computing illumination from the given light. 1
infinite::mapname string The filename of the environment map for an infinite area light. If not provided, a solid color is used. no default
point::I color The color of the light. 1 1 1
point::from point The location of the point light. 0 0 0
projection::I color The color of the light. 1 1 1
projection::fov float The field of view in terms of angular spread along the shorter image axis. 45
projection::mapname string The filename of the image to project. required - no default
sky::gain float Gain (aka scale) factor to apply to sun/skylight. 0.005
sky::nsamples integer The suggested number of shadow samples when computing illumination from the given light. 1
sky::sundir vector Direction vector of the sun. 0 0 1
sky::turbidity float Turbidity can go from 1.0 to 30+. 2-6 are most useful for clear days. 2.0
sky::aconst/bconst/cconst/dconst/econst float Perez function multiplicative constants. 1.0
spot::I color, texture The color of the light. 1 1 1
spot::from/to point Points defining the axis of the spot light. Default is down the z-axis. 0 0 0 and 0 0 1 respectively.
spot::coneangle float The angle in degrees of the spotlight cone. 30
spot::conedeltaangle float The angle at which the spotlight intensity starts to fade from the edge. 5
spot::gain float The intensity of the spot light  
sun::gain float Gain (aka scale) factor to apply to sun/skylight. 0.005
sun::nsamples integer The suggested number of shadow samples when computing illumination from the given light. 1
sun::sundir vector Direction vector of the sun. 0 0 -1
sun::turbidity float Turbidity can go from 1.0 to 30+. 2-6 are most useful for clear days. 2.0
sun::relsize float Relative size to the sun. 1.0

Shape

Here are the shape types. Each one is a separate plugin.

  • cone
  • cylinder
  • disk
  • heightfield
  • hyperboloid
  • lenscomponent
  • loopsubdiv
  • nurbs
  • paraboloid
  • plymesh
  • sphere
  • trianglemesh
  • mesh

Specific Shape Parameters

These parameters are specific to individual shape plugins. There are no common parameters.

Cone

name type description default value
cone::radius float The radius of the cone. 1.0
cone::radius2 float The radius of the cone upper face in case of a cone frustum (available since v0.7). 0.0
cone::height float The height of the cone - along the z axis 1.0
cone::phimax float The angle (degrees) swept out by the cone round its circular base 360.0

Cylinder

name type description default value
cylinder::radius float The radius of the cylinder 1.0
cylinder::zmin float The position of the bottom of the cylinder along the z axis -1.0
cylinder::zmax float The position of the top of the cylinder along the z axis 1.0
cylinder::phimax float The angle (in degrees) swept out by the cylinder 360.0

Disk

name type description default value
disk::height float The location of the disk (which is flat) along the z-axis 0.0
disk::radius float The radius to the outer rim of the disk 1.0
disk::innerradius float The radius to the inner rim of the disk - defines a "hole" in the disk 0.0
disk::phimax float The angle (degrees) swept out by the disk 360.0

Height Field

name type description default value
heightfield::nu integer Number of points in the u axis none - must be specified
heightfield::nv integer Number of points in the v axis none - must be specified
heightfield::Pz float[nu*nv] The height of each point in the grid none - must be specified

Hyperboloid

name type description default value
hyperboloid::p1 point The hyperboloid lies between p1 and p2. Here p1 defines the start of the hyperboloid 0 0 0
hyperboloid::p2 point The hyperboloid lies between p1 and p2. Here p2 defines the end of the hyperboloid 0 0 0
hyperboloid::phi float The angle (in degrees) swept out by the hyperboloid 360.0

Subdivision Surfaces

name type description default value
loopsubdiv::nlevels integer The level of subdivision applied to the base mesh 3
loopsubdiv::indices integer[n] Indices of the cage mesh - using the same format as used in the triangle primitive none - must be specified
loopsubdiv::P point[n] Vertex positions of the cage mesh - using the same format as used in the triangle primitive none - must be specified
loopsubdiv::uv float[2*n] Vertex texture coordinates of the cage mesh - using the same format as used in the triangle primitive none - optional
loopsubdiv::displacementmap string The name of a float texture to use as displacement map none - optional
loopsubdiv::dmscale float Scale the output of displacement map by the specified value (use negative value in order to invert the map) 0.1
loopsubdiv::dmoffset float Translate the output of displacement map by the specified value 0.0
loopsubdiv::dmnormalsmooth bool Interpolate normals in order to get a smooth output true
loopsubdiv::dmsharpboundary bool The output mesh will have the same boundary of the cage mesh if this flag is true, otherwise the boundary will be interpolated as well false

Lens Component

This shape is primarily used by the realistic camera. Lens are approximated by a sphere section.

name type description default value
lenscomponent::radius float The radius of the sphere 1.0
lenscomponent::zmin float The position of the bottom of the sphere along the z axis -radius
lenscomponent::zmax float The position of the top of the sphere along the z axis radius
lenscomponent::phimax float The angle (in degrees) swept out by the sphere 360.0
lenscomponent::aperture float The aperture of the lens 1.0

NURBS

name type description default value
nurbs::nu integer Sets the number of control points in the u direction none - must be specified
nurbs::nv integer Sets the number of control points in the v direction none - must be specified
nurbs::uorder integer The order (surface degree + 1) in the u direction Defines how many nearby control points affect each control point none - must be specified
nurbs::vorder integer The order (surface degree + 1) in the v direction. Defines how many nearby control points affect each control point none - must be specified
nurbs::uknots float[nu+uorder] (eg. if nu = 2 and uorder = 2 we have a float[4] such as (1,1,1,1)) The knot vector in the u direction none - must be specified
nurbs::vknots float[nv+vorder] The knot vector in the v direction none - must be specified
nurbs::u0/nurbs::v0 float The u and v coordinates from which NURB surface evaluation starts uknots[uorder-1]/vknots[vorder-1]
nurbs::u1/nurbs::v1 float The u and v coordinates from which NURB surface evaluation ends uknots[nu]/vknots[nv]
nurbs::P point[nu*nv] P specifies regular control points on the NURBS surface none - one of either P or Pw must be specified
nurbs::Pw float[4*nu*nv] Pw specifies rational control points on the surface which include a weight value for each control point none - one of either P or Pw must be specified

Paraboloid

name type description default value
paraboloid::radius float The radius of the paraboloid 1.0
paraboloid::zmin float The position of the bottom the paraboloid along the z axis 0.0
paraboloid::zmax float The position of the top the paraboloid along the z axis 1.0
paraboloid::phimax float The angle (in degrees) swept out by the paraboloid 360.0

PLY Mesh Loader

name type description default value
plymesh::filename string The .ply filename to load none
plymesh::smooth bool Toggles smoothing of the mesh faces false

Plymesh example:

AttributeBegin # Plymodel
     NamedMaterial "plymodel"
     Shape "plymesh"
     "string filename" ["c:\\blender\\models\\plymesh.ply"]
AttributeEnd

Sphere

name type description default value
sphere::radius float The radius of the sphere 1.0
sphere::zmin float The position of the bottom of the sphere along the z axis Set to - sphere::radius
sphere::zmax float The position of the top of the sphere along the z axis Set to - sphere::radius
sphere::phimax float The angle (in degrees) swept out by the sphere 360.0

Triangle Mesh

There are two types of triangle mesh: barytrianglemesh and waldtrianglemesh. Both have the same below parameters but waldtrianglemesh uses a better intersection algorithm. Using only trianglemesh defaults to the barytrianglemesh which is better tested.

name type description default value
trianglemesh::indices integer[n] An array indexing the triangles found in the P array. The three vertices of the ith triangle are given by 3i, 3i+1, 3i+2. This provides the ordering of the triangles none - must be specified
trianglemesh::P point[n] An unordered list of vertex positions in the triangle mesh. Ordered with trianglemesh::indices none - must be specified
trianglemesh::N normal[n] Per vertex normals over the triangle mesh none - optional
trianglemesh::S vector[n] Tangents given at each vertex. Tangents are perpendicular to normals none - optional (deprecated)
trianglemesh::uv float[2*n] Texture coordinates (per vertex) none - optional
trianglemesh::st float[2*n] Texture coordinates (per vertex) none - optional

Mesh

Available since v0.6.

name type description default value
mesh::N normal[n] Per vertex normals over the mesh none - optional
mesh::P point[n] An unordered list of vertex positions in the mesh. none - must be specified
mesh::acceltype string Accelerator structure to use (auto, bruteforce, grid, kdtree, none, qbvh) "auto"
mesh::displacementmap string Name of the texture used for the displacement none - optional
mesh::dmscale float Scale of the displacement (for an LDR map, this is the maximum height of the displacement in meter) 0.1
mesh::dmoffset float Offset of the displacement 0
mesh::dmnormalsmooth bool Smoothing of the normals of the subdivided faces true
mesh::dmsharpboundary bool Try to preserve mesh boundaries during subdivision false
mesh::nsubdivlevels integer Number of subdivision levels 0
mesh::quadindices integer[4*q] An array indexing the quadrilaterals found in the P array. The three vertices of the ith quadrilateral are given by 4i, 4i+1, 4i+2, 4i+3. This provides the ordering of the quadrilaterals none - must be specified
mesh::quadtype string Select the intersection routine used for quadrilaterals (quadrilateral) "quadrilateral"
mesh::subdivscheme string Subdivision algorithm (loop) "loop"
mesh::triindices integer[3*t] An array indexing the triangles found in the P array. The three vertices of the ith triangle are given by 3i, 3i+1, 3i+2. This provides the ordering of the triangles none - must be specified
mesh::tritype string Select the intersection routine used for triangles (auto, bary, wald) "auto"
mesh::uv float[2*n] Texture coordinates (per vertex) none - optional


Volume

These volume types are deprecated! Instead you should use normal shapes with Interior/Exterior defined

Here are the volume types. There is not default type.

  • exponential
  • homogenous
  • volumegrid

Common Volume Parameters

Here are the common parameters for volumes.

name type description default value
sigma_a colour The absorption cross section. 0
sigma_s colour The scattering cross section. 0
g float The phase function asymmetry parameter. 0
Le colour The volume's emission spectrum. 0
p0 point One corner of the bounding box defining the volume calculations. 0 0 0
p1 point The second corner of the bounding box defining the volume calculations. 1 1 1

Specific Volume Parameters

These parameters are specific to individual volume plugins:

name type description default value
exponential::a/b float exponential::a and exponential::b are the parameters in the ae^{-bh} formula 1
exponential::updir vector The "up" direction along which to compute height. (0,1,0)
volumegrid::nx/ny/nz integer Each of these parameters denote the number of voxels in the x,y and z directions respectively. 1
volumegrid::density float[nx*ny*nz] The array of density values. 0

Material

Here are the material types.

  • carpaint
  • glass
  • glass2
  • glossy
  • glossytranslucent
  • glossy_lossy (deprecated)
  • matte (default)
  • mattetranslucent
  • metal
  • mirror
  • mix
  • null
  • roughglass
  • shinymetal
  • scatter
  • velvet

Glossy_lossy is deprecated and should not be used. Glossy should be used instead.

Common Material Parameters

Here are the common parameters for materials. Note that float and color textures are described in the 'Texture' section.

name type description default value
bumpmap float texture The floating-point texture for use as a bump map None

Integrator Dependant Parameters

The following material parameters are available on all materials for the stated Integrators:

name type integrator description default value
compo_visible_material bool distributedpath XXX true
compo_visible_emission bool distributedpath XXX true
compo_visible_indirect_material bool distributedpath XXX true
compo_visible_indirect_emission bool distributedpath XXX true
compo_override_alpha bool distributedpath Override the alpha value in the output image for hits on this material false
compo_override_alpha_value float distributedpath Value to set alpha to when overridden 0.0

Specific Material Parameters

These parameters are specific to individual material plugins.

Car Paint

The available names for the carpaint material are:

  • "ford f8"
  • "polaris silber"
  • "opel titan"
  • "bmw339"
  • "2k acrylack"
  • "white"
  • "blue"
  • "blue matte"

Other parameters are only necessary if no name given.

name type description default value
carpaint::name string The name of the car paint model to use "ford f8"
carpaint::Kd spectrum texture Diffuse component "ford f8" data
carpaint::Ks1 / carpaint::Ks2 / carpaint::Ks3 spectrum texture Specular component of layers "ford f8" data
carpaint::R1 / carpaint::R2 / carpaint::R3 float texture Fresnel constants of layers "ford f8" data
carpaint::M1 / carpaint::M2 / carpaint::M3 float texture Microfacet roughness of layers "ford f8" data

Glass

name type description default value
glass::Kr color, texture The reflectivity of the surface [1.0 1.0 1.0]
glass::Kt color, texture Fraction of light transmitted through the surface [1.0 1.0 1.0]
glass::index float, texture The index of refraction for the glass surface 1.5
glass::cauchyb float, texture Cauchy B coefficient 0.0
glass::film float, texture The thickness in nanometers of the thin film coating (0.0 disables) on the surface 0.0
glass::filmindex float, texture The index of refraction of the thin film coating on the surface 1.5
glass::architectural bool Disables refraction during transmission, improves rendering speed with thin sheets False

Glass2

name type description default value
glass2::architectural bool Disables refraction during transmission, improves rendering speed with thin sheets False
glasss2::dispersion bool Enables chromatic dispersion. Should be used with a volume that has a fresnel texture other than "constant" False

Glossy

name type description default value
glossy::Kd color texture The coefficient of diffuse reflection 0.5
glossy::Ks color texture The coefficient of specular reflection 0.5
glossy::Ka color texture The coefficient of absorption of the coating layer 0.0
glossy::uroughness float texture The roughness of the surface in the u direction 0.1
glossy::vroughness float texture The roughness of the surface in the v direction 0.1
glossy::d float texture The depth (thickness) of the coating layer for absorption effects. (0 = disables) 0.0
glossy::index float texture IOR of the coating. 0.0

GlossyTranslucent

name type description default value
glossytranslucent::Kd color texture The coefficient of diffuse reflection 0.5
glossytranslucent::Ks color texture The coefficient of specular reflection 0.5
glossytranslucent::Kt color texture The coefficient of transmission 1.0
glossytranslucent::Ka color texture The coefficient of absorption of the coating layer 0.0
glossytranslucent::uroughness float texture The roughness of the surface in the u direction 0.1
glossytranslucent::vroughness float texture The roughness of the surface in the v direction 0.1
glossytranslucent::d float texture The depth (thickness) of the coating layer for absorption effects. (0 = disables) 0.0
glossytranslucent::index float texture IOR of the coating. 0.0
glossytranslucent::onesided bool Disable seperate coating for backface True
glossytranslucent::backface_Ks color texture The coefficient of backface specular reflection 0.5
glossytranslucent::backface_Ka color texture The coefficient of absorption of the backface coating layer 0.0
glossytranslucent::backface_uroughness float texture The roughness of the backface surface in the u direction 0.1
glossytranslucent::backface_vroughness float texture The roughness of the backface surface in the v direction 0.1
glossytranslucent::backface_d float texture The depth (thickness) of the coating layer for backface absorption effects. (0 = disables) 0.0
glossytranslucent::backface_index float texture IOR of the backface coating. 0.0

Matte

name type description default value
matte::Kd color texture The diffuse reflectivity of the surface 1.0
matte::sigma float texture The sigma parameter in the Oren-Nayer shader in degrees. Zero for pure Lambertian reflection 0.0

MatteTranslucent

name type description default value
mattetranslucent::Kr color texture The diffuse reflectivity of the surface 1.0
mattetranslucent::Kt color texture The diffuse transmitivity of the surface 1.0
mattetranslucent::sigma float texture The sigma parameter in the Oren-Nayer shader in degrees. Zero for pure Lambertian reflection 0.0
mattetranslucent::energyconserving bool Enabling forces energy conservation by making Kt = Kt*(1-Kr) (the glossytranslucent material does not have a similar flag, it acts as though it was always enabled) False

Metal

These are the possible inbuilt metal names:

  • "amorphous carbon"
  • "silver"
  • "gold"
  • "copper"
  • "aluminium"
name type description default value
metal::name string The name of the desired inbuilt metal or nkdata file. 1.0
metal::uroughness float texture Roughness of the surface in the u direction from 0 to 1. Rough surfaces have blurry highlights 0.001
metal::vroughness float texture Roughness of the surface in the v direction from 0 to 1. Rough surfaces have blurry highlights 0.001

Mirror

name type description default value
mirror::Kr color texture The reflectivity of the mirror 1.0
glass::film float texture The thickness in nanometers of the thin film coating (0.0 disables) on the surface 0.0
glass::filmindex float texture The index of refraction of the thin film coating on the surface 1.5

Mix

name type description default value
mix::namedmaterial1 string The name of the first material to mix None
mix::namedmaterial1 string The name of the second material to mix None
mix::amount float texture The value or texture to mix by 0.5

Null

The Null material takes no options.

Rough Glass

name type description default value
roughglass::Kr color texture The reflectivity of the surface 1.0
roughglass::Kt color texture Fraction of light transmitted through the surface 1.0
roughglass::uroughness float texture Roughness of the surface in the u direction from 0 to 1. Rough surfaces have blurry highlights 0.001
roughglass::vroughness float texture Roughness of the surface in the v direction from 0 to 1. Rough surfaces have blurry highlights 0.001
roughglass::index float texture The index of refraction for the glass surface 1.5
roughglass::cauchyb float texture Cauchy B coefficient 0.0

Shiny Metal

name type description default value
shinymetal::uroughness float texture Roughness of the surface in the u direction from 0 to 1. Rough surfaces have blurry highlights 0.001
shinymetal::vroughness float texture Roughness of the surface in the v direction from 0 to 1. Rough surfaces have blurry highlights 0.001
shinymetal::Ks color texture The coefficient of glossy reflection 1.0
shinymetal::Kr color texture The coefficient of specular reflection 1.0
shinymetal::film float texture The thickness in nanometers of the thin film coating (0.0 disables) on the surface 0.0
shinymetal::filmindex float texture The index of refraction of the thin film coating on the surface 1.5

Scatter

name type description default value
scatter::Kd color texture Color of the material 1.0
scatter:g float texture Value from -1 to 1.0 that sets the asymmetry of the scattering 0.0

Velvet

name type description default value
velvet::Kd color texture Color of the material's fuzz 1.0
velvet:thickness float texture Height of the fuzz 0.10
velvet:p1 float texture Polynomial that influences the fuzz -2.0
velvet:p2 float texture Polynomial that influences the fuzz 20.0
velvet:p3 float texture Polynomial that influences the fuzz 2.0

Texture

General Syntax

	Texture NAME color|float|spectrum TYPE <values>

Where NAME is a quoted string, and TYPE is one of the types listed below. The second parameter for a texture denotes if this texture defines values of type color, float or spectrum.

Textures are declared differently from what we have seen so far. An example of a texture declaration is: 

	Texture "checks" "color" "checkerboard"

'checks' is the name given by the user to the texture. This name is arbitrarily chosen by the user to refer to in the material declaration. In order to tell a "matte" material to use a checkerboard texture for diffuse reflectivity, in this example you would type: 

	Material "matte" "texture Kd" "checks"

Again, note that you refer to a texture, you type "texture param" "name" where param is the parameter you want the texture to modulate and name is the name you have assigned the texture. color refers to the texture type which can be "color" or "float". Note the US English spelling of the word.

Texture Types

There is no default texture type. The texture types are:

Type Description
band "Gradient" texture
bilerp  !TBD
blackbody Definition of the color temperature expressed in Kelvin. For example:
Texture "LampTemp" "color" "blackbody" "float temperature" [6500]
checkerboard A checkerboard. Useful to visualize the geometry flow.
constant A constant value for a color, expressed in [r g b], for example:
Texture "SolidColor" "color" "constant" "color value" [1.000 0.910 0.518]
dots  !TBD
fbm  !TBD
imagemap A texture defined with an external image.
marble Procedural marble.
mix A mix of two textures based on a third value that can be either a constant or bitmap-based.
multimix A mix of several textures based on a "weight table"
scale Used to mix (multiply) a bitmap with a color or another texture.
uv  !TDB
windy  !TBD
wrinkled  !TBD
blender_clouds Blender clouds procedural noise.
blender_musgrave Blender Musgrave procedural noise.
blender_marble Blender Marvbble procedural noise.
blender_wood Blender Wood procedural noise.

Common Texture Parameters (2D)

Only 2D textures share any parameters: these are 'bilerp','imagemap','uv','checkerboard' and 'dots'. Note that checkerboard can also be a 3D texture and that u,v coordinates are used.

name type description default value
mapping string Texture mapping to use. Can be "uv", "spherical","cylindrical" or "planar". "uv"
uscale/vscale float The scaling of the u/v texture coordinates. Only applies to "uv" mapping. 1
udelta/vdelta float u/v offset for "planar" or "uv" texture mappings. 1
v1/v2 vector The two vectors that define the plane for "planar" mapping (1,0,0) and (0,1,0) respectively

Common Texture Paramaters (3D)

name type description default value
translate vector Translate transformation for 3D texture space 0 0 0
rotate vector Rotate transformation for 3D texture space 0 0 0
scale vector Scale transformation for 3D texture space 1 1 1

Specific Texture Parameters

These parameters are specific to individual texture plugins:

name type description default value
constant::value color/float texture The constant value of this texture. 1
scale::tex1/tex2 color/float texture The textures to multiply by the "scale" texture 1
mix::tex1/tex2 color/float texture The two textures (of the same type) to mix with the "mix" texture. 0 and 1 respectively
mix::amount float texture The degree of mix between the two textures while linearly interpolating between them. 0.5
bilerp::v00/v01/v10/v11 color/float Four values to bilinearly interpolate between. 0,1,0 and 1 respectively
imagemap::filename string Path to the OpenEXR image to use. Required. No default.
imagemap::gain float Gain (brightness) for the texture. 1.0
imagemap::gamma float Gamma correction default probably at 1.0
imagemap::wrap string How to wrap the texture using "repeat", "black" (black beyond texture) or "clamp" (clamps to border color) Required. No default.
imagemap::maxanisotropy float The eccentricity of the ellipse used in the EWA algorithm 8
imagemap::trilinear bool Toggle trilinear filtering on from the default (better but slower) EWA algorithm. false
imagemap::filtertype string one of: "bilinear", "mipmap_trilinear", "mipmap_ewa", "nearest". "bilinear"
imagemap::channel string one of: "mean", "red", "green", "blue","alpha", "colored_mean". "mean"
checkerboard::dimension integer Specifies whether a 2D or 3D checkerboard texture is being used. Values can be either 2 or 3. Defaults to 2.
checkerboard::tex1/tex2 color/float texture The texture to use for even/odd squares of the checkerboard. 1 and 0 respectively
checkerboard::aamode color/float texture For 2D checkerboard only - the antialiasing mode to use: "closedform","supersample" or "none". "closedform"
dots::inside/outside color/float texture The colour or the dots/their background. 1 and 0 respectively
fbm::octaves integer The number of octaves to use in the spectrum. 8
fbm::roughness float The "bumpiness" of the texture. 0.5
wrinkled::octaves integer The number of octaves of to use in the spectrum. 8
wrinkled::roughness float The "bumpiness" of the texture. 0.5
marble::octaves integer The number of octaves to use in the spectrum. 8
marble::roughness float The "bumpiness" of the texture. 0.5
marble::scale float Scaling factor for the noise input. 1
marble::variation float moderates perturbation magnitude 0.2

Blender procedural textures emulation

LuxRender includes some code imported (indeed with author's permission) form the Blender sources in order to emulate Blender procedural textures. The list is of supported textures is:

  • blender_clouds
  • blender_musgrave
  • blender_marble
  • blender_wood

A usage example: 

Texture "mat_proc::col1" "color" "constant" "color value" [1.0 1.0 1.0]
Texture "mat_proc::col2" "color" "constant" "color value" [1.0 0.0 0.0]
Texture "mat_proc::blender_musgrave" "float" "blender_musgrave"
Texture "mat_proc::mix" "color" "mix" "texture tex1" ["mat_proc::col1"] "texture tex2" ["mat_proc::col2"] "texture amount ["mat_proc::blender_musgrave"]
Texture "mat_proc::Kd.scale" "color" "scale" "texture tex1" ["mat_proc::mix"] "color tex2" [0.900000 0.900000 0.900000]
MakeNamedMaterial "mat_proc" "string type" ["matte"] "texture Kd" ["mat_proc::Kd.scale"] "float sigma" [0.000000] "float bumpmap" [0.000000]

Texture: blender_clouds

name type description default value
type string Color type. One of: 'default', 'color' default
noisetype string Noise type. One of: 'soft_noise', 'hard_noise' soft_noise
noisebasis string Noise basis type. One of: 'blender_original', 'original_perlin', 'improved_perlin', 'voronoi_f1', 'voronoi_f2', 'voronoi_f3', 'voronoi_f4', 'voronoi_f2f1', 'voronoi_crackle', 'cell_noise' blender_original
noisesize float 0.25
noisedepth integer 2
bright float Brightness 1.0
contrast float 1.0

Texture: blender_musgrave

In order to select this kind of texture in Blender use Blender Texture Button(F6) -> Texture -> Texture Type = Musgrave

name type description default value
blender_musgrave::h float Blender Texture Button(F6) -> Musgrave -> H 1.0
blender_musgrave::lacu float Blender Texture Button(F6) -> Musgrave -> Lacu 2.0
blender_musgrave::octs float Blender Texture Button(F6) -> Musgrave -> Octs 2.0
blender_musgrave::gain float Blender Texture Button(F6) -> Musgrave -> (Ridget Multifractal, Hybrid Multifractal) Gain 1.0
blender_musgrave::offset float Blender Texture Button(F6) -> Musgrave -> (Ridget Multifractal, Hybrid Multifractal, Hetero Terrain) Ofst 1.0
blender_musgrave::noisesize float Blender Texture Button(F6) -> Musgrave -> NoiseSize 0.25
blender_musgrave::outscale float Blender Texture Button(F6) -> Musgrave -> iScale 1.0
blender_musgrave::type string Blender Texture Button(F6) -> Musgrave -> Type (valid values: multifractal, ridged_multifractal, hybrid_multifractal, hetero_terrain, fbm) multifractal
blender_musgrave::noisebasis string Blender Texture Button(F6) -> Musgrave -> Type (valid values: blender_original, original_perlin, improved_perlin, voronoi_f1, voronoi_f2, voronoi_f3, voronoi_f4, voronoi_f2f1, voronoi_crackle, cell_noise) blender_original
blender_musgrave::bright float Blender Texture Button(F6) -> Colors -> Bright 1.0
blender_musgrave::contrast float Blender Texture Button(F6) -> Colors -> Contrast 1.0

Texture: blender_marble

In order to select this kind of texture in Blender use Blender Texture Button(F6) -> Texture -> Texture Type = Marble

name type description default value
blender_marble::noisesize float Blender Texture Button(F6) -> Marble -> NoiseSize 0.25
blender_marble::noisedepth integer Blender Texture Button(F6) -> Marble -> NoiseDepth 2
blender_marble::turbulance float Blender Texture Button(F6) -> Marble -> Turbulence 5.0
blender_marble::type string Blender Texture Button(F6) -> Marble -> Soft/Sharp/Sharper (valid values: soft, sharp, sharper) soft
blender_marble::noisetype string Blender Texture Button(F6) -> Marble -> Soft Noise/Hard Noise (valid values: soft_noise, hard_noise) hard_noise
blender_marble::noisebasis string Blender Texture Button(F6) -> Marble -> Sin/Saw/Tri (valid values: sin, saw, tri) sin
blender_marble::noisebasis2 string Blender Texture Button(F6) -> Marble -> Type (valid values: blender_original, original_perlin, improved_perlin, voronoi_f1, voronoi_f2, voronoi_f3, voronoi_f4, voronoi_f2f1, voronoi_crackle, cell_noise) blender_original
blender_marble::bright float Blender Texture Button(F6) -> Colors -> Bright 1.0
blender_marble::contrast float Blender Texture Button(F6) -> Colors -> Contrast 1.0

Texture: blender_wood

name type description default value
type string Color type. One of: 'bands', 'rings', 'bandnoise', 'ringnoise' bands
noisetype string Noise type. One of: 'soft_noise', 'hard_noise' soft_noise
noisebasis string Noise basis type. One of: 'blender_original', 'original_perlin', 'improved_perlin', 'voronoi_f1', 'voronoi_f2', 'voronoi_f3', 'voronoi_f4', 'voronoi_f2f1', 'voronoi_crackle', 'cell_noise' blender_original
noisebasis2 string One of: 'sin', 'saw', 'tri' sin
noisesize float 0.25
turbulence float 5.0
bright float Brightness 1.0
contrast float 1.0
Retrieved from "http://www.luxrender.net/wiki/Scene_file_format_0.8"