Skip to content

Scripting API

Getting Started

Your first RhinoArtisan script is five lines away. All you need is Rhino, RhinoArtisan and the Python editor that ships with Rhino — no extra installs, no configuration. You can also run your scripts from Flow Studio inside RhinoArtisan, but this guide sticks to the plain Python editor.

Your first script

Open Rhino’s Python editor (EditPythonScript) with RhinoArtisan loaded, and run:

from Rhino.Geometry import Plane
from ArtisanPlugin.Scripting import GemApi as gem, Transaction

with Transaction.Begin("Add a one-carat round diamond"):
    g = gem.Create("ROUND", "Diamond", 1.0, Plane.WorldXY)

print("Created %s %s of %.2f ct (%.2f mm)" % (g.Shape, g.Material, g.CaratWeight, g.SizeX))

That’s the whole pattern:

  1. Import the facade you need from ArtisanPlugin.Scripting (short aliases like gem, bezel, pricing keep scripts readable).
  2. Wrap mutations in a Transaction so the user can undo the whole operation in one step. Read-only calls don’t need one.
  3. Work with the returned handle — Create returns an IGem you can move, resize, copy or delete later.

Reading before writing

Most facades offer discovery methods that return the exact strings their creation methods accept. Use them instead of guessing:

from ArtisanPlugin.Scripting import GemApi as gem
print("Shapes: " + ", ".join(gem.Shapes()))
print("Materials: " + ", ".join(gem.Materials()))

A more complete example

Stones distributed along a selected curve — the classic pavé starting point:

import rhinoscriptsyntax as rs
from Rhino.Geometry import Plane
from ArtisanPlugin.Scripting import GemApi as gem, Transaction

curves = rs.SelectedObjects()
if not curves:
    print("Select a curve first.")
else:
    points = rs.DivideCurve(curves[0], 20)
    with Transaction.Begin("Pave 20 round diamonds along curve"):
        for p in points:
            gem.Create("ROUND", "Diamond", 0.02, Plane(p, Plane.WorldXY.ZAxis))

The Scripting API composes naturally with rhinoscriptsyntax and Rhino.Geometry: use Rhino for raw geometry (curves, points, math) and Artisan facades for everything jewelry-aware.

Things to know about the Python host

  • Scripts run on IronPython 2.7: there are no f-strings (use % formatting), and integer division truncates (use float(...) when interpolating).
  • Don’t call Views.Redraw() — Artisan mutations already redraw the viewport.
  • Avoid interactive prompts (rs.GetPoint, rs.GetObjects) in automated scripts; work from the current selection instead.

Next steps