Apply render materials

from ArtisanPlugin.Scripting import RenderApi as render

The render materials are the photoreal ones: real metals and real gem shaders from the render catalogue, meant for a raytraced image rather than for modelling. You call this just before rendering, and go back with Apply design materials when you return to working on the piece. The two calls are the two halves of one switch — same enumeration, same attributes touched, different catalogue on the other end.

Usage

n = render.ApplyRenderMaterials()      # -> how many visible objects were visited

No arguments, and no selection is taken: this is global, exactly like the ArtisanApplyRenderMaterials command. It enumerates every visible object of every type in the active document (hidden objects are excluded) and walks the list once.

Gems, diamonds, gemstones without a reference, and certified and non-certified diamonds get the RenderMaterial from the render catalogue matching their compound; when the catalogue has no entry for that compound the object is left as it is. Pearls and cabochons get the ordinary design pearl material — the command uses the same pearl on both sides of the switch, so pearls look identical either way.

Breps, extrusions, meshes and SubDs are metal, and here — unlike on the design side — the layer decides which metal:

Object’s layer name	Metal used
Metal 02	the document’s metal 2
Metal 03	the document’s metal 3
anything else	the document’s metal 1

The name match is exact. A layer called Metal 2, or a sub-layer of Metal 02, falls into the last row and gets metal 1. This is the reason a two-tone piece reads as one colour in the viewport and correctly as two in the render.

Document-wide side effects

Beyond object attributes, this call also changes the document’s render settings, exactly as the command does:

• render sampling is forced on and set to 25 samples (UseDocumentSamples and Samples in the render settings user dictionary);
• on Rhino 8 and later, when there is no reflection environment set for rendering, or the active one is the stock “Studio” environment, the default 2Shapes environment is installed in its place. An environment you chose yourself is left alone.

Neither of these is reverted by Apply design materials; once raised, the sampling stays raised.

What the return value counts

The int is the number of visible objects enumerated, not the number actually re-materialised, and not a count of materials created. Curves, annotations and any object whose material could not be resolved in the catalogue are all in that total. Treat it as “the size of the sweep”, not as a change count.

Mutation and errors

This writes object attributes and render settings in the document, so wrap it in a Transaction for one-step undo:

from ArtisanPlugin.Scripting import RenderApi as render, Transaction

with Transaction.Begin("Render materials"):
    render.ApplyRenderMaterials()

It is a licensed call. With no document open it raises “No active document.”; with a document that has no objects at all it raises “There are no objects in the document.” — note that the render sampling and the environment are set before the object enumeration runs, so that error still leaves those settings changed.