From LuxRender Wiki

Contents 1 Introduction 2 Basics 2.1 Global vs Scene Specific Information 2.1.1 Global information 2.1.2 Scene specific information 2.1.3 Components of a .lxs file 2.1.4 Importance of parameter types 3 Transformations 4 Attributes 5 Identifiers 5.1 Camera 5.1.1 Common Camera Parameters 5.1.2 Specific Camera Parameters 5.1.2.1 perspective 5.1.2.2 realistic 5.2 Sampler 5.2.1 Samplers Parameters 5.2.1.1 random 5.2.1.2 lowdiscrepancy 5.2.1.3 metropolis 5.2.1.4 erpt 5.3 Film 5.3.1 Specific Film Parameters 5.3.1.1 fleximage 5.3.2 Tonemapper Parameters 5.3.2.1 reinhard 5.4 Filter 5.4.1 Common Filter Parameters 5.4.2 Specific Filter Parameters 5.5 Shape 5.5.1 Specific Shape Parameters 5.5.1.1 Cone 5.5.1.2 Cylinder 5.5.1.3 Disk 5.5.1.4 Height Field 5.5.1.5 Hyperboloid 5.5.1.6 Subdivision Surfaces 5.5.1.7 Lens Component 5.5.1.8 NURBS 5.5.1.9 Paraboloid 5.5.1.10 PLY Mesh Loader 5.5.1.11 Sphere 5.5.1.12 Triangle Mesh 5.5.1.13 Mesh 5.6 Accelerators 5.6.1 Specific Accelerator Parameters 5.6.1.1 Grid 5.6.1.2 Kdtree 5.6.1.3 Unsafe Kdtree 5.7 Materials 5.7.1 Common Material Parameters 5.7.2 Specific Material Parameters 5.7.2.1 Car Paint 5.7.2.2 Glass 5.7.2.3 Glossy 5.7.2.4 Matte 5.7.2.5 MatteTranslucent 5.7.2.6 Metal 5.7.2.7 Mirror 5.7.2.8 Mix 5.7.2.9 Null 5.7.2.10 Rough Glass 5.7.2.11 Shiny Metal 5.8 Texture 5.8.1 Texture Types 5.8.1.1 Common Texture Parameters (2D) 5.8.1.2 Common Texture Paramaters (3D) 5.8.1.3 Specific Texture Parameters 5.8.1.4 Blender procedural textures emulation 5.8.1.4.1 Texture: blender_clouds 5.8.1.4.2 Texuture: blender_musgrave 5.8.1.4.3 Texuture: blender_marble 5.8.1.4.4 Texture: blender_wood 5.9 Volume 5.9.1 Common Volume Parameters 5.9.2 Specific Volume Parameters 5.10 Light 5.10.1 Specific Light Parameters 5.11 Surface Integrator 5.11.1 Specific Surface Integrator Parameters 5.11.1.1 Bidirectional 5.11.1.2 Directlighting 5.11.1.3 Exphotonmap 5.11.1.4 Particletracing 5.11.1.5 Path 5.11.1.6 DistributedPath 5.12 Volume Integrator 5.12.1 Common Volume Parameters

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. 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" "color" "checkerboard"
		"float uscale" [4] "float vscale" [4]
		"color tex1" [1 0 0] "color tex2" [0 0 1]

	Material "matte"
		"texture Kd" "checks"
	Shape "disk" "float radius" [20] "float height" [-1]
AttributeEnd

WorldEnd

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.

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 you to tessellate geometry based on what is viewed from the camera, for instance.

Components of a .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:

• integer: a whole number (eg. 1, 2, 3 ...)
• float: a number with a decimal point (eg. [1.67],[2.54] ...). float[4] = (0,1,1,1) float[4] = (0,1,0,1) Note the square brackets given round the values.
• point - eg (0 0 0, 1 1 1)
• vector - for example: [45.000000 0.000000 0.000000]
• normal - will give example
• color - for example: [0.890187 0.845693 0.664541]
• bool: only two possibilities - "true" and "false"
• string: a name given in quotes such as filenames (eg. "simple.exr", "pbrt.exr").

Transformations

• rotate

Rotate will rotate an entity a given number of degrees around a given vector. example: "rotate 180.1 0 1 0" will rotate around the y-axis 180.1°

• scale

Scale will adjust the size of an entity by a given factor. example: "scale .1 .2 .3" will scale in the x-direction to 10%, the y-direction to 20%, and the z-direction to 30%

• translate

Translate will move an entity in a given direction by a vector. example: "translate 10.1 20.2 30.3" will move the center 10.1 units in the x-direction, 20.2 in the y-direction, and 30.3 in the z-direction

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.

