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.