Skip to content

Scripting API

Core Concepts

Every facade in ArtisanPlugin.Scripting follows the same conventions. Learn them once and the whole API reads the same way.

Facades and handles

The API is organized as static facade classes, one per area: GemApi, BezelApi, RingCurveApi, PricingApi, and so on. Facades do two things:

  • Query the active document (GemApi.All(), GemApi.Selected(), GemApi.Find(id)) — these return handles.
  • Create new objects (GemApi.Create(...)) — these also return a handle to what was just made.

A handle (IGem, IBezel, …) is a live view of one object in the document. It exposes read-only properties (Shape, CaratWeight, Position, LayerName) and mutation methods (Move, SetMaterial, Copy, Delete). Handles are intentionally narrow: they are the only thing a script can touch, and they never expose RhinoArtisan’s internal kernel objects. Every handle interface has its own page under Handles.

Transactions: undo as a unit

Wrap every mutating script in a Transaction with a descriptive name:

from ArtisanPlugin.Scripting import GemApi as gem, Transaction

with Transaction.Begin("Move 3 round diamonds down"):
    for g in gem.Selected():
        g.Move(Vector3d(0, 0, -1))

Everything inside the with block — Artisan calls and plain Rhino calls — becomes one undo step with that name. The user presses Ctrl+Z once and the whole scripted operation reverts. Read-only scripts (reports, measurements, price checks) don’t need a transaction.

The error contract

The API distinguishes two kinds of failure, and it matters for anything that shows messages to a user:

  • ArgumentException — you passed something invalid (unknown shape name, carat weight ≤ 0). The message is human-readable and safe to show as-is: "Unknown gem shape 'SQUIRCLE'."
  • Any other exception — something unexpected happened inside Artisan. These are bugs to report, not messages to relay.

Validate inputs with the discovery methods (Shapes(), Materials(), …) when you can, and let ArgumentException messages speak for themselves when you can’t.

Units and conventions

  • Sizes are in millimeters; gem sizes derive from carat weight through the same proportion tables the UI tools use.
  • Placement uses Rhino.Geometry.Plane — the plane’s origin is where the object goes and its Z axis is “up” for the object. Plane.WorldXY means “at the origin, flat”.
  • String parameters that map to fixed vocabularies (shapes, materials, metals) are case-insensitive and tolerate dashes/spaces ("rose-gold" → ROSE_GOLD).
  • Objects created by script land on the same layers the equivalent UI tool would use, with the same materials applied.