Indigo Renderer Manual

Scene xml format

Root element should be called 'scene'.

renderer_settings

This element provides a means of overriding various settings from inifile.txt. This element is optional, and so are each of its children. Any setting defined here overrides the respective setting from inifile.txt. See inifile.txt for an explanation of each setting.

The following settings can be set here: width, height, metropolis, large_mutation_prob, max_change, russian_roulette_live_prob, max_depth, strata_width, logging.

example:

<renderer_settings>
	<width>300</width>
	<height>225</height>
	
	<metropolis>true</metropolis>
	<large_mutation_prob>0.2</large_mutation_prob>
	<max_change>0.025</max_change>
	<russian_roulette_live_prob>0.7</russian_roulette_live_prob>
	<max_depth>1000</max_depth>
	<strata_width>14</strata_width>
	<logging>true</logging>
</renderer_settings>

Background light

Illuminates scene with a uniform environment light. Disabled if skylight is defined.

radiance

RGB Colour is defined in the radiance element.

example:

<background>
	<radiance>0 0.2 0.2</radiance>
</background>

Skylight

Illuminates scene with sunlight and scattered skylight.

sundir

The sundir element defines the 3-vector direction towards the sun. the Z axis is up, e.g. (0,0,1) places the sun directly overhead.

turbidity

The turbidity defines the haziness/clearness of the sky. Lower turbidity means a clearer sky. Should be set to something between 2 and ~5.

example:

<skylight>
	<sundir>0 1 1</sundir>
	<turbidity>2.0</turbidity>
</skylight>

Tonemapping

The tonemapping element should have one child element, either 'linear' or 'reinhard'.

tonemapping :: linear

tonemapping :: linear :: scale

A constant by which the pixel values are multiplied.

tonemapping :: reinhard

tonemapping :: reinhard :: pre_scale

The pixel buffer is scaled by this factor before the non-linear stage of the tonemapping takes place. Stands in for the middle-grey luminance scaling in part 3.1 of Reinhard et. al.'s Photographic Tone Reproduction for Digital Images paper.

tonemapping :: reinhard :: post_scale

This scaling factor is applied after the rest of the tone mapping stages. By default, the pixel with max luminance is mapped to white, so setting this scale to > 1 will result in pixels with less luminance being mapped to white. example:
<tonemapping>
	<reinhard>
		<pre_scale>1.0</pre_scale>
		<post_scale>1.0</post_scale>
	</reinhard>
</tonemapping>

Camera

pos

Defines the position of the camera.

up

Defines the up vector of the camera. This and the forwards vector uniquely determine the right vector. Need not be normalised.

forwards

Defines the forwards vector of the camera, i.e. which direction it is facing. Need not be normalised.

lens_radius

For depth of field. Defines the radius of the camera lens, or the radius of the camera aperture. Larger radius means more depth of field. A reasonable value if the units are meters is 0.02 (2cm)

focus_distance

Distance from the camera at which objects will be in focus. Has no effect if lens_radius is 0.

aspect_ratio

Influences the directions in which rays are traced. Should be set to the image width divided by the image height.

angle_of_view

The angle subtended by the viewable portion of the scene, in the horizontal direction. For example, an AOV of 90 means the cam can see 45 degrees to the left of the forwards direction and 45 degrees right. Units are degrees.

Camera element example:

<camera>
	<pos>-0.3 -4.2 0.9</pos>
	<up>0 0 1</up>
	<forwards>0.2 1 0.2</forwards>
		
	<lens_radius>0.02</lens_radius>
	<focal_length>2.0</focal_length>
	<aspect_ratio>1.33</aspect_ratio>
	<angle_of_view>120</angle_of_view>
</camera>

Materials


Diffuse

Diffuse is a lambertian diffuse material.

colour

Sets the RGB reflectance. All components should be in the range [0, 1)

example:

<diffuse>
	<colour>0.8 0.8 0.8</colour>
</diffuse>

Specular

Specular is a material that can be both a perfect specular reflector and a perfect specular transmitter.

normal_reflectance

Reflectance at normal incidence. Should be in range [0, 1). For example, glass has normal reflectance ~ 0.04. Specular reflection at grazing incidence will automatically approach 1.0 due to Fresnel effect.

transparent

true or false. If true, light can be transmitted, if not, only reflected light is simulated.

ior

Index of refraction. Should be >= 1. Glass is about 1.5.

cauchy_b_coeff

Sets the 'b' coefficient in Cauchy's equation, which is used in Indigo to govern dispersive refraction. Units are micrometers squared. Setting to 0 disables dispersion. Note: the render can be slower to converge when dispersion is enabled, because each ray refracted through a dispersive medium can represent just one wavelength. So only set cauchy_b_coeff != 0 if you really want to see dispersion :)

rgb_absorptivity

The transmittance code in Indigo is based roughly on Beer's law. See http://scienceworld.wolfram.com/physics/BeersLaw.html for an explanation.

