Samples Tips

For a visual understanding of the samples option in mental ray^®, we present a series of diagrams to illustrate its meaning, use, and relationship to filtering. In addition, we hope this provides understanding for further exploration of multipass rendering, and user framebuffer reading and writing.

Samples and pixels

mental ray produces samples as a result of tracing primary eye rays. It uses samples to construct each pixel in an image. It does so in two phases by first, populating a sample framebuffer, then, using these samples to fill an image framebuffer.

In the following diagrams, we show a 4 x 4 pixel portion of an image. At a sample rate of one sample per pixel, one might assume that each sample targets the center of a pixel. But this is not the case. By shifting the sampling point to the corner of a pixel, we allow for greater antialiasing quality when combining samples into a pixel. For example, although the average sample density across the image is the same, mental ray has more samples to use for a filter that is one pixel in size. So, for the default box filter of 1 pixel size, it can use 4 corner samples, instead of 1 center sample.

Fixed samples and what the number means

For the moment, we will ignore the adaptive part of the sampling, and concentrate on what a fixed samples number represents. In other words, with min and max samples set to the same same number, the samples represent a fixed grid.

Adaptive Sampling

Now, consider different min and max samples values. A rendered image can have a varying amount of samples. The amount depends on the contrast in a given area. Higher contrast leads to more samples. The minimum samples value determines the minimum grid of samples. The maximum samples value determines the limit to adaptive subdivision. While the contrast option controls whether or not subdivision should take place.

After four corners of a min sample area are taken, the contrast between the corners is used to determine whether or not 5 more samples will be taken, effectively subdividing the area. This can be repeated by as many levels of difference as there are between min and max samples.

Adaptive sampling uses recursive techniques. This means that further subdivision occurs locally, rather than for each level of samples across the image. In other words, the first four samples of a min sample area is tested for contrast, if subdivision is required, 5 more samples are taken to create 4 subregions, and this process is repeated for the first subregion, and the first subsubregion, etc. In the above, the min samples region is a pixel, and all the possible green samples of a pixel will be taken before moving on to the next min sample region, in this case, a pixel.

Imagine a function which does the subdivision, and then based on contrast, may call itself again; that is recursion.

As an optimization, you can see that when processing the next pixel, the samples on one or two edges may have already been taken, so there are less samples to shoot out.

In addition, the actual algorithm is a bit more complex, in that it knows how to follow contrast along edges. This is called edge following.

Here are some example possibilites for completed subdivision. On the lower right, we've increased the max levels to 3, and a small slash requires the extra subdivision.

Diagnostics

Use diagnostics as a handy way to visualize samples. For example, use
  -diagnostic samples
from the command line. Here are three examples using the sss grape:

samples -1 0	samples -2 0	samples -3 0

In the left image, the min samples are every other pixel along an edge; in the center, every 4 pixels; on the right, every 8 pixels. With max samples at 0, averaging 1 sample per pixel, the pixel is completely white in higher contrast regions such as the outline of the grape.

Also, note the red samples forming a grid in the diagnostic images. These red sample lines depict the edges of each tile. We will dig in to this concept further in the next section.

Tiles/Task Size

When watching a render in progress, take notice as the image renders a tile at a time until the entire image is covered. Each of these tiles could be distributed to a different host when using multiple rayhosts.

The tile size is determined by the task size option, ie,
  -task_size 40
at the command line. (A best guess is calculated for you if left unspecified.) The size is the length of the side of the tile. In the grape images above, the task size is 40 and the images are 160 x 120. That generates 4 x 3 tiles.

Note that because each tile goes to a separate process, possibly executing on another machine across the network, it would be difficult and time consuming to share memory for those samples. So, it is more efficient to sample adjoining tile edges twice, once for each tile that shares the edge. To see this better, we will take an 8 x 8 sample dot picture and separate the tiles with a task size of 4. The samples in red indicate the inner edges of each tile which have been repeated.

In the diagnostic mode, the bottom and left edge samples of each tile are colored red to help visualize the tiles. In the following diagnostic pictures of our grape, we have zoomed up from the rendered resolution. And we use min samples of -1, or every other pixel along an edge, to see a clearer visualization.

samples -1 0 resolution 8 8 task_size 4

