Move by normal

from ArtisanPlugin.Scripting import TransformApi as transform

Lifts or sinks objects off a surface along that surface’s own normal: raising a pavé field a tenth of a millimetre above the dome it sits on, dropping cutters into the metal, or backing a set of motifs away from a shank before a boolean. Each object is measured separately, so a row of stones following a curved surface each moves along the normal under its own centre rather than along one shared direction.

Usage

moved = transform.MoveByNormal(objectIds, surfaceId, distance = 1.0)   # -> how many objects moved

Parameter	Default	Meaning
objectIds	—	Objects to move. None or an empty list uses the current selection
surfaceId	—	The reference surface: a surface, or a polysurface/extrusion with exactly one face
distance	1.0	Millimetres along the normal; negative moves against it

For each object, the centre of its world-axis bounding box is pulled onto the surface, the surface normal is evaluated there and unitised, and the object is translated by that unit normal times distance. Objects are moved in place: the ids you passed keep pointing at the same objects, nothing is copied and nothing is created. The return value is an int — the number of objects that were actually transformed, which can be lower than the number of ids if an object has no geometry or if the closest-point evaluation on the surface fails. Those objects are skipped silently rather than raising.

distance is a plain length, not a defaulting sentinel: 0 is a legal no-op, and negative values are the normal way to move inwards.

Ids you pass explicitly must exist — a missing one raises Object {id} does not exist. naming it. Duplicate ids are collapsed. If the list is null or empty the facade falls back to the objects selected in the viewport, and if nothing is selected either it raises Nothing selected: select (or pass) at least one object.. An unknown surfaceId raises Surface {id} does not exist.; a mesh, a curve or a multi-face polysurface raises Object {id} is not a surface (single-face polysurfaces count as one)..

Like every mutation in the API, wrap it in a Transaction so the move undoes in one step.

from ArtisanPlugin.Scripting import TransformApi as transform, Transaction

with Transaction.Begin("Lift the pave"):
    transform.MoveByNormal(gemIds, domeId, 0.15)