ra.basket

Basket settings: prongs, upper and base rails.

import rhinoartisan as ra

Wraps ArtisanPlugin.Scripting.BasketApi, ArtisanPlugin.Scripting.BasketUpdateApi.

Functions

Function
all()	Basket handles for every object of this kind in the active document (empty when there is no document).
by_gem_material()
by_layer()	Basket 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 basket setting under an existing gem — the ArtisanBasket tool, headless.
find()	The handle for id, or None when the id does not belong to an object of this kind.
for_gem()	Basket handles whose mother gem is gem_id (empty for None).
selected()	Baskets currently selected in the active doc.
update_legacy_baskets()	The ArtisanBasketUpdate command, headless: finds every legacy basket (one object carrying “ObjectType = Basket” + parameters in its geometry dictionary, as saved by old Artisan versions, hidden or not), recomputes it against its mother gem with the current kernel and replaces it by the modern editable “Basket” group (metal material, RaObjectUserData with the parameters and the mother).

ra.basket.all()

ra.basket.all() -> List[Basket]

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

ra.basket.by_gem_material()

ra.basket.by_gem_material(material_name: str) -> List[Basket]

Parameter	Type
material_name	str	required

ra.basket.by_layer()

ra.basket.by_layer(layer_name: str) -> List[Basket]

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

Parameter	Type
layer_name	str	required

ra.basket.count()

ra.basket.count() -> int

Number of objects of this kind in the active document.

ra.basket.create()

ra.basket.create(gem_ids=None, prongs=None, prong_diameter=None, prong_height=None, prong_height_over_girdle=None, gem_inside=None, upper_rail=None, base_rail=None, support=None, prong_mode=None, prong_profile=None, prong_diameter_bottom=None, prong_rotation=None, straight_prong=None, support_width=None, support_thickness=None, upper_rail_width=None, upper_rail_height=None, upper_rail_height_under_girdle=None, upper_rail_gem_size_percentage=None, upper_rail_profile=None, base_rail_width=None, base_rail_height=None, base_rail_move_in_z=None, base_rail_gem_size_percentage=None, base_rail_profile=None, element=None, prong_type=None, overlap=None, v_prongs=None, v_thickness=None, v_arm_length=None) -> List[Basket]

Builds a basket setting under an existing gem — the ArtisanBasket tool, headless. One basket (its own group) per gem; gem_ids None/empty = the currently selected gems. Millimetres; omitting keeps the tool default (or the user’s saved defaults): prong_diameter 1.5 (sets top/girdle/bottom together), prong_height 4, prong_height_over_girdle 0.3. prongs 0 keeps the default (4 rotated); positive/negative counts follow the tool (negative = rotated variant). gem_inside defaults to 0.35. Those tool defaults are sized for a 5 mm stone and scale to the first gem, as in the panel (prong sizes, rails, gem inside, supports); a saved element scales from the stone it was saved on; the user’s saved defaults are used as they are on the first gem. Every other gem gets that design scaled by its size ratio to the first, so stones of different sizes each get a basket in proportion. Explicit arguments are never scaled. upper_rail/base_rail None keep the defaults (both enabled). support is NONE (default), SINGLE or DOUBLE. prong_mode is ROUND (default), CUSTOM (the prong_profile section; a profile alone implies it, and the section starts turned 90 degrees unless prong_rotation says otherwise) or CLAW; DEFAULT and CIRCLE also mean ROUND. Claw tips are built in Render mode only; tune them through the handle’s Prong section (SetClawGemInside…). prong_type is SINGLE (default), DOUBLE (a pair side by side on every position) or TRIPLE (the pair plus a thinner prong between them): ROUND prongs take all three, CLAW SINGLE or DOUBLE (the Double Claw), CUSTOM only SINGLE. overlap (mm, default 0) is how much the prongs of a pair, and the Triple’s middle, cross: 0 = they touch, never a gap; taken literally (omit it to keep the default). v_prongs True = V prongs: every prong position on a sharp corner of the girdle gets a V that wraps the corner instead of a round prong - the four corners of a princess, the tip of a pear or a heart, the tips of a six-prong marquise (its four-prong layout holds the sides and has no corner), the corners of a trillion. Round prongs only (ROUND mode); the other positions keep their prongs. v_thickness (metal width) and v_arm_length (how far each arm runs along the girdle) in mm; 0 keeps them in proportion to the prong diameter. Returns one Basket handle per gem, in input order. element = name of a saved Basket element (ra.elements.list(“Basket”)) to start from instead of the defaults; explicit arguments override it.

