Pattern

from ArtisanPlugin.Scripting import PatternApi

Pattern is the motif repeater: one carved element - a scroll, a link, a pierced cell, a bead - laid out in a rectangular grid and then wrapped onto a curved body so the repeat follows a dome, a band or the shoulder of a ring. Artisan arrays a duplicate of the source in world XY, measures the bounding rectangle of the finished grid, and morphs that rectangle onto the target surface with a Sporph flow.

Create

ids = PatternApi.Create(objectId, surfaceId = Guid.Empty, columns = 2, rows = 3,
                        xPadding = 0, yPadding = 0, rotation = 0, zMove = 0,
                        maxThickness = 0, reverseMode = -1)      # -> [ids]

Parameter	Default	Meaning
objectId	required	The source object to repeat; must exist in the document
surfaceId	none	Surface to flow the finished grid onto. Omit to leave the grid flat. A brep is accepted and its first face is used
columns	2	Cells across
rows	3	Cells down
xPadding	0	Gap added between columns, mm
yPadding	0	Gap added between rows, mm
rotation	0	Degrees about Z, accumulating cell by cell
zMove	0	Lifts the source before arraying, mm
maxThickness	off	> 0 rescales the source in Z to that thickness before arraying
reverseMode	keep (-1)	Mirrors the flow. See below

reverseMode

The flow maps a flat rectangle onto your surface, and which corner of the rectangle meets which corner of the surface decides whether the pattern lands the right way round or mirrored. reverseMode flips the rectangle before the morph:

Value	Effect
0	No reversal
1	Reverse U
2	Reverse V
3	Reverse both
-1	Keep the saved or tool default

Values outside 0-3 are silently treated as no reversal. reverseMode has no effect at all when surfaceId is omitted, since nothing is flowed.

Result

Create returns the ids of the created copies, one per cell. The source object is left untouched - it is not consumed, moved or hidden; the grid is built from duplicates, exactly as the panel does it.

The source is duplicated and translated so its bounding-box minimum sits at the world origin before the grid is built, so the array starts at the origin rather than where the source object happens to sit. zMove is applied to that repositioned copy, and maxThickness rescales it in Z only, keeping X and Y as they are.

Your saved pattern defaults always replace the model before the arguments are applied - Pattern takes no profile asset, so there is no “explicit profile skips the saved defaults” caveat here.

This is a licensed mutation and needs an active document. It raises “Object <id> not found.” for a missing objectId, “Object <id> is not a surface.” when surfaceId names something with no usable surface, and “Pattern computation failed with the given parameters (…)” for geometry that cannot be built - including INVALID_COLUMNS or INVALID_ROWS for a grid smaller than one cell, and INVALID_MAX_THICKNESS for a maxThickness below 0.1 mm. Nothing is added when the computation fails. Wrap the call in a Transaction to get one-step undo over the whole grid.