# AIFotoONLUS Number Recognition Library

This library provides a small, focused engine to detect and recognize numeric
text (digits) in images using Darknet (YOLO) models via OpenCvSharp's DNN API.
It is suitable for batch processing folders of images or individual files.

Features
- Detection network (Darknet/Yolo) to find candidate text regions.
- Recognition network (Darknet/Yolo) to identify digits inside detected crops.
- Single-file and directory-level processing APIs.
- Parallel processing with per-thread network instances for throughput.
- Diagnostic helpers to dump network output shapes and optionally save crop images.

Basic usage
1. Create a `ModelConfiguration` instance that points to your Darknet `.cfg`
and `.weights` files for both detection and recognition networks, configure
confidence and NMS thresholds and provide a list of number class labels.

2. Create an instance of `NumberRecognitionEngine`:

```csharp
using var engine = new NumberRecognitionEngine(modelConfig, logger: null);
```

3. Process a single image:

```csharp
var result = engine.ProcessImage("/path/to/image.jpg");
Console.WriteLine(result.Text);
```

4. Process a directory (parallelized):

```csharp
var results = await engine.ProcessDirectoryAsync("/path/to/images", recursive: false);
foreach (var r in results) Console.WriteLine($"{r.FileName}: {r.Text}");
```

Configuration notes
- `ModelConfiguration` controls model file paths, input sizes, thresholds and
  whether to save cropped images for diagnostics. Make sure the paths are
  accessible to the process and the model files match the expected network
  architectures.

- The engine expects detection network outputs in the YOLO-style layout:
  `[cx, cy, w, h, objectness, class1, class2, ...]`.

Threading & diagnostics
- For directory/batch processing the engine creates per-thread Net instances
  so OpenCV forward calls can run concurrently. It also contains fallback
  logic that will perform processing with shared nets under a lock if needed.

- When `EnableCropSaving` is enabled in configuration, each recognized crop is
  saved to `logs/crops` with a timestamp and optional context label to aid
  debugging false positives/negatives.

Troubleshooting
- If the engine returns no detections, verify the model files are correct and
  compatible with the expected output layout. Use
  `ProcessFileWithDiagnostics` to inspect output layer shapes.

License & Notes
This project is provided as-is. See repository for licensing information and
for the model files distribution terms (models are usually not redistributed
with code and must be obtained separately).