.NET API

ClusterApi

Cluster settings around a centre stone.

from ArtisanPlugin.Scripting import ClusterApi

See also the guide, Gemsets › Cluster, and the Python package, ra.cluster.

Methods

Method
`All`	`ICluster` handles for every object of this kind in the active document (empty when there is no document).
`ByLayer`	`ICluster` 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.
`Create`	Builds a cluster of small stones around an existing gem — the ArtisanCluster tool, headless.
`Find`	The handle for `id`, or null when the id does not belong to an object of this kind.
`ForGem`	`ICluster` handles whose mother gem is `gemId` (empty for Guid.Empty).
`Selected`	Clusters currently selected in the active doc.

All

IReadOnlyList<ICluster> ClusterApi.All()

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

Returns IReadOnlyList<ICluster>.

ByLayer

IReadOnlyList<ICluster> ClusterApi.ByLayer(string layerName)

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

Parameter	Type	Default
`layerName`	`string`	required

Returns IReadOnlyList<ICluster>.

Count

int ClusterApi.Count()

Number of objects of this kind in the active document.

Returns int.

Create

ICluster ClusterApi.Create(
    Guid gemId,
    double stoneSize = 0,
    double stoneDistance = 0,
    double distanceToGem = 0,
    int prongNumber = 0,
    double prongDiameter = 0,
    double railDiameter = 0,
    bool? doubleRail = null,
    double railDiameter2 = 0,
    string prongOrientation = null,
    double internalProngDiameter = 0,
    double externalProngDiameter = 0,
    double centralProngDiameter = 0,
    double stonesZPosition = double.NaN,
    double stonesRotation = double.NaN,
    string element = null,
    bool? centerProngs = null,
    string centerProngMode = null,
    string centerProngType = null,
    int centerProngCount = 0,
    double centerProngDiameter = 0,
    double centerProngOverlap = double.NaN)

Builds a cluster of small stones around an existing gem — the ArtisanCluster tool, headless. gemId must be a gem in the active document with a cluster-friendly shape (ROUND, CUSHION, EMERALD, OVAL, RADIANT, ASSCHER); the kernel picks the matching shape variant internally. Millimetres; 0 keeps the tool default (or the user’s saved defaults): stoneSize 1.6, stoneDistance 0.2, distanceToGem 1.0, prongDiameter 0.8 (applied to the internal, external and central prongs alike), railDiameter 1.0. prongNumber is 3, 4 or 5 (default 4). element = name of a saved Cluster element (ElementsApi.List(“Cluster”)) to start from instead of the defaults; explicit arguments override it. The centre stone’s own prongs (the Halo’s, off by default): centerProngs true turns them on (any other centerProng* value implies it). centerProngMode ROUND, CUSTOM or CLAW; centerProngType SINGLE, DOUBLE or TRIPLE (CLAW takes SINGLE or DOUBLE, CUSTOM SINGLE); centerProngCount positions, centerProngDiameter mm, centerProngOverlap mm (pairs). They run down from the stone and curve into the main gem rail; the rest through handle.CenterProngs. Returns an ICluster handle to the new cluster group.

Parameter	Type	Default
`gemId`	`Guid`	required
`stoneSize`	`double`	`0`
`stoneDistance`	`double`	`0`
`distanceToGem`	`double`	`0`
`prongNumber`	`int`	`0`
`prongDiameter`	`double`	`0`
`railDiameter`	`double`	`0`
`doubleRail`	`bool?`	`null`
`railDiameter2`	`double`	`0`
`prongOrientation`	`string`	`null`
`internalProngDiameter`	`double`	`0`
`externalProngDiameter`	`double`	`0`
`centralProngDiameter`	`double`	`0`
`stonesZPosition`	`double`	`double.NaN`
`stonesRotation`	`double`	`double.NaN`
`element`	`string`	`null`
`centerProngs`	`bool?`	`null`
`centerProngMode`	`string`	`null`
`centerProngType`	`string`	`null`
`centerProngCount`	`int`	`0`
`centerProngDiameter`	`double`	`0`
`centerProngOverlap`	`double`	`double.NaN`

Returns ICluster.

Find

ICluster ClusterApi.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 ICluster.

ForGem

IReadOnlyList<ICluster> ClusterApi.ForGem(Guid gemId)

ICluster handles whose mother gem is gemId (empty for Guid.Empty).

Parameter	Type	Default
`gemId`	`Guid`	required

Returns IReadOnlyList<ICluster>.

Selected

IReadOnlyList<ICluster> ClusterApi.Selected()

Clusters currently selected in the active doc.

Returns IReadOnlyList<ICluster>.

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.

ICluster

Handle — extends IGemSetting, IParametricObject.

