curl -X POST "https://laserchip-6dn1tl7vjz5u.adom.cloud/etch?mpn=STM32F103C8T6" \
     --data-binary @chip.step -o etched.step

adom-aiflow-etch --in part.step --mpn <MPN> --out part-etched.step --footprint part.kicad_mod
adom-aiflow-etch check part-etched.step        # must say PASS; look at part-etched.check.png

adom-chip-laser etch  <chip.step> <MPN> [out.step] [key=value ...]   # the part + its mark
adom-chip-laser inlay <chip.step> <MPN> [out.step] [key=value ...]   # the mark alone
adom-chip-laser etch vl53l7cx.step VL53L7CX out.step surface=side:-y color=light
adom-chip-laser health | url | version

# Adom Chip Laser

Laser-etch a component's **MPN into its CAD at the STEP layer** — so the
downloadable STEP, a Fusion 360 import, and the derived 3D model all carry the
part number on the die. Not a viewer-only texture: it's real geometry in the STEP.

Why STEP-layer: Fusion imports a library via the **STEP**, not a GLB. And a laser
mark on black epoxy is a **color change**, not a groove, so the mark is a flat
light sheet just off the face, in its own `Adom.LaserEtch` part you can hide.

## Call it (HTTP service)

Since **0.2.0** the service hands the STEP to service-occt `/laser-etch`, the same etch the
component pages use: the part comes back **untouched, every colour kept**, with the mark as its own
`Adom.LaserEtch` part, a flat light (or dark) sheet 5 µm off the face. The 0.1.0 CadQuery path
(recess + grey inlay, part repainted) is still there as `engine=legacy`.

```bash
curl -X POST "https://laserchip-6dn1tl7vjz5u.adom.cloud/etch?mpn=STM32F103C8T6" \
     --data-binary @chip.step -o etched.step
```

- `mpn` (required): the part number to etch.
- `surface=auto|top|side|side:-y|side:+y|side:-x|side:+x` (default `auto`): `auto` marks an LED, or
  a part whose top is busy (2+ openings in the top face and recessed faces covering 15 %+ of the
  footprint: ToF windows, lenses), on the side wall that fits the largest text; everything else on top.
- `style=flat|recessed` (default flat), `color=auto|light|dark` (default auto: contrasts with the
  marked face), `fit=adom|compact`, `rot=0|90|180|270`, `pin1_xy=x,y`, `upright=auto|off`,
  `busy_top=on|off`. `frac` is accepted and ignored (legacy only).
- A Y-up model (a vendor can lying along Y) is stood up for the fit; the mark is put back in the
  model's own frame.
- Response is `application/step`. Headers: `X-Etch-Fontsize-Mm`, `X-Etch-Face`,
  `X-Etch-Face-Reason` (why auto chose it), `X-Etch-Stood-Up`, `X-Etch-Job` (the service-occt job,
  whose `/jobs/<id>` has the full fit report). A part the text cannot fit is a 422 with the reason.
- `POST /inlay?mpn=…`: the mark alone, as its own STEP, to merge onto a published GLB.
- `GET /health` → `{"ok":true,"version":"…","engine":"service-occt"}`.

No cadquery needed on your end — any Adom app can call the service.

## Marking checklist (read before you etch)

Since 0.2.0 `/etch` keeps the part's own colours, runs the mark along the long axis of the top
face, stands Y-up models up and marks a busy top on a side. It does not know the part's end caps or
the page's standard pose, and it reads from pin 1 only when it finds a pin-1 dot (or gets `pin1_xy`
/ `rot`). For a component model, use the planner that wraps the shared STEP service:

```bash
adom-aiflow-etch --in part.step --mpn <MPN> --out part-etched.step --footprint part.kicad_mod
adom-aiflow-etch check part-etched.step        # must say PASS; look at part-etched.check.png
```

(`adom-aiflow-etch` ships with adom/adom-aiflow 0.1.48+: plain python3, nothing to install.)

The rule it enforces:

1. **Along the longest usable dimension** of the marking face: chip R/C/L along the body, in the
   band between the metal end caps; ICs parallel to the pin rows (a SOT-23-6 along its 2.9 mm
   length); side-marked LEDs along the long side wall, window clear.
2. **As large as fits**: the band minus 10 to 15 % margins each side, one line; two lines only when
   that makes the text larger.
3. **Upright, left to right, in the standard pose**: pin 1 / pad 1 lower left seen from the top
   (two-terminal: pad 1 on the left; polarised parts follow pin 1 / cathode). The iso outline then
   shows pin 1 toward the viewer and the text reads without tilting your head.
4. **Flat light mark, coplanar with the face**, in `Adom.Chip` / `Adom.LaserEtch`; never raised or
   recessed lettering.
5. **The chip outline's name is the same mark**: same face, direction and place
   (`adom-aiflow-etch outline part.step --etched part-etched.step --footprint part.kicad_mod`).
6. **Look at the result at widget size before you report** (the gate reports the cap height in
   pixels at 320 px and prints `Hint:` lines saying what to rerun when it fails).

Use `/etch` directly for a quick mark, or when the planner's footprint inputs are not at hand.

## Client CLI (installed by this package)

```bash
adom-chip-laser etch  <chip.step> <MPN> [out.step] [key=value ...]   # the part + its mark
adom-chip-laser inlay <chip.step> <MPN> [out.step] [key=value ...]   # the mark alone
adom-chip-laser etch vl53l7cx.step VL53L7CX out.step surface=side:-y color=light
adom-chip-laser health | url | version
```

`key=value` arguments go on the query (`surface`, `style`, `color`, `fit`, `rot`, `pin1_xy`,
`upright`, `busy_top`); the client prints the face, the reason and the font size. Override the
service with `ADOM_CHIP_LASER_URL`.

The source repo `adom-inc/adom-chip-laser` also has a Python `board` command (etched chip GLB +
animated board GLB); it still uses the legacy CadQuery etch.

## What you get

- A **downloadable STEP** whose die carries the MPN — survives into Fusion.
- A **3D model** with the mark and a toggleable `laser_etch` layer.
- Auto-fit along the long axis, as large as fits, MPN-only; every colour of the source kept.

First live on the component page [`adom/stm32f103c8t6`](https://wiki.adom.inc/adom/stm32f103c8t6).

Source: `adom-inc/adom-chip-laser` · MIT.