# scan-core
Motor de visión por computadora en Rust para la detección y rectificación de exámenes. Optimizado para alto rendimiento y facilidad de integración.
## 🚀 Modos de Escaneo
| `Aruco4x4` | ✅ Sí | `ARUCO_4X4_50` (16 bits) | **Recomendado**. Rápido y compacto |
| `Aruco5x5` | ✅ Sí | 25 bits | Entornos con interferencia visual |
| `Aruco6x6` | ✅ Sí | 36 bits | Máxima seguridad contra falsos positivos |
| `Invisible` | ❌ No | Bordes + Anclas NCC | Exámenes sin marcadores visibles |
---
## 🛠️ Uso como Librería (Rust)
```rust
use scan_core::{scan, ScanConfig, ScanMode, AnchorConfig}
let img = image::open('examen.jpg')?.to_luma8()
let config = ScanConfig {
mode: ScanMode::Invisible,
debug: true,
anchors: Some(vec![
AnchorConfig {
name: 'logo'.to_string(),
x: 5.0, y: 3.0,
width: 12.0, height: 8.0,
reference: Some(base64_de_la_imagen),
}
]),
..Default::default()
}
let result = scan(&img, &config)?
if result.success {
// result.cropped_image -> Base64 PNG del examen rectificado
// result.marked_image -> Base64 JPEG con bordes/anclas resaltados
// result.match_score -> Confianza de detección (0.0 - 1.0)
// result.logs -> Logs de depuración
}
```
## 🖥️ Uso como CLI
El binario `scan-core-test` expone la funcionalidad del motor vía línea de comandos.
### Escaneo con salida JSON (integración con otros sistemas)
```bash
scan-core-test scan --input examen.jpg --mode invisible --json --debug
```
Esto imprime el `ScanResult` completo como JSON a stdout, incluyendo las imágenes en base64 inline. Ideal para integración con Python, Node.js u otros backends.
**Campos del JSON de respuesta:**
| `success` | `bool` | Si la detección fue exitosa |
| `error` | `string?` | Mensaje de error (si aplica) |
| `cropped_image` | `string?` | Base64 PNG del examen rectificado |
| `marked_image` | `string?` | Base64 JPEG con bordes y anclas |
| `debug_image` | `string?` | Base64 PNG del mapa de bordes (con `--debug`) |
| `corners` | `Point[]?` | Esquinas detectadas (TL, TR, BR, BL) |
| `detected_markers` | `Marker[]?` | Marcadores ArUco encontrados |
| `match_score` | `float?` | Score de confianza NCC (modo invisible) |
| `logs` | `string[]` | Logs de depuración |
### Escaneo con salida visual (inspección humana)
```bash
scan-core-test scan --input examen.jpg --mode aruco4x4 --debug
```
Genera archivos en `result/<carpeta>/`:
- `*_cropped.png` — Examen rectificado
- `*_marked.jpg` — Original con marcas de detección
- `*_debug.png` — Mapa de bordes
### Generar marcadores ArUco
```bash
scan-core-test marker --id 1 --mode aruco4x4 --output marker_1.png
```
### Opciones disponibles
| `--input` | (requerido) | Imagen o directorio a procesar |
| `--mode` | `Aruco4x4` | `Aruco4x4`, `Aruco5x5`, `Aruco6x6`, `Invisible` |
| `--json` | `false` | Salida JSON a stdout (para integración) |
| `--debug` | `false` | Incluir imágenes de depuración |
| `--ids` | `1,2,3,4` | IDs de marcadores ArUco (orden TL,TR,BR,BL) |
| `--min-markers` | `3` | Mínimo de marcadores requeridos |
| `--max-hamming` | `1` | Tolerancia Hamming máxima |
| `--anchors` | (ninguno) | Archivo JSON con config de anclas (modo Invisible) |
---
## 📐 Sistema de Coordenadas
Todas las coordenadas de anclas usan **porcentaje relativo al Ancho** (0.0 a 100.0).
- `x: 50.0` = centro horizontal
- En documentos A4 (más altos que anchos), `y` puede superar 100.0
## ⚙️ Configuración de Anclas (JSON)
```json
[
{
"name": "logo",
"x": 5.0,
"y": 3.0,
"width": 12.0,
"height": 8.0,
"reference": "<base64 de imagen de referencia>"
}
]
```
---
## 🧪 Ejemplo de integración con Python
```python
import subprocess, json
result = subprocess.run(
['scan-core-test', 'scan', '--input', 'exam.png', '--mode', 'invisible', '--json', '--debug'],
capture_output=True, text=True
)
data = json.loads(result.stdout)
if data['success']:
cropped_b64 = data['cropped_image'] # Base64 PNG
score = data['match_score'] # 0.0 - 1.0
```
---
Para más detalles técnicos sobre algoritmos internos, consultar:
- [Guía de Anclas Dinámicas](GUIAS/ANCLAS.md)
- [Implementación de Vision (src/cv/)](src/cv/)