options

Class

options

Synopsis
This node is used to set various global attributes which control the rendering of the scene.

 



AA_samples

Called Camera (AA) Samples in the plugins.

Supersampling control over the number of rays per pixel that will be traced from the camera. The higher the number of samples, the better the anti-aliasing quality, and the longer the render times. The exact number of rays per pixel is the square of this value. For example, a Camera samples value of 3 means 3x3 = 9 pixel samples. In practice, you may consider using a value of 4 for medium quality, 8 for high quality, and (rarely) 16 for super-high quality. This control acts as a global multiplier of all the different rays, multiplying the number of Diffuse and Glossy rays. Motion blur and depth of field quality can only be improved by increasing Camera samples.

Camera samples multiplies Diffuse, Glossy, and light samples after being squared.
For example, 6 Camera samples and 6 Glossy samples = 62 x 62 = 1296 rays per pixel for the Diffuse, and another 1296 rays per pixel for the indirect glossy specular. Therefore when you increase the Camera samples to get better geometric anti-aliasing, you should decrease the others to compensate.


AA_seed
The AA_seed by default is set to the current frame number, so the noise changes at every frame, like film grain. This can be locked so the sampling noise won't change.
AA_sample_clamp
If enabled, this control will clamp pixel samples to this specified maximum value. This can make it easier to anti-alias certain high-dynamic range effects such as bright motion blurred specular streaks (at the cost of reduced contrast). What is clamped is the resulting output value of the renderer computations of each pixel sample. Example: If the Max Clamp Value is set to 2, no pixels will have an RGB value greater than 2.0, 2.0, 2.0


AA_sample_clamp_affects_aovs
With this control enabled the pixel samples of the AOVs will also be clamped. AOV clamping will affect every RGB and RGBA (except the A component) AOV. Currently, there is no way to tell Arnold which AOV's to clamp and which ones to preserve.
threads
Number of threads used for rendering. Set it to zero to autodetect and use as many threads as cores in the system. Negative values indicate how many cores to not use, so that -3, for instance, will use 29 threads on a 32 logical core machine.  Negative values are useful when you want to reserve some of the CPU for non-arnold tasks.
pin_threads
Arnold can pin threads on linux so they don't jump between multiple processors. This can improve scalability in modern machines multiple processors. It can be set to off, on or auto. By default is set to auto, meaning that if the number of threads is more than half the number of logical cores on the machine, arnold will pin the threads.

If client code, for instance a custom shader, spawns their own threads manually (with pthread_create or similar), these threads will inherit the same thread affinity, which totally breaks the point of spawning threads; in these situations they can either set options.pin_threads to off or they can create their threads with the Arnold API AiThreadCreate() which will un-pin the created thread.


abort_on_error
Rendering will abort as soon as an error is detected. This is the recommended setting. In general, you should not ignore important error messages, or you'll risk crashes, rendering artifacts and undefined behavior.
abort_on_license_fail
If set, rendering will stop if the license is not detected when the render begins.
skip_license_check
Switch this on to avoid taking an Arnold license from the license server. This will always render your image with a watermark.
error_color_bad_texture
The color to display if there is an error reading a texture or it doesn't exist.
error_color_bad_pixel
The color to display if the pixel returned to the render is a NaN (Not a Number).
error_color_bad_shader
The color to display if there is a problem with the assigned shader or no shader is assigned.
outputs
An string array that associates AOVs (Arbitrary Output Variables) with corresponding output drivers and filters.
xres
Horizontal resolution of the rendered image.
yres
Vertical resolution of the rendered image.
region_min_x, region_min_y, region_max_x, region_max_y 
These define the 2d window in the projection plane that will be rendered. If set to their default (-1,-1) (1,1) the frame will exactly match with the defined region, after taking aspect_ratio into account so that there is no distortion. These should be set if you want to stretch, squash or zoom to a particular area in image.
aspect_ratio
This sets the pixel aspect ratio defined as pixel height divided by pixel width. Note that this is the inverse of the way it is defined for Nuke, OpenEXR and other applications.
bucket_size
The size of the image buckets. The default size is 64x64 pixels, which is a good compromise; bigger buckets use more memory, while smaller buckets may perform redundant computations and filtering and thus render slower but give initial faster feedback.
bucket_scanning
Specifies the spatial order in which the image buckets (i.e. threads) will be processed. By default, buckets start in the center of the image and proceed outwards in a spiral pattern. 


