.NET API

GemToolsApi

Headless facade for the gem utility commands (the Gems ribbon tools that are not gem creators): center points, prong guides, curves from/around gems, copy-by-gems, color-by-size, rotation, tags and recovery of dumb gems exported by other CADs. Conventions shared by every method: - all lengths are millimetres (in a mm document); - a null/empty gemIds list means “the gems currently selected in the viewport” (the same commands accept preselection); the three tools whose command also accepts Enter-with-nothing-selected (CenterBetweenGems, ColorBySize, AddTags) additionally fall back to EVERY gem in the document when the selection has no gems, exactly like the command; - ids passed explicitly must be Artisan diamonds/gemstones, otherwise an ArgumentException names the offending id; - methods that modify the document call LicenseGate.RequireValid() first and end with a viewport redraw.

from ArtisanPlugin.Scripting import GemToolsApi

See also the guide, Gems › Gem tools, and the Python package, ra.gem_tools.

Methods

Method
`AddCenterPoints`	The ArtisanGemsCenter command, headless: adds a point object at the center (plane origin) of each gem.
`AddTags`	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).
`AlignGems`	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.
`CenterBetweenGems`	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.
`ColorBySize`	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.
`CopyByGems`	The ArtisanCopyByGems command, headless: copies `objectIds` (a prong, a cutter, a bezel…) onto every gem in `targetGemIds`, mapping from the origin gem’s plane to each target gem’s plane (history-linked copies, like the command).
`CurveFromGems`	The ArtisanCurveFromGems command, headless: interpolates a degree-3 curve through the centers of the gems, IN THE ORDER of `gemIds` (selection order when null) — the order defines the shape of the curve, just like the pick order does in the command.
`ExtractGemCurves`	The ArtisanGemsCurve command, headless: duplicates the girdle curve of each gem as a plain document curve (useful as a cutting/section profile).
`OffsetGemCurves`	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.
`RecoverGems`	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.
`RotateGems`	The document effect of the ArtisanGemsOrientation handles (and of ArtisanRotateGemsLeft/Right), headless: rotates each gem around its own plane normal, in place.

AddCenterPoints

IReadOnlyList<Guid> GemToolsApi.AddCenterPoints(IEnumerable<Guid> gemIds = null)

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	Default
`gemIds`	`IEnumerable<Guid>`	`null`

Returns IReadOnlyList<Guid>.

AddTags

IReadOnlyList<Guid> GemToolsApi.AddTags(IEnumerable<Guid> gemIds = null)

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. null/empty gemIds = 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	Default
`gemIds`	`IEnumerable<Guid>`	`null`

Returns IReadOnlyList<Guid>.

AlignGems

int GemToolsApi.AlignGems(
    IEnumerable<Guid> targetIds,
    IEnumerable<Guid> gemIds = null,
    bool flip = false,
    bool adaptToSurface = false,
    bool alignTop = false)

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); adaptToSurface true = orient the gem’s axis to the surface normal at the landing point (the command’s Orientation toggle, Keep by default); alignTop 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. null/empty gemIds = the selected gems. In-place moves: returns the number of gems aligned.

Parameter	Type	Default
`targetIds`	`IEnumerable<Guid>`	required
`gemIds`	`IEnumerable<Guid>`	`null`
`flip`	`bool`	`false`
`adaptToSurface`	`bool`	`false`
`alignTop`	`bool`	`false`

Returns int.

CenterBetweenGems

IReadOnlyList<Guid> GemToolsApi.CenterBetweenGems(IEnumerable<Guid> gemIds = null)

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. null/empty gemIds = 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	Default
`gemIds`	`IEnumerable<Guid>`	`null`

Returns IReadOnlyList<Guid>.

Centers

IReadOnlyList<Point3d> GemToolsApi.Centers(IEnumerable<Guid> gemIds = null)

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 gemIds (selection order when null).

Parameter	Type	Default
`gemIds`	`IEnumerable<Guid>`	`null`

Returns IReadOnlyList<Point3d>.

ColorBySize

int GemToolsApi.ColorBySize(IEnumerable<Guid> gemIds = null)

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. null/empty gemIds = 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	Default
`gemIds`	`IEnumerable<Guid>`	`null`

Returns int.

CopyByGems

IReadOnlyList<Guid> GemToolsApi.CopyByGems(
    IEnumerable<Guid> objectIds,
    IEnumerable<Guid> targetGemIds,
    Guid? originGemId = null,
    string scale = "No")

The ArtisanCopyByGems command, headless: copies objectIds (a prong, a cutter, a bezel…) onto every gem in targetGemIds, mapping from the origin gem’s plane to each target gem’s plane (history-linked copies, like the command). originGemId = Guid.Empty 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 null/empty objectIds = the current selection. Returns the ids of the created copies (targets x objects).

Parameter	Type	Default
`objectIds`	`IEnumerable<Guid>`	required
`targetGemIds`	`IEnumerable<Guid>`	required
`originGemId`	`Guid?`	`null`
`scale`	`string`	`"No"`

Returns IReadOnlyList<Guid>.

CurveFromGems

Guid GemToolsApi.CurveFromGems(IEnumerable<Guid> gemIds = null)

The ArtisanCurveFromGems command, headless: interpolates a degree-3 curve through the centers of the gems, IN THE ORDER of gemIds (selection order when null) — 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	Default
`gemIds`	`IEnumerable<Guid>`	`null`

Returns Guid.

ExtractGemCurves

IReadOnlyList<Guid> GemToolsApi.ExtractGemCurves(IEnumerable<Guid> gemIds = null)

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	Default
`gemIds`	`IEnumerable<Guid>`	`null`

Returns IReadOnlyList<Guid>.

OffsetGemCurves

IReadOnlyList<Guid> GemToolsApi.OffsetGemCurves(
    IEnumerable<Guid> gemIds = null,
    double distance = 1)

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	Default
`gemIds`	`IEnumerable<Guid>`	`null`
`distance`	`double`	`1`

Returns IReadOnlyList<Guid>.

RecoverGems

int GemToolsApi.RecoverGems()

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).

Returns int.

RotateGems

int GemToolsApi.RotateGems(IEnumerable<Guid> gemIds = null, double angleDegrees = 90)

The document effect of the ArtisanGemsOrientation handles (and of ArtisanRotateGemsLeft/Right), headless: rotates each gem around its own plane normal, in place. angleDegrees 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	Default
`gemIds`	`IEnumerable<Guid>`	`null`
`angleDegrees`	`double`	`90`

Returns int.