decorate_during_print
Add a decoration to an in-flight paused 3D print, then preview and inspect the result in an interactive 3D stage.
Instructions
Add a decoration to an in-flight paused print (Pro). Opens Kiln's interactive inline 3D stage on the result (orbit/zoom panel in MCP Apps hosts; hosted sessions add a browser stage link).
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": {
"decoration": "<decoration>",
"gcode_path": "<gcode_path>",
"current_layer": "<current_layer>"
},
"name": "decorate_during_print"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bevel | No | Slant the carved walls over the top N layers for cleaner edges (default True). Default: true. | |
| style | No | How the image becomes a carve mask: ``"stencil"`` (the default, a clean binary silhouette) or ``"coin"`` (a medallion-style recessed background around the image); the other image styles of Kiln's emboss pipeline are accepted too. A style the pipeline refuses fails with ``HEIGHTMAP_GENERATION_FAILED``. Default: "stencil". | |
| bed_temp | No | Bed temperature, read and checked the same way as ``hotend_temp``. | |
| depth_mm | No | Deboss depth in mm, (0, 5]. Defaults to 1.2 which looks clean on 0.4 nozzles. Default: 1.2. | |
| threshold | No | Heightmap value above which a pixel is treated as carved-away (0.0–1.0, default 0.35). Default: 0.35. | |
| decoration | Yes | Plain-language spec string (``photo:``, ``logo:``, a texture name, or a description). | |
| gcode_path | Yes | Original sliced .gcode of the in-flight job. | |
| output_dir | No | Engine session directory. Empty = system temp dir (a new ``kiln_midprint_*`` subdirectory). Default: "". | |
| hotend_temp | No | Nozzle temperature for the resume pre-heat and Bambu 3MF metadata. Leave unset to use the print's own (read off ``gcode_path`` at the pause). A value that differs from the print's own is kept and said in ``warnings``. | |
| image_scale | No | 0.0–1.0, what fraction of the top-face AABB the image fills. Default 0.7 leaves a visual margin. Default: 0.7. | |
| printer_name | No | Printer identifier — passed to provenance and to the fleet layer. Default: "default". | |
| aspect_policy | No | ``"auto_crop"`` / ``"auto_scale"`` / ``"strict"`` — how to handle aspect mismatch between image and top face. Default: "auto_crop". | |
| current_layer | Yes | 1-indexed layer the printer is paused at. | |
| filament_type | No | The print's material, for Bambu 3MF metadata and material-routing provenance. Leave it out and Kiln reads the print's own material; when nothing says which, the call is refused (``PRINT_MATERIAL_UNKNOWN``). | |
| image_center_xy | No | Optional ``[x, y]`` in bed coords for where the image's center lands. ``None`` = center of the top-face AABB. | |
| printer_z_known | No | REQUIRED ``True``. The safety gate from ``generate_recovery_gcode`` — refuses with ``PRINTER_Z_UNKNOWN`` if the printer's absolute Z can't be trusted (power-cycle / reconnect / etc.). Default: false. | |
| source_3mf_path | No | Optional original .3mf — passed to the Bambu wrapper so the resume 3MFs inherit the thumbnails + 3D model preview from the original job. Default: "". | |
| target_ams_slot | No | Optional 0-indexed material slot that must feed the transformed resume artifact. On Bambu this is verified against AMS status. On non-Bambu adapters it is accepted only as an explicit declared tool slot route, for example when the user says the requested material/color is in slot 2. ``-1`` means no explicit material route was requested. Default: -1. | |
| parent_design_id | No | Optional identifier of the design this print is derived from — threads through to the provenance sidecar so reprint/diff tooling can follow the lineage. Default: "". | |
| require_ams_match | No | When True, refuse to emit a material-changing resume artifact unless AMS status proves the requested slot/type/color. Keep True for user-facing work. Default: true. | |
| accept_unsafe_depth | No | Caller's acknowledgement that the carve mask satisfies the centered-carve safety envelope (centered interior, uniform top-to-bottom, no lost bridge endpoints). Required when ``start_layer_override`` is strictly below the analyzer's ``band_floor``. Without it the engine raises ``DEPTH_UNSAFE_WITHOUT_ACKNOWLEDGEMENT``. Default: false. | |
| start_layer_override | No | Force the carver's first carved layer. ``0`` (the default) defers to the analyzer's verified ``top_band_start_layer`` floor — the correct choice for any carve whose mask might touch a perimeter. A non-zero value reaches down to that layer instead, enabling deeper tactile debosses on thin parts whose analyzer floor is overly conservative. Setting this below the analyzer's band_floor requires ``accept_unsafe_depth=True`` AND a centered carve mask (the analyzer's depth-safety envelope). Default: 0. | |
| target_filament_type | No | Optional expected tray material (``PLA``, ``PETG``, etc.). Without an explicit slot, the tool resolves exactly one loaded matching AMS tray from Kiln's existing ``ams_status`` data or fails closed. Default: "". | |
| target_filament_color | No | Optional expected tray color (``#RRGGBB`` or common name like ``blue``). Used with the same hard verification as ``target_filament_type``. Default: "". | |
| accept_bridge_cascade_risk | No | THIRD safety gate on top of ``start_layer_override`` + ``accept_unsafe_depth``. Required when the override drops below ``band_floor`` AND any layer in ``[override, last_layer]`` is tagged ``;TYPE:Bridge infill`` or ``;TYPE:Internal infill`` in the source gcode. Crossing one of those layers removes the substrate the solid infill above was going to cool against, cascading into a cap failure. Without it the engine raises ``BRIDGE_CASCADE_RISK``. Default: false. | |
| manual_material_change_confirmed | No | Non-Bambu safety gate for material/color changes. Set True only after the target material is loaded in the active feed path; otherwise Kiln refuses before emitting an artifact. Default: false. |