Document

from ArtisanPlugin.Scripting import DocumentApi as docapi

Everything that acts on the document as a whole: getting designs in, getting them out, and the global switches you see at the top of the Outliner. Deliberately dialog-free — anything that would prompt fails with a clear error instead, so the whole surface works headless.

The page follows the order of a headless run — open a design, save or export it, and the global parameters you change in between.

docapi.Open(r"C:\designs\halo.3dm")     # open a design...
docapi.SetMetal("GOLD_ROSE_18")         # ...tweak it...
docapi.Save(r"C:\out\halo-rose.3dm")    # ...save a copy
docapi.Stl(r"C:\out\halo.stl")          # ...and a printable mesh

Open

Getting a document in front of you — and knowing what you are about to lose.

• OpenOpen a 3dm, dialog-free.
• InspectThe document's path and unsaved-changes state.
• NewA fresh document, from the default or your own template.

docapi.Open(r"C:\designs\halo.3dm")        # fails on unsaved changes...
docapi.Open(path, discardChanges = True)   # ...unless you discard explicitly

Parameter	Default	Meaning
path	—	The 3dm to open
discardChanges	False	Throw away unsaved changes instead of failing

Inspect

The pre-flight checks before switching files — read-only:

docapi.GetPath()                     # full path, or "" for an unsaved document
docapi.IsModified()                  # unsaved changes?

New

docapi.New()                         # default template; template = a .3dm path

Save & Export

Getting the design back out — as a 3dm you keep working on, or as one of the three delivery formats.

• SaveSave in place, or Save As to a new path.
• STLBinary STL for 3D printing — everything visible or the selection.
• Report PDFA layout page to 300-dpi PDF, vector where possible.
• GLBThe whole document to GLB, viewer-grade.

The exports return the full path written, append the right extension if missing, and create missing folders.

Save

docapi.Save()                        # needs an existing path
docapi.Save(r"C:\out\copy.3dm")      # Save As — the document adopts the path

STL

docapi.Stl(r"C:\out\ring.stl")                       # everything visible
docapi.Stl(r"C:\out\head.stl", onlySelection = True) # just the selection

Binary STL for 3D printing, through Rhino’s native exporter with its default meshing parameters.

Parameter	Default	Meaning
path	—	Destination STL
onlySelection	False	True exports only the current selection instead of everything visible

Report PDF

docapi.ReportPdf(r"C:\out\design-report.pdf", pageName = "Template")

Prints a layout page to a 300-dpi PDF, vector where possible.

Parameter	Default	Meaning
path	—	Destination PDF
pageName	the report layout	The layout page to print — by default the one the report tools produce (see DraftingApi.CreateReport on Drafting). Unknown page names fail listing the available layouts

GLB

docapi.Glb(r"C:\out\design.glb")

Exports the whole document to GLB — the same conversion the Realtime Render viewer uses.

Global parameters

The document-wide settings — the same switches the Outliner shows at the top.

• DescribeA human-readable summary of the whole design.
• Computation modeRender display quality or production-accurate geometry.
• MetalsRead and set the document's metal — or its three positions.
• Ring sizeRegion, size and diameter of the parametric ring.

Describe

from ArtisanPlugin.Scripting import SemanticsApi as semantics
print(semantics.DescribeDocument())

A human-readable summary of the active document (SemanticsApi) — design type, finger size, metals, gems and the parametric elements it contains. Built by the same semantics engine the plugin uses internally; the best first call to understand what is in front of you, and perfect answer material for “what is this design?”.

Computation mode

docapi.GetComputationMode()          # "Render" or "Manufacturing"
docapi.SetComputationMode("Manufacturing")

Render = smooth display quality; Manufacturing = production-accurate geometry (the alias "Rendering" is accepted).

Metals

docapi.GetMetals()                   # e.g. ["GOLD_YELLOW_18"] — 1, 2 or 3 entries
docapi.SetMetal("GOLD_ROSE_18")               # whole document
docapi.SetMetal("PLATINUM", position = 2)     # metal position 2 (multi-metal designs)

Parameter	Default	Meaning
position	0	0 sets the whole document; 1–3 target a metal position, turning the document into a multi-metal design like the Outliner’s selectors do

Metal names come from WeightApi.Metals(); input is case-insensitive and tolerates dashes/spaces. Layer materials update immediately.

Ring size

docapi.GetRingSize()               # → Region, Size, Diameter (mm), or None on non-ring designs
docapi.RingSizeRegions()           # "USA", "EUROPE", "BRITISH", ...
docapi.SetRingSize("EU", "54")
docapi.SetRingSizeByDiameter(17.35)          # nearest catalog size, current region

Region names accept the catalog ids and common short aliases (US, EU, UK, JP, …). Unknown regions and sizes fail listing the valid options.

Command panels

from ArtisanPlugin.Scripting import PanelsApi as panels

Artisan’s command panels (the side panel that ArtisanBail, ArtisanCutters… open, with its live preview) are interactive and can’t be driven headless, so build with the typed facades instead. A script that runs a panel command through RhinoApp.RunScript can still see the panel and close it:

Method	Returns
Active()	The name of the open panel ("Bail", "Cutter", "Basket"…), or None
Close()	Closes it without applying, like its X button: the preview is discarded and objects hidden while editing come back. Returns the closed panel’s name, or None if no panel was open

Through MCP, run_command warns when it leaves a panel open, and close_panel closes it. In the Python package, this is ra.panels.