Skip to content

Commit 9923246

Browse files
yushulxyushulx
committed
Added MRZ scanner
1 parent f0c609b commit 9923246

9 files changed

Lines changed: 1502 additions & 0 deletions

File tree

‎examples/mrz-scanner/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# LiteCam MRZ Scanner
2+
3+
A desktop MRZ (Machine-Readable Zone) scanner built with Java, LiteCam, and the [Dynamsoft Capture Vision SDK](https://www.dynamsoft.com/capture-vision/docs/server/programming/java/). Detects and parses MRZ data from passports and travel documents in real time via camera or from image files.
4+
5+
---
6+
7+
## Features
8+
9+
- **Camera mode** — continuous, low-latency MRZ detection from a live camera feed (~30 FPS)
10+
- **File mode** — load images via file picker or drag-and-drop
11+
- **Parsed MRZ fields** — document type, ID / passport number, surname, given names, nationality, issuing state, date of birth, date of expiry, sex
12+
- **Visual overlay** — green polygon drawn around the detected MRZ zone (when location data is available), plus an on-screen banner showing the document type and ID
13+
- **Supported document types** — ICAO TD3 passports (`MRTD_TD3_PASSPORT`), TD1/TD2 IDs, and other ICAO-compliant travel documents
14+
15+
---
16+
17+
18+
## Dynamsoft License
19+
20+
The application requires a Dynamsoft license key.
21+
22+
The default key in `MRZScanner.java` is a **public trial key** that requires an active internet connection. For offline use or production deployment, obtain a dedicated key from the [Dynamsoft Customer Portal](https://www.dynamsoft.com/customer/license/trialLicense/?product=dcv&package=cross-platform).
23+
24+
Replace the key in `main()`:
25+
26+
```java
27+
LicenseManager.initLicense("YOUR_LICENSE_KEY_HERE");
28+
```
29+
30+
---
31+
32+
## Build
33+
34+
```bash
35+
# Windows
36+
.\build.ps1
37+
38+
# Linux / macOS
39+
./build.sh
40+
```
41+
42+
This installs the local LiteCam JAR, downloads all Maven dependencies, and produces a fat JAR at:
43+
44+
```
45+
target/litecam-mrz-scanner-1.0.0.jar
46+
```
47+
48+
---
49+
50+
## Run
51+
52+
```bash
53+
# Windows (camera mode — default)
54+
.\run.ps1
55+
56+
# Windows (file mode — no camera required)
57+
.\run.ps1 --file
58+
59+
# Linux / macOS (camera mode)
60+
./run.sh
61+
62+
# Linux / macOS (file mode)
63+
./run.sh --file
64+
```
65+
66+
Or run the fat JAR directly:
67+
68+
```bash
69+
java -jar target/litecam-mrz-scanner-1.0.0.jar
70+
java -jar target/litecam-mrz-scanner-1.0.0.jar --file
71+
```
72+
73+
---
74+
75+
## Usage
76+
77+
### Camera Mode (default)
78+
79+
1. Launch the application. The camera feed appears on the left panel.
80+
2. Hold a passport or travel document in front of the camera with the MRZ strip visible.
81+
3. Detected MRZ fields appear automatically in the **MRZ Results** panel on the right.
82+
4. Use **Switch to File Mode** to switch modes without restarting.
83+
84+
### File Mode
85+
86+
1. Launch with `--file`, or click **Switch to File Mode** while running.
87+
2. Click **Load Image File** or drag and drop an image onto the display area.
88+
3. Supported formats: JPEG, PNG, BMP, TIFF.
89+
4. Parsed fields are displayed immediately in the **MRZ Results** panel.
90+
91+
---
92+
93+
## Supported Document Types
94+
95+
| Code type | Description |
96+
|---|---|
97+
| `MRTD_TD3_PASSPORT` | ICAO TD3 passport (2-line, 44 characters per line) |
98+
| `MRTD_TD1_ID` | ICAO TD1 ID card (3-line) |
99+
| `MRTD_TD2_ID` | ICAO TD2 ID card (2-line) |
100+
101+
---

‎examples/mrz-scanner/build.ps1‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Build script for LiteCam Barcode Scanner Maven Example
2+
# PowerShell version
3+
4+
$ErrorActionPreference = "Stop"
5+
6+
# Define Maven executable path
7+
$MavenPath = "C:\ProgramData\chocolatey\lib\maven\apache-maven-3.9.11\bin\mvn.cmd"
8+
9+
Write-Host "Building LiteCam MRZ Scanner Maven Example..." -ForegroundColor Green
10+
Write-Host "=================================================" -ForegroundColor Green
11+
12+
# Check if Maven is available at the expected path
13+
if (-not (Test-Path $MavenPath)) {
14+
# Try to find Maven in PATH
15+
if (-not (Get-Command mvn -ErrorAction SilentlyContinue)) {
16+
Write-Host "Error: Maven is not installed or not found" -ForegroundColor Red
17+
Write-Host "Expected Maven location: $MavenPath" -ForegroundColor Red
18+
exit 1
19+
} else {
20+
$MavenPath = "mvn"
21+
}
22+
}
23+
24+
# Check if Java is installed
25+
if (-not (Get-Command java -ErrorAction SilentlyContinue)) {
26+
Write-Host "Error: Java is not installed or not in PATH" -ForegroundColor Red
27+
exit 1
28+
}
29+
30+
# Verify litecam.jar exists
31+
if (-not (Test-Path "libs\litecam.jar")) {
32+
Write-Host "Error: litecam.jar not found in libs\ directory" -ForegroundColor Red
33+
Write-Host "Please copy litecam.jar to libs\ directory first" -ForegroundColor Red
34+
exit 1
35+
}
36+
37+
Write-Host "`nJava version:" -ForegroundColor Yellow
38+
java -version
39+
40+
Write-Host "`nMaven version:" -ForegroundColor Yellow
41+
& $MavenPath -version
42+
43+
Write-Host "`nCleaning previous build..." -ForegroundColor Yellow
44+
& $MavenPath clean
45+
46+
Write-Host "`nCompiling project..." -ForegroundColor Yellow
47+
& $MavenPath compile
48+
49+
Write-Host "`nRunning tests..." -ForegroundColor Yellow
50+
& $MavenPath test
51+
52+
Write-Host "`nCreating fat JAR with dependencies..." -ForegroundColor Yellow
53+
& $MavenPath package
54+
55+
Write-Host "`nBuild completed successfully!" -ForegroundColor Green
56+
Write-Host ""
57+
Write-Host "To run the application:"
58+
Write-Host " Option 1: & `"$MavenPath`" exec:java -Dexec.mainClass=`"com.example.litecam.MRZScanner`""
59+
Write-Host " Option 2: java -jar target\litecam-mrz-scanner-1.0.0.jar"
60+
Write-Host ""
61+
62+
$jarPath = "target\litecam-mrz-scanner-1.0.0.jar"
63+
if (Test-Path $jarPath) {
64+
$jarSize = (Get-Item $jarPath).Length
65+
$jarSizeMB = [math]::Round($jarSize / 1MB, 2)
66+
Write-Host "JAR file created: $jarPath"
67+
Write-Host "JAR size: $jarSizeMB MB"
68+
} else {
69+
Write-Host "Warning: JAR file not found at expected location" -ForegroundColor Yellow
70+
}

‎examples/mrz-scanner/build.sh‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
#!/bin/bash
2+
# Build script for LiteCam Barcode Scanner Maven Example
3+
4+
set -e
5+
6+
echo "Building LiteCam Barcode Scanner Maven Example..."
7+
echo "================================================="
8+
9+
# Check if Maven is installed
10+
if ! command -v mvn &> /dev/null; then
11+
echo "Error: Maven is not installed or not in PATH"
12+
exit 1
13+
fi
14+
15+
# Check if Java is installed
16+
if ! command -v java &> /dev/null; then
17+
echo "Error: Java is not installed or not in PATH"
18+
exit 1
19+
fi
20+
21+
# Verify litecam.jar exists
22+
if [ ! -f "libs/litecam.jar" ]; then
23+
echo "Error: litecam.jar not found in libs/ directory"
24+
echo "Please copy litecam.jar to libs/ directory first"
25+
exit 1
26+
fi
27+
28+
echo "Java version:"
29+
java -version
30+
31+
echo ""
32+
echo "Maven version:"
33+
mvn -version
34+
35+
echo ""
36+
echo "Cleaning previous build..."
37+
mvn clean
38+
39+
echo ""
40+
echo "Compiling project..."
41+
mvn compile
42+
43+
echo ""
44+
echo "Running tests..."
45+
mvn test
46+
47+
echo ""
48+
echo "Creating fat JAR with dependencies..."
49+
mvn package
50+
51+
echo ""
52+
echo "Build completed successfully!"
53+
echo ""
54+
echo "To run the application:"
55+
echo " Option 1: mvn exec:java -Dexec.mainClass=\"com.example.litecam.BarcodeScanner\""
56+
echo " Option 2: java -jar target/litecam-barcode-scanner-1.0-SNAPSHOT-shaded.jar"
57+
echo ""
58+
echo "JAR file created: target/litecam-barcode-scanner-1.0-SNAPSHOT-shaded.jar"
59+
echo "JAR size: $(du -h target/litecam-barcode-scanner-1.0-SNAPSHOT-shaded.jar 2>/dev/null | cut -f1 || echo 'Unknown')"

‎examples/mrz-scanner/dependency-reduced-pom.xml‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
<groupId>com.example</groupId>
5+
<artifactId>litecam-mrz-scanner</artifactId>
6+
<name>LiteCam MRZ Scanner</name>
7+
<version>1.0.0</version>
8+
<description>A machine-readable zone (MRZ) scanner using LiteCam SDK and Dynamsoft Capture Vision</description>
9+
<build>
10+
<plugins>
11+
<plugin>
12+
<artifactId>maven-compiler-plugin</artifactId>
13+
<version>3.13.0</version>
14+
<configuration>
15+
<source>${java.version}</source>
16+
<target>${java.version}</target>
17+
<encoding>${project.build.sourceEncoding}</encoding>
18+
</configuration>
19+
</plugin>
20+
<plugin>
21+
<artifactId>maven-surefire-plugin</artifactId>
22+
<version>3.1.2</version>
23+
<configuration>
24+
<includes>
25+
<include>**/*Test.java</include>
26+
<include>**/*Tests.java</include>
27+
</includes>
28+
</configuration>
29+
</plugin>
30+
<plugin>
31+
<artifactId>maven-shade-plugin</artifactId>
32+
<version>3.5.0</version>
33+
<executions>
34+
<execution>
35+
<phase>package</phase>
36+
<goals>
37+
<goal>shade</goal>
38+
</goals>
39+
<configuration>
40+
<transformers>
41+
<transformer>
42+
<mainClass>com.example.litecam.MRZScanner</mainClass>
43+
</transformer>
44+
</transformers>
45+
<filters>
46+
<filter>
47+
<artifact>*:*</artifact>
48+
<excludes>
49+
<exclude>META-INF/*.SF</exclude>
50+
<exclude>META-INF/*.DSA</exclude>
51+
<exclude>META-INF/*.RSA</exclude>
52+
</excludes>
53+
</filter>
54+
</filters>
55+
<artifactSet>
56+
<includes>
57+
<include>*:*</include>
58+
</includes>
59+
</artifactSet>
60+
</configuration>
61+
</execution>
62+
</executions>
63+
</plugin>
64+
<plugin>
65+
<artifactId>maven-resources-plugin</artifactId>
66+
<version>3.3.1</version>
67+
<configuration>
68+
<encoding>${project.build.sourceEncoding}</encoding>
69+
</configuration>
70+
</plugin>
71+
<plugin>
72+
<artifactId>maven-install-plugin</artifactId>
73+
<version>3.1.1</version>
74+
<executions>
75+
<execution>
76+
<id>install-litecam</id>
77+
<phase>initialize</phase>
78+
<goals>
79+
<goal>install-file</goal>
80+
</goals>
81+
<configuration>
82+
<file>${project.basedir}/libs/litecam.jar</file>
83+
<groupId>com.example</groupId>
84+
<artifactId>litecam</artifactId>
85+
<version>1.0.0</version>
86+
<packaging>jar</packaging>
87+
</configuration>
88+
</execution>
89+
</executions>
90+
</plugin>
91+
</plugins>
92+
</build>
93+
<profiles>
94+
<profile>
95+
<id>dev</id>
96+
<properties>
97+
<log.level>DEBUG</log.level>
98+
</properties>
99+
</profile>
100+
<profile>
101+
<id>prod</id>
102+
<properties>
103+
<log.level>INFO</log.level>
104+
</properties>
105+
</profile>
106+
</profiles>
107+
<repositories>
108+
<repository>
109+
<id>central</id>
110+
<url>https://repo1.maven.org/maven2</url>
111+
</repository>
112+
<repository>
113+
<id>dcv</id>
114+
<url>https://download2.dynamsoft.com/maven/jar</url>
115+
</repository>
116+
</repositories>
117+
<dependencies>
118+
<dependency>
119+
<groupId>org.junit.jupiter</groupId>
120+
<artifactId>junit-jupiter</artifactId>
121+
<version>5.10.0</version>
122+
<scope>test</scope>
123+
<exclusions>
124+
<exclusion>
125+
<artifactId>junit-jupiter-api</artifactId>
126+
<groupId>org.junit.jupiter</groupId>
127+
</exclusion>
128+
<exclusion>
129+
<artifactId>junit-jupiter-params</artifactId>
130+
<groupId>org.junit.jupiter</groupId>
131+
</exclusion>
132+
<exclusion>
133+
<artifactId>junit-jupiter-engine</artifactId>
134+
<groupId>org.junit.jupiter</groupId>
135+
</exclusion>
136+
</exclusions>
137+
</dependency>
138+
</dependencies>
139+
<properties>
140+
<java.version>17</java.version>
141+
<maven.compiler.source>17</maven.compiler.source>
142+
<maven.compiler.target>17</maven.compiler.target>
143+
<slf4j.version>2.0.9</slf4j.version>
144+
<dynamsoft.dcv.version>3.4.1000</dynamsoft.dcv.version>
145+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
146+
<junit.version>5.10.0</junit.version>
147+
<logback.version>1.5.18</logback.version>
148+
</properties>
149+
</project>

‎examples/mrz-scanner/libs/litecam.jar‎

127 KB
Binary file not shown.

0 commit comments

Comments
 (0)