samples -1 0 resolution 128 128 task_size 64

For each task, the render takes samples recursively until the tile is completed. Then, the render uses these samples to create image pixels. It filters samples into image pixels in the final stage of the task. The whole process repeats for the next task, creating the finished image a tile at a time. If you use distributed rendering, or have a multithreaded multiprocessor machine, it renders multiple tiles simultaneously across processors/threads.

Temporal Sampling/Motion Blur

For each spatial sample taken during adaptive sampling, mental ray may take a number of temporal samples, averaging them together for the result. That result is used for the contrast test.

In addition, mental ray offers another temporal sampling mode for fixed sample rates. It is referred to as "fast motion blur" in the documentation.

To see these details and more on motion blur, please go to the following resource page:

Filtering to pixels

After each tile has been sampled, we enter the filtering stage. Based on the filter choices, (eg, box, triangle, gauss, mitchell, lanczos), the filtering process converts samples into image pixels. The basic box filter will average all samples with equal weights, while the other filters will give more weight to samples nearer the center of the pixel. At samples 0 0, using the default filter box 1 1, the filter will average the four pixel corners. In the diagram below left, we use the cyan samples for pixel 5; below right, pixel 6. Our pixels are numbered from the bottom left, starting with 0.

The arguments after the filter name specify the extent, or size, of the filter in terms of pixels. This is why the default filter box 1 1 covers exactly one pixel. If we were to use filter box 2 2, the filter area would cover 2 pixels, or 1 pixel in each direction from the center of the pixel. Using samples 1 1 to clarify the box filter visualization for pixels 5 and 6:

But what if we need to filter pixel 0, or any other edge pixel? For those pixels, we actually have to take more samples on the edge in order to filter at that size. This means that extra lines of samples must be taken on each edge of the tile, and we should include them in our diagrams with filter sizes greater than 1 1.

Note that as filter window sizes increase greater than 1 1, the width over on the edge of the tile increases. At 2 2, above, you can see an extra half pixel wide edge; at 3 3 below, an extra 1 pixel wide edge; and at 5 5, an extra 2 pixel wide edge.

Because tiles overlap in this region, all samples there are taken twice. The thickness of the region grows with the filter size. In our 4 x 4 pixel tile, we indicate overlap samples in red below.

Also, make sure that the max samples number is not too high, as high max samples plus high filter sizes can quickly use a large number of points to calculate any given pixel. Here's an example using the filter size of 3 3 and samples increased to 2 2, showing the samples used to calculate a single pixel on the left, and the overlap samples for our 4 x 4 pixel tile on the right.

Also note that after sampling is finished, when there is a difference between min and max samples, a sample framebuffer may have sample gaps, some number of possible sample locations that are not filled. The filtering techniques weight the samples taking into account both the filter shape and these gaps.

Writing multipass sample buffers

Using the
  pass write "passfilename"
camera option, one can write a whole image worth of samples to disk for later use. These pass files include samples for all the tiles, so that there are redundant rows and columns of samples at adjoining tile boundaries. A useful message at the end of the render is printed about the size and characteristics of the pass. For example, here it is for our 8 x 8 grape image with a task size of 4, and max samples 0:
...
RC 0.2 info : pass file grape.pass: wrote 100 samples (44% empty, 42% black) in 4 rects
RC 0.2 info : rendering statistics
RC 0.2 info : type number per eye ray
RC 0.2 info : eye rays 56 1.00
...
Each quadrant has 4 x 4 pixels, or with max samples 0, 5 x 5 samples. That makes 25 samples times 4 tiles. So that is why the pass file message above indicates 100 samples written.

Accessing with multipass preprocess

Multipass sample files may be processed using the multipass preprocessing functionality. You must supply a function and use it with the pass prep statement. In your function, use the mi_renderpass_sample_get() function to access a sample.

If you create a multipass preproc function which uses mi_renderpass_sample_get() on a sample location gap, then at access time a sample is constructed out of the linear combination of the nearest corners.

Jittering

OK, with respect to the placement of the samples in the pixel corners, we lied, sort of. With jittering off, using the jitter 0 option, the samples are in the corners. However, when you turn on jittering with jitter 1, the sample locations aren't exactly in the corners of each subdivided space. Below we show the region for the jitter in the lower left sample of the lower left pixel in yellow.