buckets
Specifies a list of buckets to use when bucket_scanning is set to list. Each element in the array corresponds to any 2d point inside the bucket you want to render next.
ignore_textures

Ignore all textures when rendering.

ignore_shaders
Ignore all shaders when rendering, Arnold will render with a simple "N dot eye" shader instead.


ignore_atmosphere
Ignore atmospheric shaders. 


ignore_lights
Ignore all light sources.


ignore_shadows
Don't perform shadow calculations.


ignore_direct_lighting
Ignore all direct light sources.
ignore_subdivision
No objects will be subdivided. This parameter is not interactive.


ignore_displacement
Displacements will be ignored. This parameter is not interactive.


ignore_bump
Ignore bump mapping.


ignore_motion_blur
Ignore motion blur. This can be useful for debugging problematic scenes with motion blur. When ignore motion blur is enabled, Arnold will use the geometry state defined by the reference_time parameter (located in the options node as well and in the range of 0-1).


ignore_dof
Ignore Depth of Field computation.


ignore_smoothing
Polygon normals will not be smoothed, resulting in a faceted appearance. This parameter is not interactive.


ignore_sss
Ignore Subsurface scattering.


ignore_list
---
shader_override

Global shader override which allows you to override the shader for all objects in the scene.

auto_transparency_mode
auto transparency mode controls when Arnold applies automatic ray continuation. The default value: "always"means that Arnold will automatically compute transparency for both primary, secondary and shadow rays. Setting the mode to "never" allows for quickly disabling all transparency in the scene, regardless of how it was set up. Finally, with "shadow-only"only shadow rays will track several hits at once.
auto_transparency_depth

The number of allowed transparency hits. With 0 objects will be treated as opaque. The example below consists of six glass cubes that are sitting on top of each other. Arnold returns black when there is an insufficient number of rays due to the limit imposed by the Transparency Depth. Increasing this value allows more rays to pass through the transparent surfaces. In this case a Transparent Depth of 12 is enough to get a good result.

auto_transparency_threshold
Defines at which point the accumulated opacity can be considered as opaque. This optimization parameter is designed to save computations when an object tagged as transparent has large areas that are nearly opaque.


texture_max_open_files
The maximum number of files that the texture system keeps open at any given time to avoid excessive closing and re-opening of files when caching individual texture tiles. Increasing this number may result in slightly better texture caching performance. On the other hand, if this value is higher than the maximum number of concurrently open files supported by the operating system (e.g. Linux vs Windows), some texture lookups may fail and return red. This is set by default to 0, which means that the maximum number of texture files that can be simultaneously opened is automatically computed by Arnold using a heuristic that tries to guess what the optimal number would be for each particular machine. We expect that the majority of users will be able to leave this at 0 and get the best performance.
texture_max_memory_MB
The maximum amount of memory to be used for texture caching. Arnold uses a tile based cache with a LRU (Least Recently Used) type algorithm, where the least recently used tiles are discarded when the texture caches is full.
texture_per_file_stats
Enables useful per texture statistics, with time spent on textures queries, amount of texture data read, memory consumption, etc.
texture_searchpath
Defines a location to search for textures.
texture_automip
If a texture map file is not natively mipmapped (e.g. a JPEG file), enabling this option will trigger the generation of a mipmap on demand. The output will be stored in memory and put in the global texture cache. This mipmap generation increases render time, specially for scenes with many high resolution textures. To avoid this performance slowdown, it is recommended to use texture file formats that natively support mipmapping (such as TIFF and EXR), where the mipmaps are preprocessed before the render and stored in the file. This preprocessing can be done with the maketx utility.
texture_autotile
If a texture map file is stored in scanline mode (e.g. a JPEG file), enabling this option will trigger the generation of tiles on demand. The output will be stored in memory and put in the global texture cache. This process increases render time, specially for scenes with many high resolution textures. To avoid this performance slowdown, it is recommended to use texture file formats that natively support tile mode (such as TIFF and EXR). You can create tile textures with the maketx utility.
texture_accept_untiled
High-resolution untiled texture maps are very inefficient to render, because they must be loaded entirely into memory as soon as the renderer needs to access the first texel. When this flag is disabled, any attempt at loading an untiled file will produce an error and abort the renderer.
texture_accept_unmipped
High-resolution unmipped texture maps are very inefficient to render, because the highest resolution level must be loaded into memory regardless of the distance rather than a lower resolution level. When this flag is disabled, any attempt at loading an unmipped file will produce an error and abort the renderer.
texture_failure_retries
When opening or reading a tile from a texture fails, Arnold's texture system will pause and try again, up to the texture_failure_retries value before returning a failure. This is meant to address spooky disk or network failures. The default is zero, meaning that failures of open or tile reading will immediately return as a failure.
texture_conservative_lookups
Determines the texture filter width policy. It will err on the side of softer texture look-up
texture_glossy_blur
Blurring of texture for lookups by glossy rays. When using the Cook-Torrance BRDF, textures are automatically blurred and this parameter is ignored.
texture_diffuse_blur
Controls the amount of blur in texture look-ups for Diffuse rays.
texture_sss_blur
Controls the amount of blur in texture look-ups in the context of sss
texture_max_sharpen
texture_max_sharpen is used to improve the quality of textures so that they do not appear blurry. As texture_max_sharpen is increased, textures lookups occur from higher res mipmap levels. The theoretical optimal value of texture_max_sharpen is to set it to AtOptions::AA_samples. The reason we do not have it set to this by default is that querying the higher res mipmap levels also results in an increase in texture data that must be read into arnold. This can be an issue when there are GBs of textures being read in. Instead, we allow the tradeoff for slightly blurrier textures to be used in exchange for substantial savings in texture data read. The default setting of texture_max_sharpen=1 will often appear slightly blurry. Setting it to around 1.5 will result in significantly sharper textures which in most cases are almost indistinguishable from the optimal setting. In some situations, even higher quality textures might be required and so higher values should be used. Since using a value larger than AtOptions::AA_samples is not a good idea since aliasing will occur, we clamp values larger than this to AA_samples. This can be used to your advantage if you always want the highest quality settings to be used; just set texture_max_sharpen to an extremely large value, such as 9999, so that it will always end up being clamped down to AA_samples.
camera
The name camera to be used for rendering.
background
The name of the shader to be evaluated as background for rays that don't hit any geometry.
background_visibility
Defines the Background visibility mask 
atmosphere
The name of the shader to be evaluated for the global atmosphere evaluation.
bump_multiplier
A global scaling value useable by bump mapping shaders
luminaire_bias
---
low_light_threshold

