Python package

ra.drafting

Reports, gems maps, cost tables, dimensions.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.DraftingApi, ArtisanPlugin.Scripting.DraftingExtraApi.

Functions

Function
`create_breakdown_table()`	Draws one of the four Breakdown cost tables into the document at `point` (the ArtisanBreakdownMetals / ArtisanBreakdownGems / ArtisanBreakdownProcesses / ArtisanBreakdownExtras commands without their pick prompt).
`create_gems_map()`	Draws the gems map (the 2D stone chart: one colored circle + size label per gem in the document) centered at `point`, same as the ArtisanGemsMap command but without the pick prompt.
`create_gems_table()`	Draws the gems list table (the ArtisanGemsList command family) starting at `point`: one row per distinct gem with SHAPE, size “X x Y”, carats, quantity, total carats and compound, rows 1.5 units apart, in black.
`create_metals_table()`	Draws the metals weight table (the ArtisanMetalsList / ArtisanMetalsListBySelection commands without their checklist dialog and prompts) at `point`: a header row (Weight / Processed) and one row per requested metal with the estimated cast weight computed from the summed volume of the measured objects — gems are skipped; Breps, extrusions, meshes and SubDs count.
`create_report()`	Creates the A4 report layout page for the current design (same as the ArtisanReport command): logo, four detail views (top, perspective, front, side), title block with name, metal + weight, finger size, notes and date.
`create_report_from_template()`	Creates a report from a TEMPLATE (the Report panel’s Create button, headless): imports the template’s layout as the next “Report N” page, zooms every detail, and replaces the template tags ([CLIENT_ID], [PO], [STYLE], [CAD_DESIGNER], [DESCRIPTION], metals, [PRODUCT_SIZE], custom fields…) plus the special list markers (METAL_LIST, GEM_LIST, PROCESS_LIST, EXTRA_LIST, GEM_MAP).
`export_gems_list()`	Writes the gems list as a semicolon-delimited CSV (same columns as the ArtisanGemsListToExcel command: Shape, Size X, Size Y, Carats, Quantity, Total Carats), without the save-file dialog.
`generate_dimensions()`	Generic auto-dimensioning of the design.
`generate_dimensions_by_box()`	Bounding-box dimensions (the ArtisanGenerateDimensionsByBox command without its selection prompt): meshes the given objects together at low resolution and draws three linear dimensions around the global bounding box — width in X above the model, depth in Y at its right and the real height in Z.
`generate_dimensions_from_bangle()`	Bangle dimensions (the ArtisanGenerateDimensionsFromBangle command without its selection prompt): meshes the given objects together at low resolution, sections the mesh with the world XY / YZ planes and dimensions the four cross sections (top, bottom, left, right) plus the two global spans between them.
`generate_dimensions_from_ring()`	Ring-specific dimensions: bottom, top and size annotations built from the ring mesh and the document’s finger size.
`report_templates()`	The report template names available to CreateReportFromTemplate — the *.3dm files in the configured report-templates folder, without extension.
`add_logo()`	Creates the report logo file from the given objects (same as ArtisanAddLogo): copies them, scales the copies so the largest extent is 28 mm, centers them at (65, 25, 0), exports the copies as logo.3dm in the Artisan user folder and deletes the copies.
`apply_artisan_layout()`	Applies the Artisan window layout (ArtisanLayout / the ribbon’s Window Layout button): imports ArtisanSkin.rhw and activates the “Artisan” layout.
`create_technical_chart()`	The technical chart (ArtisanTechnicalChart panel, headless): the production breakdown WITHOUT prices — per metal the net weight, waste, total and wax weight, volume and surface area; the gems by shape and size with carats and setting type; the setting, printing and extra processes.
`export_gems_list_by_ids()`	Writes the gems list of the given gems as a semicolon-delimited CSV (ArtisanGemsListToExcelBySelection / …BySelectionGroups without the pick and the save dialog; columns Shape, Size X, Size Y, Carats, Quantity, Total Carats).
`open_report_template()`	Opens a report template for editing (ArtisanOpenReportTemplate without the file dialog).
`reduce_dimensions()`	Reduces the DISPLAYED value of distance dimensions by `percentage` (same as ArtisanDimensionsReduce / …BySelection): only the text is overridden, the geometry is untouched.
`restore_dimensions()`	Restores distance dimensions to their real measured value by putting back the ”<>” placeholder (same as ArtisanDimensionsRestore / …BySelection).
`save_report_template()`	Saves the ACTIVE document as a report template (ArtisanSaveReportTemplate without the save dialog): a “Save As” into the report-templates folder, so the document adopts that path.

