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) -> 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). Returns an Cluster handle to the new cluster group. element = name of a saved element (ra.elements.list) to start from; explicit arguments override it.

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

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