Raising this value can speed up rendering by allowing Arnold to ignore tracing a shadow ray for light samples whose light contribution is below a certain value. For many scenes, a slightly higher threshold can offer significant rendering speed increases without noticeably darkening the image.


In the example below, increasing the Low Light Threshold to 0.1 shows a good speedup in render time with little noticeable difference in the image.

Low Light Threshold 0.01 (11 mins 43 secs) vs Low Light Threshold 0.1: 3 mins 28 secs (rollover image).

 

However, increasing the Low Light Threshold value too much can have an adverse effect on the lighting:

shadows_obey_light_linking
Defines if for shadow linking the shadow_group from the shapes is used instead of the light_group.
skip_background_atmosphere
Doesn't apply the atmosphere shader in the background.
GI_sss_samples

This value controls the number of lighting samples (direct and indirect) that will be taken to estimate lighting within a radius of the point being shaded to compute sub-surface scattering. Higher values produce a cleaner solution, but will take longer to render.

Some additional noise in indirect glossy and Diffuse GI originating from an object with SSS is expected, in particular if the Diffuse samples setting is set lower than the SSS samples setting. To combat this type of noise you can try using higher Camera settings and lower Glossy, Diffuse and SSS sampling rates or increase the Diffuse/ Glossy samples. Increasing the SSS samples will only make the subsurface effect have less noise in camera, reflection and refraction rays.

In the images below you can see that there is noise in the darker areas of the eye socket. Increasing the Diffuse samples will reduce this type of noise.

GI_volume_samples
Controls the number of sample rays that get fired to compute indirect lighting of the volume. Like the other sampling rate controls (Camera, light samples, Diffuse samples, etc), the number of actual samples is squared, so a setting of 3 fires 3x3=9 rays. Setting it to 0 turns off indirect lighting of the volume. Note that indirect volume lighting is tied to the 'Volume' ray depth render option and therefore there must be at least 1 Volume bounce for indirect lighting to be computed.


