Wednesday, July 23, 2008

MOSAIC feature ramblings - part 12

Part 12 - Mapping utilities tutorial:

This post represents the last of the MOSAIC feature ramblings series and will focus on actually building and rendering a simple scene using mapping.
In particular this tutorial will focus on the following tasks:

  • Build a basic scene in Blender highlighting RenderMan setup

  • Prepare shaders via materials

  • Set up MOSAIC

  • Set up an occlusion map pass

  • Set up an environment map pass

  • Set up a shadow map pass

  • Set up a caustic map pass

  • Set up camera DOF

  • Add, build and use RenderMan shader sources and fragments

  • Tweak RenderMan settings

  • Tweak shaders via MOSAIC's GUI

This tutorial will specifically target MOSAIC's mapping utilities to create advanced rasterization techniques, because of this I will be using Aqsis for this tutorial (since it's a pure REYES renderer). Before we begin be sure you have at least Blender 2.46, Aqsis 1.4 and CVS 1.39 or newer.

If you're impatient and, like me, just want to see the scene, you can download it here:

Also the first image is the final render, so you can use it as reference for building your scene ;)

Building the scene

To start off with, we will need to build a scene in Blender keeping in mind a few details related to how MOSAIC and RenderMan work. To save a little time instead of outlining every step of this I'll just explain what's in the scene and show some scene shots. I'm assuming a basic knowledge of Blender if we're using external renderers :)

Here's what's in the scene, look at the pictures to the right for the layout:

  • 1024x1024 UV test grid image saved as a tif.

  • 1 mesh plane Scale 13.7x13.7, double sided, UV unwrap, with unique material.

  • 1 mesh Suzanne Scale 2.1x2.1x2.1, double sided, smooth, SDS mod with unique material.

  • 4 instances (alt d) Suzanne Scale 1x1x1, double sided, smooth SDS mod with unique material.

  • 1 standard spot light, energy 1.2, color RGB 1.0,0.9,0.8.

  • 1 standard camera with 35mm lens.

Now that we have the basic components and layout of the scene let's setup the RenderMan related settings. To start off with we need to assign the large Suzanne to a group, this is because later on we will assign it to caustic pass by itself.

Preparing shaders via materials

Next let's quickly outline the material settings:

For the plane use standard material :
  • Col RGB=1,1,1,

  • Amb=1 (sets occlusion),

  • Spec=0,

  • create image texture using tif image, disable map to Col, enable map to Disp, and set its Disp slider to 0.477 (this tells MOSAIC to use texture for micropoly displacements).

For big central Suzanne use standard material :
  • Col RGB=0.098,0.665,0.544,

  • Ref=0.709,

  • Spec=2,

  • Hard=309,

  • Amb=0.607,

  • RayMir=1,

  • Mir Fresnel=1.2,

  • IOR=1.3,

  • Transp Fresnel=2.0.

For the instanced Suzannes use standard material :
  • Col RGB=0.617,0.617,0.617,

  • Spec=0.184,

  • Hard=215,

  • Amb=1,

  • enable "Subsurface Scattering";
  • Scale=1,
  • IOR=1.3,
  • Error=0.05,
  • Col RGB=1,0.791,0,
  • Front=0.8,
  • Back=1.

One thing to note about the big Suzanne's material is you'll notice that we're setting the ray mirror and transp settings even though we're not enabling Ray Mirror and Transp. This is because if MOSAIC sees an environment map enabled on an object it will use its material's ray mirror and transp settings on the map as if it were raytraced. This allows more advanced control such as fresnel over the environment map. If an environment map is enabled you will need to first disable it before being able to use raytracing even if you enable the "Ray Mirror" and "Ray Transp" toggles (maps take precedence since they involve render passes to MOSAIC).

Just for a nice effect let's also enable some fog. Go to Blender's world material settings and set the HorRGB color to 0.289,0.542,0.817. Also enable "Mist" and set "Dist" to 30. The other default settings should work but you may want to play with them to get other effects :)

Finally we need to setup the camera for DOF by switching on the camera's Limits and adjusting the Dof Dist (yellow cross) so that it's near the front of the big Suzanne. This will tell MOSAIC where the focal point for the DOF will be.

Setting up MOSAIC

Now that we have the camera, lights, objects and materials setup now it's time to setup MOSAIC. Before we begin be sure to go to the "MOSAIC Settings" tab and make sure you have "Aqsis" selected in the preset menu.

In the previous posts I briefly mention the mapping utilities and several buttons related to this, let's describe this in a little more detail.