• ObjectBegin

The ObjectBegin attribute indicates the beginning of the description of a named object, which is useful for creating instances. Its only parameter is the object name:

name	type	description	default value
name	string	the name of the object	none - must be specified

• 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:

name	type	description	default value
ObjectInstance	string	the name of an object	none - a named object must be chosen

Identifiers

The following identifiers can be included in the scene:

• Camera
• Sampler
• Film
• PixelFilter
• Shape
• Accelerator
• Material
• Texture
• Volume
• Light
• SurfaceIntegrator
• VolumeIntegrator

Each of these shall be covered in turn.

Camera

The following camera types are available. Each of them is a plugin. The default camera type is 'perspective'.

• perspective (default)

the most common camera, resemble most closely what is seen by the human eye

• 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

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
hither	float	Geometry closer than this distance will not be rendered	10 − 3
yon	float	Geometry further than this distance will not be rendered	1030
shutteropen	float	The time in seconds at which the virtual shutter opens	0.0
shutterclose	float	The time in seconds at which the virtual shutter closes	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
focaldistance	float	Focal distance of the virtual lens. Use the control focus in depth of field effects. Ignored by environment and realistic cameras	1030
frameaspectratio	float	this is normally computed from resolution but can be overridden here. Ignored by realistic camera	computed from given resolution
screenwindow	float[4]	Specifies area in camera that the virtual film occupies - the bounds in screen space. Ignored by realistic camera	Normally covers whole of screenspace

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
perspective: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)	90
perspective: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

realistic

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

Sampler

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

• random (default)

Completely random sampler

• lowdiscrepancy

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

• metropolis

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

• erpt

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

Samplers Parameters

These samplers accept the parameters below. Valid values for pixelsampler are hilbert (since v0.6), linear, vegas, lowdiscrepancy, tile (or alias grid), and random.

NOTE: grid pixel sampler is mainly intended for long run rendering with Multi-thread & Network rendering support. 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

name	type	description	default value
random::pixelsamples	integer	Number of samples per pixel / pass	4
random::pixelsampler	string	Pixel sampler algorithm to use	vegas

lowdiscrepancy

name	type	description	default value
lowdiscrepancy::pixelsamples	integer	Number of samples per pixel / pass	4
lowdiscrepancy::pixelsampler	string	Pixel sampler algorithm to use	vegas

metropolis

name	type	description	default value
metropolis::initsamples	integer	Number of warm-up samples	100000
metropolis::maxconsecrejects	integer	Number of consecutive rejects before a next mutation is forced. Low values can cause bias	512
metropolis::largemutationprob	float	Probability of generating a large sample mutation	0.4f
metropolis::micromutationprob	float	Probability of generating mutations on a small subset of samples	0.f
metropolis::mutationrange	float	Maximum distance in pixel for a small mutation
metropolis::usevariance	bool	Use the variance hint provided by some integrators to alter sample acceptance	false

erpt

name	type	description	default value
erpt::initsamples	integer	Number of warm-up samples	100000
erpt::chainlength	integer	Number of mutations from a given seed	2000
erpt::mutationrange	float	Maximum distance in pixel for a small mutation

Film

There is currently only one film type:

• fleximage (default)

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

Specific Film Parameters

fleximage

name	type	description	default value
xresolution	integer	The number of pixels in the xdirection	800
yresolution	integer	The number of pixels in the ydirection	600
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,1,0,1)
gamma	float	Gamma correction value	2.2
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	true
write_tonemapped_exr	bool	Toggles the .exr high dynamic range tonemapped output	true
write_untonemapped_exr	bool	Toggles the .exr high dynamic range raw output	false
write_tonemapped_igi	bool	Toggles the .igi high dynamic range tonemapped output	false
write_untonemapped_igi	bool	Toggles the .igi high dynamic range raw output	false
write_tonemapped_tga	bool	Toggles the .tga low dynamic range tonemapped output	false
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 progrsive 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"
writeinterval	integer	The interval in seconds between all image writes	60
displayinterval	integer	The interval in seconds between display updates	12
reject_warmup	integer	The minimum number of samples per pixel before rejecting samples	12
haltspp	integer	It will stop the rendering when the average number of samples per pixel is higher than 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 equals or less than 0 disable this option.	0

Tonemapper Parameters

Fleximage uses "reinhard" as the tonemapper. It accepts the following parameters:

reinhard

name	type	description	default value
reinhard_prescale	float	Defines the amount of pre-scale	1.0
reinhard_postscale	float	Defines the amount of post-scale	1.0
reinhard_burn	float	Defines the amount of burn	6.0

