apply_image_texture
Wraps a photo texture over selected faces or whole 3D meshes as debossed or embossed relief, then opens an interactive 3D stage to inspect the result.
Instructions
Apply a photo-based texture as a tiled deboss/emboss pattern. 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>",
"image_path": "<image_path>"
},
"name": "apply_image_texture"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| face | No | Surface targeting mode: ``"auto"`` — find the largest flat face (current default). ``"front"`` — single flat panel on the front of a cylinder. ``"cylindrical"`` — wrap texture around the full cylinder using *num_panels* flat panels. ``"top"``, ``"bottom"``, ``"back"``, ``"left"``, ``"right"`` — target a specific flat face by name. ``"side:l2"`` — a sketch-built part's own wall, by the sketch entity that swept it (the recipe must sit beside the mesh); it follows the wall through a resize and rebuild. Default: "auto". | |
| mode | No | ``"deboss"`` (grooves, default) or ``"emboss"`` (raised ridges). Default: "deboss". | |
| style | No | How the photo becomes a heightmap: ``"posterized"`` (the default), ``"sharp"`` or ``"soft"``, as described under Heightmap styles above. Any other value is read as ``"soft"``. Default: "posterized". | |
| invert | No | Swap which part of the image stands out (the dark detail is normally the feature; ``True`` makes the light parts the feature instead). Whole-object coverage only. Default: false. | |
| region | No | Wrap the image over ONE named surface region and leave the rest plain — the same regions ``segment_mesh_regions`` shows and ``paint_mesh_regions`` colours, by name ("Outside"), id, or the user's own word ("the handle"). Implies whole-object coverage (``surface`` narrows it, default "all"); the relief eases out at the region's edge like it eases off the bed. A word fitting several surfaces refuses with the candidates. The output remembers the region so it can still be painted by name. Can't combine with an explicit ``face``. | |
| surface | No | **Whole-object coverage** — wrap the user's OWN image around EVERY selected surface of ANY mesh (curved, organic, imported — not just flat faces and cylinders) by direct mesh displacement. ``"all"`` / ``"outside"`` / ``"walls"`` / ``"caps"``; can't combine with an explicit ``face``. This is the path for "wrap my leather photo around this dragon". A hollow body's inside and any thin rim stay plain. The bed-contact band stays flat and thin walls are automatically protected, same as the preset textures. | |
| depth_mm | No | Deboss/emboss depth in mm (default 1.2). Default: 1.2. | |
| smoothing | No | Softness dial 0.0-1.0 (default 0 = crisp). Higher rounds the relief into a soft, gentle finish — best for fabric/organic looks or a photo that prints rough. Whole-object coverage only. Default: 0.0. | |
| symmetric | No | Sculpt the image BOTH ways around the surface (image mid-grey = the untouched wall) instead of only cutting in or only raising out — a fuller, coin-like relief. Needs a bit more wall thickness. Whole-object coverage only. Default: false. | |
| image_path | Yes | Path to a texture photo (JPEG or PNG). | |
| input_path | Yes | Path to an STL file -- or, with ``surface`` / ``region``, a painted 3MF whose paint follows the carve by surface name (see ``apply_geometric_texture``). | |
| num_panels | No | Number of flat panels for cylindrical wrap (default 8, range 4-12). More panels = smoother wrap but slower compile. Only used when ``face="cylindrical"``. Default: 8. | |
| projection | No | How the image wraps the shape (whole-object coverage only): ``"auto"`` detects (one closed outline → seam-hidden wrap round the walls, notched or hollow → per-face planar); ``"planar"`` / ``"cylindrical"`` force it; ``"spherical"`` wraps like a globe — for balls, domes, ornaments. Default: "auto". | |
| resolution | No | Max pixels per tile edge before tiling (default 300; higher is capped, since finer detail exceeds what FDM prints). Default: 300. | |
| tile_size_mm | No | Physical size of one tile repeat in mm. Default (None) is ONE-SHOT SMART: the motif period is read from the image itself and the repeat sized so motifs print at a size the material can show, as the curated presets are. The response carries ``auto_tile_mm`` + a warning naming the chosen size. Pass an explicit value to override; smaller = more repeats = finer pattern. | |
| falloff_curve | No | Shape of the ``edge_falloff_mm`` fade: ``"smoothstep"`` (default, eases both ends), ``"linear"`` (straight ramp), or ``"ease"`` (subtlest, most organic). Only meaningful with ``edge_falloff_mm``. Default: "smoothstep". | |
| angle_limit_deg | No | Tighten how much of the object counts as the chosen ``surface`` (``"walls"`` or ``"caps"`` only). Only surfaces within this 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" or the image is creeping onto a shoulder/dome they didn't mean. ~45 reproduces the default split. Whole-object coverage only. | |
| edge_falloff_mm | No | Feather the texture's edges (default 0 = off): the relief fades smoothly to nothing over the last N mm before the textured region ends, instead of stopping at an abrupt step. Reach for it when the user says the texture "just stops", "looks like a sticker", or asks for it to "blend/feather/fade into the surface". 2–5mm reads naturally. Whole-object coverage only. Default: 0.0. | |
| prevent_overhangs | No | Print-safety guard, default ``"auto"`` (leave it alone): relief that would make the model need supports it didn't need before is eased back automatically on round / organic bodies, where that can actually happen, and left alone on flat-faced parts, where it can't. The model's own overhangs are never touched. ``True`` / ``False`` force it on or off. Whole-object coverage only. Default: "auto". | |
| segmentation_params | No | The block ``segment_mesh_regions`` returned, passed back verbatim so ``region`` means the partition the user saw. Optional. |