Property	Type
`CenterProngs`	`IClusterCenterProngs`	get	The optional prongs of the centre stone itself (the Halo’s), see IClusterCenterProngs.
`CentralProngDiameter`	`double`	get
`ClusterStoneCount`	`int`	get	Stones forming the cluster (around the center gem)
`ClusterStoneSize`	`double`	get
`ClusterStoneWeight`	`double`	get
`ClusterTotalWeight`	`double`	get
`DistanceToGem`	`double`	get
`DoubleRail`	`bool`	get
`ExternalProngDiameter`	`double`	get
`FilletFactor`	`double`	get
`GemCaratWeight`	`double`	get	(from IGemSetting)
`GemMaterial`	`string`	get	(from IGemSetting)
`GemShape`	`string`	get	(from IGemSetting)
`Id`	`Guid`	get	(from IParametricObject)
`InternalProngDiameter`	`double`	get
`LayerName`	`string`	get	(from IParametricObject)
`MotherGemId`	`Guid`	get	(from IParametricObject)
`ObjectType`	`string`	get	(from IParametricObject)
`Position`	`Point3d`	get	(from IParametricObject)
`ProngCount`	`int`	get	3, 4 or 5
`ProngOrientation`	`string`	get	”CURVE” \| “CENTER”
`RailDiameter1`	`double`	get
`RailDiameter2`	`double`	get
`StoneDistance`	`double`	get
`StoneSize`	`double`	get	Current values. Millimetres / degrees; several are signed.
`StonesRotation`	`double`	get	signed
`StonesZPosition`	`double`	get	signed

Method
`void Delete()`	(from IParametricObject)
`void Move(Vector3d translation)`	(from IParametricObject)
`void SetBaseHeight(double height)`
`void SetBaseMoveInZ(double moveInZ)`	signed
`void SetBaseWidth(double width)`
`void SetCentralProngDiameter(double diameter)`
`void SetDistanceToGem(double distance)`
`void SetDoubleRail(bool enabled)`
`void SetElement(string element)`	Applies a saved Cluster element (ElementsApi.List(“Cluster”)) to this cluster: its parameters replace the current ones, the mother gem stays, and the cluster regenerates in place (same id).
`void SetExternalProngDiameter(double diameter)`
`void SetFilletFactor(double factor)`
`void SetInternalProngDiameter(double diameter)`
`void SetProngCount(int count)`	3, 4 or 5
`void SetProngDiameter(double diameter)`	all three families at once
`void SetProngOrientation(string orientation)`	CURVE \| CENTER
`void SetRailDiameter1(double diameter)`
`void SetRailDiameter2(double diameter)`
`void SetRailMoveInZ1(double moveInZ)`	signed
`void SetRailMoveInZ2(double moveInZ)`	signed
`void SetStoneDistance(double distance)`
`void SetStoneSize(double size)`	Parametric edits — each regenerates the cluster (the group keeps its id) and calls LicenseGate.RequireValid() first. These take LITERAL values: 0 and negatives are allowed where the parameter is signed.
`void SetStonesRotation(double degrees)`	signed
`void SetStonesZPosition(double z)`	signed

IClusterCenterProngs

Section.

The cluster’s optional prongs of the centre stone itself - the Halo’s (round, Double, Triple, Claw, Double Claw or a custom section) - on top of the internal prongs the cluster stones share with it. They run down from the stone and curve into the main gem rail. Off by default.

Property	Type
`BridgeMode`	`string`	get	”CURVED” \| “STRAIGHT”: how the prongs run into the main gem rail
`CapBump`	`double`	get	mm, the bulge of the round cap
`ClawGemInside`	`double`	get	CLAW, mm: how far the tip reaches in toward the stone centre
`ClawHeight`	`double`	get	CLAW, mm, signed: the tip moved up or down
`ClawOnCurve`	`int`	get	CLAW, % of the prong below the girdle where the hook starts (Smoothness, 1-30)
`ClawTension`	`double`	get	CLAW, degrees the hook bends down (the panel’s Tip direction, 10-60)
`Count`	`int`	get	prong positions round the stone
`Diameter`	`double`	get	mm
`Enabled`	`bool`	get
`ExtensionForManufacturing`	`double`	get	mm, MANUFACTURING extension
`GemInside`	`double`	get	mm into the stone, signed
`HeightOverGirdle`	`double`	get	mm above the girdle
`Mode`	`string`	get	”ROUND” \| “CUSTOM” \| “CLAW”
`MoveInZ`	`double`	get	mm, signed
`Overlap`	`double`	get	mm the prongs of a pair, and the Triple’s middle, cross: 0 = they touch
`ProfileName`	`string`	get	CLOSED_PROFILE asset name of the CUSTOM section, "" when unset
`Rotation`	`double`	get	degrees (CUSTOM section)
`Type`	`string`	get	”SINGLE” \| “DOUBLE” \| “TRIPLE”: prongs per position. ROUND takes all three, CLAW SINGLE or DOUBLE (the Double Claw), CUSTOM SINGLE.

Method
`void SetBridgeMode(string mode)`	CURVED \| STRAIGHT
`void SetCapBump(double capBump)`
`void SetClawGemInside(double gemInside)`	mm, not 0
`void SetClawHeight(double height)`
`void SetClawOnCurve(int onCurve)`	%, 0-100
`void SetClawTension(double tension)`	degrees, 1-90
`void SetCount(int count)`
`void SetDiameter(double diameter)`
`void SetEnabled(bool enabled)`
`void SetExtensionForManufacturing(double extension)`
`void SetGemInside(double gemInside)`
`void SetHeightOverGirdle(double height)`
`void SetMode(string mode)`	ROUND \| CUSTOM \| CLAW; becoming CUSTOM, or CLAW from a TRIPLE, sets Type back to SINGLE
`void SetMoveInZ(double moveInZ)`
`void SetOverlap(double overlap)`
`void SetProfile(string assetName)`	CLOSED_PROFILE asset; switches the mode to CUSTOM
`void SetRotation(double degrees)`
`void SetType(string type)`	SINGLE \| DOUBLE \| TRIPLE, within what the mode takes