decorate_surface

For repeating patterns (wood grain, camo, honeycomb) that tile across
the entire surface, use ``apply_geometric_texture`` or
``apply_procedural_texture`` instead.  This tool is for one-off
content placement (logos, text, images).

Takes a model and content (image file, text string, SVG) and returns
a new STL with the content embossed or debossed onto the surface.
Automatically detects the best face for placement and scales content
to fit.  Single-color coin-relief style — no multi-material needed.

**Content types** (auto-detected from *content* string):

- **Image file** (PNG/JPG/SVG): ``"/path/to/photo.jpg"``
- **Text**: ``"text:KILN"`` or ``"text:Hello World"``

**Image styles** for raster images:

- "auto" — a logo/wordmark/line-art image routes to "stencil"
  (crisp traced strokes); a photo is sculpted and Kiln picks the look
  from the photo and the part, saying why in relief.chosen_because
- "coin" — a sunk relief, the subject rising to the rim plane
- "cameo" — the same relief raised on the face (emboss)
- "etched" — edges first, for a small part
- "sketch" — engraved contour lines, one layer deep (was "portrait")
- "medallion" — a coin with a rim ring; "photo" and
  "composite" mean "coin"
- "stencil" (alias "logo") — the mark's ink is traced into
  vector strokes and carved directly: crisp edges, no background
  tile, correct orientation.  The right choice for brand logos.

**Examples**::

    decorate_surface(model_path="coaster.stl", content="photo.jpg",
                     mode="deboss", depth_mm=1.5, image_style="coin")

    decorate_surface(model_path="keychain.stl", content="text:KILN",
                     face="top", depth_mm=0.5)

Requires OpenSCAD installed locally for compilation.

:param model_path: Path to the base model (STL or OBJ).
:param content: What to put on the surface — file path (PNG/JPG/SVG)
    or ``"text:..."`` for text.
:param face: Which face to decorate: ``"auto"`` (largest flat face),
    ``"top"``, ``"bottom"``, ``"front"``, ``"back"``, ``"left"``,
    ``"right"``, or ``"wall"`` (wraps text, an SVG logo or a line-art
    mark around the upright round wall of a cup, jar, vase or bowl;
    STL and deboss only; a photo relief goes on a flat face).  On
    ``"wall"``, *scale* is the letter height or mark width as a share
    of the wall, *absolute_size_mm* pins it exactly, and
    *offset_x/y_mm* / *placement* do not apply; the response reports
    the size and depth used.  Placement on ``top``/``bottom``/``front``
    is exact; on ``back`` content may land rotated 180°.
:param depth_mm: Emboss/deboss depth in mm.  ``0`` picks a depth for
    *material* and for the content (a photo relief is bounded by how
    much part sits under the face); the response reports the depth
    used.
:param mode: ``"deboss"`` (cut into surface) or ``"emboss"`` (raised).
:param scale: Fraction of the face to cover (0.1-1.0, default 0.7).
:param material: Material for depth auto-tuning (default ``"PLA"``).
:param content_type: Override auto-detection: ``"svg"``, ``"image"``,
    ``"text"``.  Default ``"auto"`` detects from *content*.
:param offset_x_mm: Placement offset from the face centre along the
    face's own WIDTH axis, in mm — positive slides the content
    toward the content's right.  Offsets are FACE-LOCAL: they are
    applied inside the face-aligning rotation, so they always move
    the art in the face plane, never along its normal.
:param offset_y_mm: Same, along the face's HEIGHT axis — positive
    slides the content toward the content's top.  Measured
    world-axis mapping per face: top +y, bottom −y, front +z,
    back −z.
:param image_style: Image preprocessing style: ``"auto"`` (a logo or
    line-art image is traced as ``"stencil"``; a photo is sculpted and
    the look chosen for it), ``"coin"``, ``"cameo"``, ``"etched"``,
    ``"sketch"``, ``"medallion"``, ``"stencil"`` (alias ``"logo"``).
    An unknown style is refused naming the accepted list.
:param placement: Named position preset for content placement.
    ``"center"`` (default), ``"top"``, ``"bottom"``, ``"top-rim"``,
    ``"bottom-rim"``.  Use ``"bottom"`` for text below a centered
    portrait on a coaster.  Manual ``offset_x/y_mm`` is added on
    top of the preset for fine-tuning.
:param svg_id: Target a specific SVG group by ``id`` attribute when using
    SVG ``import()`` fallback on OpenSCAD 2024+.  E.g. ``"icon"`` targets
    ``<g id="icon">``.  No effect on the native polygon path.
:param svg_layer: Target a specific SVG layer by ``layer`` attribute when
    using SVG ``import()`` fallback on OpenSCAD 2024+.  E.g.
    ``"foreground"`` targets a layer named ``foreground``.
:param template_id: Optional template ID (e.g. ``"nameplate"``), used
    for provenance tracking only.  To auto-fill ``face``, ``depth_mm``,
    ``mode``, ``scale``, and ``image_style`` from a template's curated
    decoration profile, call ``resolve_template_decoration()`` first
    (kiln-pro) and pass its results explicitly.
:returns: Dict with output STL path, preview info, and metadata.
:param absolute_size_mm: Exact letter height (text) or mark width (marks)
    in mm, overriding *scale*; ``0`` leaves *scale* in charge.