MatchingShankApi

Matching shanks — bands fitted against an existing ring so the pair stacks without a gap. Query-only for now: run ArtisanMatchingShank in the UI to fit the first one, then script every variant from its handle.

from ArtisanPlugin.Scripting import MatchingShankApi

See also the guide, Shanks › Matching shank, and the Python package, ra.matching_shank.

Methods

Method
All	IMatchingShank handles for every object of this kind in the active document (empty when there is no document).
ByLayer	IMatchingShank 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 null when the id does not belong to an object of this kind.
ForRing	The matching shanks fitted against a given ring.
Selected	IMatchingShank handles for the objects of this kind currently selected in the active document.

All

IReadOnlyList<IMatchingShank> MatchingShankApi.All()

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

Returns IReadOnlyList<IMatchingShank>.

ByLayer

IReadOnlyList<IMatchingShank> MatchingShankApi.ByLayer(string layerName)

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

Parameter	Type	Default
layerName	string	required

Returns IReadOnlyList<IMatchingShank>.

Count

int MatchingShankApi.Count()

Number of objects of this kind in the active document.

Returns int.

Find

IMatchingShank MatchingShankApi.Find(Guid id)

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

Parameter	Type	Default
id	Guid	required

Returns IMatchingShank.

ForRing

IReadOnlyList<IMatchingShank> MatchingShankApi.ForRing(Guid ringId)

The matching shanks fitted against a given ring.

Parameter	Type	Default
ringId	Guid	required

Returns IReadOnlyList<IMatchingShank>.

Selected

IReadOnlyList<IMatchingShank> MatchingShankApi.Selected()

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

Returns IReadOnlyList<IMatchingShank>.

Handles and sections

What the methods above hand back. A handle’s setters regenerate the object; wrap changes in a Transaction so they land as one undo step.

IMatchingShank

Handle — extends IParametricObject.

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
BothSides	bool	get	build one band on each side
BottomHeight	double	get	mm — 0 = same as the top
BottomWidth	double	get	band section at the bottom, mm — 0 = same as the top
Clearance	double	get	gap kept against the mother, mm
Comfort	double	get	mm — used when InteriorType is “COMFORT”
CurveFromRingSize	bool	get	rail generated from the ring size instead of a picked curve
Distance	double	get	axial gap; negative presses the band into the mother, mm
FlipSide	bool	get	build on the other side of the mother
Gems	IMatchingShankGems	get
Id	Guid	get	(from IParametricObject)
InteriorType	string	get	”SOLID” or “COMFORT”
LayerName	string	get	(from IParametricObject)
Metal	string	get	e.g. “GOLD_YELLOW_18”
MotherGemId	Guid	get	(from IParametricObject)
MotherRingIds	IReadOnlyList<Guid>	get	The ring(s) this shank was fitted against, and the rail it follows.
NumberOfPoints	int	get	sections used to follow the mother — always even
ObjectType	string	get	(from IParametricObject)
Position	Point3d	get	(from IParametricObject)
ProfileHeight	double	get	mm
ProfileName	string	get	RING_PROFILE asset name, "" when unset
ProfileWidth	double	get	band section at the top, mm
RingCurveId	Guid	get	Guid.Empty when built from the ring size
RingDiameterMm	double	get
RingSizeLabel	string	get
RingSizeRegion	string	get
SectionContactOffsets	IReadOnlyList<double>	get
SectionDeltas	IReadOnlyList<double>	get	Per-section fit. Deltas are yours to set; contact offsets are what the last computation measured (read-only output).
TopDistance	double	get	extra axial gap at the ring top, fading to 0 at 90 degrees, mm