The absorptivity specified in the xml file defines the absorptivity for light in the red, green and blue 'bands'. The units I'm using are cm^-1, because this seems to be the convention. I'm not taking into account molar concentration. The equation for light transmission I'm using are thus

I = Ii * exp(-l*a)

where I is the transmitted intensity, Ii is the incident intensity, l is the distance travelled through the medium in cm, and a is the absorptivity for the given wavelength.

So for example, if you set a = 0, then you get I = Ii * exp(0) = Ii, i.e. none of the light is absorbed. Setting a high 'a' results in the light for that wavelength being absorbed very quickly as it passes through the material. So to make a pink glass, try something like

<rgb_absorptivity>0 0.003 0.003<rgb_absorptivity>
this lets all red light through, but absorbs a little green and blue, thereby giving the glass a slight pink tint.

example:

<specular>
	<normal_reflectance>0.05</normal_reflectance>
	<transparent>true</transparent>
	<ior>1.5</ior>
	<cauchy_b_coeff>0.0</cauchy_b_coeff>
	<rgb_absorptivity>0 0 0</rgb_absorptivity>
</specular>

Phong

Phong is a physically based glossy reflection model using a Phong lobe. Also can have a lambertian diffuse substrate.

diffuse

The RGB reflectance of the diffuse substrate. Note that the diffuse substrate can also be textured. All components should be in the range [0, 1).

specular

The specular RGB reflectance along the Phong lobe, at normal incidence. All components should be in the range [0, 1). Specular reflection at grazing incidence automatically approaches (1,1,1) due to Fresnel effect, as far as energy loss permits.

exponent

Sets the exponent of the Phong lobe controlling specular reflection. Higher exponent means more 'perfect' reflection, lower exponent leads to more glossy+diffuse highlights. Can range from ~1 to up to 10000 or more.

example:

<phong>
	<diffuse>0.0 0.0 0.0</diffuse>
	<specular>0.8 0.8 0.8</specular>
	<exponent>10000</exponent>
</phong>

Emitters

rectanglelight

The rectangle light element defines a horizontal area light with normal (0,0,-1).

pos

The (x, y, z) position of the middle of the rectangle area light.

width

Width in x direction.

height

Width in y direction.

peak_min

The wavelength in nm of the start of the spectrum peak.

peak_width

The width of the spectrum peak, in nm.

base_value

Exitant radiance for wavelengths outside the peak part of the spectrum.

peak_value

Exitant radiance for wavelengths inside the peak part of the spectrum.

example:

<rectanglelight>
	<pos>0 -4 2</pos>
	<width>2.0</width>
	<height>2.0</height>
		
	<peak_min>400</peak_min>
	<peak_width>500</peak_width>
	<base_value>0</base_value>
	<peak_value>20</peak_value>	
</rectanglelight>

meshlight

TODO. See meshlight_test.xml for an example.

Geometry

model

Places a .3ds model in the scene. The transformations below are applied in the following order: rotation, scale, translation.

pos

Translation applied to the model vertex positions.

scale

Uniform scale applied to the model vertex positions.

rotation

Optional element that defines a rotation that is applied to the model vertex positions.

rotation :: matrix

Defines a 3x3 rotation matrix, in row-major format. For example, the identity matrix / null rotation can be defined like this:
<rotation>
	<matrix>
		1 0 0 0 1 0 0 0 1
	</matrix>
</rotation>

path

The path to the .3ds mesh, eg 'prism\prism.3ds'. The path is relative to the deepest directory containing the scene file. Either backslashes or forward slashes can be used as directory separators.

normal_smoothing

If this is set to false, normal smoothing will be disabled, and the geometric normal will always be used for this model.

matoverride

Material overrides provide a means of using a .3ds file in an Indigo scene, while being able to override the .3ds materials with arbitrary Indigo materials.

matname attribute: the name of the .3ds material to override. Have a look at the log.txt output when loading a scene to see the materials defined in each .3ds file.

The only child of a matoverride element should be a material element, eg 'phong', 'specular', or 'diffuse'.

example:

<model>
	<pos>0 0 0</pos>
	<scale>0.05</scale>
	<rotation>
		<matrix>
			0.970275 0.239186 0.036835 -0.100456 0.536542 -0.837873 -0.220172 0.809267 0.544621 
		</matrix>
	</rotation>
	<path>bathroom/bathroom2.3ds</path>
	<normal_smoothing>false</normal_smoothing>
	
	<matoverride matname="CHROME">
		<phong>
			<diffuse>0 0 0</diffuse>
			<specular>0.8 0.8 0.8</specular>
			<exponent>1000</exponent>
		</phong>
	</matoverride>
	
	<matoverride matname="PORCELAINE">
		<phong>
			<diffuse>0.8 0.8 0.8</diffuse>
			<specular>0.05 0.05 0.05</specular>
			<exponent>200</exponent>
		</phong>
	</matoverride>
</model>

plane

TODO

sphere

TODO

Contact

Indigo was created by Nicholas Chapman. Contact: nickamy@paradise.net.nz