HaloApi

A halo of small stones around a centre stone.

from ArtisanPlugin.Scripting import HaloApi

See also the guide, Gemsets › Halo, and the Python package, ra.halo.

Methods

Method
All	IHalo handles for every object of this kind in the active document (empty when there is no document).
ByLayer	IHalo 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 null when the id does not belong to an object of this kind.
ForGem	IHalo handles whose mother gem is gemId (empty for Guid.Empty).
Selected	Halos currently selected in the active doc.

All

IReadOnlyList<IHalo> HaloApi.All()

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

Returns IReadOnlyList<IHalo>.

ByLayer

IReadOnlyList<IHalo> HaloApi.ByLayer(string layerName)

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

Parameter	Type	Default
layerName	string	required

Returns IReadOnlyList<IHalo>.

Count

int HaloApi.Count()

Number of objects of this kind in the active document.

Returns int.

Create

IHalo HaloApi.Create(
    Guid gemId,
    double stoneSize = 0,
    double stoneDistance = 0,
    double distanceToGem = 0,
    double channelWidth = 0,
    double channelHeight = 0,
    string prongType = null,
    string profile = null,
    double channelPositionZ = double.NaN,
    double channelRotation = double.NaN,
    double channelBrightCut = double.NaN,
    double channelInnerWidth = 0,
    double channelInnerHeight = 0,
    double stoneVertical = double.NaN,
    double stoneGemInside = double.NaN,
    string drillType = null,
    bool? forceEvenNumber = null,
    int prongCount = 0,
    double prongDiameter = 0,
    string prongProfile = null,
    string element = null,
    string prongMode = null)

Builds a halo of small stones around an existing gem — the ArtisanHalo tool, headless. gemId must be a gem in the active document with a halo-friendly shape (ROUND, CUSHION, EMERALD, OVAL, RADIANT, ASSCHER, PEAR). Millimetres; 0 keeps the tool default (or the user’s saved defaults): stoneSize 1.2, stoneDistance 0.2, distanceToGem 1.2, channelWidth 1.5, channelHeight 1.5. prongType is NONE (default), 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: prongMode ROUND, CUSTOM (the prongProfile section; a profile alone implies it) or CLAW (DEFAULT and CIRCLE also mean ROUND); claw tips are built in Render mode only and tuned through the handle (SetClawGemInside…). element = name of a saved Halo element (ElementsApi.List(“Halo”)) to start from instead of the defaults; explicit arguments override it. Returns an IHalo handle to the new halo group.

Parameter	Type	Default
gemId	Guid	required
stoneSize	double	0
stoneDistance	double	0
distanceToGem	double	0
channelWidth	double	0
channelHeight	double	0
prongType	string	null
profile	string	null
channelPositionZ	double	double.NaN
channelRotation	double	double.NaN
channelBrightCut	double	double.NaN
channelInnerWidth	double	0
channelInnerHeight	double	0
stoneVertical	double	double.NaN
stoneGemInside	double	double.NaN
drillType	string	null
forceEvenNumber	bool?	null
prongCount	int	0
prongDiameter	double	0
prongProfile	string	null
element	string	null
prongMode	string	null

Returns IHalo.

Find

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

ForGem

IReadOnlyList<IHalo> HaloApi.ForGem(Guid gemId)

IHalo handles whose mother gem is gemId (empty for Guid.Empty).

Parameter	Type	Default
gemId	Guid	required

Returns IReadOnlyList<IHalo>.

Selected

IReadOnlyList<IHalo> HaloApi.Selected()

Halos currently selected in the active doc.

Returns IReadOnlyList<IHalo>.

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.

IHalo

Handle — extends IGemSetting, IParametricObject.

Property	Type
ChannelBrightCut	double	get
ChannelDistanceToGem	double	get
ChannelHeight	double	get
ChannelInnerHeight	double	get
ChannelInnerWidth	double	get
ChannelPositionZ	double	get	signed
ChannelRotation	double	get	degrees, signed
ChannelWidth	double	get	The metal rail carrying the halo stones. PositionZ and Rotation are what make a halo sit flush, float or tilt.
ClawGemInside	double	get	The halo’s own claw tip, CLAW mode only (built in Render mode only), under the panel’s names: how far in toward the gem the tip reaches (a fraction of the way to the gem centre; 0 builds no tip).
ClawTension	double	get	1-100
ClawTipDistance	double	get	the panel’s “Tip distance”: height of the rounded tip
ClawTipHeight	double	get
ClawTipWidth	double	get
DrillType	string	get	”NONE” | “ROUND” | “QUAD”
ForceEvenNumber	bool	get
GemCaratWeight	double	get	(from IGemSetting)
GemMaterial	string	get	(from IGemSetting)
GemShape	string	get	(from IGemSetting)
HaloStoneCount	int	get	Stones forming the halo ring (around the center gem)
HaloStoneSize	double	get
HaloStoneWeight	double	get
HaloTotalWeight	double	get
Id	Guid	get	(from IParametricObject)
LayerName	string	get	(from IParametricObject)
MotherGemId	Guid	get	(from IParametricObject)
ObjectType	string	get	(from IParametricObject)
Position	Point3d	get	(from IParametricObject)
ProngCount	int	get	the MOTHER gem’s prongs
ProngDiameter	double	get
ProngMode	string	get	”ROUND” | “CUSTOM” | “CLAW”: the mother gem’s prongs, as on every setting with prongs.
StoneSetting	string	get	”NONE” | “SHARED” | “SCALLOPED”

Method
void Delete()	(from IParametricObject)
void Move(Vector3d translation)	(from IParametricObject)
void SetAutomaticProngSize(bool automatic)
void SetChannelBrightCut(double brightCut)
void SetChannelDistanceToGem(double distance)	signed
void SetChannelHeight(double height)
void SetChannelInnerHeight(double height)
void SetChannelInnerWidth(double width)
void SetChannelPositionZ(double positionZ)	signed
void SetChannelProfile(string assetName)	CHANNEL_PROFILE asset
void SetChannelRotation(double degrees)	signed
void SetChannelWidth(double width)
void SetClawGemInside(double gemInside)	not 0
void SetClawTension(double tension)	1-100
void SetClawTipDistance(double distance)
void SetClawTipHeight(double height)
void SetClawTipWidth(double width)
void SetDrillSize(double width, double height)
void SetDrillType(string drillType)	NONE | ROUND | QUAD
void SetElement(string element)	Applies a saved Halo element (ElementsApi.List(“Halo”)) to this halo: its parameters replace the current ones, the mother gem stays, and the halo regenerates in place (same id).
void SetFilletFactor(double factor)
void SetForceEvenNumber(bool forceEven)
void SetProngCount(int count)	the MOTHER gem’s prongs
void SetProngDiameter(double diameter)
void SetProngGemInside(double gemInside)	signed
void SetProngHeightOverGirdle(double height)
void SetProngMode(string mode)	ROUND | CUSTOM | CLAW (DEFAULT and CIRCLE also mean ROUND). CLAW on a halo whose claw values are all 0 starts from the tool’s defaults.
void SetProngProfile(string assetName)	CLOSED_PROFILE asset; switches the prongs to CUSTOM
void SetProngRotation(double degrees)	signed
void SetStoneDistance(double stoneDistance)
void SetStoneGemInside(double gemInside)	signed
void SetStoneSetting(string setting)	NONE | SHARED | SCALLOPED
void SetStoneSize(double stoneSize)	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. Millimetres, and LITERAL values: 0 and negatives are allowed where the parameter is signed.
void SetStoneVertical(double vertical)	signed