docs: add asset label photo matching docs

2026-05-29 08:37:38 -04:00
parent a6d96de534
commit 5e0313443a
1 changed files with 46 additions and 0 deletions
@@ -0,0 +1,46 @@
+# Asset Label Photo Matching
+
+**Added:** 2026-05-29
+
+New system for matching label photos (serial numbers, barcodes, QR codes) against the assets database.
+
+## Normalization
+
+`classify_makes.py` contains `normalize_identifier()` which:
+
+- Strips label prefixes (`S/N:`, `ID#`, `Machine ID:`, `Monyx ID`, etc.)
+- Removes dots, dashes, spaces, slashes, colons
+- Uppercases, keeps alphanumeric only
+
+Examples:
+- `"2500.0100.0025534"` → `"2500010000255534"`
+- `"S/N: 2500.0100.0025534"` → `"2500010000255534"`
+- `"RY10006338"` → `"RY10006338"`
+
+## DB Matching
+
+`find_asset_by_normalized_id()` searches across `serial_number`, `connect_id`, `equipment_id`, `machine_id`, and `barcode` columns — normalizing all before comparing.
+
+## API Endpoints
+
+### `POST /api/ocr`
+Existing photo upload endpoint enhanced. Now returns `matched_assets` in addition to the legacy `machine_id` field. Uses Tesseract OCR. Falls through gracefully when OCR produces garbage.
+
+### `POST /api/match-text`
+New endpoint for client-side processing:
+```
+curl -sk https://canteen.ourpad.casa:8901/api/match-text \
+  -d "text=2500.0100.0025534"
+```
+Returns `{raw_text, matched_assets[], match_count}`.
+
+## CLI Tool
+
+```
+python3 scripts/match_label_photo.py photo.jpg
+python3 scripts/match_label_photo.py --text "S/N: 2500.0100.0025534"
+```
+
+## Vision Fallback
+
+The vision model at opencode.ai (`mimo-v2-omni`) is used when Tesseract fails on dark-background or complex labels. The app can accept text from client-side vision processing via `/api/match-text`.