Introduction to LuxBlend Classic API - LuxRender Wiki
Luxrender GPL Physically Based Renderer

Introduction to LuxBlend Classic API

Personal tools

From LuxRender Wiki

Jump to: navigation, search

This page contains instructions for using LuxBlend, LuxRender's interface and export add-on for Blender 2.7x. It will cover basic usage and is intended for first time users of LuxBlend.


Introduction to LuxBlend

This page uses the Classic API for setting up materials. If you are new to LuxRender, you should try the new way instead. Classic API will not be worked on any more and will eventually be replaced by LuxCore API.

If you have not done so already, please install LuxBlend using these instructions, and make sure that LuxRender is selected as render engine.


Hello world

Let's render something simple: Blender's default cube. To be able to render anything we need a light so let's use the sun lamp. Press Shift+A, Lamp > Sun. Move it to the right of the cube and rotate it to face the cube. Add a plane (Shift+A > Mesh > Plane) under the cube. Press F12. LuxBlend will now export the scene and start LuxRender.

Luxblend default qube.jpg

Nice, it works. The cube and plane are using the default material because we did not set that up. Let's take care of that in just a minute. But first let's do a one-time setup of LuxBlend.

LuxBlend setup

This step is not absolutely necessary but recommended because it will make LuxBlend and LuxRender easier to work with. And we only need to do this once. When we are done we simply save the startup file in Blender and the settings are there the next time you start Blender.

The Output section on the Render tab is where all LuxRender scene files will be exported to when starting the render (F12). Selecting a separate folder here helps a lot instead of using a temporary folder ( /tmp\ ). Pick one that's convenient and easy to find. This folder will grow in time with LuxRender scene files and rendered images. If you ever close LuxRender without saving the render image to a file, this folder is where you can find a backup of it.

Luxblend render tab output.jpg

In LuxRender output format we have Write FLM and Restart FLM. The .flm file contains the already rendered samples for the scene. This .flm file can later be used to open or resume a previous render. Keep these two check boxes enabled. If you render something for several hours and there is a power outage, all that render work will not be lost, but safe in the .flm file. Later you simply start LuxRender and click File->Resume FLM. LuxRender will then ask for the scene file first (.lxs), and that can be found in the folder you chose above in the Output section. Next it asks for the .flm file and that can be found in the same folder. Write FLM makes LuxRender enable use of the .flm file and updates it every 15 minutes by default. Restart FLM makes LuxRender clear the .flm if it is present at beginning of rendering.

Luxblend render panel flm.jpg

Move over to the scene tab in Blender. In the Units section pick the measurement unit you are used to. This is important for several reasons:

1. LuxRender is a physically based render engine, and that means you need to model the scene with correct size and scale in order to get a correct render. If you model a glass of water, model it to scale (about 10cm tall, not 1-2m tall). Blender's default cube is 2m x 2m x 2m and you can confirm this by using orthographic mode(numpad 5) and front view(numpad 1). Check the upper left corner of the 3D view and check the background grid.

2. A lot of settings in LuxBlend uses real units, like bump and displacement maps and hair strand size. Take an orange for example. Let's say it's not modeled to scale, instead it's about 1m wide. You know that the bump amount on an orange is about 0.5-1mm simply by looking at one. So you put that bump amount in LuxBlend and you hit F12, and later wonder why it's showing a weak bump or no bump in the render. Because a 0.5mm bump is very little on a 1m wide orange :)

3. You will sooner or later reuse an old model and append that into another blender file. If you did not model to scale the sizes will be off. Sure, it can be scaled afterwards to fit the new scene but all the settings that rely on real sizes will then be wrong and the render will not look the same.

Luxblend scene panel units.jpg

It's good practice to get in the habit of modeling to scale. Once you do, it takes just a few seconds to find out or estimate an object's size before starting modeling.
One more thing that's important about scale is Blender's scale property found on the properties panel in the 3D view (N). Select a mesh object and check the panel. These three should all be '1'. LuxRender uses this scale so be sure to apply the scale (CTRL+A) if you scale in object mode.

Luxblend object scale.jpg

That's it for the first-time setup of LuxBlend. Save the start-up file now to have Blender use your settings from now on.

