dotnetANPR 0.1.0

dotnetANPR

Cross-platform automatic number plate recognition (ANPR) for .NET. dotnetANPR locates licence plates in car photos, segments individual characters, classifies them, and optionally corrects the result against known plate formats.

This project is a .NET port of javaanpr by Ondrej Martinsky, preserving the original pipeline of histogram-based region detection, heuristic filtering, and pattern-based character recognition.

Table of contents

• Features
• Project status
• Requirements
• Getting started
• Usage
  • Library
  • Command-line tool
  • Diagnostics
• How it works
• API reference
• Configuration
• Configuration reference
• Syntax configuration reference
• Development
• Contributing
• Acknowledgements
• License

Features

• End-to-end recognition — from a full car image to a plate string in one call
• Two classifiers — KNN pattern matching (default) or feed-forward neural network
• Syntax correction — post-processing against configurable country/format templates
• Skew correction — optional Hough-transform de-skewing for rotated plates
• Cross-platform — netstandard2.0 library with SkiaSharp for image I/O
• Inspectable pipeline — dump intermediate processing stages as JPEGs for debugging
• Extensible — custom alphabets, neural networks, plate formats, and tuning parameters via XML config

Project status

This is an active work in progress. The core recognition pipeline and CLI have been ported from javaanpr; GUI components have not. Automated recognition tests and real-world accuracy tuning are ongoing.

Contributions — bug reports, test images, alphabet data, configuration improvements, and pull requests — are welcome.

Requirements

Getting started

Clone the repository and build the solution:

git clone https://github.com/bolorundurowb/dotnetANPR.git
cd dotnetANPR
dotnet build ./src/dotnetANPR.slnx --configuration Release

Add the library to your project

Reference the project directly (NuGet package publishing is not set up yet):

<ItemGroup>
  <ProjectReference Include="path/to/dotnetANPR/src/dotnetANPR/dotnetANPR.csproj" />
</ItemGroup>

Character training data

Recognition requires alphabet training images at the path configured by char_learnAlphabetPath (default: Resources/alphabets/alphabet_8x13). If this directory is not present in your checkout, copy it from the upstream javaanpr repository. Each file should be a normalised character image matching the configured dimensions (8×13 px by default).

Usage

Library

using dotnetANPR;
using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(b => b.AddConsole());
var engine = new AnprEngine(new AnprOptions { LoggerFactory = loggerFactory });

// Recognise from a file path
var result = engine.Recognize("car.jpg");
if (result.Success)
    Console.WriteLine($"Plate: {result.Text} (confidence {result.Confidence:F2}, {result.Duration.TotalMilliseconds:F0} ms)");

// Recognise with diagnostics and optional skew correction
result = engine.Recognize("car.jpg", new RecognitionOptions
{
    DumpStagesDirectory = "./stages",
    EnableSkewCorrection = true,
});

// Recognise from a stream
using var stream = File.OpenRead("car.jpg");
result = engine.Recognize(stream);

// Recognise from a SkiaSharp bitmap (caller owns the bitmap by default)
using var bitmap = SKBitmap.Decode("car.jpg");
result = engine.Recognize(bitmap);

Recognize returns a RecognitionResult with Text (null when no plate was found), Confidence, Duration, and optional Candidates diagnostics. An invalid image path throws ArgumentException.

Command-line tool

dotnet run --project ./src/dotnetANPR.CLI -- car.jpg

# Dump intermediate processing stages for inspection
dotnet run --project ./src/dotnetANPR.CLI -- car.jpg --dump-stages ./stages

Or run the built executable directly:

./src/dotnetANPR.CLI/bin/Release/net8.0/dotnetANPR.CLI car.jpg

Diagnostics

Pass a dumpDir argument (library) or --dump-stages <dir> (CLI) to write sequentially numbered JPEG snapshots of each pipeline stage — thresholding, band extraction, plate cropping, character segmentation, and more. This is useful when tuning configuration or investigating misrecognitions.

How it works

Recognition follows a multi-stage pipeline inspired by classical computer vision rather than deep learning end-to-end models:

flowchart LR
    A[Car image] --> B[Adaptive thresholding]
    B --> C[Band detection]
    C --> D[Plate candidate search]
    D --> E[Optional skew correction]
    E --> F[Character segmentation]
    F --> G[Feature extraction]
    G --> H[KNN or neural classifier]
    H --> I[Syntax analysis]
    I --> J[Plate text]