Method
void Delete()	(from IParametricObject)
void Move(Vector3d translation)	(from IParametricObject)
void SetBothSides(bool bothSides)
void SetBottomHeight(double height)	0 = same as the top
void SetBottomWidth(double width)	0 = same as the top
void SetClearance(double clearance)
void SetComfort(double comfort)
void SetDistance(double distance)
void SetElement(string element)	Applies a saved MatchingShank element (ElementsApi.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.
void SetFlipSide(bool flip)
void SetInteriorType(string interiorType)	”SOLID” or “COMFORT”
void SetNumberOfPoints(int points)
void SetProfile(string assetName)	Setters — each regenerates the shank in place (same Guid), re-baking its gems and prongs, and calls LicenseGate.RequireValid() first. RING_PROFILE asset by name — list them with AssetsApi.List(“RING_PROFILE”)
void SetProfileHeight(double height)
void SetProfileWidth(double width)
void SetSectionDeltas(IEnumerable<double> deltas)	one per section, mm
void SetTopDistance(double distance)

IMatchingShankGems

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
Angle	double	get	degrees
AutomaticProngDiameter	bool	get
BottomInnerHeight	double	get	mm — 0 = same as the top
BottomInnerWidth	double	get	mm — 0 = same as the top
BrightCut	double	get	mm
Distribution	string	get	”FULL”, “SIDE” or “TOP”
DoubleProngSetting	bool	get
DrillAllowIntersection	bool	get
DrillEnabled	bool	get
DrillHeight	double	get	mm
DrillType	string	get	”NONE”, “ROUND” or “QUAD”
DrillVisible	bool	get
DrillWidth	double	get	mm
Enabled	bool	get
EndAngle	double	get	degrees — used when Distribution is “SIDE”
EndProngCount	int	get
ExtensionForManufacturing	double	get	mm
GemInside	double	get	mm
GemShape	string	get	”ROUND”, “PRINCESS”, …
GemSize	double	get	mm
GemSizeEnd	double	get	mm
GemSizeMiddle	double	get	mm
GemSizeStart	double	get	mm
Gradient	bool	get	Stone-size gradient along the row.
GradientMiddlePosition	double	get	0..1
GradientPoints	int	get
InnerHeight	double	get	inner channel height at the top, mm
InnerMargin	double	get	mm
InnerWidth	double	get	inner channel width at the top, mm
Margin	double	get	mm
MinDistance	double	get	mm
ProngBottomDiameter	double	get	mm — 0 = same as the top
ProngDiameter	double	get	mm
ProngDistance	double	get	mm
ProngGrow	double	get	mm
ProngHeight	double	get	mm
ProngMinDiameter	double	get	mm
ProngSpacing	double	get	mm
ProngTopDiameter	double	get	mm — 0 = automatic
ProngType	string	get	”NONE”, “SHARED” or “SCALLOPED”
RowOffset	double	get	mm
ScallopGemHeight	double	get
ScallopGemWidth	double	get	Scalloped-setting proportions (percentages, not mm).
ScallopProngHeight	double	get
ScallopProngWidth	double	get
ScallopRailHeight	double	get
ScallopRailWidth	double	get
ScallopRemoveChannel	bool	get
StartAngle	double	get	degrees from the top — used when Distribution is “SIDE”
TopAngle	double	get	total arc in degrees — used when Distribution is “TOP”
Vertical	double	get	mm

Method
void SetAngle(double degrees)
void SetAutomaticProngDiameter(bool automatic)
void SetBottomInnerHeight(double height)	0 = same as the top
void SetBottomInnerWidth(double width)	0 = same as the top
void SetBrightCut(double brightCut)
void SetDistribution(string distribution)	”FULL”, “SIDE” or “TOP”
void SetDoubleProngSetting(bool enabled)
void SetDrillAllowIntersection(bool allow)
void SetDrillEnabled(bool enabled)
void SetDrillHeight(double height)
void SetDrillType(string drillType)	”NONE”, “ROUND” or “QUAD”
void SetDrillVisible(bool visible)
void SetDrillWidth(double width)
void SetEnabled(bool enabled)
void SetEndProngCount(int count)
void SetExtensionForManufacturing(double extension)
void SetGemInside(double gemInside)
void SetGemShape(string shape)
void SetGemSize(double size)
void SetGemSizeGradient(double start, double middle, double end)
void SetGradient(bool enabled)
void SetGradientMiddlePosition(double position)	0..1
void SetGradientPoints(int points)
void SetInnerHeight(double height)
void SetInnerMargin(double margin)
void SetInnerWidth(double width)
void SetMargin(double margin)
void SetMinDistance(double distance)
void SetProngBottomDiameter(double diameter)	0 = same as the top
void SetProngDiameter(double diameter)
void SetProngDistance(double distance)
void SetProngGrow(double grow)
void SetProngHeight(double height)
void SetProngMinDiameter(double diameter)
void SetProngSpacing(double spacing)
void SetProngTopDiameter(double diameter)	0 = automatic
void SetProngType(string prongType)	”NONE”, “SHARED” or “SCALLOPED”
void SetRowOffset(double offset)
void SetScallopGem(double width, double height)
void SetScallopProng(double width, double height)
void SetScallopRail(double width, double height)
void SetScallopRemoveChannel(bool enabled)
void SetSideAngles(double startAngle, double endAngle)
void SetTopAngle(double degrees)
void SetVertical(double vertical)