Python package

ra.document

The document: open/save/new, computation mode, metals, ring size, STL/PDF/GLB exports.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.DocumentApi.

Functions

Function
`get_computation_mode()`	Current computation mode as a string (“Render” or “Manufacturing”).
`get_metals()`	The document’s metals by position, honoring how many the document uses (1, 2 or 3 entries).
`get_path()`	Full path of the active document, or empty for an unsaved document.
`get_ring_size()`	The document’s current finger size, or None when the document has no ring size (non-ring designs).
`glb()`	Exports the whole document to a GLB file (the same conversion the Realtime Render pipeline uses).
`is_modified()`	True when the active document has unsaved changes.
`new()`	Creates a new document, replacing the active one — like File > New, but without the template picker: `template` is a .3dm template file path, or None for Rhino’s default template.
`open()`	Opens a 3dm file.
`refresh_all()`	Regenerates the parametric objects, exactly like the Outliner’s Refresh button: by default only the ones flagged as pending (RequireRegenerate — e.g.
`report_pdf()`	Exports a layout page to a 300-dpi PDF (vector where possible).
`ring_size_regions()`	The available sizing regions (“EU”, “US”, …) for SetRingSize.
`save()`	Saves the active document.
`save_copy()`	Saves a COPY of the active document to `path` (File > SaveCopyAs): the document keeps its own path and modified state, you keep working in the original file — checkpoints and versioning from a flow.
`set_computation_mode()`	Switches the computation mode, exactly like the Outliner’s Rendering/Manufacturing selector: when the mode actually changes, every parametric object is REGENERATED at the new quality (a long operation on heavy documents).
`set_metal()`	Sets a document metal, exactly like the Outliner’s metal selector: the change re-applies the metal materials on the layers.
`set_ring_size()`	Changes the ring’s finger size, exactly like the Outliner’s size selector: the parametric ring geometry is UPDATED to the new size and every object refreshed (long on heavy documents).
`set_ring_size_by_diameter()`	Same, but from an inner diameter in mm — resolves to the nearest catalog size of `region` (omitted = the document’s current region).
`stl()`	Exports geometry to a binary STL for 3D printing: everything visible, or only the current selection with `only_selection`.

ra.document.get_computation_mode()

ra.document.get_computation_mode() -> str

Current computation mode as a string (“Render” or “Manufacturing”).

ra.document.get_metals()

ra.document.get_metals() -> List[str]

The document’s metals by position, honoring how many the document uses (1, 2 or 3 entries).

ra.document.get_path()

ra.document.get_path() -> str

Full path of the active document, or empty for an unsaved document.

ra.document.get_ring_size()

ra.document.get_ring_size() -> RingSizeInfo

The document’s current finger size, or None when the document has no ring size (non-ring designs).

ra.document.glb()

ra.document.glb(path: str) -> str

Exports the whole document to a GLB file (the same conversion the Realtime Render pipeline uses).

Parameter	Type
`path`	`str`	required

ra.document.is_modified()

ra.document.is_modified() -> bool

True when the active document has unsaved changes.

ra.document.new()

ra.document.new(template=None, discard_changes=None)

Creates a new document, replacing the active one — like File > New, but without the template picker: template is a .3dm template file path, or None for Rhino’s default template. Fails on unsaved changes unless discard_changes is True.

Parameter	Type
`template`	`str`	optional — None = the tool default
`discard_changes`	`bool`	optional — None = the tool default

ra.document.open()

ra.document.open(path: str, discard_changes=None) -> str

Opens a 3dm file. The active document is replaced, like File > Open. Fails when the current document has unsaved changes, unless discard_changes is True (there is never a save prompt). Returns the full path opened.

Parameter	Type
`path`	`str`	required
`discard_changes`	`bool`	optional — None = the tool default

ra.document.refresh_all()

ra.document.refresh_all(force=None)

Regenerates the parametric objects, exactly like the Outliner’s Refresh button: by default only the ones flagged as pending (RequireRegenerate — e.g. children whose mother moved); force True regenerates EVERYTHING (the button’s double-click), a long operation on heavy documents.

Parameter	Type
`force`	`bool`	optional — None = the tool default

ra.document.report_pdf()

ra.document.report_pdf(path: str, page_name=None) -> str

Exports a layout page to a 300-dpi PDF (vector where possible). page_name defaults to “Template” — the layout the report-template tools produce. Throws listing the available layouts when the page doesn’t exist (the underlying service only logged it).

Parameter	Type
`path`	`str`	required
`page_name`	`str`	optional — None = the tool default

ra.document.ring_size_regions()

ra.document.ring_size_regions() -> List[str]

The available sizing regions (“EU”, “US”, …) for SetRingSize.

ra.document.save()

ra.document.save(path=None) -> str

Saves the active document. With path it saves a copy there and the document adopts that path (File > Save As); without it the document must already have a path. Returns the full path written.

Parameter	Type
`path`	`str`	optional — None = the tool default

ra.document.save_copy()

ra.document.save_copy(path: str) -> str

Saves a COPY of the active document to path (File > SaveCopyAs): the document keeps its own path and modified state, you keep working in the original file — checkpoints and versioning from a flow. Returns the full path written.

Parameter	Type
`path`	`str`	required

ra.document.set_computation_mode()

ra.document.set_computation_mode(mode: str)

Switches the computation mode, exactly like the Outliner’s Rendering/Manufacturing selector: when the mode actually changes, every parametric object is REGENERATED at the new quality (a long operation on heavy documents). “Render” = smooth display quality; “Manufacturing” = production-accurate geometry.

Parameter	Type
`mode`	`str`	required

ra.document.set_metal()

ra.document.set_metal(metal: str, position=None)

Sets a document metal, exactly like the Outliner’s metal selector: the change re-applies the metal materials on the layers. metal Metal enum name (“GOLD_YELLOW_18”, “PLATINUM”, … — see ra.weight.metals()) position 0 (default) = the WHOLE document uses this metal (single-metal mode); 1, 2 or 3 = that metal position (using different metals per position turns the document into a 2- or 3-metal design, as in the Outliner).

Parameter	Type
`metal`	`str`	required
`position`	`int`	optional — None = the tool default

ra.document.set_ring_size()

ra.document.set_ring_size(region: str, size: str)

Changes the ring’s finger size, exactly like the Outliner’s size selector: the parametric ring geometry is UPDATED to the new size and every object refreshed (long on heavy documents). region accepts the catalog ids (“USA”, “EUROPE”, “BRITISH”, …) and the common short aliases (“US”, “EU”, “UK”, …). Only valid on ring designs with a current size.

Parameter	Type
`region`	`str`	required
`size`	`str`	required

ra.document.set_ring_size_by_diameter()

ra.document.set_ring_size_by_diameter(diameter: float, region=None)

Same, but from an inner diameter in mm — resolves to the nearest catalog size of region (omitted = the document’s current region).

Parameter	Type
`diameter`	`float`	required
`region`	`str`	optional — None = the tool default

ra.document.stl()

ra.document.stl(path: str, only_selection=None) -> str

Exports geometry to a binary STL for 3D printing: everything visible, or only the current selection with only_selection. Runs Rhino’s native STL exporter with its default meshing parameters.

Parameter	Type
`path`	`str`	required
`only_selection`	`bool`	optional — None = the tool default