scan-core 0.1.2

Computer vision engine for exam detection and ArUco marker rectification
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

# 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


| Modo        | Marcas en papel | Dictado                  | Uso ideal                                |
| :---------- | :-------------- | :----------------------- | :--------------------------------------- |
| `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         |
| **Robust**  | ✅ Sí           | Least Squares (16 pts)   | **Novedad v0.1.2**. Máxima precisión     |

---

## 🛠️ 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:**

| Campo              | Tipo        | Descripción                                   |
| :----------------- | :---------- | :-------------------------------------------- |
| `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


| Flag            | Default     | Descripción                                        |
| :-------------- | :---------- | :------------------------------------------------- |
| `--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/)