BSP Diagnostics

• diagnostic bsp off|depth|size

This mode^3.x visualizes the depth and leaf size of the BSP tree used for ray tracing acceleration. This works only if ray tracing is enabled (trace on) and the BSP algorithm is used (acceleration bsp). Both modes are the default. The image is scaled so that black means zero depth or size, and red or white means highest depth or size encountered (the absolute values are shown in the message output if the verbosity is 4 or higher). BSP diagnostics can be used to check how often the maximum BSP depth and the maximum leaf size were reached, as specified with bsp depth and bsp size statements. If this happens frequently, the parameters should be increased.

depth 28	depth 32
depth 35	depth 40

A visual guideline for a healthy bsp setting would be to pick the even mix between all colors (middle two), rather than two much red or too much blue.

Sampling Diagnostics

• diagnostic samples on|off

This mode replaces the rendered image with a gray scale image showing the number of image samples made for each pixel. A black pixel has had no samples, whereas a white pixel has had the maximum amount as specified with the -samples option. In addition, a red grid is drawn indicating task boundaries. Samples that lie exactly on pixel boundaries are considered to belong to the lower and/or left pixel. This mode is useful when tuning the samples and the contrast options for optimal effect.

Finalgather Diagnostics

• diagnostic finalgather on|off3.1

This mode shows final gathering points, as green dots for initial raster-space final gathering points and red dots for render-time final gathering points.

The first batch of interesting numbers comes right after finalgather point computation:

JOB 0.0 progr: 100.0% computing final gather points on madtv.0
RCFG 0.0 info : depth   #finalgather points
RCFG 0.0 info : 0         144129 <--- can also be visualized with '-diagnostic finalgather'
RCFG 0.0 info : ray type        number
RCFG 0.0 info : eye             155675
RCFG 0.0 info : finalgather   32284896
RCFG 0.0 info : wallclock 0:03:59.50 for computing finalgather points <----- how long FG phase took
RCFG 0.0 info : CPU user 0:03:37.62 for computing finalgather points
RCFG 0.0 info : allocated 79911 KB, max resident 0 KB
RCFG 0.0 info : optimizing final gather points access (144129 points)

The next batch comes at the end of rendering:

JOB 0.3 progr: 100.0% rendered on madtv.3
RC 0.0 info : rendering statistics
RC 0.0 info :   type               number    per eye ray
RC 0.0 info :  eye rays             974954      1.00
RC 0.0 info :  finalgather rays  156091936    160.10
RCI 0.0 info : main bsp tree statistics:
RCI 0.0 info : max depth       : 30
RCI 0.0 info : max leaf size   : 75
RCI 0.0 info : average depth   : 26 <----compare average with max depth (see bsp section)
RCI 0.0 info : average leaf size : 7
RCI 0.0 info : leafnodes         : 377596
RCI 0.0 info : bsp size (Kb)     : 17654 <-----how much memory bsp tree takes up, watch out for higher depths
RC 0.0 progr: calling output shaders
PHEN 0.0 progr: writing image file FG_500_0.1.tif (frame 109)
RC 0.0 progr: rendering finished
RC 0.0 info : wallclock 0:21:48.01 for rendering <----_total render time, in human time
RC 0.0 info : CPU user 0:03:43.43 for rendering
RC 0.0 info : allocated 145911 KB, max resident 0 KB <---- peak memory consumption was about 150 Mb
GAPM 0.0 info : triangle count excluding retessellation : 279423
GAPM 0.0 info : triangle count including retessellation : 279423 <---- check your tesselation settings!
JOB 0.0 info : 9738 known jobs, 5808 currently known, 9736 done (0 redone, 2 recycled), 0 deleted
JOB 0.0 info : 0.341446 prereqs/job on average, 0% were discovered late
JOB 0.0 info : 0 geometry cache flushes deleted 0 KB in 0 sec (0 sec avg)
JOB 0.0 info : cache memory use: current 27921 KB, max 44016 KB

Not all are fatal, in fact some are harmless, but may provide hints to things in your scene you should fix.

GEOM 0.4 info : 206333 tris in 1175.9 ms of _0:8410::INST_house_door [0] with 2 free-form surfaces

When in verbose mode, the above message prints if an object tessellates to more than 100,000 triangles. This may be reasonable for the object, but then again it may be a little screw somewhere that can't be seen. mental ray is just letting you know...

Here are some harmless errors that come to mind:

RCFG 0.2 warn 542002: angle between normal and geometry normal more than 90 degrees
API 0.0 warn 302005: /path/mray/include/mySHOW_shader.mi, line 5: while defining declaration "mySHOW_shader": ignoring redeclaration of function my_input_shader

If you want to track the memory consumption while rendering on a Unix-based OS, the best tool to use is the unix tool: top.

top shows both the process size and the RSS (resident set size - the part of the program currently in physical memory). When the process size exceeds the RSS by more than ~20%, then swapping is occuring and steps should be taken to check parameters and reduce memory consumption. The total process memory is made up of several elements: the heap (dynamically allocated memory = scene database, acceleration data structures, scratch memory, stuff allocated by shaders), all stacks (local variables, etc), the program itself, and all memory-mapped segments.

For advanced debugging, you can place a debug statement after the render command in the mi scene file:
render "myWorld" "camera1" "myOptions"
debug "mem summary"

Unlike renderman, mental ray runs in parallel by default. If you need to force it to run on just one thread, type:
  -threads 1
as an option to the ray executable on the command line. The number after the hostname in the progress message indicates the thread number that completed the task. mental ray also does hyperthreading, so you may see that the threadnumber is greater than the number of CPUs on your machine.

JOB 0.3 progr: 99.3% rendered on madtv.3

As you have seen, changing a few settings can dramatically reduce render times and memory consumption. To prevent hours upon hours of wasted renderfarm hours, pick a representative frame from your sequence and do a test render to see how on target your settings are. For the patience-impaired, test renders can be accelerated by rendering

• in lower resolution ( -resolution W H ) or
• with crop regions ( -window XL YL XH YH ).

Lowering sampling or finalgather settings can also help, but if you are checking images for quality rather than efficiency, this may not be such a good idea. However, keep in mind that sometimes the finalgather settings can be lowered without loss of quality (do your diagnostics). I have seen an example where the # of rays when cut in half did not affect quality, but increasing the max radius affected quality adversely. Nobody can know until they test.