Scripting API

Pave on surface

from ArtisanPlugin.Scripting import PaveApi as pave

Pavé is a field of small stones set close together so the metal all but disappears under them. Rather than placing each stone by hand, this tool takes any surface, brep or mesh, meshes it at high resolution and packs diamonds across it automatically, optionally adding the prongs that hold them and the cutters that seat them - the headless form of the ArtisanPaveOnCurve tool.

OnSurface is the only method on this facade.

Create

ids = pave.OnSurface(surfaceIds, gemDiameter = 0, prongDiameter = 0,
                     distanceToBorder = 0, prongs = True, cutters = False,
                     variableSize = None, fillMode = None,
                     startPoint = None)                        # -> gem ids

Parameter	Default	Meaning
`surfaceIds`	-	One or more surfaces, breps or meshes to pave - throws if empty or unmeshable
`gemDiameter`	`0` (tool default `1.3`)	Stone diameter, mm
`prongDiameter`	`0` (tool default `0.8`)	Prong diameter, mm
`distanceToBorder`	`0` (tool default `0.1`)	Margin kept clear at the edge of the surface, mm
`prongs`	`True`	Build the prongs between the stones
`cutters`	`False`	Build a seat cutter under each stone
`variableSize`	`None`	Let stones shrink towards `0.9` mm to fill the awkward areas; `None` keeps the tool default
`fillMode`	`None`	`"FROM_BORDER"` (default) or `"FROM_CENTER"`
`startPoint`	unset	Seed point for `FROM_CENTER`; ignored otherwise

All dimensions are millimetres, and 0 keeps the tool default for that parameter, so you only pass what you actually mean to change.

Fill modes. FROM_BORDER starts the packing at the edges of the surface and works inwards - the usual choice, and what you get if you pass nothing. FROM_CENTER grows the field outwards from a seed, and requires startPoint: pass a point on or near the surface and it is pulled to the closest point on the mesh before packing starts. Omitting it throws. The mode string is matched loosely, so "FROM_CENTER", "from center" and "CENTER" all work; anything else throws.

Edit

There is no pavé handle. OnSurface returns the ids of the created gems only - unlisted gemstones on the secondary gems layer, collected in one Rhino group. Prongs and cutters are baked too, each into its own group, but their ids are not returned; pick them up from the document if you need them.

This is a multi-gem, surface-driven object: MotherGemId does not apply, and the gems come back as ordinary gem objects you can query, move or delete individually. To change the packing, delete the field and call OnSurface again.

from ArtisanPlugin.Scripting import PaveApi as pave, Transaction

with Transaction.Begin("Pave the dome"):
    gems = pave.OnSurface([domeId], gemDiameter = 1.1,
                          variableSize = True, cutters = True)

Mutations belong inside a Transaction so the whole field lands as one undo step.

OnSurface throws if no valid object is passed, if the objects cannot be meshed, if the computation fails, or if the packing produces no gems at all - which usually means the surface is too small for the requested gemDiameter.