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

🛠️ Uso como Librería (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)

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)

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

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)

[
  {
    "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

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:

scan-core 0.1.1