Apply design materials

from ArtisanPlugin.Scripting import RenderApi as render

The design materials are the flat, fast viewport look you model in: plain metal and plain stone colours that redraw instantly and let you read the geometry. You switch to them whenever you go back to working on the piece, and switch away with Apply render materials when you want a photoreal image. The two calls are the two halves of one switch — same enumeration, same attributes touched, different catalogue on the other end.

Usage

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

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

Gems, diamonds, gemstones without a reference, and certified and non-certified diamonds get the document-table gem material matching their compound. Pearls and cabochons get the pearl material — the same one used on the render side, since there is only one pearl material. Breps, extrusions, meshes and SubDs get the document’s Metal 1 material, unconditionally: on this side of the switch the Metal 02 and Metal 03 layers are deliberately ignored, so a three-metal design collapses to one colour in the viewport and only separates again under render materials. Everything else in the enumeration — curves, annotations, points — is visited and left alone.

For each object it touches it sets the attribute material source to material from object and assigns the material index, then redraws the views at the end.

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 or layers. Curves and annotations are in that total, as are gems whose gem object could not be read. Treat it as “the size of the sweep”, not as a change count.

Mutation and errors

This writes object attributes in the document, so it needs a Transaction if you want the whole sweep to collapse into a single undo step:

from ArtisanPlugin.Scripting import RenderApi as render, Transaction

with Transaction.Begin("Design materials"):
    render.ApplyDesignMaterials()

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.” before anything is assigned.

Unlike its counterpart, this call changes nothing outside the objects: render sampling and the render environment are left exactly as they are, so switching back to design materials does not undo the render settings that Apply render materials put in place.