Scripting API

Texture 3D

from ArtisanPlugin.Scripting import Texture3DApi

Relief pushed into a metal surface from a picture: hammered finishes, woven and basket patterns, bark, engine-turning, a logo raised out of a signet face. The tool reads a grayscale image as a heightmap and rebuilds your surface as a new one whose points are displaced along the surface normal - white pixels rise to the full relief height, black pixels stay flush.

Create

id = Texture3DApi.Create(surfaceId, texturePath = None, u = 1, v = 1,
                         height = 0.6, rotation = 0)                      # -> id

Parameter	Default	Meaning
`surfaceId`	-	The existing surface to emboss
`texturePath`	the default texture	Path to an image file on disk
`u`	`1`	How many times the image is tiled across the surface’s U direction
`v`	`1`	How many times it is tiled across V
`height`	`0.6`	Relief at pure white, mm - black sits flush with the original surface
`rotation`	`0`	Degrees the tiled image is turned before it is applied

texturePath is optional. Omit it and the tool uses its own default texture, the same one the panel opens with. Give a path and the file must exist on disk, or the call fails with “Texture image not found: ’…’”. The image does not have to be grayscale to begin with - it is converted before use.

u and v tile, they do not stretch: u = 3, v = 2 lays six copies of the image over the surface, so the motif gets smaller and repeats rather than distorting. height scales linearly with pixel brightness, so a mid-grey pixel rises to half of it. rotation turns the tiled image about its centre before it is wrapped onto the surface; unusually for this API it is applied whenever it is non-zero rather than only when positive, so negative angles work as you would expect.

Behind the scenes the facade repeats the panel’s worker exactly: resize the bitmap by the texture resolution, convert it to grayscale, tile it u × v, rotate it, and bake the result to a temporary JPEG that the kernel reads while computing. The kernel then samples one point per pixel across the surface’s domain and offsets each along the normal, so the image’s pixel count decides how heavy the resulting geometry is - a large photograph produces a very dense NURBS surface. The four edge rows and columns are pinned at zero displacement, so a textured patch still meets its neighbours cleanly.

Returns the id of a single Texture 3D smart component (Texture3DCustomObject, mother = your surface), on the metal layer with the document’s metal material, exactly like the panel’s Accept. The source surface is left in the document.

Note the input check: unlike the curve-based facades, this one only verifies that the id exists - “Object … not found.” - and does not report a wrong object type up front. A non-surface simply fails later with “Texture computation failed. Check the surface and the image.”

u, v and height follow the house 0-keeps-default convention: 0 means “use my saved Texture 3D defaults, or the tool’s”. No -1 sentinel is needed, since none of them is meaningful at zero.

This is a licensed mutation. Wrap it in a Transaction for one-step undo:

from ArtisanPlugin.Scripting import Texture3DApi, Transaction

with Transaction.Begin("Hammered face"):
    Texture3DApi.Create(surfaceId, r"C:\textures\hammered.png", u = 2, v = 2,
                        height = 0.35, rotation = 15)