Python package

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, prong_mode=None, extend_to_bridge=None, height_to_bridge=None, bridge_mode=None, center_prong_type=None, prong_overlap=None, remove_channel=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, HEART, MARQUISE). 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, a channel), FLUSH (no channel), SHARED or SCALLOPED: how the halo stones are held. profile picks a CHANNEL_PROFILE asset by name; omitted = the default profile. The center stone’s prongs: prong_mode ROUND, CUSTOM (the prong_profile section; a profile alone implies it) or CLAW (DEFAULT and CIRCLE also mean ROUND). The claw is the basket’s, a prong that hooks over the stone, built in Render mode only and tuned through the handle (SetClawGemInside, SetClawHeight, SetClawTension, SetClawOnCurve). center_prong_type SINGLE (default), DOUBLE (a pair side by side on every position) or TRIPLE (the pair plus a thinner prong between them): ROUND takes all three, CLAW SINGLE or DOUBLE (the Double Claw), CUSTOM only SINGLE. prong_overlap (mm) is how much the prongs of a pair, and the Triple’s middle, cross: 0 = they touch, never a gap (NaN = keep). remove_channel True drops the channel notch under the stones for SHARED and SCALLOPED (None = keep); FLUSH never has it. drill_type NONE, ROUND or QUAD: ROUND is a cutter shaped on each stone (the Cathedral’s drill), tuned through handle.DrillCutter; QUAD a rectangle of the drill width x height. element = name of a saved Halo element (ra.elements.list(“Halo”)) to start from instead of the defaults; explicit arguments override it. extend_to_bridge extends the mother gem’s prongs down below the halo into a bridge, height_to_bridge mm under the channel (NaN = keep), joined bridge_mode CURVED or STRAIGHT (None = keep). Returns an Halo handle to the new halo 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
`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
`prong_mode`	`str`	optional — None = the tool default
`extend_to_bridge`	`Optional[bool]`	optional — None = the tool default
`height_to_bridge`	`float`	optional — None = the tool default
`bridge_mode`	`str`	optional — None = the tool default
`center_prong_type`	`str`	optional — None = the tool default
`prong_overlap`	`float`	optional — None = the tool default
`remove_channel`	`Optional[bool]`	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
`bridge_mode`	`str`	yes	”CURVED” \| “STRAIGHT”
`center_prong_type`	`str`	yes	”SINGLE” \| “DOUBLE” \| “TRIPLE”: the mother gem’s prongs per position - one, a pair side by side, or the pair plus a thinner prong between them, as on the basket. ROUND prongs take all three, CLAW SINGLE or DOUBLE (the Double Claw), CUSTOM SINGLE.
`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.
`claw_gem_inside`	`float`	yes	The claw, CLAW mode only (built in Render mode only), the basket’s: a prong of square section that hooks over the stone. How far its tip reaches in toward the gem centre, mm (the panel’s “Gem Inside”).
`claw_height`	`float`	yes	mm, signed: the claw tip moved up or down (the panel’s “Height”)
`claw_on_curve`	`int`	yes	where the hook starts, % of the prong below the girdle (the panel’s “Smoothness”, 1-30)
`claw_tension`	`float`	yes	degrees the hook bends down (the panel’s “Tip direction”, 10-60)
`drill_cutter`	DrillCutter		The ROUND drill: a cutter shaped on each stone (DrillType ROUND only)
`drill_type`	`str`	yes	”NONE” \| “ROUND” \| “QUAD”
`extend_to_bridge`	`bool`	yes	The mother gem’s prongs extended down below the halo into a bridge (the panel’s “Extend To Bridge”): HeightToBridge mm under the channel, joined CURVED or STRAIGHT.
`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`
`height_to_bridge`	`float`	yes
`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
`prong_mode`	`str`	yes	”ROUND” \| “CUSTOM” \| “CLAW”: the mother gem’s prongs, as on every setting with prongs.
`prong_overlap`	`float`	yes	mm the prongs of a pair, and the Triple’s middle, cross: 0 = they touch (never a gap)
`remove_channel`	`bool`	yes	SHARED and SCALLOPED: True drops the channel notch under the stones (FLUSH never has it)
`stone_setting`	`str`	yes	”NONE” (channel) \| “FLUSH” (no channel) \| “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; switches the prongs to CUSTOM
`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).

DrillCutter (section)

The ROUND drill of a halo: a cutter shaped on each stone, the Cathedral’s drill. Sizes and heights are PERCENTAGES of the stone, GemInside is millimetres; 0 is legal for all of them. Each setter regenerates the owner in place.

Property	Type	Settable
`drill_type`	`int`	yes	0 gem shape, 1 round, 2 square, 3 hexagon
`gem_inside`	`float`	yes	mm, signed
`height_crown`	`float`	yes
`height_drill`	`float`	yes
`height_girdle`	`float`	yes
`height_pavilion`	`float`	yes
`height_top`	`float`	yes
`size_bottom`	`float`	yes
`size_drill`	`float`	yes
`size_top`	`float`	yes