Python package

ra.gem_tools

Utilities over existing stones: centers, tags, alignment, curves from gems, copy by gems, colors by size.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.GemToolsApi.

Functions

Function
`add_center_points()`	The ArtisanGemsCenter command, headless: adds a point object at the center (plane origin) of each gem.
`add_tags()`	The ArtisanGemTags command, headless: places a 3-line text entity on the top face (table) of each gem — measures (“X x Y” in mm), carat weight and material — with the text height scaled to the stone (18% of its largest side).
`align_gems()`	The ArtisanAlignGems command, headless: drops each gem onto the target objects by shooting a ray from the gem’s center along its own axis (+Z first, then -Z, so a gem already past the surface still lands on it) and translating the gem to the hit point.
`center_between_gems()`	The ArtisanCenterBetweenGems command, headless: for every triple of mutually adjacent gems (center distance below the sum of their diameters, near-equilateral unless the stones are big enough to still share a prong) it fits the circle tangent to the three girdle circles and adds it to the document — the classic shared-prong guide.
`centers()`	Center of each gem (its plane origin, on the girdle), read-only: nothing is added to the document, no license needed.
`color_by_size()`	The ArtisanGemsColorBySize command, headless: paints every gem with a per-size display color (sizes grouped with a 1e-3 mm tolerance; color 0 is always the smallest size), so equal stones read at a glance.
`copy_by_gems()`	The ArtisanCopyByGems command, headless: copies `object_ids` (a prong, a cutter, a bezel…) onto every gem in `target_gem_ids`, mapping from the origin gem’s plane to each target gem’s plane (history-linked copies, like the command).
`curve_from_gems()`	The ArtisanCurveFromGems command, headless: interpolates a degree-3 curve through the centers of the gems, IN THE ORDER of `gem_ids` (selection order when None) — the order defines the shape of the curve, just like the pick order does in the command.
`extract_gem_curves()`	The ArtisanGemsCurve command, headless: duplicates the girdle curve of each gem as a plain document curve (useful as a cutting/section profile).
`offset_gem_curves()`	The ArtisanGemOffset command, headless: offsets the girdle curve of each gem OUTWARD by `distance` mm (the command’s default is 1.0) and adds the result as the parametric gem-offset curve, linked with history to its gem so it follows when the gem moves.
`recover_gems()`	The ArtisanGemsRecover command, headless: scans the WHOLE document for dumb gem geometry exported by Matrix, MatrixGold, RhinoGold or an older RhinoArtisan (recognized by their exact mesh/brep topology) and replaces each one with a parametric Artisan gemstone of the measured shape and size.
`rotate_gems()`	The document effect of the ArtisanGemsOrientation handles (and of ArtisanRotateGemsLeft/Right), headless: rotates each gem around its own plane normal, in place.

ra.gem_tools.add_center_points()

ra.gem_tools.add_center_points(gem_ids=None) -> List[str]

The ArtisanGemsCenter command, headless: adds a point object at the center (plane origin) of each gem. Returns the ids of the created points.

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

ra.gem_tools.add_tags()

ra.gem_tools.add_tags(gem_ids=None) -> List[str]

The ArtisanGemTags command, headless: places a 3-line text entity on the top face (table) of each gem — measures (“X x Y” in mm), carat weight and material — with the text height scaled to the stone (18% of its largest side). The tags land on the primary user layer. None/empty gem_ids = the selected gems, or every gem in the document when nothing is selected (command behavior on Enter). Returns the ids of the created text entities.

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

ra.gem_tools.align_gems()

ra.gem_tools.align_gems(target_ids: Sequence[IdLike], gem_ids=None, flip=None, adapt_to_surface=None, align_top=None) -> int

The ArtisanAlignGems command, headless: drops each gem onto the target objects by shooting a ray from the gem’s center along its own axis (+Z first, then -Z, so a gem already past the surface still lands on it) and translating the gem to the hit point. The targets are meshed as one high-resolution mesh, like the command. Positions are aligned; the gem keeps its own orientation unless told otherwise: flip True = turn the gem upside down at the landing point (the command’s Flip toggle; default No); adapt_to_surface True = orient the gem’s axis to the surface normal at the landing point (the command’s Orientation toggle, Keep by default); align_top True = sink the gem along its axis by its own height above the girdle, so the top face (table) sits on the surface (the command’s Alignment toggle, On Girdle by default). Gems whose axis never hits the targets are skipped, like in the command. None/empty gem_ids = the selected gems. In-place moves: returns the number of gems aligned.

Parameter	Type
`target_ids`	`Sequence[IdLike]`	required
`gem_ids`	`Sequence[IdLike]`	optional — None = the tool default
`flip`	`bool`	optional — None = the tool default
`adapt_to_surface`	`bool`	optional — None = the tool default
`align_top`	`bool`	optional — None = the tool default

ra.gem_tools.center_between_gems()

ra.gem_tools.center_between_gems(gem_ids=None) -> List[str]