Applying Materials

Here is how to apply materials (shaders) to objects. Please make sure that Classic API is selected on the Render tab. It is the old way of setting up materials but works just fine and this wiki page was written based on it.

Luxblend render panel render api classic.jpg

We can use the sun from the previous section but delete the cube and add an icosphere instead (Shift+A Mesh->Ico Sphere). Add a two level subdivision surface modifier to it (CTRL+2) and set shading to smooth. Move to the material tab and add a new material for the sphere. If there is a material left over from Cycles or Blender Internal, delete it and add a new one.


Pick the Glossy Material type. This is a basic shiny material shader, and can be used to create a lot of different materials which are glossy (plastic, anything painted, lacquered wood, wet concrete). Open the material preview to see the changes being made. Pick a color for the diffuse color channel to give the sphere a solid color. You should never pick a color value higher than 0.8 on either R, G or B channels because no material in the real world is that bright (LuxRender is physically based renderer). Adjust how shiny it is by changing the Roughness. Specular color is not the same as specularity (Cycles). Roughness is the same as Specularity (Cycles). Specular color is the color of the specular highlights, and it should always be a dark color (default 0.04).

Luxblend glossy basic material.jpg

The slots that have the T button can be textured by an image map or procedural texture. Let's try that. Move over to the Textures tab and add a new texture by clicking New and rename it to sphere bump. There are two categories because both LuxRender and Blender have their own textures, but LuxRender can use both. Pick Type: Clouds and LuxRender Type: Use Blender texture. If we check orthographic mode(NUMPAD 5) and front view(NUMPAD 1) we see that the sphere is 2m wide. If we then check the texture preview the bumps will be pretty big so we'll scale them down to 0.1 on all axes. Increase contrast to 3 to make the edges sharper.

Luxblend procedural texture bump.jpg

Head back to the Material tab, enable the texture slot T for the bump and pick the texture we just created. Change bump map amount to 5mm and hit render. Give Lux a few seconds to render that and we will have a bumpy ball.

Next let's add a texture for the diffuse slot as well. On the Textures tab add a new texture and rename it to sphere diffuse. We will use an image here so change the LuxRender type to: LuxRender Textures -> Image Map. The other texture type can be left as it is because it won't be used unless the LuxRender type is set to Use Blender texture. Change the image map type to color and select an image. Back on the Material tab click the T next to Diffuse Color and pick the texture we created, sphere diffuse. Whenever you use an image map you need to UV unwrap the model. Open the same image in Blender's Image Editor and UV unwrap the sphere using sphere projection. Render!

Sphere using the glossy material with green diffuse color and bump
Sphere using the glossy material with texture and bump

Each texture slot has this M button and that multiplies the texture with the slot's color. If the diffuse slot has for example a green color and it uses a texture on the texture slot, that green color is multiplied with the texture if the M button is pressed. If the button is not pressed LuxRender will use only the color from the texture and ignore the green. The M button is an easy way to tweak the texture without changing the actual image itself. The button is not pressed by default except for the bump amount, which should always be pressed. The bump amount is by default 1 (1 meter), and keeping the button pressed makes LuxRender use the correct bump amount as set by the user, in our case 5mm.


LuxRender has two glass types, Glass and Glass2. Glass is easier to set up and can be used for objects which do not interact with other volumes, such as an empty glass or vase. Glass is also the type to use for painted glass. Glass2 is the type to use for a glass with liquid in it. Change the material type for the sphere to Glass and render. The default settings gives a solid clear glass ball. Try changing the Reflection and transmission colors. These can be textured too so let's try that. Move over to the Textures tab, add a new texture and rename it to Glass 1 noise. We will use this noise texture to get the procedural texture and later use another texture to put some color to it since all Blender textures that LuxBlend uses are black and white (float) textures. First for the procedural texture pick Type: Clouds and Basis: Voronoi Crackle and Scale 0.5.

Luxblend glass procedural texture.jpg

Next to put some color to it we need a new texture 'Glass 1 color' and this time pick LuxRender type: Utility Textures->Mix. Change the Mix to output a color texture, and pick the two colors to be mixed. Enable the T for the Amount and pick Glass 1 noise we created earlier.

