Scale by weight

from ArtisanPlugin.Scripting import TransformApi as transform

Every quote starts from the cast weight, so the usual request is not “make it 5% smaller” but “make it come out at 4 grams in 18k yellow”. This is the ArtisanScaleByWeight tool running headless: it measures the volume of the objects, works out the uniform factor that makes that volume weigh targetGrams at the density of metal, and applies it. The scale is uniform on the three axes and the objects are scaled as one set.

Usage

factor = transform.ScaleByWeight(objectIds, targetGrams,
                                 metal = None, keepOriginal = False)   # -> the factor applied

Parameter	Default	Meaning
objectIds	-	Objects to scale; None or empty falls back to the current viewport selection
targetGrams	-	Target cast weight in grams, must be > 0
metal	None	Metal name; None/empty uses the document’s primary metal (Metal 01)
keepOriginal	False	True scales a copy and leaves the original untouched

The return value is a double: the uniform scale factor that was applied, read off the transform’s diagonal. 1.0 means the objects already weighed the target; 0.8 means everything came down to 80% of its former size. It is not a weight and not a list of ids - if you scale a copy, the new ids are not returned, so find them through the selection or by diffing the document.

By default the objects are scaled in place: the same ids survive, with the same layers and attributes. With keepOriginal = True the originals stay where they are and the scaled result is a set of fresh copies. The tool’s own toggle is Delete Original, and keepOriginal is simply its inverse.

Metal names are the values of WeightApi.Metals() - see Weights for the list. Hyphens and spaces are normalised to underscores and matching is case-insensitive, so "18k yellow gold" and "18K_Yellow_Gold" resolve alike. An unrecognised name throws Unknown metal '<name>'. - note that, unlike WeightApi, this method does not append the valid names to the message.

Volume is what drives the calculation, so the objects must be closed solids or meshes. Open surfaces contribute nothing and the computation fails with Scale-by-weight computation failed. The objects must be closed solids or meshes. A non-positive targetGrams throws Target weight must be > 0 grams., and an empty resolved list throws Nothing to scale: select (or pass) at least one object. Unlike the other placement methods, ids you pass here are not checked for existence up front: a stale Guid is simply skipped by Rhino rather than named in an error.

The call mutates the document, so wrap it in a Transaction when it belongs to a larger edit and you want one undo step.

from ArtisanPlugin.Scripting import TransformApi as transform, Transaction

with Transaction.Begin("Scale to 4 g"):
    factor = transform.ScaleByWeight(ids, 4.0, "18K_Yellow_Gold")