reference_time
When disabling motion blur with ignore_motion_blur, the time specified by reference_time will be used instead of the shutter open time. This time is mapped on [0,1] with 0 being shutter open and 1 the shutter closed.
CCW_points
Defines if the points in triangles of a polymesh are defined clock or counterclockwise
max_subdivisions
A global override for the maximum polymesh.subdiv_iterations
procedural_searchpath
Defines a location to search for procedurals.
shader_searchpath
Defines a location to search for shaders. Required if importing .ass files from other plugins.
preserve_scene_data
---
curved_motionblur
Interpolation between two transformation keys now accounts better for rotation. This improvement is very obvious when rotating a propeller blade by close to 180º, since now the blade properly follows the curved path. Note that only angles of up to 180º will be interpolated, so blurring a 360º rotation (or more), will still take multiple keys. However, the number of keys required can now be greatly reduced (this option may become the default for motion blur in the future).

display_driver
This is the output gamma applied to the render region/renderview.


texture_gamma
Applies an inverse gamma correction to texture lookups. For example, a value of 2.2 will linearize a texture that comes in with a gamma of 2.2. This is done for 8 and 16 bit images.


light_gamma
Applies an inverse gamma correction to the light color swatches. This should only be set to 2.2 in DCC software such as Maya which will not allow you to gamma correct the color swatch widgets.


shader_gamma
Applies an inverse gamma correction to the shader parameters of color type that are not connected.


GI_diffuse_depth

Defines the maximum ray diffuse depth bounces. Zero diffuse is equal to disabling Diffuse illumination. Increasing the depth will add more bounced light to the scene, which can be especially noticeable in interiors. You may notice subtle differences when increasing the diffuse bounces incrementally. For example the top of the cube has no light on it with Diffuse set to 1, whereas it is visible with Diffuse set to 2.

Below is an example showing the dramatic difference that diffuse ray depth can have in a scene. Note the effect of the bounced light on the floor behind the door when rendering with ray depth 2 compared to ray depth 1 and 0.

We can clearly see a difference in the appearance and render time when increasing the ray depth in the production interior scene below:

The current Arnold code will only take one random sample after a split has happened in the ray tree, causing the regions behind glossy refractions/reflections and Diffuse to have much fewer shadow samples than those that are viewed directly by the camera. Splitting occurs after the first bounce.

Diagram showing how diffuse rays are propagated in an Arnold render.

You can see the effect that increasing the diffuse ray depth has on the number of rays per pixel and how that impacts render time by checking the render log. 

Rendering using the 'raycount' aov shows the total number of rays that are created/traced to compute a certain pixel (diffuse, glossy and shadow rays are shown). 

Images rendered using the 'builtin' 'raycount' aov

 

GI_glossy_depth

Defines the maximum number of times a ray can be glossily reflected. Scenes with many glossy reflective surfaces may require higher values in order to look correct. A minimum value of 1 is necessary to get any glossy reflections. 

GI_reflection_depth
Defines the maximum number of times a ray can be reflected. Scenes with many reflective surfaces may require higher values in order to look correct.

The example below is an internal reflection test. The scene is very simple and consists of a point light positioned at the end of a cube that has a high reflection value assigned to it. When the reflection depth value is raised, the number of reflections increase. The total ray depth must also be increased in order to match the reflection depth values (the maximum total depth value is 256).  

Point light positioned at the end of a cube with a highly reflective material assigned to it


GI_refraction_depth
The maximum number of times a ray can be refracted. Scenes with many refractive surfaces may require higher values in order to look correct. 

Glass surface with double sided thickness.


GI_total_depth
Specifies the total maximum recursion depth of any ray in the scene (Diffuse + Reflection + Refraction + Glossy <= Total).
GI_diffuse_samples

Called Diffuse Samples in the plugins.

Controls the number of rays fired when computing the reflected indirect-radiance integrated over the hemisphere. The exact number of hemispherical rays is the square of this value. Increase this number to reduce the indirect diffuse noise. Remember that the diffuse sampling is done for each AA sample, so high values for both AA Samples and Diffuse samples will tend to result in slow renders.

When Diffuse samples are more than zero, camera rays intersecting with diffuse surfaces fire indirect diffuse rays. The rays are fired in random directions within a hemispherical spread. Noise is introduced when there are insufficient rays to resolve the range of values from the environment.

Increasing the number of Diffuse samples will increase the number of diffuse rays fired from a point: 

Indirect Diffuse Ray sampling & Indirect Diffuse Noise


The table below shows the effect of increasing the number of Diffuse samples (GI_diffuse_samples) to resolve indirect diffuse noise:

Diffuse samples (GI_diffuse_samples): 1 2 4 6. Render time: 131 156 271 427