Luxblend glass mix texture.jpg

Back on the Materials tab enable the T for Reflection and Transmission and pick Glass 1 color and render. Back on the Textures tab you can get a varying mix by enabling the M and change the Amount value. Switch the colors to get an inverted result. Now we have a glass ball with a colored surface. The inside is still clear glass.

Glass ball with textured diffuse and transmission

To get a color to the inside of the ball we need to use a volume. Move over to the World tab and add a new volume. Name it Glass ball 1, pick Type: Clear and choose an IOR. The materials Glass and Rough Glass won't use this IOR, they have their own on the Material tab. Glass2 however will use it since it's a volumetric material so choose the IOR now so we can use the same volume when setting up the Glass2 material. For the color of the volume we choose an absorption color and a depth. This specifies what color the volume will have at that depth into the volume. Out glass ball is 2m wide so leaving Absorption depth at 1m is OK and pick a light color for the absorption. The absorption depth is not limited to the size of the sphere.

Luxblend worldtab volumes.jpg

Back on the Material tab pick the Glass ball 1 volume as interior. Disable the T for Transmission and Reflection to see the internal color clearer. Render. Increase or decrease the Absorption at depth value to get a fainter/darker internal color. If you get only clear or black glass, keep in mind how big the object is. Keep the absorption at depth value to somewhat close to the size of the object.

Glass ball with a volume

Two important things about glass:

1. It must always have a thickness. Always. A sphere or cube or the Suzanne monkey already have thickness but a simple plane or circle does not. It's very easy to get thickness to them by using the excellent solidify modifier in Blender. For a sheet of window glass you could use a simple plane and use the solidify modifier with a 3-4mm thickness.

2. Get the normals right. This is very important in LuxRender because it uses the normals when rendering. This applies not only to Glass but all materials. Get in the habit of checking the normals. It's very quick and easy to do and once you do you will have no problem dealing with volumes. Blender does a fantastic job on getting the normals right when using CTRL+N in edit mode but some times it's off. The sphere has correct normals but let's check it anyway before moving on to Glass2. Go into edit mode and open up the properties panel (N). Toggle on show normals and change size to 10cm. The normals are pointing out from the sphere and that is correct. Normals are always pointing to the exterior. Opposite side of the normals we have the interior. Consider a ray of light going through the sphere from right to left. As it hits the sphere (A) it enters the interior of the ball so we choose the Glass Ball 1 volume to be the interior of the ball. Following the ray of light it exits at B, leaving the Glass ball 1 volume and enters its exterior volume. We left that blank so LuxRender will use the default World volume for it. LuxRender will use that for interiors and exteriors which we leave blank unless we define our own default on the World tab.

Luxblend sphere normals.jpg Luxblend light ray through sphere.jpg


Glass2 works great with volumes that are interacting with each other, such as water in a glass. Model a glass (to scale). Check the normals to make sure they are all pointing out from the glass object. First let's add the water to it. In edit mode, find or add a loop cut where the water surface should be. ALT+right click that to select all of it and hit F to fill in a face. Then hit I and place the loop cut close to the outer one. Select the center face and press I again and place the loop cut close the previous one. Move them down a little to get the capillary action. Hit CTRL + NUMPAD+ to select the next loop as well. Hit Y to split the water surface from the rest of the glass.

Luxblend glass and water.jpg

We will have two volumes here (glass and water) so let's set those up first. On the World tab add a new volume, name it glass, pick Type: Clear and pick an appropriate IOR. Pick an absorption color or leave it at pure white for clear glass. If you use a color pick absorption depth to somewhat close to the size of the object. Next add a new volume, name it liquid, pick Type: Clear and pick an appropriate IOR. For water pick absorption color to a light blue, about R:0.7 G:0.9 B:1.0 and depth to 0.5m.

Now we need to figure out how we are going to set up the interior and exterior for the materials. We can do this easily by following an imaginary ray of light. From left to right it would go from air to glass(A), glass to water(B). The rest of the way is the exact opposite because the object is round so no need to go any further. So we need two volume transitions: air to glass and glass to water and that means two materials.