1. Preprocessing — adaptive thresholding converts the photo to a binary map
2. Region search — vertical histogram peaks locate horizontal bands; each band is searched for plate-shaped regions
3. Heuristic filtering — candidate plates and characters are validated by size, aspect ratio, brightness, and contrast rules
4. Classification — each character is normalised and matched against a learned alphabet (KNN by default)
5. Syntax analysis — the raw string is corrected against templates in Resources/syntax.xml (German, Slovak, Czech formats included)

API reference

The AnprEngine class is the main entry point. XML documentation is provided on all public types and members.

RecognitionResult exposes Text, Confidence, Duration, Success, and optional Candidates (per-plate diagnostics).

Advanced diagnostics are available via RecognitionResult.Candidates rather than direct access to internal pipeline types.

Configuration

Pipeline behaviour is controlled by Resources/config.xml. Parameters are loaded at startup via the Configurator singleton; defaults are embedded in code and overridden by the XML file when present.

To start from the defaults and customise:

var engine = new AnprEngine(new AnprOptions());
engine.ExportDefaultConfig("my-config.xml");
// Edit my-config.xml, then place it at Resources/config.xml or adjust loading as needed

The tables below document every parameter. In most cases the defaults work well; adjust heuristics and graph parameters only when your source images differ significantly from typical front/rear car photos.

Configuration reference

Photo preprocessing

Skew detection

Plate candidate search

Plate heuristics

Character heuristics

Character normalisation and feature extraction

Classification method

Neural network parameters

Syntax analysis

Graph peak analysis

These parameters control histogram peak detection used for finding plate bands, plates, and characters. They should generally not need adjustment unless the source images have unusual characteristics.

Syntax configuration reference

Resources/syntax.xml defines known licence plate format templates per country. Each <type> is a named template (e.g. germany). Each <char> element defines the set of allowed characters at that position. During syntax analysis, the parser tries to match recognised text against these templates and corrects mismatches when possible.

Format templates

Character set notation

• a-z — alphabetic characters (uppercase or lowercase)
• 0-9 — numeric digits
• o — the letter O, often included in digit positions because O and 0 are visually similar and frequently confused by OCR
• 0 — the digit zero, often included in letter positions for the same reason

Adding a new format

To add a custom plate format, add a <type> element inside <structure>:

<type name="uk">
    <char content="abcdefghijklmnopqrstuvwxyz"/>
    <char content="0123456789"/>
    <char content="0123456789"/>
    <char content="abcdefghijklmnopqrstuvwxyz"/>
    <char content="abcdefghijklmnopqrstuvwxyz"/>
    <char content="abcdefghijklmnopqrstuvwxyz"/>
</type>

Each <char> element represents one position in the plate. The content attribute lists all characters allowed at that position.

Development

Solution layout

src/
├── dotnetANPR/           # Core library (netstandard2.0)
│   ├── AnprEngine.cs     # Public entry point
│   ├── Configuration/    # XML config loader
│   ├── ImageAnalysis/    # Plate/character segmentation
│   ├── Intelligence/     # Recognition orchestration & syntax parser
│   ├── NeuralNetwork/    # Feed-forward network implementation
│   ├── Recognizer/       # KNN and neural classifiers
│   └── Resources/        # config.xml, syntax.xml, neural networks
├── dotnetANPR.CLI/       # Sample command-line application (.NET 8)
└── dotnetANPR.Tests/     # Test project

Build and test

dotnet build ./src/dotnetANPR.slnx --configuration Release
dotnet test --solution ./src/dotnetANPR.slnx

CI runs on every push and pull request to master via GitHub Actions.

Contributing

1. Fork the repository and create a feature branch
2. Make your changes with focused commits
3. Run dotnet build and dotnet test locally
4. Open a pull request with a clear description of the change and how you tested it

Bug reports and feature requests can be filed via GitHub Issues. Include sample images (where possible), expected vs. actual output, and your configuration when reporting recognition problems.

Acknowledgements

• javaanpr by Ondrej Martinsky — original Java implementation and algorithm design
• SkiaSharp — cross-platform 2D graphics

License

MIT — see LICENSE.