Parameter	Type
gem_ids	Sequence[IdLike]	optional — None = the tool default
prongs	int	optional — None = the tool default
prong_diameter	float	optional — None = the tool default
prong_height	float	optional — None = the tool default
prong_height_over_girdle	float	optional — None = the tool default
gem_inside	float	optional — None = the tool default
upper_rail	Optional[bool]	optional — None = the tool default
base_rail	Optional[bool]	optional — None = the tool default
support	str	optional — None = the tool default
prong_mode	str	optional — None = the tool default
prong_profile	str	optional — None = the tool default
prong_diameter_bottom	float	optional — None = the tool default
prong_rotation	float	optional — None = the tool default
straight_prong	Optional[bool]	optional — None = the tool default
support_width	float	optional — None = the tool default
support_thickness	float	optional — None = the tool default
upper_rail_width	float	optional — None = the tool default
upper_rail_height	float	optional — None = the tool default
upper_rail_height_under_girdle	float	optional — None = the tool default
upper_rail_gem_size_percentage	float	optional — None = the tool default
upper_rail_profile	str	optional — None = the tool default
base_rail_width	float	optional — None = the tool default
base_rail_height	float	optional — None = the tool default
base_rail_move_in_z	float	optional — None = the tool default
base_rail_gem_size_percentage	float	optional — None = the tool default
base_rail_profile	str	optional — None = the tool default
element	str	optional — None = the tool default
prong_type	str	optional — None = the tool default
overlap	float	optional — None = the tool default
v_prongs	Optional[bool]	optional — None = the tool default
v_thickness	float	optional — None = the tool default
v_arm_length	float	optional — None = the tool default

ra.basket.find()

ra.basket.find(id: IdLike) -> Basket

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

Parameter	Type
id	IdLike	required

ra.basket.for_gem()

ra.basket.for_gem(gem_id: IdLike) -> List[Basket]

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

Parameter	Type
gem_id	IdLike	required

ra.basket.selected()

ra.basket.selected() -> List[Basket]

Baskets currently selected in the active doc.

ra.basket.update_legacy_baskets()

ra.basket.update_legacy_baskets() -> List[str]

The ArtisanBasketUpdate command, headless: finds every legacy basket (one object carrying “ObjectType = Basket” + parameters in its geometry dictionary, as saved by old Artisan versions, hidden or not), recomputes it against its mother gem with the current kernel and replaces it by the modern editable “Basket” group (metal material, RaObjectUserData with the parameters and the mother). Baskets whose mother gem is gone or that fail to compute are left untouched. Returns the ids of the new baskets (ra.basket.find / handles); empty when the document has no legacy baskets.

Handles

Objects returned by the functions above. Assigning a settable property regenerates the object; the change is one undo step inside ra.transaction().

Basket (handle)

Property	Type	Settable
base_rail	BasketRail
gem_carat_weight	float
gem_material	str
gem_shape	str
layer_name	str
mother_gem_id	str
object_type	str
position	Point3d
prong	BasketProng		The rest of the tool’s parameters, grouped as the panel groups them.
prong_count	int	yes	signed: negative = the rotated layout
prong_diameter_bottom	float
prong_diameter_girdle	float		stored for older files only: the prong’s girdle section is built from ProngDiameterTop
prong_diameter_top	float
prong_height	float	yes
prong_mode	str	yes	”ROUND” | “CUSTOM” | “CLAW”: the prong construction, as on every setting with prongs. The claw values live in the Prong section.
prongs_rotated	bool
upper_rail	BasketRail

Method
delete()
move(translation: VectorLike)
set_element(element: str)	Applies a saved Basket element (ra.elements.list(“Basket”)) to this basket: its parameters replace the current ones, the mother gem stays, and the basket regenerates in place (same id).
set_prong_diameter(diameter: float)	writes all three diameters

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

BasketRail (section)

One of the basket’s two rails. The upper rail additionally carries the chamfer; the base rail carries its vertical offset. Members that do not apply to a rail throw NotSupportedException rather than silently doing nothing.

Property	Type	Settable
chamfer	bool	yes	upper rail only
chamfer_offset	float	yes	upper rail only
enabled	bool	yes
flush_fit	bool	yes	base rail only: no rail, the prongs converge under the gem and meet at the centre (the head sits flat on the shank)
flush_fit_angle	float	yes	base rail only, degrees 0-75: the angle from vertical the bent prongs arrive at the base with (0 = vertical, more = they cross at the centre)
flush_fit_bend	float	yes	base rail only, 0-90 %: the share of the drop the prong goes straight down before turning in to the centre (0 = it turns from the girdle)
flush_fit_offset	float	yes	base rail only, mm: the radius the prong bottoms stop at in flush fit (0 = they meet at the centre)
flush_fit_round_foot	bool	yes	base rail only: domed feet, so they run into one another at the centre (False = flat feet)
gem_size_percentage	float	yes	rail diameter as % of the gem
gems	CathedralGems		The gems on the rail’s outer face, between the prongs (the panel’s Gallery Rail Gems on the upper rail, Lower Rail Gems on the base rail): the same section a cathedral’s gems use, off by default. Every free stretch between prongs takes as many stones as fit, so Mode, Count and Angle are not used. ProngType is “FLUSH”, “SHARED” (prongs) or “SCALLOPED”, never “NONE”. While they are enabled the rail is built with the SQUARE section whatever its Mode, and Width and Height grow to hold the stones. The base rail takes none in flush fit.
height	float	yes	mm
height_under_girdle	float	yes	upper rail only
mode	str	yes	DEFAULT (elliptical section), SQUARE (rectangular section with slightly rounded corners) or CUSTOM (the CLOSED_PROFILE)
move_in_z	float	yes	base rail only, signed
profile_name	str		CLOSED_PROFILE asset name (used in CUSTOM mode)
rotation	float	yes	degrees, signed
width	float	yes	mm