This shows the performance impact when increasing the number of Diffuse samples (GI_diffuse_samples). Because indirect diffuse rays are so prevalent, this can get expensive. In this example, the performance hit from 1 to 6 samples was over 320%.  

Indirect diffuse noise

This is one of the most common causes of noise, and can have a number of different sources. It manifests as granularity in the scene, usually in shadowed areas. 

There are a couple of different methods to determine indirect diffuse noise. If you've rendered AOV's you can check the indirect diffuse AOV; if noise is present in this AOV only, you can be quite certain this raytype is responsible. You can check if an area of noise is created by indirect diffuse noise by turning Indirect Diffuse samples to zero; this will effectively turn off indirect diffuse. If this raytype is responsible then the noise will disappear. If the image darkens with the indirect diffuse gone, but the noise is still present, indirect diffuse rays are not responsible for the noise.

In the example below a directional light is pointing into an enclosed space. With Diffuse samples set to 0, no light is able to bounce off of the surfaces and therefore there is no indirect light in the scene. Increasing the Diffuse samples to 1 allows diffuse rays to bounce around the scene. However it produces a noisy result, especially in the corners of the scene. Increasing the Diffuse samples to 3 gives an improved result. It is good practise to use this value sparingly. Increase it incrementally and see if you notice any difference in the quality of the indirect diffuse component.

Remember that the Diffuse sampling is done for each AA sample, so high values for both AA Samples and Diffuse Samples will tend to result in slow renders.

GI_single_scatter_samples
The number of samples taken to compute the result of the API function AiSSSTraceSingleScatter() is controlled linearly by this parameter.
GI_glossy_samples
Controls the number of rays fired when computing the reflected indirect-radiance integrated over the hemisphere weighted by a specular BRDF. The exact number of rays is the square of this value. Increase this number to reduce the indirect specular noise (soft/blurry reflections). Remember that the glossy sampling is done for each Camera (AA) sample, so high values for both Camera samples and Glossy samples will tend to result in slow renders.

Diagram showing how glossy reflection rays are propagated in an Arnold render

 

In the example below the floor surface has high specular and roughness values. In the image on the left you can see that there are not enough Glossy samples and therefore there is noise in the floor. Increasing the Glossy samples gives a better result.

If you reduce the number of Glossy samples to zero and the Glossy ray depth to zero and the noise disappears, then the noise is due to specular reflections.

GI_refraction_samples
Controls the number of samples used to simulate the microfacet-based glossy refraction evaluations. Increase this value to resolve any noise in the refraction.

If you switch this parameter to zero, the GI_refraction_depth to zero and the noise disappears, you will know that the noise is due to glossy refractions.

Diagram showing how glossy refraction rays are propagated in an Arnold render

 

Glossy Ray Sampling and Reflection/Refraction Noise

While it is normally a straightforward matter to determine whether it is a glossy reflection or refraction causing the noise, we need to confirm that glossy rays are responsible for a given type of noise: If you've rendered AOV's you can check the indirect diffuse AOV; if noise is present in this AOV only, you can be quite certain this raytype is responsible. Also, you can switch the GI_glossy_samples and GI_refraction_samples and glossy depth types to zero in the Arnold Render Settings. Again, this essentially turns off glossy rays. If the glossy rays are responsible, the noise will disappear with this test. If the glossy component disappears but the noise is still there, glossy rays are not responsible.

 

GI_falloff_start_dist
---
GI_falloff_stop_dist
---
enable_displacement_derivs
---
enable_threaded_procedurals
---
enable_procedural_cache
---
procedural_force_expand

Forces load_at_init to true on every procedural.

Saving the resulting scene as an ass file with AiAssWrite will not preserve the inherited attributes of nodes inside the procedural.

 

GI_volume_depth

This parameter sets the number of multiple scattering bounces within a volume (defaults to 0). This is useful when rendering volumes such as clouds for which multiple scattering has a large influence on their appearance.

enable_fast_opacity  

This can be enabled to get faster textured mapped opacity mask renders, such as for tree leaves. This flag also toggles a fix for more accurate renders, where previously the object would be rendered more transparent when further away from the camera. When using this option, noise/flicker can occur on far away geometry, similar to when rendering far away high res geometry. If this happens, it is best to use a high amount of AA samples (and correspondingly lower amount of diffuse/glossy/light samples) to reduce flickering in animation. The fast opacity flag is enabled for anything that is connected to any RGB parameter called "opacity", so custom shaders that have an RGB opacity parameter will benefit from this.



 

  • No labels