Scripting API

Editing smart components

from ArtisanPlugin.Scripting import SmartComponentApi

The accessory creators (BailApi, BangleApi, BeadApi, …) return plain object ids. SmartComponentApi gives you a handle on the result, so a component can be edited after it is created, take a preset, or be read back. This works from a script and through MCP, without opening its panel.

It covers Bail, Named pendant, Bangle, Bead, Charm, Link, Milgrain, Rope, Texture 3D and Engrave ring. Voronoi, Honeycomb and User element are not covered yet.

Finding them

Method	Returns
`Find(id)`	The handle for a component. For bails and named pendants the id can be any member of the group. Returns `None` when the id isn’t one of these components
`All()` / `Count()`	Every component of these kinds in the document
`Selected()`	Components with at least one member selected
`ByLayer(name)`	Components on a layer, by full path

The handle

A smart component has no typed setters. ISmartComponent edits the stored kernel model directly, the same JSON its panel saves:

Member	Does
`Component`	`Bail`, `NamedPendant`, `EngraveRing`, `Bangle`, `Bead`, `Charm`, `Link`, `Milgrain`, `Rope` or `Texture3D`
`ParametersJson`	The whole model, as JSON. Read it to discover the paths
`GetParameter(path)`	One value, or `None` when the path doesn’t exist
`SetParameter(path, value)`	Sets one value and regenerates
`SetParameters(json)`	Merges a JSON object into the model and regenerates once
`SetElement(name)`	Applies a saved element of the same component. A named pendant keeps its text

A path is dotted. You can write it in PascalCase (TopProfile.Width) or snake_case (top_profile.width). The value you set is converted to the type of the stored value, and an unknown path fails instead of being added silently. Numbers are always read and written with a . decimal separator, whatever the Windows language.

from ArtisanPlugin.Scripting import SmartComponentApi, Transaction

bail = SmartComponentApi.Find(bailId)
print(bail.Component, bail.GetParameter("top_profile.width"))

with Transaction.Begin("Edit the bail"):
    bail.SetParameter("diameter_top", "3.5")
    bail.SetParameters('{"TorusEnable": true, "TorusDiameter": 2.4}')

The ids stay the same when a component regenerates. Bails and named pendants rebuild their breps inside the same group, on the plane stored on their members. Link, Milgrain, Rope and Texture 3D rebuild on their plane, mother curve or surface. The pieces stay on the layer they were on.

From the MCP

MCP reaches these components as SMART_COMPONENT, with the same tools as any other parametric object:

list_objects lists them.
describe_object_parameters shows the current model and its paths.
edit_object edits by path, for example {"top_profile.width": 4.5}, or applies a preset with {"element": "BL001"}.
delete_objects deletes them.

In the Python package, this page corresponds to ra.smart_component.