fresnel.tracer

Overview

Path

Path tracer.

Preview

Preview ray tracer.

Tracer

Base class for all ray tracers.

Details

Ray tracers process a Scene and render output images.

  • Preview generates a quick approximate render.

  • Path which provides soft shadows, reflections, and other effects.

See also

Tutorials:

class fresnel.tracer.Path(device, w, h)

Bases: Tracer

Path tracer.

Parameters:

  • device (Device) – Device to use.

  • w (int) – Output image width.

  • h (int) – Output image height.

The path tracer applies advanced lighting effects, including soft shadows, reflections, and depth of field. It operates by Monte Carlo sampling. Each call to render performs one sample per pixel. The output image is the mean of all the samples. Many samples are required to produce a smooth image. sample provides a convenience API to make many samples with a single call.

reset()

Clear the output buffer.

Start sampling a new image. Increment the random number seed so that the new image is statistically independent from the previous.

sample(scene, samples, reset=True, light_samples=1)

Sample the image.

Parameters:

  • scene (Scene) – The scene to render.

  • samples (int) – The number of samples to take per pixel.

  • reset (bool) – When True, call reset before sampling

  • light_samples (int) – The number of light samples per primary camera ray.

As an unbiased renderer, the sampling noise will scale as \(\frac{1}{\sqrt{\text{total_samples}}}\), where total_samples is samples*light_samples.

The samples parameter controls the number of samples from the camera (depth of field and antialiasing). light_samples is the number of rays shot from the first intersection of the primary camera ray.

Using (samples=N, light_samples=1) would have an equal number of camera and lighting samples and would produce an excellent image. Using (samples=N // M, light_samples=M) (where M is some integer 10-100) will similarly produce a similarly good image, provided N >> M, and may have better performance. On the GPU, using light_samples > 1 can boost performance moderately. On the CPU, it can boost performance slightly due to improved cache coherency.

Returns:

A reference to the current output buffer.

Return type:

ImageArray

Note

When reset is False, subsequent calls to sample will continue to add samples to the current output image. Use the same number of light samples when sampling an image in this way.

class fresnel.tracer.Preview(device, w, h, anti_alias=True)

Bases: Tracer

Preview ray tracer.

Parameters:

  • device (Device) – Device to use.

  • w (int) – Output image width.

  • h (int) – Output image height.

  • anti_alias (bool) – Whether to perform anti-aliasing. If True, uses an 64 samples.

Overview

The Preview tracer produces a preview of the scene quickly. It approximates the effect of light on materials. The output of the Preview tracer will look very similar to that from the Path tracer, but will miss soft shadows, reflection, transmittance, depth of field and other effects.

Anti-aliasing

The default value of anti_alias is True to smooth sharp edges in the image. The anti-aliasing level corresponds to aa_level=3 in fresnel versions up to 0.11.0. Different seed values will result in different output images.

property anti_alias

Whether to perform anti-aliasing.

Type:

bool

class fresnel.tracer.Tracer

Bases: object

Base class for all ray tracers.

Tracer provides operations common to all ray tracer classes.

Each Tracer instance stores a pixel output buffer. When you render a Scene, the output is updated.

Note

You cannot instantiate Tracer directly. Use one of the subclasses.

disable_highlight_warning()

Disable the highlight clipping warnings.

enable_highlight_warning(color=(1, 0, 1))

Enable highlight clipping warnings.

When a pixel in the rendered image is too bright to represent, make that pixel the given color to flag the problem to the user.

Parameters:

color (tuple) – Color to make the highlight warnings.

histogram()

Compute a histogram of the image.

The histogram is computed as a lightness in the sRGB color space. The histogram is computed only over the visible pixels in the image, fully transparent pixels are ignored. The returned histogram is nbins x 4, the first column contains the lightness histogram and the next 3 contain R,B, and G channel histograms respectively.

Returns:

(histogram, bin_positions).

property linear_output

Reference to the current output buffer in linear color space.

Note

The output buffer is modified by render and resize.

Type:

Array

property output

Reference to the current output buffer.

Note

The output buffer is modified by render and resize.

Type:

ImageArray

render(scene)

Render a scene.

Parameters:

scene (Scene) – The scene to render.

Returns:

A reference to the current output buffer as a fresnel.util.ImageArray.

Render the given scene and write the resulting pixels into the output buffer.

resize(w, h)

Resize the output buffer.

Parameters:

  • w (int) – New output buffer width.

  • h (int) – New output buffer height.

Warning

resize clears the output buffer.

property seed

Random number seed.

Type:

int