Python package

ra.cluster

Cluster settings around a centre stone.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.ClusterApi.

Functions

Function
`all()`	`Cluster` handles for every object of this kind in the active document (empty when there is no document).
`by_layer()`	`Cluster` 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 None when the id does not belong to an object of this kind.
`for_gem()`	`Cluster` handles whose mother gem is `gem_id` (empty for None).
`selected()`	Clusters currently selected in the active doc.

ra.cluster.all()

ra.cluster.all() -> List[Cluster]

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

ra.cluster.by_layer()

ra.cluster.by_layer(layer_name: str) -> List[Cluster]

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

Parameter	Type
`layer_name`	`str`	required

ra.cluster.count()

ra.cluster.count() -> int

Number of objects of this kind in the active document.

ra.cluster.create()

ra.cluster.create(gem_id: IdLike, stone_size=None, stone_distance=None, distance_to_gem=None, prong_number=None, prong_diameter=None, rail_diameter=None, double_rail=None, rail_diameter2=None, prong_orientation=None, internal_prong_diameter=None, external_prong_diameter=None, central_prong_diameter=None, stones_z_position=None, stones_rotation=None, element=None, center_prongs=None, center_prong_mode=None, center_prong_type=None, center_prong_count=None, center_prong_diameter=None, center_prong_overlap=None) -> Cluster

Builds a cluster of small stones around an existing gem — the ArtisanCluster tool, headless. gem_id 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; omitting keeps the tool default (or the user’s saved defaults): stone_size 1.6, stone_distance 0.2, distance_to_gem 1.0, prong_diameter 0.8 (applied to the internal, external and central prongs alike), rail_diameter 1.0. prong_number is 3, 4 or 5 (default 4). element = name of a saved Cluster element (ra.elements.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): center_prongs True turns them on (any other center_prong* value implies it). center_prong_mode ROUND, CUSTOM or CLAW; center_prong_type SINGLE, DOUBLE or TRIPLE (CLAW takes SINGLE or DOUBLE, CUSTOM SINGLE); center_prong_count positions, center_prong_diameter mm, center_prong_overlap mm (pairs). They run down from the stone and curve into the main gem rail; the rest through handle.CenterProngs. Returns an Cluster handle to the new cluster group.

Parameter	Type
`gem_id`	`IdLike`	required
`stone_size`	`float`	optional — None = the tool default
`stone_distance`	`float`	optional — None = the tool default
`distance_to_gem`	`float`	optional — None = the tool default
`prong_number`	`int`	optional — None = the tool default
`prong_diameter`	`float`	optional — None = the tool default
`rail_diameter`	`float`	optional — None = the tool default
`double_rail`	`Optional[bool]`	optional — None = the tool default
`rail_diameter2`	`float`	optional — None = the tool default
`prong_orientation`	`str`	optional — None = the tool default
`internal_prong_diameter`	`float`	optional — None = the tool default
`external_prong_diameter`	`float`	optional — None = the tool default
`central_prong_diameter`	`float`	optional — None = the tool default
`stones_z_position`	`float`	optional — None = the tool default
`stones_rotation`	`float`	optional — None = the tool default
`element`	`str`	optional — None = the tool default
`center_prongs`	`Optional[bool]`	optional — None = the tool default
`center_prong_mode`	`str`	optional — None = the tool default
`center_prong_type`	`str`	optional — None = the tool default
`center_prong_count`	`int`	optional — None = the tool default
`center_prong_diameter`	`float`	optional — None = the tool default
`center_prong_overlap`	`float`	optional — None = the tool default

ra.cluster.find()

ra.cluster.find(id: IdLike) -> Cluster

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

Parameter	Type
`id`	`IdLike`	required

ra.cluster.for_gem()

ra.cluster.for_gem(gem_id: IdLike) -> List[Cluster]

Cluster handles whose mother gem is gem_id (empty for None).

Parameter	Type
`gem_id`	`IdLike`	required

ra.cluster.selected()

ra.cluster.selected() -> List[Cluster]

Clusters currently selected in the active doc.

Handles

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

Cluster (handle)

Property	Type	Settable
`center_prongs`	ClusterCenterProngs		The optional prongs of the centre stone itself (the Halo’s), see ClusterCenterProngs.
`central_prong_diameter`	`float`	yes
`cluster_stone_count`	`int`		Stones forming the cluster (around the center gem)
`cluster_stone_size`	`float`
`cluster_stone_weight`	`float`
`cluster_total_weight`	`float`
`distance_to_gem`	`float`	yes
`double_rail`	`bool`	yes
`external_prong_diameter`	`float`	yes
`fillet_factor`	`float`	yes
`gem_carat_weight`	`float`
`gem_material`	`str`
`gem_shape`	`str`
`internal_prong_diameter`	`float`	yes
`layer_name`	`str`
`mother_gem_id`	`str`
`object_type`	`str`
`position`	`Point3d`
`prong_count`	`int`	yes	3, 4 or 5
`prong_orientation`	`str`	yes	”CURVE” \| “CENTER”
`rail_diameter1`	`float`	yes
`rail_diameter2`	`float`	yes
`stone_distance`	`float`	yes
`stone_size`	`float`	yes	Current values. Millimetres / degrees; several are signed.
`stones_rotation`	`float`	yes	signed
`stones_z_position`	`float`	yes	signed

Method
`delete()`
`move(translation: VectorLike)`
`set_base_height(height: float)`
`set_base_move_in_z(move_in_z: float)`	signed
`set_base_width(width: float)`
`set_element(element: str)`	Applies a saved Cluster element (ra.elements.list(“Cluster”)) to this cluster: its parameters replace the current ones, the mother gem stays, and the cluster regenerates in place (same id).
`set_prong_diameter(diameter: float)`	all three families at once
`set_rail_move_in_z1(move_in_z: float)`	signed
`set_rail_move_in_z2(move_in_z: float)`	signed

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

ClusterCenterProngs (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	Settable
`bridge_mode`	`str`	yes	”CURVED” \| “STRAIGHT”: how the prongs run into the main gem rail
`cap_bump`	`float`	yes	mm, the bulge of the round cap
`claw_gem_inside`	`float`	yes	CLAW, mm: how far the tip reaches in toward the stone centre
`claw_height`	`float`	yes	CLAW, mm, signed: the tip moved up or down
`claw_on_curve`	`int`	yes	CLAW, % of the prong below the girdle where the hook starts (Smoothness, 1-30)
`claw_tension`	`float`	yes	CLAW, degrees the hook bends down (the panel’s Tip direction, 10-60)
`count`	`int`	yes	prong positions round the stone
`diameter`	`float`	yes	mm
`enabled`	`bool`	yes
`extension_for_manufacturing`	`float`	yes	mm, MANUFACTURING extension
`gem_inside`	`float`	yes	mm into the stone, signed
`height_over_girdle`	`float`	yes	mm above the girdle
`mode`	`str`	yes	”ROUND” \| “CUSTOM” \| “CLAW”
`move_in_z`	`float`	yes	mm, signed
`overlap`	`float`	yes	mm the prongs of a pair, and the Triple’s middle, cross: 0 = they touch
`profile_name`	`str`		CLOSED_PROFILE asset name of the CUSTOM section, "" when unset
`rotation`	`float`	yes	degrees (CUSTOM section)
`type`	`str`	yes	”SINGLE” \| “DOUBLE” \| “TRIPLE”: prongs per position. ROUND takes all three, CLAW SINGLE or DOUBLE (the Double Claw), CUSTOM SINGLE.

Method
`set_profile(asset_name: str)`	CLOSED_PROFILE asset; switches the mode to CUSTOM