Skip to content

Scripting API

Render Studio scene

from ArtisanPlugin.Scripting import RenderStudioApi as studio

The two methods behind clicking a tile in the ArtisanRenderAndAnimation panel: one sets the scene environment that lights and reflects the piece, the other drops a studio material onto objects. Both write to the Rhino document, which is what separates them from the Realtime Render viewer — the viewer’s SetViewerMaterial restyles a private copy of the scene inside the render window and leaves the document alone, whereas these two change the real thing and show up in the viewport, in a save, and in undo.

Both require a valid licence and an active document, and both take names from the catalogs.

Usage

from ArtisanPlugin.Scripting import RenderStudioApi as studio, Transaction

with Transaction.Begin("Stage the scene"):
    studio.ApplyEnvironment()                              # the studio default setup
    studio.ApplyEnvironment("Jewelry Studio")              # a named .renv
    studio.ApplyMaterial("Metals", "Yellow Gold 18k")      # onto the current selection
    studio.ApplyMaterial("Metals", "Platinum", objectIds)  # onto specific objects
    studio.ApplyMaterial("Grounds", "White Matte")         # onto the ground plane

Both return void. Both mutate the document, so wrap them in a Transaction if you want the staging to undo in one step.

ApplyEnvironment

studio.ApplyEnvironment(name = None)

Applies a scene environment as both the lighting environment and the reflection/refraction environment — exactly what clicking an Environment tile does. name is one of the strings from ListEnvironments(); matching ignores case and trims the argument.

name = None — and equally an empty or whitespace-only string — does not mean “leave the environment as it is”. It means the studio’s default setup: the 2Shapes environment for lighting, the diamond refraction environment, and a white ground plane. This is the state the panel puts the scene into before any render, so calling it with no argument is the reliable way to get a scene back to a known-good starting point rather than a no-op.

An unrecognised name throws before anything is changed:

ArgumentException: No environment named 'Foo'. Available: 2Shapes, Jewelry Studio, Softbox.

The available list is the same one ListEnvironments() returns, or (none installed) when the Environments folder is empty. With no active document you get InvalidOperationException("No active document.").

ApplyMaterial

studio.ApplyMaterial(family, name, objectIds = None)

family and name are both required and both come from the catalogs. What the call targets depends on the family.

Grounds targets the ground plane

If the resolved family is Grounds (case-insensitively), the material goes onto the render ground plane, not onto geometry: the background style is switched to Environment, the ground plane is enabled and taken out of shadow-only mode, and the material is assigned to it. objectIds is ignored entirely for this family — nothing needs to be selected, and passing ids does not skin them.

Every other family skins objects

For Metals, Gems, Misc and any custom family, the material is assigned to the objects you name, with MaterialSource set to material from object. It then propagates to every member of every group those objects belong to — the same behaviour as the panel, where dropping a metal on a ring shank re-skins the whole ring. If that is not what you want, ungroup first; there is no flag to switch it off.

objectIds = None — and an empty sequence — falls back to the current selection in the document, not to the whole document. If nothing is passed and nothing is selected, the call throws:

ArgumentException: Nothing selected: select (or pass) at least one object to receive the material.

Validation order

Everything that can be checked is checked before the document is touched, so a bad call leaves the scene exactly as it was: the licence, the active document, the family folder, an empty name, the material file, and finally the target list. The messages follow the catalog pattern —

ArgumentException: A material name is required (see ListMaterials()).
ArgumentException: No material named 'Foo' in family 'Metals'. Available: Platinum, Yellow Gold 18k.
InvalidOperationException: The material file could not be loaded: C:\...\Platinum.rmtl

The one check that happens inside the loop is the object id lookup: ArgumentException("No object with id {guid}."). Because it fires per object, a list where the fifth id is stale leaves the first four already skinned — another reason to keep the call inside a Transaction.

Side effects worth knowing

  • The lighting is repaired first. If the document has no lighting environment, or is still on Rhino’s stock Studio one, the studio default environment is applied before the material lands — the same guard the panel runs. A script that calls ApplyMaterial without ever calling ApplyEnvironment therefore still ends up with studio lighting.
  • The material is loaded once per document. Each material carries a tag in its Notes field built from the family and the name (METALS-YELLOW_GOLD_18K); later calls find it by that tag and reuse the existing RenderMaterial instead of adding a duplicate. Renaming or clearing that Notes tag by hand will cause a second copy to be added on the next call.
  • The views are redrawn at the end, so the change is visible immediately.