Weight by area

from ArtisanPlugin.Scripting import WeightApi as weight

The volume-based weight methods need closed geometry. Plenty of jewellery is not modelled that way: a stamped pendant, a hollow dome, a piece of sheet bent into a cuff, an earring back - all of these are often single open surfaces with the material thickness existing only in the maker’s head. CalculateByArea is the estimate for those: it adds up the surface area of the objects you give it, multiplies by the thickness you state, and treats the product as the volume to cast.

Read-only, like everything in WeightApi: no licence gate, no Transaction.

Usage

r = weight.CalculateByArea(objectIds, thickness, metal = None)   # -> MetalWeightResult
r = weight.CalculateSelectionByArea(thickness, metal = None)     # same, over the viewport selection

Parameter	Default	Meaning
objectIds	-	Objects whose area to sum. CalculateSelectionByArea takes the current selection instead
thickness	-	Required. Sheet thickness in model units - mm in a millimetre document. Must be > 0
metal	None	A name from Metals(). Empty or None uses the document’s primary metal

Note that thickness does not follow the usual “0 keeps the tool default” convention: 0 or any negative value throws ArgumentOutOfRangeException with "Thickness must be > 0.". There is no default sheet thickness to fall back on. The metal argument is the one that takes a sentinel here, and its sentinel is None/empty, not 0.

CalculateSelectionByArea is a straight wrapper: it gathers the selected ids, calls CalculateByArea, and relabels the result. Selecting nothing gives zeros rather than an error.

What comes back

The same MetalWeightResult as the volume-based methods - Layer, Metal, Volume, Grams, ProcessedGrams, WaxGrams - with two differences worth keeping in mind:

• Volume is the synthetic area x thickness figure, not a measured volume.
• Layer is the literal "(by area)", or "(selection, by area)" from the selection variant. Nothing is read from, or attributed to, the Metal layers.

Grams, ProcessedGrams and WaxGrams are then derived exactly as elsewhere: density x volume, the configured finishing loss, and the configured wax density.

When it is the right tool

Reach for it when the geometry is an open surface or shell and the material thickness is a manufacturing parameter rather than modelled geometry. Sheet, stamped and formed parts are the typical case.

Do not reach for it for solid, closed pieces - use CalculateForObjects or Calculate(), which measure the real volume. If you pass a closed solid anyway, the area sum takes its entire skin, inner and outer faces included, so a hollow closed shell counts both walls and comes out roughly twice as heavy as intended, and a plain solid gets a shell of thickness wrapped around a body that is already full. The method has no way to detect this; it will happily return a confident, wrong number.

Area is summed for Breps, extrusions, meshes and SubDs only. Curves, points and annotations contribute nothing. Ids that do not resolve, and geometry too degenerate to compute an area for, are skipped silently - so an empty or unresolvable id list gives a valid result with zero grams.

from ArtisanPlugin.Scripting import WeightApi as weight

r = weight.CalculateByArea(shell_ids, 0.8, "SILVER_925")
print("%.2f mm2 of 0.8 mm sheet -> %.2f g" % (r.Volume / 0.8, r.Grams))

Both methods throw InvalidOperationException "No active document." when no document is open, and ArgumentException for an unknown metal name (see metal names).