ra.drafting.create_breakdown_table()

ra.drafting.create_breakdown_table(category: str, point: PointLike, scale=None)

Draws one of the four Breakdown cost tables into the document at point (the ArtisanBreakdownMetals / ArtisanBreakdownGems / ArtisanBreakdownProcesses / ArtisanBreakdownExtras commands without their pick prompt). One method instead of four because the commands are identical except for the table they draw. category METALS | GEMS | PROCESSES | EXTRAS (case-insensitive). point insertion point (top-left corner of the table). scale layout / text-height scale factor; None = the tool default (2). Like the commands, when no breakdown has been computed yet (or it is empty) it is computed first from the active manufacturer — the commands ask with a yes/no dialog, here it happens silently through the same engine ra.pricing.calculate() uses. The texts are grouped as BREAKDOWN_METALS / BREAKDOWN_GEMS / BREAKDOWN_PROCESSES / BREAKDOWN_EXTRAS respectively.

Parameter	Type
`category`	`str`	required
`point`	`PointLike`	required
`scale`	`float`	optional — None = the tool default

ra.drafting.create_gems_map()

ra.drafting.create_gems_map(point: PointLike, scale=None, spherical=None, expand_overlapping=None)

Draws the gems map (the 2D stone chart: one colored circle + size label per gem in the document) centered at point, same as the ArtisanGemsMap command but without the pick prompt. scale drawing scale factor (command default 2; valid 0.01-10) spherical False = planar projection (default), True = spherical expand_overlapping True = push overlapping circles apart so every label is readable The resulting curves/texts/hatches are grouped as “GEMS_MAP”. With no gems in the document it draws nothing and reports it on the command line, same as the command.

Parameter	Type
`point`	`PointLike`	required
`scale`	`float`	optional — None = the tool default
`spherical`	`bool`	optional — None = the tool default
`expand_overlapping`	`bool`	optional — None = the tool default

ra.drafting.create_gems_table()

ra.drafting.create_gems_table(point: PointLike, only_selection=None, group_by_selection=None)

Draws the gems list table (the ArtisanGemsList command family) starting at point: one row per distinct gem with SHAPE, size “X x Y”, carats, quantity, total carats and compound, rows 1.5 units apart, in black. only_selection True = only the currently selected gems (the ArtisanGemsListBySelection command); False = every visible gem in the document (ArtisanGemsList). group_by_selection True = the ArtisanGemsListBySelectionGroups variant: the SELECTED gems are bucketed by their Rhino group and drawn as one sub-table per group, each with the group’s name as a header row (plus an “Ungrouped” section for gems in no group). Implies only_selection. The texts are grouped as “GEMS_LIST” (“GEMS_LIST_BY_SELECTION_GROUPS” for the grouped variant). With no visible gems it draws nothing, like the command; the selection variants throw when the selection holds no gems, mirroring the commands’ cancel.

Parameter	Type
`point`	`PointLike`	required
`only_selection`	`bool`	optional — None = the tool default
`group_by_selection`	`bool`	optional — None = the tool default

ra.drafting.create_metals_table()

ra.drafting.create_metals_table(point: PointLike, metals: Sequence[str], include_wax=None, only_selection=None)

Draws the metals weight table (the ArtisanMetalsList / ArtisanMetalsListBySelection commands without their checklist dialog and prompts) at point: a header row (Weight / Processed) and one row per requested metal with the estimated cast weight computed from the summed volume of the measured objects — gems are skipped; Breps, extrusions, meshes and SubDs count. The Processed column is the weight after finishing (the configured processed-weight percentage removed); the wax row has none. Everything is added to a new unnamed group, like the commands. metals Metal enum names to list (the command’s checklist: GOLD_24 … PALLADIUM), case-insensitive. Rows keep the checklist order regardless of input order. include_wax True = append the wax weight row (the checklist’s Wax entry), using the configured wax density. only_selection True = measure only the currently selected objects (ArtisanMetalsListBySelection); False = every non-hidden object in the document.

Parameter	Type
`point`	`PointLike`	required
`metals`	`Sequence[str]`	required
`include_wax`	`bool`	optional — None = the tool default
`only_selection`	`bool`	optional — None = the tool default

ra.drafting.create_report()

ra.drafting.create_report() -> bool

Creates the A4 report layout page for the current design (same as the ArtisanReport command): logo, four detail views (top, perspective, front, side), title block with name, metal + weight, finger size, notes and date. Returns True when the command reports success. Implemented by invoking the command itself — it needs no input, and wrapping it keeps the report identical to the one users get from the ribbon (and picks up future improvements automatically).