We shift the sample locations by some deterministic offsets provided by complicated Quasi-Monte Carlo (QMC) algorithms. This means that the offsets will create sample patterns which do not look like regular grids, yet they are repeatable over renders. For each sample, this location stays within each subpixel region defined by the max samples density.

So far, we've shown the regions in a fixed sample image; now let's look at some adaptive sample examples. Note that because the size of the subpixel jitter region is defined by max samples, the min sample areas do not cover the whole image. Below left, we show the lower left pixel in yellow, with a box for each min sample region. Below right, with the same settings, we color the jitter regions for all the min samples.

Now as we adaptively add samples, each jittered sample lies somewhere within its subpixel region.

Technical Note: The floating point raster x and y values reflect the jittered location.

Sample Lock

Note that sample lock does not apply to the samples we are talking about here, ie, for the primary eye rays. It doesn't affect spatial or temporal sampling. Sample lock applies to the QMC patterns created for things such as area light sampling, etc.

Object samples

Now that you've got the basic idea, we can get even more sophisticated. For the pixels covered by each object, we have the ability to specify the min and max samples levels. In an .mi scene file, this is a flag on the object in the object definition block Let's take our grape example with samples -1 0 in the option block. If we put samples 0 0 in the object definition, our diagnostics image should show the entire grape as white, instead of just the contour. And if we decrease the overall samples to -2 -1, it will override the object samples. Allowing some range within the object with object samples -1 0, we get more samples in the grape, but some variation.

samples -1 0 object samples 0 0

samples -2 -1 object samples 0 0

samples -2 0 object samples -1 0

Up to now, you may have noticed we have not shown diagnostic images with levels greater than 0. That was before we discussed filtering just above. Now with a better understanding of filtering, we'll give it a try. By increasing the global samples range and the object samples range up to samples level 1, with a box 1 1 filter, we'll use up to 5 more samples per pixel, so we have more levels of gray in the diagnostic image.

samples -2 1 object samples 0 1 contrast 0.2 0.2 0.2

samples -2 1 object samples 0 1 contrast 0.1 0.1 0.1

samples -2 1 object samples 0 1 contrast 0.05 0.05 0.05

Notice that we increase sample density by decreasing contrast threshold. This is the recommended way to increase your sample densities.

Default object samples

We can also specify a default min and max samples levels for any point looking into the scene which does not hit an object with its per-object samples set. This includes rays not hitting any objects, as well as objects without per-object samples. We add default samples levels in the options block as a 3rd and 4th argument to samples statement, e.g.,
  samples -2 1 -2 0
Note that if there are no per-object samples, default samples has the same effect as changing overall samples. So specifying object samples defaults is really only useful in conjuction with per-object samples.

A per-object samples specification can override the default. More specifically, a higher per-object min or max will replace a lower default min or max. However, both the default and the object specific samples must be within the original min and max samples range.

samples -2 1 -2 0 object samples 0 0

samples -2 1 -2 0 object samples 0 1

samples -2 1 0 0 object samples 0 1

Also note that higher defaults can override the per-object samples:

samples -2 1 -2 0 object samples 0 0

samples -2 1 -2 1 object samples 0 0

samples -2 1 1 1 object samples 0 0

Additionally, for any given ray, the samples min/max will be the highest of any per-object samples min/max that it touches. And if the default limits are set, they, too are used as if they are one of the objects touched, so a higher default min/max will override any per-object min/max.

And with two objects in this scene, a cube and a plane, lit by a spot:

samples -2 1 -2 1 plane samples -2 1 cube samples -2 1

samples -2 1 -2 -1 plane samples 0 0 cube samples 1 1

If we reverse the plane and cube samples, we find out more about sampling. The diagnostic picture below left has a trace depth set to 0, while the one below right has a trace depth of 2. Because the surface of the cube is reflective, the eye rays bounce off the cube and hit the plane which has a samples 1 1 setting. On the right, only the rays hitting the top of the cube don't touch the plane object sampling of 1 1.

samples -2 1 -2 -1 plane samples 1 1 cube samples 0 0 trace depth 0

samples -2 1 -2 -1 plane samples 1 1 cube samples 0 0 trace depth 2