Luxblend light ray through glass and water.jpg

On the Materials tab add a new material to the glass, Type: Glass2. Glass2 comes with less settings than Glass because it's volumetric and uses the settings from the volume we assign to it. Rename it to Glass-air. We needed two materials so add a new material named Glass-liquid and pick Type: Glass2. Enter edit mode and select all faces on the inside of the glass that would make contact with the liquid. This will make sense in just a minute :) Assign those faces to use the Glass-liquid material.

Luxblend glass and water faces.jpg

Toggle on show normals. Now we use the imaginary light ray again. From left to right: air to glass (A), glass to liquid (B). For the Glass-air material we see that the normals are pointing away from the glass so that material's exterior will be blank (World default) and its interior will be Glass. The normals always point to the exterior.
For the Glass-liquid material we see that the normals are pointing away from the glass so that material's exterior will be liquid and its interior will be Glass.
Keep following the light ray until it exits the glass on the other side and you will notice that the interior and exterior for our two materials are still correct.

There is one more volume transition we need, and that is air-liquid which happens for a light ray coming from the top and enters the liquid directly. No problem. Add a new material and rename it to air-liquid. Check the water surface to make sure that the normals are pointing out from the liquid, flip them if they are wrong. This makes the liquid's surface exterior to be blank (world default) and its interior volume to be liquid. Render!

If you got the normals right you should now have a glass of water rendering correctly. Final note: When rendering glass you should expect some longer render times because glass is difficult to render. LuxRender handles glass beautifully but it takes time.


Lighting is usually done by using mesh lights. That is usually just a simple plane but it can be any mesh object. The lighting property is enabled on the Materials tab and light will emit in the direction of the normal. The emission color has a T button so that property can be textured as well using a lamp color preset, procedural texture or image map. Lamp color presets are LuxRender textures and can be added on the Textures tab (LuxRender type > Emission and Spectrum Textures > Lamp Spectrum). That texture can then be chosen on the emission color slot on the Materials tab.

Light groups are a very powerful feature of LuxRender. With these you can control the power and color of the lights at render time. Light groups are first added on the World tab and can later be used on the Material tab for lights to be grouped. Emission power for the groups is changed in LuxRender on the Light Groups tab at render time. For HDRI lighting add a Hemi lamp, SHIFT-A Lamp -> Hemi. The location of this lamp in the scene does not matter, only its rotation. For a sun add the sun lamp, SHIFT-A Lamp -> sun. The location of this lamp does not matter either, only its rotation. The rotation relates to the real sun's position in the sky so it won't emit any light if the direction is rotated upwards.

1. The traditional way using a plane with emission enabled.
2. Four mesh circles using four of LuxRender's many lamp emission color presets.
3. A sphere using vertex colors as emission color (pink, green and black).
4. Suzanne monkey using a procedural texture as emission color.


LuxRender supports Loop subdivision + displacement and Microdisplacement. To use them you need a grey scale image map or procedural texture. To use an image map the object must be UV unwrapped. Let's try a procedural texture:
Select the object and go to the Textures tab. Set up the procedural texture and name it displacement. Move over to the Object Data tab and in the LuxRender Mesh Options pick a subdivision scheme. Select the procedural texture you created for Displacement Map and use Scale to select the amount of displacement. Render!

Displacement settings on Object data tab
Sphere with displacement using a voronoi procedural texture

Depth of Field

Depth of field can be enabled by changing the settings for the camera. But first let's add two spheres, a ground plane and a sun lamp to the scene. Move one of the spheres further away from the camera, give them each a glossy material and a diffuse color (remember to keep RGB below 0.8). Render it now and it will be rendered without any depth of field. Select the camera and go to the Object data tab. Enable Use Depth of Field, pick the icosphere that is closer to the camera as Focus, disable Autofocus and pick 2.0 as f/Stop value. A low f/Stop value means only the Focus object you pick will be in focus. A high f/stop (around 10) means the whole scene will be in focus.

Depth of field disabled and enabled

Camera object data tab

Final words

This page was just an introduction to LuxBlend. It showed new users where to find the most important settings and how to use them. For details on the settings please refer to the LuxBlend manual and the LuxRender manual.