ra.matching_shank

Matching shanks fitted against an engagement ring.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.MatchingShankApi, ArtisanPlugin.Scripting.MatchingShankBuilderApi.

Functions

Function
all()	MatchingShank handles for every object of this kind in the active document (empty when there is no document).
by_layer()	MatchingShank handles on the layer with the given full path (empty when the layer does not exist).
count()	Number of objects of this kind in the active document.
find()	The handle for id, or None when the id does not belong to an object of this kind.
for_ring()	The matching shanks fitted against a given ring.
selected()	MatchingShank handles for the objects of this kind currently selected in the active document.
create()	Builds a matching shank (the ArtisanMatchingShank tool, headless): a band shaped to sit against an existing ring — the mother — so the pair stacks without a gap.

ra.matching_shank.all()

ra.matching_shank.all() -> List[MatchingShank]

MatchingShank handles for every object of this kind in the active document (empty when there is no document).

ra.matching_shank.by_layer()

ra.matching_shank.by_layer(layer_name: str) -> List[MatchingShank]

MatchingShank handles on the layer with the given full path (empty when the layer does not exist).

Parameter	Type
layer_name	str	required

ra.matching_shank.count()

ra.matching_shank.count() -> int

Number of objects of this kind in the active document.

ra.matching_shank.find()

ra.matching_shank.find(id: IdLike) -> MatchingShank

The handle for id, or None when the id does not belong to an object of this kind.

Parameter	Type
id	IdLike	required

ra.matching_shank.for_ring()

ra.matching_shank.for_ring(ring_id: IdLike) -> List[MatchingShank]

The matching shanks fitted against a given ring.

Parameter	Type
ring_id	IdLike	required

ra.matching_shank.selected()

ra.matching_shank.selected() -> List[MatchingShank]

MatchingShank handles for the objects of this kind currently selected in the active document.

ra.matching_shank.create()

ra.matching_shank.create(ring_ids: Sequence[IdLike], width=None, height=None, finger_diameter=None, profile=None, metal=None, clearance=None, distance=None, top_distance=None, interior_type=None, comfort=None, number_of_points=None, flip_side=None, both_sides=None, with_gems=None, gem_size=None, gem_distribution=None, element=None) -> MatchingShank

Builds a matching shank (the ArtisanMatchingShank tool, headless): a band shaped to sit against an existing ring — the mother — so the pair stacks without a gap. The mother ring must sit at the origin like every Artisan ring (the rail is the finger-size circle there). ring_ids: the ring to hug — document ids of its solids (breps, extrusions, meshes) or the Id of an Artisan shank handle (classic, eternity, wedding band…; its stones are ignored). Millimetres; omitting keeps the tool default (or the user’s saved defaults): width 3, height 2, number_of_points 8, comfort 0.3. NaN keeps the default for the signed / zero-legit ones: clearance 0.3 (gap kept against the mother), distance 0 (axial gap; negative presses into the mother), top_distance 0. interior_type “SOLID” | “COMFORT”. flip_side builds on the other side of the mother, both_sides one band on each side (both baked in the same group). with_gems adds a row of round stones along the crest: gem_size (default 1.5), gem_distribution “FULL” | “SIDE” | “TOP”. finger_diameter 0 = the document’s finger size; profile picks a RING_PROFILE asset by name; metal a Metal name (omitted = the document’s Metal 01). Returns the MatchingShank handle of the new group; the mother ring is its parametric mother, so the band follows the ring’s edits. element = name of a saved element (ra.elements.list) to start from; explicit arguments override it.

Parameter	Type
ring_ids	Sequence[IdLike]	required
width	float	optional — None = the tool default
height	float	optional — None = the tool default
finger_diameter	float	optional — None = the tool default
profile	str	optional — None = the tool default
metal	str	optional — None = the tool default
clearance	float	optional — None = the tool default
distance	float	optional — None = the tool default
top_distance	float	optional — None = the tool default
interior_type	str	optional — None = the tool default
comfort	float	optional — None = the tool default
number_of_points	int	optional — None = the tool default
flip_side	bool	optional — None = the tool default
both_sides	bool	optional — None = the tool default
with_gems	bool	optional — None = the tool default
gem_size	float	optional — None = the tool default
gem_distribution	str	optional — None = the tool default
element	str	optional — None = the tool default

Handles

Objects returned by the functions above. Assigning a settable property regenerates the object; the change is one undo step inside ra.transaction().

MatchingShank (handle)

A matching shank: a band shaped to sit against an existing ring (the “mother”), so the pair stacks without a gap. Holds several gems, so no single MotherGem — the mothers it was fitted to are in MotherRingIds.

