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:

- ``"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"`` — binary silhouette
- ``"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"``.
: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: Horizontal offset from center (mm).
:param offset_y_mm: Vertical offset from center (mm).
: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.