Weights

from ArtisanPlugin.Scripting import WeightApi as weight

What the piece will cost to cast. WeightApi wraps the same WeightTools math the ArtisanWeight command uses - volume of the closed geometry multiplied by the metal’s density - so the grams a script reports always match the figures in the dialog. Volume comes from Breps, extrusions, meshes and SubDs; objects that are not closed contribute nothing meaningful, which is why open shells need weight by area instead.

Everything on this page is read-only: no licence gate, no Transaction, nothing added to the document.

Metal names

weight.Metals()   # -> ["GOLD_24", "GOLD_YELLOW_22", "GOLD_YELLOW_18", ..., "PLATINUM", "SILVER_925", ...]

Metals() returns the exact names the metal argument accepts - the members of the Metal enum, covering the gold karats and colours, the silver and platinum alloys, palladium, rhodium, steel, zinc, zamac and pewter.

Matching is forgiving, the same convention as GemApi: the name is trimmed, dashes and spaces are converted to underscores, and the comparison is case-insensitive. So "GOLD_YELLOW_18", "gold yellow 18" and "gold-yellow-18" all resolve to the same metal. What it does not do is reorder words or translate trade names - "18k yellow gold" will not parse.

An unrecognised name throws ArgumentException reading Unknown metal '<name>'. Valid names: <the full list>., and an empty or whitespace name throws "Metal name is required.".

The result

Every method on this page returns a MetalWeightResult:

Field	Meaning
Layer	What the row describes: a Metal layer name from Calculate(), or the literal "(objects)" / "(selection)" from the other two
Metal	The resolved Metal enum name, e.g. "GOLD_YELLOW_18"
Volume	Volume in model units cubed - mm³ in a millimetre document
Grams	Cast weight: volume x the metal’s density
ProcessedGrams	The cast weight after the configured finishing loss percentage (Options; 5% out of the box)
WaxGrams	Weight of the wax model at the configured wax density (Options; 0.97 out of the box)

Densities honour the user’s Custom Metal List when one is configured, so a house alloy gives house grams.

Whole document

rows = weight.Calculate()   # -> list of MetalWeightResult, one per metal position

The per-metal breakdown of the document, mirroring the ArtisanWeight dialog. Volumes are read from the layers named Metal 01, Metal 02 and Metal 03, then grouped according to how many metals the document is configured for:

Document metals	Rows returned
1	Metal 01+02+03 - everything on the Metal layers casts together, in the document’s first metal
2	Metal 01, then Metal 02+03 combined in the second metal
3	Metal 01, Metal 02, Metal 03, each in its own document metal

The metals themselves come from the document settings, not from an argument - Calculate() takes no parameters. A layer that is missing or holds no geometry still produces a row, with zero volume and zero grams, rather than being dropped. If there is no active document, Calculate() returns an empty list rather than throwing; it is the only method here that does not require one.

Given objects

r = weight.CalculateForObjects(objectIds, "GOLD_YELLOW_18")

Parameter	Default	Meaning
objectIds	-	The objects to weigh; ids that are not in the document are silently skipped
metal	-	Required. A name from Metals()

The scriptable form of “weigh this bit”: what an arbitrary set of objects would weigh if cast in one metal, regardless of which layer they live on. Layers and document metal settings are ignored entirely - one set of ids, one metal, one result with Layer set to "(objects)".

The objects must be closed solids or meshes for their volume to count. An empty id list, or ids that all fail to resolve, gives a valid result with zero volume and zero grams.

Current selection

r = weight.CalculateForSelection("PLATINUM")

The same calculation over whatever is selected in the viewport: it collects the selected object ids and hands them to CalculateForObjects, then relabels the result’s Layer as "(selection)". metal is required here too - the selection carries no metal of its own. With nothing selected you get zeros, not an error.

Both CalculateForObjects and CalculateForSelection throw InvalidOperationException "No active document." when there is no document open, and the metal name is parsed before anything else, so a typo fails immediately.

from ArtisanPlugin.Scripting import WeightApi as weight

for row in weight.Calculate():
    print("%-16s %-18s %8.2f g  (%.2f g processed)"
          % (row.Layer, row.Metal, row.Grams, row.ProcessedGrams))