Property	Type	Settable
both_sides	bool	yes	build one band on each side
bottom_height	float	yes	mm — 0 = same as the top
bottom_width	float	yes	band section at the bottom, mm — 0 = same as the top
clearance	float	yes	gap kept against the mother, mm
comfort	float	yes	mm — used when InteriorType is “COMFORT”
curve_from_ring_size	bool		rail generated from the ring size instead of a picked curve
distance	float	yes	axial gap; negative presses the band into the mother, mm
flip_side	bool	yes	build on the other side of the mother
gems	MatchingShankGems
interior_type	str	yes	”SOLID” or “COMFORT”
layer_name	str
metal	str		e.g. “GOLD_YELLOW_18”
mother_gem_id	str
mother_ring_ids	List[str]		The ring(s) this shank was fitted against, and the rail it follows.
number_of_points	int	yes	sections used to follow the mother — always even
object_type	str
position	Point3d
profile_height	float	yes	mm
profile_name	str		RING_PROFILE asset name, "" when unset
profile_width	float	yes	band section at the top, mm
ring_curve_id	str		None when built from the ring size
ring_diameter_mm	float
ring_size_label	str
ring_size_region	str
section_contact_offsets	List[float]
section_deltas	List[float]	yes	Per-section fit. Deltas are yours to set; contact offsets are what the last computation measured (read-only output).
top_distance	float	yes	extra axial gap at the ring top, fading to 0 at 90 degrees, mm

Method
delete()
move(translation: VectorLike)
set_element(element: str)	Applies a saved MatchingShank element (ra.elements.list(“MatchingShank”)) to this shank: its band and gems replace the current ones, the ring size, mother ring(s) and rail stay, and the shank regenerates in place.
set_profile(asset_name: str)	Setters — each regenerates the shank in place (same Guid), re-baking its gems and prongs, and calls LicenseGate.RequireValid() first.

Plus what every handle has: id, delete(), update(**kwargs), parameters(), equality and hashing by id, and raw (the underlying .NET object).

MatchingShankGems (section)

The gems row a matching shank can carry. A live view over the shank’s stored parameters: getters read the current values, setters regenerate the shank in place (same Guid) and are license-gated.

Property	Type	Settable
angle	float	yes	degrees
automatic_prong_diameter	bool	yes
bottom_inner_height	float	yes	mm — 0 = same as the top
bottom_inner_width	float	yes	mm — 0 = same as the top
bright_cut	float	yes	mm
distribution	str	yes	”FULL”, “SIDE” or “TOP”
double_prong_setting	bool	yes
drill_allow_intersection	bool	yes
drill_enabled	bool	yes
drill_height	float	yes	mm
drill_type	str	yes	”NONE”, “ROUND” or “QUAD”
drill_visible	bool	yes
drill_width	float	yes	mm
enabled	bool	yes
end_angle	float		degrees — used when Distribution is “SIDE”
end_prong_count	int	yes
extension_for_manufacturing	float	yes	mm
gem_inside	float	yes	mm
gem_shape	str	yes	”ROUND”, “PRINCESS”, …
gem_size	float	yes	mm
gem_size_end	float		mm
gem_size_middle	float		mm
gem_size_start	float		mm
gradient	bool	yes	Stone-size gradient along the row.
gradient_middle_position	float	yes	0..1
gradient_points	int	yes
inner_height	float	yes	inner channel height at the top, mm
inner_margin	float	yes	mm
inner_width	float	yes	inner channel width at the top, mm
margin	float	yes	mm
min_distance	float	yes	mm
prong_bottom_diameter	float	yes	mm — 0 = same as the top
prong_diameter	float	yes	mm
prong_distance	float	yes	mm
prong_grow	float	yes	mm
prong_height	float	yes	mm
prong_min_diameter	float	yes	mm
prong_spacing	float	yes	mm
prong_top_diameter	float	yes	mm — 0 = automatic
prong_type	str	yes	”NONE”, “SHARED” or “SCALLOPED”
row_offset	float	yes	mm
scallop_gem_height	float
scallop_gem_width	float		Scalloped-setting proportions (percentages, not mm).
scallop_prong_height	float
scallop_prong_width	float
scallop_rail_height	float
scallop_rail_width	float
scallop_remove_channel	bool	yes
start_angle	float		degrees from the top — used when Distribution is “SIDE”
top_angle	float	yes	total arc in degrees — used when Distribution is “TOP”
vertical	float	yes	mm

Method
set_gem_size_gradient(start: float, middle: float, end: float)
set_scallop_gem(width: float, height: float)
set_scallop_prong(width: float, height: float)
set_scallop_rail(width: float, height: float)
set_side_angles(start_angle: float, end_angle: float)