Taper

from ArtisanPlugin.Scripting import TransformApi as transform

Tapers objects along an axis through their common bounding box, exactly like the Taper panel: the section is left alone at the near end and widened or narrowed by deltaMm at the far end, with everything in between interpolated linearly. This is the tapered-shank move - a band that thins towards the bottom, a motif coned towards its tip - and, with a break position, the taper can be made to start partway along instead of at the very end.

Usage

ids = transform.Taper(objectIds, deltaMm, direction = None, mode = None,
                      breakOne = 0, breakTwo = 0, flat = False, infinite = False,
                      rigidIds = None, keepOriginal = False)    # -> new object ids

Parameter	Default	Meaning
objectIds	—	Objects to taper; None/empty = the current selection
deltaMm	— (required)	Change of the half-width at the far end, in mm: positive widens, negative narrows. Must be non-zero
direction	None = "ZTop"	Axis through the bounding box: ZTop, ZBottom, YTop, YBottom, XTop, XBottom. Case-insensitive; the named end is the one that changes size
mode	None = "Uniform"	Uniform (whole axis), OneBreak (only from breakOne to the far end), TwoBreaks (only between the two breaks)
breakOne	0	Normalised 0-1 position along the axis; 0 = the tool default, 0.5
breakTwo	0	Normalised 0-1 position along the axis; 0 = the tool default, 0.75
flat	False	True tapers only in the gumball plane’s X - a one-directional squeeze instead of a cone
infinite	False	True carries the taper on beyond the ends of the axis instead of clamping there
rigidIds	None	Objects that must not distort - gems, heads - carried along rigidly
keepOriginal	False	True leaves the originals in the document

Everything is millimetres; there are no ratios and no -1 sentinel anywhere in this signature. deltaMm is an absolute half-width change, added to a reference half-width taken as half the bounding box’s X extent, so deltaMm = -0.5 on a 3 mm-wide band brings the far end to roughly 2 mm. Zero is rejected outright: ArgumentException("Nothing to taper: the delta is 0 mm."). The breaks, by contrast, do follow the house 0 rule - 0 means “keep the tool default” (0.5 and 0.75) - and are only read in OneBreak and TwoBreaks mode; in TwoBreaks they are sorted, so their order does not matter. A break outside 0-1 throws ArgumentOutOfRangeException with Break positions are normalized: 0 = tool default, otherwise between 0 and 1 along the axis. An unknown direction or mode throws naming the valid values, e.g. Unknown mode 'half'. Use one of: Uniform, OneBreak, TwoBreaks. A failed computation raises InvalidOperationException("Taper computation failed."), or Taper computation failed: <reason>.

What you get back, and what is left in the document

The return value is an IReadOnlyList[Guid]: the tapered objects first, in the order you passed them, then the rigid ones. Nothing is deformed in place. Each object is baked as a new object with the original’s attributes - layer, colour, material, groups - and the originals are then deleted, unless keepOriginal = True, in which case originals and tapered copies both remain. Ids that no longer resolve are skipped silently.

rigidIds objects do not taper. Each is copied and repositioned with a plane-to-plane transform: a frame at its bounding-box centre is pushed through the same morph, and the object is moved and rotated onto the result - so gems and heads ride the tapered metal at full size. The frame follows the taper axis (WorldXY for the Z directions, WorldZX for Y, WorldYZ for X, flipped for the Bottom variants). One quirk, replicated from the panel on purpose: a rigid object that is an extrusion is fully morphed instead of moved rigidly. Convert such objects to Breps beforehand if they must stay rigid. Rigid ids not in the document throw Rigid object <id> not found in the document.

An empty or None objectIds falls back to the objects currently selected in the viewport. If that is empty too you get ArgumentException("Nothing to deform: select (or pass) at least one object."), and any id you pass that is not in the document throws Object <id> not found in the document.

Space morph, so: what survives

This is a Rhino space morph, not a transform. Control points are moved, so a Brep stays a Brep and a curve stays a curve, but analytic faces come back as free-form surfaces, and a shape with few control points tapers coarsely. Extrusions are converted to Breps before morphing, so an extrusion you taper comes back as a Brep with a new id. Circles are not rebuilt here (unlike Twist), so a four-point rational circle will barely change section - convert it to a denser NURBS curve first if you are tapering curves. Meshes morph vertex by vertex at their existing density. Document tolerance settings are not consulted; the morph is applied by the tool with its own settings and none of them are exposed to the script.

The whole operation runs inside a single Rhino undo record named “Artisan Taper” and ends with a viewport redraw, so one Ctrl+Z undoes it. Wrap it in a Transaction when you want it grouped with other mutations as one step.