.NET API

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,
    bool? extendToBridge = null,
    double heightToBridge = double.NaN,
    string bridgeMode = null,
    string centerProngType = null,
    double prongOverlap = double.NaN)

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, HEART, MARQUISE). 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). 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). centerProngType 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. prongOverlap (mm) is how much the prongs of a pair, and the Triple’s middle, cross: 0 = they touch, never a gap (NaN = keep). element = name of a saved Halo element (ElementsApi.List(“Halo”)) to start from instead of the defaults; explicit arguments override it. extendToBridge extends the mother gem’s prongs down below the halo into a bridge, heightToBridge mm under the channel (NaN = keep), joined bridgeMode CURVED or STRAIGHT (null = keep). 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`
`extendToBridge`	`bool?`	`null`
`heightToBridge`	`double`	`double.NaN`
`bridgeMode`	`string`	`null`
`centerProngType`	`string`	`null`
`prongOverlap`	`double`	`double.NaN`

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
`BridgeMode`	`string`	get	”CURVED” \| “STRAIGHT”
`CenterProngType`	`string`	get	”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.
`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 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”).
`ClawHeight`	`double`	get	mm, signed: the claw tip moved up or down (the panel’s “Height”)
`ClawOnCurve`	`int`	get	where the hook starts, % of the prong below the girdle (the panel’s “Smoothness”, 1-30)
`ClawTension`	`double`	get	degrees the hook bends down (the panel’s “Tip direction”, 10-60)
`DrillType`	`string`	get	”NONE” \| “ROUND” \| “QUAD”
`ExtendToBridge`	`bool`	get	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.
`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
`HeightToBridge`	`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.
`ProngOverlap`	`double`	get	mm the prongs of a pair, and the Triple’s middle, cross: 0 = they touch (never a gap)
`StoneSetting`	`string`	get	”NONE” \| “SHARED” \| “SCALLOPED”

Method
`void Delete()`	(from IParametricObject)
`void Move(Vector3d translation)`	(from IParametricObject)
`void SetAutomaticProngSize(bool automatic)`
`void SetBridgeMode(string mode)`	CURVED \| STRAIGHT
`void SetCenterProngType(string type)`	SINGLE \| DOUBLE \| TRIPLE, within what the mode takes (see CenterProngType)
`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)`	mm, not 0
`void SetClawHeight(double height)`	mm, signed
`void SetClawOnCurve(int onCurve)`	%, 0-100
`void SetClawTension(double tension)`	degrees, 1-90
`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 SetExtendToBridge(bool extend)`	extends the mother gem’s prongs down into a bridge
`void SetFilletFactor(double factor)`
`void SetForceEvenNumber(bool forceEven)`
`void SetHeightToBridge(double height)`	mm below the channel, >= 0; used while ExtendToBridge is on
`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; becoming CUSTOM, or CLAW from a TRIPLE, sets CenterProngType back to SINGLE.
`void SetProngOverlap(double overlap)`	mm, 0 or more (0 = the prongs touch)
`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