ra.drafting.create_report_from_template()

ra.drafting.create_report_from_template(template=None, style=None, client_id=None, po=None, cad_designer=None, description=None, custom_fields=None, spherical_gems_map=None) -> str

Creates a report from a TEMPLATE (the Report panel’s Create button, headless): imports the template’s layout as the next “Report N” page, zooms every detail, and replaces the template tags ([CLIENT_ID], [PO], [STYLE], [CAD_DESIGNER], [DESCRIPTION], metals, [PRODUCT_SIZE], custom fields…) plus the special list markers (METAL_LIST, GEM_LIST, PROCESS_LIST, EXTRA_LIST, GEM_MAP). template template name from ReportTemplates(); None = the first one (the panel’s default selection) style/client_id/po/cad_designer/description the title-block fields; None keeps the value the document already carries (the panel’s fields) custom_fields extra [MY_FIELD] tag values by field name; merged over the document’s saved custom fields spherical_gems_map projection of the GEM_MAP marker The breakdown is recomputed silently when missing (the tags read it). Returns the name of the new layout page (e.g. “Report 1”) — print it to PDF with ra.document.report_pdf(path, page_name: that_name).

Parameter	Type
`template`	`str`	optional — None = the tool default
`style`	`str`	optional — None = the tool default
`client_id`	`str`	optional — None = the tool default
`po`	`str`	optional — None = the tool default
`cad_designer`	`str`	optional — None = the tool default
`description`	`str`	optional — None = the tool default
`custom_fields`	`Dict[str, str]`	optional — None = the tool default
`spherical_gems_map`	`bool`	optional — None = the tool default

ra.drafting.export_gems_list()

ra.drafting.export_gems_list(path: str, only_selection=None, use_system_decimals=None) -> str

Writes the gems list as a semicolon-delimited CSV (same columns as the ArtisanGemsListToExcel command: Shape, Size X, Size Y, Carats, Quantity, Total Carats), without the save-file dialog. path destination file; “.csv” is appended when missing only_selection True = only the currently selected gems use_system_decimals True = format numbers with the system’s decimal separator (the command’s “Force Point” option inverted); default is invariant (point) Returns the full path actually written.

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

ra.drafting.generate_dimensions()

ra.drafting.generate_dimensions() -> bool

Generic auto-dimensioning of the design.

ra.drafting.generate_dimensions_by_box()

ra.drafting.generate_dimensions_by_box(object_ids: Sequence[IdLike], offset=None, add_box=None)

Bounding-box dimensions (the ArtisanGenerateDimensionsByBox command without its selection prompt): meshes the given objects together at low resolution and draws three linear dimensions around the global bounding box — width in X above the model, depth in Y at its right and the real height in Z. Exactly like the command, the low resolution analysis mesh and a marker point at the Y dimension’s plane origin are also left in the document. object_ids objects to dimension (the command’s selection). offset gap between the geometry and the dimension lines (the command’s Offset option; default 2, valid 0-100). add_box True = also add the bounding box as a Brep (the command’s Box option).

Parameter	Type
`object_ids`	`Sequence[IdLike]`	required
`offset`	`float`	optional — None = the tool default
`add_box`	`bool`	optional — None = the tool default

ra.drafting.generate_dimensions_from_bangle()

ra.drafting.generate_dimensions_from_bangle(object_ids: Sequence[IdLike], offset=None, add_box=None)

Bangle dimensions (the ArtisanGenerateDimensionsFromBangle command without its selection prompt): meshes the given objects together at low resolution, sections the mesh with the world XY / YZ planes and dimensions the four cross sections (top, bottom, left, right) plus the two global spans between them. The bangle is expected centered on the world origin, like the command expects. object_ids objects to dimension (the command’s selection). offset gap between the geometry and the dimension lines (the command’s Offset option; default 2, valid 0-100). add_box True = also add the bounding box as a Brep (the command’s Box option).

Parameter	Type
`object_ids`	`Sequence[IdLike]`	required
`offset`	`float`	optional — None = the tool default
`add_box`	`bool`	optional — None = the tool default

ra.drafting.generate_dimensions_from_ring()

ra.drafting.generate_dimensions_from_ring() -> bool

Ring-specific dimensions: bottom, top and size annotations built from the ring mesh and the document’s finger size.

ra.drafting.report_templates()

ra.drafting.report_templates() -> List[str]

The report template names available to CreateReportFromTemplate — the *.3dm files in the configured report-templates folder, without extension. Read-only.

ra.drafting.add_logo()

ra.drafting.add_logo(ids: Sequence[IdLike]) -> str

