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)

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

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