Filter

Here are the filter types. Each one is a separate plugin:

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

Common Filter Parameters

Here are the common parameters for filters.

name	type	description	default value
xwidth	float	Width of the filter in the x direction	2
ywidth	float	Width of the filter in the y direction	2

Specific Filter Parameters

These parameters are specific to individual filter plugins:

name	type	description	default value
box::xwidth / box::ywidth	float	The size of the box filter. 0.5 is measured from the center, so the default is one pixel's worth of area.	0.5
gaussian::alpha	float	Gaussian rate of falloff. Lower values give blurrier images.	2
mitchell::B / mitchell::C	float	Specify the shape of the Mitchell filter. Often best result is when B + 2C = 1	1/3
sinc::tau	float	Permitted number of cycles of the sinc function before it is clamped to zero.	3
sinc:xwidth / sinc:ywidth	float	The area over which the sinc function operates. Works well with large areas.	4

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

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, 3(i+1), 3(i+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	float	Per vertex normals over the triangle mesh	none - optional
trianglemesh::S	vector	Tangents given at each vertex. Tangents are perpendicular to normals	none - optional
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::P	point[n]	An unordered list of vertex positions in the mesh.	none - must be specified
mesh::N	float	Per vertex normals over the mesh	none - optional
mesh::UV	float[2*n]	Texture coordinates (per vertex)	none - optional
mesh::tritype	string	Select the intersection routine used for triangles: "wald" or "bary"	wald
mesh::triindices	integer[n]	An array indexing the triangles found in the P array. The three vertices of the ith triangle are given by 3i, 3(i+1), 3(i+2). This provides the ordering of the triangles	none - must be specified
mesh::quadtype	string	Select the intersection routine used for quadrilaterals: "quadrilateral"	quadrilateral
mesh::quadindices	integer[n]	An array indexing the quadrilaterals found in the P array. The three vertices of the ith quadrilateral are given by 4i, 4(i+1), 4(i+2), 4(i+3). This provides the ordering of the quadrilaterals	none - must be specified

Accelerators

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

• grid
• tabreckdtree or kdtree (default)
• unsafekdtree
• none

Specific Accelerator Parameters

These parameters are specific to individual accelerator plugins. There are no common parameters:

Grid

name	type	description	default value
grid::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

Kdtree

name	type	description	default value
kdtree::intersectcost	integer	Parameter that specifies how computationally expensive ray-object intersections are expected to be. This is used to control the kdtree built.	80
kdtree::traversalcost	integer	Computational cost expected for traversing a ray through the kdtree	1
kdtree::emptybonus	float	Promotes kd-tree nodes that represent empty space.	0.5
kdtree::maxprims	integer	Maximum number of primitives in a kdtree volume before further splitting of the volume occurs.	1
kdtree::maxdepth	integer	If positive, the maximum depth of the tree. If negative this value is set automatically.	-1

Unsafe Kdtree

This accelerator is not thread-safe and so its use should be avoided.

name	type	description	default value
unsafekdtree::intersectcost	integer	Parameter that specifies how computationally expensive ray-object intersections are expected to be. This is used to control the kdtree built.	80
unsafekdtree::traversalcost	integer	Computational cost expected for traversing a ray through the kdtree	1
unsafekdtree::emptybonus	float	Promotes kd-tree nodes that represent empty space.	0.5
unsafekdtree::maxprims	integer	Maximum number of primitives in a kdtree volume before further splitting of the volume occurs.	1
unsafekdtree::maxdepth	integer	If positive, the maximum depth of the tree. If negative this value is set automatically.	-1

Materials

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

• carpaint
• glass
• glossy
• matte (default)
• mattetranslucent
• metal
• mirror
• mix
• null
• roughglass
• shinymetal

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

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
glass::Kt	color texture	Fraction of light transmitted through the surface	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

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

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
matte::Kr	color texture	The diffuse reflectivity of the surface	1.0
matte::Kt	color texture	The diffuse transmitivity 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

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
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
shinymetal::Ks	color texture	The coefficient of glossy reflection	1.0
shinymetal::Kr	color texture	The coefficient of specular reflection	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

Texture

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:

• bilerp
• checkerboard
• constant
• dots
• fbm
• imagemap
• marble
• mix
• scale
• uv
• windy
• wrinkled
• blender_clouds
• blender_musgrave
• blender_marble
• blender_wood

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	colour/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	colour/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::wrap	string	How to wrap the texture using "repeat", "black" (black beyond texture) or "clamp" (clamps to border colour)	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
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	colour/float texture	The texture to use for even/odd squares of the checkerboard.	1 and 0 respectively
checkerboard::aamode	colour/float texture	For 2D checkerboard only - the antialiasing mode to use: "closedform","supersample" or "none".	"closedform"
dots::inside/outside	colour/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

Texuture: 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

Texuture: 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

Volume

Here are the volume types. Each one is a separate plugin. 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

Light

Here are the light types. Each one is a separate plugin. There is no default type.

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

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

Specific Light Parameters

These parameters are specific to individual light plugins. There are no common parameters:

name	type	description	default value
area::L	colour	The colour 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	colour	The colour 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	colour	The colour of the light	1 1 1
goniometric::mapname	string	The filename of the goniometric file (goniometric diagram of light distribution)	no default
infinite::L	colour	The colour 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 colour is used.	no default
point::I	colour	The colour of the light.	1 1 1
point::from	point	The location of the point light.	0 0 0
projection::I	colour	The colour 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	colour	The colour 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
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

Surface Integrator

Here are the surface integrator types. Each one is a separate plugin.

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

Specific Surface Integrator Parameters

These parameters are specific to surface integrator plugins. There are no common parameters.

Bidirectional

name	version	type	description	default value
bidirectional::eyedepth	0.5	integer	The maximum length of an eye subpath	8
bidirectional::lightdepth	0.5	integer	The maximum length of a light subpath	8

Directlighting

name	version	type	description	default value
directlighting::maxdepth	0.5	float	The maximum recursion depth for ray casting.	5
directlighting::strategy	0.5	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"

Exphotonmap

name	version	rendering mode	type	description	default value
exphotonmap::renderingmode	0.6	directlighting/path	string	Select the rendering strategy between "directlighting" (v0.5 rendering mode) and a new mode "path" (available since v0.6).	"directlighting"
exphotonmap::strategy	0.5	directlighting/path	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"
exphotonmap::causticphotons	0.5	directlighting/path	integer	Set the size of the caustic photonmap.	20000
exphotonmap::indirectphotons	0.5	directlighting/path	integer	Set the size of the indirect photonmap.	200000
exphotonmap::maxdirectphotons	0.5 (removed in 0.6)	directlighting/path	integer	Set the maximum number of the direct photon traced.	1000000
exphotonmap::directphotons	0.6	directlighting/path	integer	Set the size of the direct photonmap.	200000
exphotonmap::radiancephotons	0.6	directlighting/path	integer	Set the size of the radiance photonmap.	200000
exphotonmap::nused	0.5	directlighting/path	integer	Set the number of photon used in irradiance computation.	50
exphotonmap::maxdepth	0.5	directlighting/path	integer	Set the maximum number of specular bounces.	5
exphotonmap::finalgather	0.5	directlighting	bool	Enables/disable final gather step.	true
exphotonmap::finalgathersamples	0.5	directlighting	integer	Set the number of samples used in the final gather step.	32
exphotonmap::maxdist	0.5	directlighting/path	float	Set the maximum distance of photon included in irradiance computation.	0.5
exphotonmap::gatherangle	0.5	directlighting	float	Set photon gathering angle.	10.0
exphotonmap::strategy	0.6	directlighting/path	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"
exphotonmap::gatherrrstrategy	0.6	directlighting	string	Russian roulette strategy to use: "efficiency", "probability", "none" .	efficiency
exphotonmap::gatherrrcontinueprob	0.6	directlighting	string	Russian roulette continue probability. Used when strategy "probability".	0.65
exphotonmap::mapsfile	0.6	directlighting/path	string	If the file exists load the photon maps from the file otherwise save maps to it.	None
exphotonmap::distancethreshold	0.6	path	string	Fallbacks to path tracing when rendering corners in order to avoid photon leaks. Enabled by default.	Same value of maxdist

Particletracing

name	version	type	description	default value
particletracing::maxdepth	0.5	integer	The maximum length of a path.	5
particletracing::rrcontinueprob	0.5	float	Russian roulette probability of not terminating a path.	0.65

Path

name	version	type	description	default value
path::maxdepth	0.5	integer	The maximum length of a path.	16
path::strategy	0.5	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"

DistributedPath

name	version	type	description	default value
path::diffusedepth	0.5	integer	The maximum length of a diffuse path.	3
path::glossydepth	0.5	integer	The maximum length of a glossy path.	2
path::speculardepth	0.5	integer	The maximum length of a specular path.	5
path::strategy	0.5	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"

Volume Integrator

Here are the volume integrator types. Each one is a separate plugin.

• emission (default)
• single

Common Volume Parameters

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

name	type	description	default value
stepsize	float	The stepping distance to use along a ray while performing the ray marching algorithm	1