Elements

from ArtisanPlugin.Scripting import ElementsApi as elements

An element is a named preset that a panel saves with its Save as element button: a bezel called “Chunky”, a basket called “Client A”, or one of the factory presets such as BA001 (baskets) and BL001 (bails). Scripts can use elements in four ways:

1. Build from one. Most creators take an element= argument.
2. Apply one to an object that already exists, with SetElement on its handle.
3. Save an object as a new element.
4. Organize the library: rename, duplicate, mark favorites, delete, and export or import bundles.

Elements belong to the user’s library, not to the document. Saving, renaming or deleting one changes that library and does not touch the 3dm file.

Browsing the library

Method	Returns
Types()	The element types the library can hold: Basket, Bail, Bezel, Classic, Halo, Peghead, SmartProfile…
List(type)	The saved elements of one type, each with Id, Name, Type and Favorite
Count(type)	How many elements of that type are saved
Find(type, name)	One element by name (case-insensitive). If the name doesn’t match, the error lists every available name, so a script or an assistant can correct itself
GetParametersJson(type, name)	The stored parameters, as JSON. Use it to inspect a preset; creators take the preset by name

from ArtisanPlugin.Scripting import ElementsApi as elements

for e in elements.List("Basket"):
    print(("* " if e.Favorite else "  ") + e.Name)

Build from a preset

The creators below accept element as their last argument:

Family	Creators
Shanks	ClassicApi, CathedralApi, GraduatedApi, BypassApi, EternityApi, SplitShankApi, SignetRingApi, AdvancedCathedralApi, AdvancedRingApi, ClassRingApi, PaveShankBuilderApi, TwoRowsShankBuilderApi, MatchingShankBuilderApi, WeddingBuilderApi (wedding band), RingCurveApi
Gemsets	BasketApi, AdvancedBasketApi, BezelApi, AdvancedBezelApi, HaloApi, ClusterApi, PegheadApi, TrilogyApi
Components	BailApi, BangleApi, BeadApi, CharmApi, NamedPendantApi, SmartProfileApi

The preset replaces the creator’s starting model, including your saved defaults. The creator then re-applies the call’s own context (the mother gem, the ring size, the curve or the mother rings), and any argument you pass explicitly still overrides the preset:

from ArtisanPlugin.Scripting import BasketApi as basket, Transaction

with Transaction.Begin("Basket from a preset"):
    b = basket.Create([gemId], element = "Client A", prongDiameter = 0.9)[0]

When you omit element, the creator behaves as it always did. Types without an element argument cannot be built from a preset: Huggie, Link, Trellis, Wedding Rings, Advanced Signet Ring and the legacy types.

Apply a preset to an existing object

25 handles have SetElement(name): every shank and gemset handle that can be built from a preset, plus IAdvancedSignetRing, ITrilogy, ISmartProfile and ISmartComponent (bails, bangles…). The preset’s parameters replace the object’s current ones. The object keeps what belongs to it, such as its gem, every finger-size copy, its mother rings or its curve, and regenerates in place with the same id.

from ArtisanPlugin.Scripting import HaloApi as halo, Transaction

with Transaction.Begin("Apply the Chunky halo"):
    for h in halo.Selected():
        h.SetElement("Chunky")

A trilogy picks the element type from its own style and keeps its gems. A named pendant keeps its text.

Save an object as a new element

info = elements.SaveFromObject(objectId, "Client B")   # -> ElementInfo

This is the panels’ Save as element button. objectId can be the object itself or any member of a parametric group, so a bail, basket or halo can be saved from any of its pieces, and smart components without a typed handle can be saved too. The name must be new within its type. No preview image is stored.

Organizing the library

Each method picks the element by type and name, where name can also be "id:<guid>". Names stay unique within a type.

Method	Does
Rename(type, name, newName)	Renames it
Duplicate(type, name, newName = None)	Copies it. An empty newName gives "<name> (Copy)". The copy shares the original’s preview
SetFavorite(type, name, favorite = True)	Marks or unmarks it as a favorite. Favorites list first
Delete(type, name)	Deletes it permanently
ExportBundle(type, name, filePath)	Writes a .zip bundle with the parameters and preview, to share the element or move it to another machine. Returns the path
ImportBundle(filePath)	Reads a bundle (from ExportBundle or the panels) into the library. Returns the imported element

From the MCP

AI assistants have the same features through MCP:

• list_elements browses the library.
• element is an argument of about 25 create_*/add_* tools.
• edit_object {"element": name} applies a preset.
• save_element stores an object as a new element.
• manage_elements renames, duplicates, sets favorites, deletes, exports and imports.

See the tool reference.

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