The mapping utilities collectively are just a series of buttons throughout MOSAIC interface that allow you to create and edit map related render passes. You can find these button connected to the thing they make a map for, such as occlusion maps with scenes, environment maps with objects, shadow and caustic maps with lights. Once clicked , you will be presented with a dialog that allows you to setup how you want the map to be generated and how you want its contents updated. When complete MOSAIC will generate a render pass entry in the "Project Setup" tab and a scene to use as the pass using the name of the object and a special extension as its name (such as, see post 5 for details). Once the pass is created the button for the utility will be pressed in (letting you know at a glance if the pass already exists), if you click on the utility button again the scene and all its render pass entries will be removed. You can click the "edit" button next to the utility buttons to edit an existing pass without destroying its contents. The mapping dialogs have a set of controls that are standard for all dialogs and some that are specific to the map type.

Here are some of the standard ones:

  • SizeX/Y - These are standard controls for all utilities and adjust the width and height of the map.

  • Use Shaders - This is standard for all utilities and if enabled the shaders for the scene are used in the pass. This should be turned on if the map needs to see displacement mapping or surface shader related transparency (for deep shadows, etc). This is best left off for faster render times unless needed.

  • Use Preview - This is standard for all utilities and if enabled the pass will use the framebuffer display (will popup a render window). This should only be enabled if you wish to see the passes render output.

  • Degrees/Scale - This is standard for all utilities and has different meaning depending on the object type. If this is an environment or point shadow pass then this controls the seams for the cube mapping, if this is a sun lamp then this is orthographic scale (usually good to start a 9 or so), if this is a spot light then it does nothing (lens determined from spot size). In the case of occlusion mapping this does nothing because the occlusion rig uses spot lights.

  • Shading Rate - This is standard for all utilities and sets the shading rate for the pass. This is by default set very high for lower quality but faster rendering (which is usually OK for support passes), set this lower for higher detail and higher for faster render times.

  • Group - This is standard for all utilities and combined with the other filter settings control how the generated pass is built from the beauty pass. MOSAIC creates the pass from the current scene which becomes the passes beauty scene, the filter settings at the end of all utility dialogs tell MOSAIC what to use from the beauty scene. Depending on the pass type, some of these controls are always forced to certain values and some are available to the user. This one (group filter), is the most commonly used and just tells MOSAIC to build this pass only from objects contained in the specified group.

Now that we've covered a little about how mapping utilities work let's use them to setup the passes for this scene.

Set up an occlusion map

Let's start by going to the "Scenes Setup" tab and pressing the "Enable Occlusion Mapping" button. The default setting for this should be fine.

Just in case you were wondering, here are what some of the controls do:

  • Hemisphere - This is exclusive to occlusion mapping and controls whether the occlusion rig is a hemisphere or a full sphere. MOSAIC does occlusion mapping by creating a mesh in the pass and dupliverting a spot light to it, thereby making a dome light rig.

  • Rig Segment / Rings - This is exclusive to occlusion mapping and controls the number of segment and rings used in the occlusion rig. The higher these numbers the more lights are used in the rig.

This will produce an occlusion map that Aqsis will use to calculate occlusion.

The occlusion color is set by the world's HorRGB color and its intensity is controlled by each material's Amb slider, just like Blender.

Set up an environment map

Next click on the big Suzanne and let's give her an environment map!

Once you've clicked on the big Suzanne go to the "Geometry Setup" tab and click the
"Enable Environment Mapping" button.

Unlike last time instead of using all defaults enable the "Use EnvDOF" toggle and set
"fstop" to 600.