The ArtisanCenterBetweenGems command, headless: for every triple of mutually adjacent gems (center distance below the sum of their diameters, near-equilateral unless the stones are big enough to still share a prong) it fits the circle tangent to the three girdle circles and adds it to the document — the classic shared-prong guide. The circles are grouped so one click picks the whole guide set. None/empty gem_ids = the selected gems, or every gem in the document when nothing is selected (command behavior on Enter). Returns the ids of the created circles (may be empty when no triple qualifies).

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

ra.gem_tools.centers()

ra.gem_tools.centers(gem_ids=None) -> List[Point3d]

Center of each gem (its plane origin, on the girdle), read-only: nothing is added to the document, no license needed. The points come back in the same order as gem_ids (selection order when None).

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

ra.gem_tools.color_by_size()

ra.gem_tools.color_by_size(gem_ids=None) -> int

The ArtisanGemsColorBySize command, headless: paints every gem with a per-size display color (sizes grouped with a 1e-3 mm tolerance; color 0 is always the smallest size), so equal stones read at a glance. None/empty gem_ids = the selected gems, or every gem in the document when nothing is selected (command behavior on Enter). Returns the number of gems recolored.

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

ra.gem_tools.copy_by_gems()

ra.gem_tools.copy_by_gems(object_ids: Sequence[IdLike], target_gem_ids: Sequence[IdLike], origin_gem_id=None, scale=None) -> List[str]

The ArtisanCopyByGems command, headless: copies object_ids (a prong, a cutter, a bezel…) onto every gem in target_gem_ids, mapping from the origin gem’s plane to each target gem’s plane (history-linked copies, like the command). origin_gem_id = None means the objects are modeled on the world XY plane (the command’s “Enter = CPlane” answer). scale is the command’s option list: “No” (default) copy as-is “2D” scale X/Y by targetGemSizeX / originGemSizeX “3D” scale X/Y/Z by the same factor None/empty object_ids = the current selection. Returns the ids of the created copies (targets x objects).

Parameter	Type
`object_ids`	`Sequence[IdLike]`	required
`target_gem_ids`	`Sequence[IdLike]`	required
`origin_gem_id`	`Optional[IdLike]`	optional — None = the tool default
`scale`	`str`	optional — None = the tool default

ra.gem_tools.curve_from_gems()

ra.gem_tools.curve_from_gems(gem_ids=None) -> str

The ArtisanCurveFromGems command, headless: interpolates a degree-3 curve through the centers of the gems, IN THE ORDER of gem_ids (selection order when None) — the order defines the shape of the curve, just like the pick order does in the command. Consecutive coincident centers (stacked duplicates) are skipped. At least two distinct centers are required. Returns the id of the created curve.

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

ra.gem_tools.extract_gem_curves()

ra.gem_tools.extract_gem_curves(gem_ids=None) -> List[str]

The ArtisanGemsCurve command, headless: duplicates the girdle curve of each gem as a plain document curve (useful as a cutting/section profile). Returns the ids of the created curves.

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

ra.gem_tools.offset_gem_curves()

ra.gem_tools.offset_gem_curves(gem_ids=None, distance=None) -> List[str]

The ArtisanGemOffset command, headless: offsets the girdle curve of each gem OUTWARD by distance mm (the command’s default is 1.0) and adds the result as the parametric gem-offset curve, linked with history to its gem so it follows when the gem moves. A distance smaller than the document tolerance adds the girdle curve unchanged (same as answering 0 in the command). Gems whose offset fails (self intersecting result, etc.) are skipped, like in the command. Returns the ids of the created curves.

Parameter	Type
`gem_ids`	`Sequence[IdLike]`	optional — None = the tool default
`distance`	`float`	optional — None = the tool default

ra.gem_tools.recover_gems()

ra.gem_tools.recover_gems() -> int

The ArtisanGemsRecover command, headless: scans the WHOLE document for dumb gem geometry exported by Matrix, MatrixGold, RhinoGold or an older RhinoArtisan (recognized by their exact mesh/brep topology) and replaces each one with a parametric Artisan gemstone of the measured shape and size. The command already runs without prompts, so it is invoked directly — that keeps the recovery byte-identical to the ribbon button and picks up new fingerprints automatically. Returns the number of gems recovered (0 = nothing recognizable).

ra.gem_tools.rotate_gems()

ra.gem_tools.rotate_gems(gem_ids=None, angle_degrees=None) -> int

The document effect of the ArtisanGemsOrientation handles (and of ArtisanRotateGemsLeft/Right), headless: rotates each gem around its own plane normal, in place. angle_degrees is counter-clockwise when positive (each click of the orientation gumball is +90, the default); pass a negative angle to rotate clockwise. Returns the number of gems rotated.

Parameter	Type
`gem_ids`	`Sequence[IdLike]`	optional — None = the tool default
`angle_degrees`	`float`	optional — None = the tool default