Creates the report logo file from the given objects (same as ArtisanAddLogo): copies them, scales the copies so the largest extent is 28 mm, centers them at (65, 25, 0), exports the copies as logo.3dm in the Artisan user folder and deletes the copies. The originals are untouched. Returns the full path of logo.3dm.

Parameter	Type
`ids`	`Sequence[IdLike]`	required

ra.drafting.apply_artisan_layout()

ra.drafting.apply_artisan_layout() -> bool

Applies the Artisan window layout (ArtisanLayout / the ribbon’s Window Layout button): imports ArtisanSkin.rhw and activates the “Artisan” layout. Rhino 8 or later only. Returns True when applied.

ra.drafting.create_technical_chart()

ra.drafting.create_technical_chart(path=None, quote_certified=None) -> TechnicalChartResult

The technical chart (ArtisanTechnicalChart panel, headless): the production breakdown WITHOUT prices — per metal the net weight, waste, total and wax weight, volume and surface area; the gems by shape and size with carats and setting type; the setting, printing and extra processes. The breakdown is recomputed first (the panel’s Create button) and stored in the document. path optional export: “.xlsx” (the panel’s Excel, no prices) or “.json” (the raw breakdown object); None = no file quote_certified False = skip the live Nivoda quote of certified diamonds (faster, offline) Returns the chart as data (plus Path when a file was written).

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

ra.drafting.export_gems_list_by_ids()

ra.drafting.export_gems_list_by_ids(path: str, ids=None, group_by_rhino_groups=None, use_system_decimals=None) -> str

Writes the gems list of the given gems as a semicolon-delimited CSV (ArtisanGemsListToExcelBySelection / …BySelectionGroups without the pick and the save dialog; columns Shape, Size X, Size Y, Carats, Quantity, Total Carats). Non-gem ids are ignored. ids gem ids; None = every visible gem group_by_rhino_groups True = one section per Rhino group the gems belong to (group name as header) plus an “Ungrouped Gems” section at the end use_system_decimals True = system decimal separator (default point) Returns the full path written (“.csv” appended when missing).

Parameter	Type
`path`	`str`	required
`ids`	`Sequence[IdLike]`	optional — None = the tool default
`group_by_rhino_groups`	`bool`	optional — None = the tool default
`use_system_decimals`	`bool`	optional — None = the tool default

ra.drafting.open_report_template()

ra.drafting.open_report_template(template: str, save_changes_first=None, discard_changes=None) -> str

Opens a report template for editing (ArtisanOpenReportTemplate without the file dialog). The active document is REPLACED by the template file — every id of the previous document becomes invalid. template name from ra.drafting.report_templates() or a full .3dm path save_changes_first True = save the current document before (it must already have a path) discard_changes True = lose unsaved changes silently Fails when the document has unsaved changes and neither flag is set. Returns the full path opened.

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

ra.drafting.reduce_dimensions()

ra.drafting.reduce_dimensions(percentage=None, ids=None) -> DimensionValueReport

Reduces the DISPLAYED value of distance dimensions by percentage (same as ArtisanDimensionsReduce / …BySelection): only the text is overridden, the geometry is untouched. Metal shrinks when cast, so plans often need the pre-shrinkage value. Angular dimensions and dimensions already overridden are skipped. percentage 0 = the command default (5); valid 0-100 ids dimension ids; None = every dimension in the document Returns the counts: Changed and Skipped (already overridden).

Parameter	Type
`percentage`	`float`	optional — None = the tool default
`ids`	`Sequence[IdLike]`	optional — None = the tool default

ra.drafting.restore_dimensions()

ra.drafting.restore_dimensions(ids=None) -> int

Restores distance dimensions to their real measured value by putting back the ”<>” placeholder (same as ArtisanDimensionsRestore / …BySelection). Dimensions that already show the real value are left alone. ids dimension ids; None = every dimension in the document Returns the number of dimensions restored.

Parameter	Type
`ids`	`Sequence[IdLike]`	optional — None = the tool default

ra.drafting.save_report_template()

ra.drafting.save_report_template(name: str, overwrite=None) -> str

Saves the ACTIVE document as a report template (ArtisanSaveReportTemplate without the save dialog): a “Save As” into the report-templates folder, so the document adopts that path. Design a layout page with the [TAGS] first; afterwards it is listed by ra.drafting.report_templates() and usable with ra.drafting.create_report_from_template(name). name template name (“.3dm” optional) or a full .3dm path overwrite True = replace an existing template of that name Returns the full path written.

Parameter	Type
`name`	`str`	required
`overwrite`	`bool`	optional — None = the tool default