This will produce a glossy like reflection by using DOF to make objects further away
blurry (in this particular scene it's not very visible so could be skipped).

Set up a shadow map

Next click on the light and go to the "Lights Setup" tab and press the "Enable Shadow
Mapping" button. The default settings should be fine for this, but note if we weren't
wanting displacements in shadows we could cut render times by disabling "Use Shaders".

Set up a caustic map

We also want to click "Enable Caustic Mapping" for this light but instead of using all the defaults set "Group" to "Group" (or whatever group you assigned the big Suzanne to

We need to do this because by assigning a group to the filter, this pass will only use
objects in that group, in this case that's just the big Suzanne.

Since we only want caustics for that one glass object then this works well, if you were to
add more glass objects with caustics you would just assign them to the same groups.

Set up camera DOF

Finally the last thing we need to setup is the camera.

Click on the camera and go to the
"Cameras Setup" tab.

Enable the "Use DOF" toggle and
set the "fstop" to 240.

This tells the renderer to use DOF
and MOSAIC will set the focal point
to the camera's Dof Dist setting.

At this point we can now render a
basic scene but you'll probably
notice that the environment map
renders get "eyesplits" errors and
overall the rendering is slow.

Also the scene lacks the interesting procedural displacements.

Adding, building and using RenderMan shader sources

Let's go ahead and play with some RenderMan procedural shaders :) If you've installed a full version of MOSAIC you will have a folder in the installation called "shaders", let's use a couple of the shaders in there. In Blender setup a window to the "Text Editor", click "File" and browse to MOSAIC's "shader/displacements" folder and load two shader sources: "" and "". When shader sources are loaded into Blender's text editor MOSAIC can use them automatically, but in order to use them in the project we need shader fragments. To do this go to the "MOSAIC Utilities" tab and click "Generate Shader Fragment". Once clicked, select the "" and "" one at a time to automatically generate shader fragments for those shaders. Once shader fragments have been generated then you can select them in the "Shader Parameters" menu to manually edit them (and of course you can now use them in the "Materials Setup" tab).

Now that we have shader fragments let's edit them so they look like my example. Select "ds_bubbly" in the "Shader Parameters" menu and edit the following (including the square brackets):

  • Kd = [ -0.15 ]

  • bubsize = [ 0.5 ]

For the "ds_dented" the default values will be fine. Now that we have tweaked our shader values let's apply them. Select the big Suzanne and go to the "Materials Setup" tab (make sure this really is the material for the big Suzanne). Change the "Displacement Shader" entry to "ds_dented", this will apply the dented shader to this material which is applied to the big Suzanne. Next select one of the instanced smaller Suzannes, go to the material setup tab and change the "Displacement Shader" entry to "ds_bubbly". This will apply the bubbly shader to this material which is applied to all the instanced Suzannes.

That's it for using shader sources, very easy :)

Tweaking RenderMan settings

At this point everything should begin looking like the example render I've provided, but you're probably getting errors on the environment passes and things are a little slower than they should be, so let's look at optimizing this scene for RenderMan :)

Eyesplits happen when geometry passes through the eye plane of the camera (it helps to think of this as the near clip visually), when this happens the renderer has to continue to dice and split the geometry into finer pieces to create a clean edge. How many times this happens is controlled by the "eyesplits" control in the "Scenes Setup" tab, but you want to be careful because eyesplits are very slow and can usually be avoided. One of the first things to look for when getting eyesplits is whether the camera is too close to any geometry, when rendering environment maps the camera is placed at the center of where the object is (which is usually very close to other objects). To correct this one of the simplest things to do is decrease the DisplaceBound setting. The DisplaceBound setting basically extends the bounding box of an object to make extra room for displacement shaders, this is necessary because RenderMan renderers are really sensitive to the bounding box since it's used to determine how far to calculate the shaders. The bounds have to be manually adjusted because the renderer has no way of knowing how far the displacements are passing outside the bounds box. By default MOSAIC uses 0.100 for all objects which is actually very large (I did this so all displacements would work for beginners).

So, I said all that to say this, to remove the eyesplits error for the environment map and increase overall render performance change the "DisplaceBound" settings in the "Geometry Setup" tab for each object to these:

  • plane = 0.010

  • big Suzanne = 0.010

  • smaller Suzannes = 0.030

Another small tweak that can help performance depending on your machine and memory is to increase the "bucketsize" in the "Scene Setup" tab to 32. This determines how large each render bucket is and will usually use more memory the larger it is but render each bucket a little faster (up to a point).

Tweaking shaders via MOSAIC's GUI

Finally one of the last areas I want to discuss for tweaking the scene is manual shader parameters.

The built-in shaders that come with MOSAIC have several parameters that have no where to hook into Blender's interface.

One thing to keep in mind when tweaking these are that they are global in scope, this is because the same shader fragments are usually used by everything in the project (this is possible because tokens allow each object to pass different settings through the same fragment).

One way around this would be to copy the built-in fragment and apply it to the individual objects you wanted.

Here's some parameters on "ls_MOSAIClight" I've tweaked to improve the caustic effect by coloring, smoothing and adding a little procedural noise:

  • CausticAlpha = [ 0.7 ]

  • CausticColor = [ 0.0 1.0 0.6 ]

  • CausticSamples = [ 256 ]

  • CausticBlur = [ 0.12 ]

  • noisefreq = [ 1.5 ] (this turns on noise)

Well that's it, thanks to everybody who's encouraged me to continue writing these blogs (it's been a lot of work).

Also a big thanks for everyone who's played a part in making MOSAIC better, it's absolutely amazed me how people's ideas, encouragements and bug reports have made MOSAIC far better then I ever planned :D

Thanks for reading, WHiTeRaBBiT


  1. Hey WHiTeRaBBiT,

    Well done with these blog posts, I know how much work there is in writing good documentation. These posts will be an extremely good place for me to get my feet wet when I finally get around to learning enough about blender to make proper use of mosaic.

    Of course, it's really great to see you using aqsis to produce such compelling results too :-D. I suppose you're using environment mapping a lot here for the refractions? Unfortunately the environment filtering is rather broken in aqsis-1.4, but it's the first thing on my todo list. (ie, hopefully fixed in aqsis svn within a week or two).

    ~Chris (c42f).

  2. Hey Chris :)

    I can code for days straight with no sleep or food without thinking, but writing docs for just a few hours make me cross eyed :s The hard part is still yet to come, eventually I'll need to re-write these into a more orderly manual format for the Wiki.

    As far as technique this is just environment maps used as reflection and refraction. Then their spruced up with fresnel and DOF for the env render to simulate blurry refl/refr. Also I displaced the surface slightly to hide the lack of self refl/refr. Also using occlusion mapping and SSS on shadow maps.

    I haven't had time to try yet, but I think for most "nature" and "worn" scenes and surfaces these techniques will be completely convincing, since you wouldn't have perfectly refl/refr materials anyway. And there crazy fast when compared to raytracing (especially with heavy displacements, atmosphere, SSS, ect). Also I'll be doing really, really large renders on a farm (I'm talking 4'x8'@600dpi large format prints) and env maps, occlusion maps, shadow maps distribute more parallel then anything I've tried, I find that most of the technology is geared toward caching single frames to be rendered 1 frame per blade for animation. The only renderers I see handling parallel rendering well are unbiased but can't come close to rendering at those sizes. Thats what drew me to RenderMan, its flexible enough I think this is possible :)


  3. It's amazing how you can get away without using self reflection and refraction just by adding a little displacement. If I was given this image and told that it was made by a physically correct renderer I wouldn't know any different :)

    You say 4'x8'@600dpi... wow, that's seriously amazingly large. I've been rendering what I consider "large" images in the last few days - A4 @ 300dpi, but that's nothing compared to what you're talking about! Good luck, I think renderman in some form or other will definitely be up to the task :-)

  4. Well, I'm not sure if its quite unbiased quality, although I think its possible with a lot more work :)

    I've been spending a little time hanging out at Indigo and Luxrender and find myself surprised why they would tolerate 4-8 hour renders for images that could be done in 4-8 minutes in RenderMan. It all depends on what your doing and I'd say at least 1/3 of the images I've seen didn't require unbiased :s

    I've been working on a "pet project" to do really large format images, the printers are getting affordable and computer hardware is to the point that a medium sized farm is possible (talking 100-200 computers). I already have a 20 node farm of athlon 2.8, but in order to really take advantage of them you need "true" parallel rendering. Using light maps, occlusion maps, env maps, tile rendering, ect automatically parallel and can provide much higher speed to quality scaling then raytracing can :) I also plan on adding Aqsis/Gelato layered shading and a feature for tiling images to passes to help make this possible. I think by using a combination of textures for the overall "feel" with layered procedurals for fine details that extreme detail and artistic control should be possible.

    I want images you could spend hours up close looking at :D

  5. Anonymous11/8/08 09:16

    thank you for all your hard work. this is an amazing project that just keeps getting better. i didnt think i'd see this much development/documentation in such a short time. Thank you again. :)

  6. I am so pleased you decided to write this renderman exporter. I have been following a lot of different renderman and gelato exporters over the last few years and was getting used to just being able to export the geometry and then doing the rest out side of blender. Then I found your plug in and was totally amazed how far you had got and what a great way of doing it you had. I like the way it is possible to input external parts and also even write the shaders from within blender. It has progressed fast and now I am happily reading the blog to get the most out of using it. Now it is extremely possible to use renderman with blender thanks to you. This has been needed for a long time. Thank you very much.

  7. Hey,
    I don't know much about Renderman type renderers, but that is changing now thanks to you. MOSAIC is full of pleasant surprises.
    Keep on your great work and Thanks...

    Zdenek Tuka
    Design student

  8. Hey..

    I am not able to follow this documentation.. pls update as of now whats inside mosaic.. I am not able to get gi, AO working.. :(

  9. hello mohan,

    This particular series was written for the last package release of MOSAIC and not the CVS version which is unstable and constantly changing. I encourage everyone to use the CVS version however it is usually not documented at all!

    Unfortunately writing documentation and tutorials takes as much time as programming and I don't have time for both. I plan on beginning a new blog series soon to outline the newest features but only after they are complete and stable enough to demonstrate. Until then please refer to some of the links I've provided in response to your group forum post :)

    I am nearing completion of the built-in shaders so I will be blogging about them very soon soon ;)

    Eric Back (WHiTeRaBBiT)