apply_geometric_texture
Carves or raises a procedural geometric texture, such as wood, honeycomb, or carbon fiber, as printable surface relief on a 3D model, then opens an interactive 3D stage to inspect the result.
Instructions
Apply a procedural texture as physical surface relief. Opens Kiln's interactive inline 3D stage on the result (orbit/zoom panel in MCP Apps hosts; hosted sessions add a browser stage link).
Free accounts get 3 textures a month; Pro has no monthly limit.
INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"input_path": "<input_path>"
},
"name": "apply_geometric_texture"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| face | No | Target face -- ``"top"``, ``"bottom"``, ``"front"``, ``"back"``, ``"left"``, ``"right"``. If not specified, auto-detects: prefers top face, falls back to largest. On a sketch-built part whose recipe sits beside the mesh, the sketch's own wall name (``"side:l2"``) is accepted and follows that wall through a resize and rebuild. | |
| mode | No | ``"deboss"`` (grooves) or ``"emboss"`` (ridges). Default: "deboss". | |
| seed | No | Random seed for reproducible results (default 0). Default: 0. | |
| scale | No | Texture scale multiplier. The default (1.0) is SMART: motifs keep their material-true physical size (a scale pattern prints the same size on a coaster as on a suitcase), and only a too-small object shrinks the pattern — just enough for a couple of motifs to fit, never below what the nozzle can print (the response carries ``auto_scale`` + a warning when this fired). Pass an explicit value to override. Default: 1.0. | |
| invert | No | Swap which part of the pattern stands out. Normally the pattern's dark detail is the feature (wood-grain lines get carved/raised) and the rest stays flat; ``True`` flips it so the background becomes the feature instead. Reach for it when the user wants the "negative" of a texture, or says the raised-vs-flat parts look backwards. Whole-object coverage only (requires ``surface=``). Default: false. | |
| region | No | Texture ONE named surface region and leave the rest plain — the same regions ``segment_mesh_regions`` shows and ``paint_mesh_regions`` colours: the region's name ("Outside", "Top rim", "Inside floor"), its id, or the user's own word for it ("the outside", "handle", "lid"). "Honeycomb the outside, leave the rim plain" is ``region="outside"``. Whole-object coverage is implied (``surface`` narrows it further, default "all"); the relief eases out at the region's edge the way it eases off the bed, so the pattern meets its neighbour with a shoulder, not a cliff. A word that fits several surfaces refuses with the candidates — ask the user, never guess. The result's ``coverage.region`` names what was textured and ``coverage.left_plain`` what was not, and the output remembers the region so ``paint_mesh_regions`` can still colour it by the same name afterwards. Can't combine with ``face`` / ``mark_image_path``. | |
| surface | No | OPT-IN whole-object coverage via mesh displacement -- ``"all"``, ``"outside"`` (outward-facing only), ``"walls"`` (vertical-ish), or ``"caps"`` (horizontal-ish). Every choice covers outside-facing surfaces: a hollow body's inside stays plain, and so does a thin rim (a lip, a tray edge) with the relief easing in below it -- the result's ``left_plain`` says which. Only valid without ``face`` / ``mark_image_path`` (those imply one face); see the docstring note on its finish vs the single-face carve. | |
| texture | No | Geometric texture type -- ``"wood"``, ``"lava"``, ``"alligator"``, ``"snakeskin_python"``, ``"snakeskin_diamond"``, ``"bamboo"``, ``"carbon_fiber"``, ``"brushed_metal"``, or ``"honeycomb"``. Required unless ``region_textures`` names the textures per region. | |
| depth_mm | No | Relief depth in millimeters. Leave unset and Kiln decides from the texture's mastered depth and the motif size that actually prints, lifted to a depth the printer can show and capped on walls so the relief stays printable. The result's ``relief_plan`` says what was chosen and why; ``summary`` is the one-sentence version. With ``region_textures`` a given depth applies to every texture; unset, each texture is decided on its own. | |
| smoothing | No | Softness dial, 0.0–1.0 (default 0.0 = off). 0 keeps the pattern crisp with sharp, defined edges (best for geometric motifs, logos, carbon fiber). Higher values round the pattern into a soft, gentle relief (best for leather, fabric, organic looks) and also tame a sharp texture that is printing rough. Reach for it when the user wants a softer or more natural finish. Whole-object coverage only. Default: 0.0. | |
| symmetric | No | Sculpt the pattern BOTH ways around the surface instead of only into it (or only out of it). Default relief is one-sided — it starts at the wall and only cuts in (deboss) or only bulges out (emboss). ``True`` treats the image's mid-grey as the untouched wall, raising the lighter parts on one side and sinking the darker parts on the other — a fuller, more three-dimensional carved-relief / coin look. It works both faces, so it needs a bit more wall thickness. Reach for it when the user wants more depth/dimension, or says a one-sided texture looks flat. Whole-object coverage only. Default: false. | |
| input_path | Yes | Path to an STL file -- or, with ``surface`` / ``region`` (whole-object coverage), a painted 3MF: the mesh under the paint is carved and the paint follows by surface name, so the result is a painted 3MF too (``output_3mf``, ``painted_surfaces``; a surface the carve renamed is listed in ``paint_dropped``). | |
| mark_scale | No | Mark box as a fraction of the face (default 0.45); the mark contain-fits inside, aspect kept. Default: 0.45. | |
| mark_style | No | Image processing for the mark -- ``"stencil"`` (bold binary, best for logos; the default), ``"coin"`` (posterized photo relief in a circular medallion), ``"photo"``, ``"medallion"``, ``"portrait"``, or ``"default"``. Same styles as ``decorate_surface``. Default: "stencil". | |
| printer_id | No | The registered printer that will print this part. Its nozzle width sets the smallest motif the relief keeps and its layer height the shallowest relief that prints; both are read from the printer's recorded nozzle (else its model's stock nozzle) and its slicer profile. Unset or unknown: 0.4mm / 0.2mm assumed, and the plan says so. | |
| projection | No | How the pattern wraps onto the shape (whole-object coverage only). On every wrap the relief eases in just above the bed, so a raised pattern climbs off the first layer and never overhangs it. ``"auto"`` (default) detects the shape: anything with one closed outline — a cylinder, a box, a tray — gets a seam-hidden wrap around its walls by arc length, so the pattern marches round every corner like a label; a notched or hollow outline gets stable per-face planar mapping. Right for almost everything, so only override it when the result looks wrong. ``"planar"`` forces flat per-face mapping. ``"cylindrical"`` forces the wrap-around (use for an outline auto declines to wrap). ``"spherical"`` wraps like a globe — reach for it on balls, domes, and ornaments, where the other mappings visibly seam or stretch; pattern compresses a little toward the poles (every globe does). Default: "auto". | |
| resolution | No | Heightmap resolution in pixels, for the SINGLE-FACE carve only. Unset adapts to the detected face, fine enough to resolve the smallest groove a nozzle can print and no finer. Explicit values are honored there (a value above what FDM can print is capped, since finer detail only inflates the mesh). Under whole-object coverage (``surface=``) it does NOT apply: that engine locks the heightmap to the mesh sampling pitch so the relief cannot alias, and reports the value back as ignored rather than returning an unchanged carve in silence. | |
| falloff_curve | No | Shape of the ``edge_falloff_mm`` fade. ``"smoothstep"`` (default) eases in and out — right for almost everything. ``"linear"`` ramps straight (a more mechanical, chamfer-like fade); ``"ease"`` stays subtle longest — the softest, most organic blend. Only meaningful with ``edge_falloff_mm``. Default: "smoothstep". | |
| mark_depth_mm | No | Mark carve depth (default: the texture's own depth, so the finish reads as one carve). | |
| mark_placement | No | ``"center"`` (default), ``"top"``, ``"bottom"``, ``"top-rim"``, or ``"bottom-rim"``. Default: "center". | |
| angle_limit_deg | No | Tighten how much of the object counts as the chosen ``surface`` (``surface="walls"`` or ``"caps"`` only). The built-in walls/caps split is ~45 deg, so on a rounded shape "walls" creeps well up the shoulder and "caps" spills onto it from above. Pass an angle and only surfaces within that many degrees of vertical (walls) or of flat (caps) keep the texture. Reach for it when the user says "only on the sides, not the rounded top", "keep the pattern off the shoulders/dome", or the texture is creeping onto a part of the shape they didn't mean. ~45 reproduces the default coverage; smaller = stricter. Pair with ``edge_falloff_mm`` so the tighter boundary fades instead of cutting off. Whole-object coverage only. | |
| edge_falloff_mm | No | Feather the texture's edges, default 0 = off. Wherever the textured region ends (the walls/caps border, an ``angle_limit_deg`` cutoff, or just above the bed), the relief normally stops at full depth — an abrupt step, like a sticker slapped on. Pass a distance and the carve instead fades smoothly to nothing over that last stretch, blending the pattern into the plain surface. Reach for it when the user says the texture "just stops", "ends abruptly", "looks like a sticker", or asks for it to "blend", "feather", or "fade into the surface". 2–5mm reads naturally on hand-sized objects. Whole-object coverage only. Default: 0.0. | |
| mark_image_path | No | Optional PNG/JPG of a logo or photo to set into the textured face (see **Layered finish** above). | |
| region_textures | No | Several regions, each with its OWN texture, in one carve: ``{"front": "honeycomb", "back": "honeycomb", "top": "wood"}`` -- keys are surfaces exactly as ``region`` takes them (name, id, or the user's word), values are geometric texture names. "Honeycomb on the walls, wood on the lid" is one call. Regions that share a texture share one pattern; every region keeps its own edge ease, the thin-wall clamp sees each texture's depth, and the output remembers every region by name for the paint step. Leave ``texture`` out (the map names them all). Can't combine with ``region``. | |
| save_to_library | No | If True, save this finish's RECIPE (texture + depth + scale + seed + mode) to the decoration library so the dialed-in look is nameable and reusable -- offer this when the user has tuned depth/scale/seed away from the defaults and likes the result. Default: false. | |
| mark_offset_x_mm | No | Continuous placement offset from the face centre, along the face's own width axis (image right), in mm. Adds on top of ``mark_placement``. Default: 0.0. | |
| mark_offset_y_mm | No | Same, along the face's height axis (image up). The mark's clear panel is clamped to stay on the face after offsets. Default: 0.0. | |
| prevent_overhangs | No | Print-safety guard. Default ``"auto"`` and you should almost never touch it: a texture that quietly makes a model need supports it didn't need before is a defect, not an option, so the guard runs by itself wherever the geometry can actually cause that (a round / organic body, where the surface curves away under the relief). Flat-faced parts can't produce the failure, so it stays off there rather than shallowing their relief for nothing. Relief that would tip a surface past the printable overhang angle is eased back; the model's OWN overhangs are always left alone. ``True`` forces it on (costs some relief depth on steep curves), ``False`` forces it off — only reach for those if the user explicitly asks. Whole-object coverage only. Default: "auto". | |
| segmentation_params | No | The ``segmentation_params`` block a ``segment_mesh_regions`` call returned, passed back verbatim, so ``region`` / ``region_textures`` refer to the exact partition the user was shown. Optional — omitted, the mesh is segmented at the same defaults that call uses. |