Method
set_profile(asset_name: str)	also switches the rail to CUSTOM mode, where the profile is used

BasketProng (section)

The prongs and their support posts.

Property	Type	Settable
bottom_rail_inside	float	yes
cap_bump	float	yes	mm
claw_gem_inside	float	yes	The basket’s claw tip, CLAW mode only (built in Render mode only). mm the tip reaches in toward the gem.
claw_height	float	yes	mm added to the height over the girdle, signed
claw_on_curve	int	yes	the panel’s “Smoothness” (1-30): on STRAIGHT prongs, where the claw starts to bend, as a % of the girdle-to-base distance; curved prongs (the default) ignore it
claw_tension	float	yes	degrees, the panel’s “Tip direction” (10-60)
count	int	yes	negative = the rotated layout
diameter_bottom	float	yes	mm
diameter_top	float	yes	mm
extension_for_manufacturing	float	yes
gem_inside	float	yes	mm, signed
height	float	yes	mm
height_over_girdle	float	yes	mm
mode	str	yes	”ROUND” | “CUSTOM” | “CLAW” (the same as Basket.ProngMode)
overlap	float	yes	mm the prongs of a pair, and the Triple’s middle, cross: 0 = they touch (never a gap)
profile_name	str		CLOSED_PROFILE asset name, "" when unset
rotation	float	yes	degrees, signed
straight	bool	yes	straight vs curved prong body
support	str	yes	”NONE” | “SINGLE” | “DOUBLE”
support_thickness	float	yes	mm
support_width	float	yes	mm
type	str	yes	”SINGLE” | “DOUBLE” | “TRIPLE”: prongs per position - one, a pair side by side, or the pair plus a thinner prong between them. ROUND prongs take all three, CLAW SINGLE or DOUBLE (the Double Claw), CUSTOM SINGLE.
v_arm_length	float	yes	mm, how far each arm of the V runs along the girdle as built: the set value, or 1.2 x DiameterTop while none is set
v_prongs	bool	yes	V prongs: every position on a sharp corner of the girdle (princess corners, pear and heart tips, six-prong marquise tips, trillion corners) gets a V that wraps the corner. ROUND mode only; the other positions keep their prongs.
v_thickness	float	yes	mm, the V’s metal width as built: the set value, or 0.8 x DiameterTop while none is set

Method
set_profile(asset_name: str)	CLOSED_PROFILE asset; also switches the prongs to CUSTOM mode, where the profile is used (from another mode, Rotation starts at 90; Type goes back to SINGLE)

CathedralGems (section)

The pavé row a cathedral carries along its top — one run per arm.

Property	Type	Settable
angle	float	yes	degrees of the band covered by gems (180 = top half)
automatic_prong_diameter	bool	yes
automatic_prong_distance	bool	yes	SHARED: True, the two prongs of a gap sit where they fit tangent to the stones and the channel edges (they follow the channel width); False, at ProngDistance
bright_cut	float	yes	bright-cut width, mm
count	int	yes	number of gems per side (per arm) in “COUNT” mode
double_prong_setting	bool	yes
drill_allow_intersection	bool	yes
drill_enabled	bool	yes
drill_height	float	yes	mm
drill_type	str	yes	”NONE”, “ROUND” or “QUAD”
drill_visible	bool	yes	bake the drill cutters as visible objects
drill_width	float	yes	mm
enabled	bool	yes
extension_for_manufacturing	float	yes	mm
gem_inside	float	yes	how deep the gems sit inside, mm
gem_shape	str	yes	”ROUND”, “PRINCESS”, …
gem_size	float	yes	mm
inner_height	float	yes	inner channel height, mm
inner_margin	float	yes	inner margin, mm
inner_width	float	yes	inner channel width, mm
margin	float	yes	side margin, mm
min_distance	float	yes	minimum distance between gems, mm
mode	str	yes	”ANGLE” (the gems cover Angle, the count follows) or “COUNT” (exactly Count gems per side, the angle follows)
prong_diameter	float	yes	mm — used when AutomaticProngDiameter is False
prong_distance	float	yes	SHARED, mm: centre-to-centre distance across the channel between the two prongs of a gap when AutomaticProngDistance is False; 0 = a single prong on the centre line
prong_height	float	yes	mm
prong_type	str	yes	”FLUSH” (no channel), “NONE” (channel), “SHARED” or “SCALLOPED”
scallop_gem_height	float
scallop_gem_width	float		Scalloped-setting proportions (percentages, not mm).
scallop_prong_height	float
scallop_prong_width	float
scallop_rail_height	float
scallop_rail_width	float
scallop_remove_channel	bool	yes	SHARED and SCALLOPED: True drops the channel under the stones (FLUSH never has it)
vertical	float	yes	vertical displacement of the row, mm

Method
set_scallop_gem(width: float, height: float)
set_scallop_prong(width: float, height: float)
set_scallop_rail(width: float, height: float)