ra.halo

A halo of small stones around a centre stone.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.HaloApi.

Functions

Function
all()	Halo handles for every object of this kind in the active document (empty when there is no document).
by_layer()	Halo 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 halo of small stones around an existing gem — the ArtisanHalo tool, headless.
find()	The handle for id, or None when the id does not belong to an object of this kind.
for_gem()	Halo handles whose mother gem is gem_id (empty for None).
selected()	Halos currently selected in the active doc.

ra.halo.all()

ra.halo.all() -> List[Halo]

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

ra.halo.by_layer()

ra.halo.by_layer(layer_name: str) -> List[Halo]

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

Parameter	Type
layer_name	str	required

ra.halo.count()

ra.halo.count() -> int

Number of objects of this kind in the active document.

ra.halo.create()

ra.halo.create(gem_id: IdLike, stone_size=None, stone_distance=None, distance_to_gem=None, channel_width=None, channel_height=None, prong_type=None, profile=None, channel_position_z=None, channel_rotation=None, channel_bright_cut=None, channel_inner_width=None, channel_inner_height=None, stone_vertical=None, stone_gem_inside=None, drill_type=None, force_even_number=None, prong_count=None, prong_diameter=None, prong_profile=None, element=None) -> Halo

Builds a halo of small stones around an existing gem — the ArtisanHalo tool, headless. gem_id must be a gem in the active document with a halo-friendly shape (ROUND, CUSHION, EMERALD, OVAL, RADIANT, ASSCHER, PEAR). Millimetres; omitting keeps the tool default (or the user’s saved defaults): stone_size 1.2, stone_distance 0.2, distance_to_gem 1.2, channel_width 1.5, channel_height 1.5. prong_type is NONE (default), SHARED or SCALLOPED. profile picks a CHANNEL_PROFILE asset by name; omitted = the default profile. Returns an Halo handle to the new halo 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
channel_width	float	optional — None = the tool default
channel_height	float	optional — None = the tool default
prong_type	str	optional — None = the tool default
profile	str	optional — None = the tool default
channel_position_z	float	optional — None = the tool default
channel_rotation	float	optional — None = the tool default
channel_bright_cut	float	optional — None = the tool default
channel_inner_width	float	optional — None = the tool default
channel_inner_height	float	optional — None = the tool default
stone_vertical	float	optional — None = the tool default
stone_gem_inside	float	optional — None = the tool default
drill_type	str	optional — None = the tool default
force_even_number	Optional[bool]	optional — None = the tool default
prong_count	int	optional — None = the tool default
prong_diameter	float	optional — None = the tool default
prong_profile	str	optional — None = the tool default
element	str	optional — None = the tool default

ra.halo.find()

ra.halo.find(id: IdLike) -> Halo

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

Parameter	Type
id	IdLike	required

ra.halo.for_gem()

ra.halo.for_gem(gem_id: IdLike) -> List[Halo]

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

Parameter	Type
gem_id	IdLike	required

ra.halo.selected()

ra.halo.selected() -> List[Halo]

Halos 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().

Halo (handle)

Property	Type	Settable
channel_bright_cut	float	yes
channel_distance_to_gem	float	yes
channel_height	float	yes
channel_inner_height	float	yes
channel_inner_width	float	yes
channel_position_z	float	yes	signed
channel_rotation	float	yes	degrees, signed
channel_width	float	yes	The metal rail carrying the halo stones. PositionZ and Rotation are what make a halo sit flush, float or tilt.
drill_type	str	yes	”NONE” | “ROUND” | “QUAD”
force_even_number	bool	yes
gem_carat_weight	float
gem_material	str
gem_shape	str
halo_stone_count	int		Stones forming the halo ring (around the center gem)
halo_stone_size	float
halo_stone_weight	float
halo_total_weight	float
layer_name	str
mother_gem_id	str
object_type	str
position	Point3d
prong_count	int	yes	the MOTHER gem’s prongs
prong_diameter	float	yes
stone_setting	str	yes	”NONE” | “SHARED” | “SCALLOPED”

Method
delete()
move(translation: VectorLike)
set_automatic_prong_size(automatic: bool)
set_channel_profile(asset_name: str)	CHANNEL_PROFILE asset
set_drill_size(width: float, height: float)
set_element(element: str)	Applies a saved Halo element (ra.elements.list(“Halo”)) to this halo: its parameters replace the current ones, the mother gem stays, and the halo regenerates in place (same id).
set_fillet_factor(factor: float)
set_prong_gem_inside(gem_inside: float)	signed
set_prong_height_over_girdle(height: float)
set_prong_profile(asset_name: str)	CLOSED_PROFILE asset
set_prong_rotation(degrees: float)	signed
set_stone_distance(stone_distance: float)
set_stone_gem_inside(gem_inside: float)	signed
set_stone_size(stone_size: float)	Parametric edits — each regenerates the halo (the group keeps its id, so this handle stays valid; the member objects are rebuilt) and calls LicenseGate.RequireValid() first.
set_stone_vertical(vertical: float)	signed

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