# Python samples — Titan-ANPR SDK

Minimal **`ctypes`** examples for **Windows x64**, in the same spirit as the C# projects under `samples/csharp`.

## Requirements

- **Windows x64**
- **Python 3.10+** (3.11 or 3.12 recommended)
- **Microsoft Visual C++ Redistributable (x64)** on the target machine
- The native SDK **bin** folder with **`Titan-ANPR.dll`** and its dependencies (ONNX Runtime, OpenVINO, etc., depending on your distribution)
- A **valid license** to run `TitanANPR_Init` / detection (return code **`-10`** often means invalid runtime license)

## Setup

```powershell
cd samples\python
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
```

**`numpy`** and **`Pillow`** are only required for **`example_detect.py`** (RGB image buffer). The license sample uses the standard library plus **`ctypes`** only.

## Locating `Titan-ANPR.dll`

1. Environment variable **`TITAN_ANPR_NATIVE_DIR`**: path to the folder that contains the DLL.  
2. The **`--bin`** argument on the scripts.  
3. Automatic search: walk up from `samples/python` looking for `bin/Titan-ANPR/Release/x64/bin` or `.../Debug/x64/bin`.  
4. Current working directory if **`Titan-ANPR.dll`** is present there.

On Python **3.8+**, `titan_anpr_bindings.load_dll` calls **`os.add_dll_directory`** for that folder so Windows can load dependent DLLs next to **`Titan-ANPR.dll`**.

## Usage

### License (`example_license.py`)

```powershell
python example_license.py --bin "D:\sdk\bin" hwid
python example_license.py info
python example_license.py validate
python example_license.py activate "YOUR-KEY"
python example_license.py deactivate
```

To request a license key, use the same flow as the C# samples: send the **hardware ID** (from the `hwid` command) to **licenses@safetyroad.es**.

### Detection (`example_detect.py`)

```powershell
python example_detect.py --bin "D:\sdk\bin" path\to\photo.jpg
```

Prints plate text, `found`, total confidence, and approximate **`TitanANPR_Detect`** time (does not include **`Init`**).

The image is converted to **8-bit RGB**, tightly packed rows, **`stride = width × 3`** (no extra row padding). If the native engine expects a different pixel layout or 4-byte-aligned stride, adjust buffer preparation (e.g. with **`numpy`**).

## Files

| File | Description |
|------|-------------|
| `titan_anpr_bindings.py` | `ctypes` structures, path resolution, DLL load. |
| `example_license.py` | Subcommands: `info`, `hwid`, `validate`, `activate`, `deactivate`. |
| `example_detect.py` | Single image → `TitanANPR_Init` / `Detect` / `Dispose`. |

## Limitations

- **Windows only**: the DLL is native Win32/Win64.  
- The unified API returns **one** primary plate per call.  
- No overlay PNG or GUI in these scripts; extend with Pillow/OpenCV as needed.
