Scale to dimensions

from ArtisanPlugin.Scripting import TransformApi as transform

The everyday sizing request - “make this motif 20 mm wide”, “bring the pendant down to 30 mm tall” - stated as a measurement rather than a factor. This is the ArtisanScaleByDimensions panel headless: the objects are measured as one set, using the common world-axis bounding box, and scaled about that box’s centre until it measures the sizes you asked for.

Usage

ids = transform.ScaleToDimensions(objectIds, sizeX = 0, sizeY = 0, sizeZ = 0,
                                  keepAspect = True, keepOriginal = False)   # -> resulting ids

Parameter	Default	Meaning
objectIds	-	Objects to scale; None or empty falls back to the current viewport selection
sizeX	0	Target bounding-box width in mm; 0 leaves that axis undriven
sizeY	0	Target bounding-box depth in mm; 0 leaves that axis undriven
sizeZ	0	Target bounding-box height in mm; 0 leaves that axis undriven
keepAspect	True	Uniform scale on all three axes, driven by exactly one target size
keepOriginal	False	True scales a copy and leaves the original untouched

Here 0 does not mean “tool default” - it means leave that axis alone. At least one size must be given, otherwise Give at least one target size (in mm). A negative size throws Target sizes must be positive (0 = keep that axis).

With keepAspect = True (the panel’s own default) exactly one of the three sizes may be given: the factor derived from that axis is applied uniformly to all three, so proportions are preserved. Passing two or three sizes with keepAspect on throws With keepAspect only one axis can be driven: give a single target size, or disable keepAspect. Turn keepAspect off and each given axis scales independently, distorting the geometry - which is exactly what you want for a flattened band or a stretched plate, and rarely what you want otherwise.

The return value is an IReadOnlyList<Guid>. With keepOriginal = False (the default) the objects are scaled in place and the list is the same ids you passed - useful for chaining, but not new geometry. With keepOriginal = True the originals are left untouched and the list holds the ids of the newly created, scaled copies. There is no handle and no query method: what you get back is the id list, nothing more.

An axis with zero extent cannot be driven - dividing by it would be a division by zero, and the panel simply disables that field. Driving a flat axis throws The selection is flat on <axis> (zero extent): that axis cannot be driven. There is one asymmetry worth knowing: with keepAspect = True the uniform factor is derived through the X extent, so a selection that is flat on X throws The selection is flat on X: keepAspect cannot derive a uniform factor. Disable keepAspect. even when the size you gave was on Y or Z.

Ids you pass are validated one by one before anything happens: a Guid that is not in the document throws Object <id> does not exist. An empty resolved list (nothing passed, nothing selected) throws Nothing selected: select (or pass) at least one object. If the kernel cannot build the transform you get Scale-by-dimensions computation failed., with the kernel’s own key in brackets when it supplies one.

The call mutates the document and ends with a viewport redraw; wrap it in a Transaction to fold it into a single undo step.

from ArtisanPlugin.Scripting import TransformApi as transform, Transaction

with Transaction.Begin("Motif to 20 mm wide"):
    ids = transform.ScaleToDimensions(motifIds, sizeX = 20)