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"`` — detects the image kind: a logo/wordmark/line-art
  image routes to ``"stencil"`` (crisp traced strokes); a
  continuous-tone photo routes to ``"coin"``
- ``"coin"`` — histogram-equalized posterize, best for FDM coin-relief
- ``"portrait"`` — edge-detected line art
- ``"composite"`` — posterize base + edge overlay hybrid
- ``"medallion"`` — coin + raised border ring (premium look)
- ``"photo"`` — simple 3-level posterize
- ``"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.
- ``"lithophane"`` — full gradient for backlit prints

**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"`` picks the largest
    flat face.  Also accepts ``"top"``, ``"bottom"``, ``"front"``,
    ``"back"``, ``"left"``, ``"right"``.  A deboss now carves into
    the body on every cardinal face, and ``offset_x/y_mm`` place
    face-locally (see below).  ``top``/``bottom``/``front`` are the
    battle-tested three; ``back`` carves and offsets correctly but
    content may still land rotated 180° (content orientation is
    unaddressed by the placement fix); on ``left``/``right`` the
    carve lands but the offset axis scaling is less verified.  Prefer
    the front-facing three when exact placement matters.
:param depth_mm: Emboss/deboss depth in mm.  ``0`` = auto based on
    *material* (e.g. 0.6 mm for PLA, 1.2 mm for TPU).
: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"`` uses
    ``"coin"`` for photos.  See docstring for all options.
: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"``).
    When provided, auto-fills ``face``, ``depth_mm``, ``mode``,
    ``scale``, and ``image_style`` from the template's decoration
    profile.  Explicit values you provide override the profile.
    Use ``list_decoratable_templates()`` to see which templates
    have profiles.
:returns: Dict with output STL path, preview info, and metadata.