init commit

.gitattributes

@@ -0,0 +1,11 @@
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.weights filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.xlsx filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.DS_Store
+venv/
+.env
+output/
+data/output/
+

README.md

@@ -0,0 +1,110 @@
+# Passport OCR Tool
+
+A robust tool to extract data from passport images (PNG, JPG) and PDFs using OCR. It extracts MRZ (Machine Readable Zone) data and exports it to Excel or CSV formats.
+
+## Features
+
+- **Multi-format Support**: Handles images (JPG, PNG) and PDFs.
+- **Batch Processing**: Process single files or entire directories.
+- **Data Export**: Save results to Excel (`.xlsx`) or CSV.
+- **Validation**: Basic validation of extracted fields.
+- **Web Interface**: User-friendly web app for easy demonstration.
+- **Local Processing**: Runs entirely on your local machine.
+
+## Prerequisites
+
+### 1. Python
+Ensure you have Python 3.7+ installed.
+
+### 2. System Dependencies (Poppler)
+This tool requires `poppler` for PDF processing.
+
+- **macOS** (using Homebrew):
+  ```bash
+  brew install poppler
+  ```
+
+- **Ubuntu/Debian**:
+  ```bash
+  sudo apt-get install poppler-utils
+  ```
+
+- **Windows**:
+  1. Download the latest binary from [@oschwartz10612 version](https://github.com/oschwartz10612/poppler-windows/releases/).
+  2. Extract the zip file.
+  3. Add the `bin/` folder to your System PATH environment variable.
+
+## Installation
+
+1. Clone the repository:
+   ```bash
+   git clone <repository-url>
+   cd passport-ocr-tool
+   ```
+
+2. Create a virtual environment (recommended):
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. Install Python dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Usage
+
+### 1. Web App (Recommended for Demos)
+Launch the easy-to-use web interface:
+
+```bash
+streamlit run app.py
+```
+This will open the tool in your default web browser (usually at `http://localhost:8501`). You can drag and drop files and download the results as Excel/CSV.
+
+### 2. Command Line Interface (CLI)
+
+Run the tool using `main.py`:
+
+```bash
+# Process a single image
+python main.py --input path/to/passport.jpg
+
+# Process a directory of images/PDFs
+python main.py --input path/to/folder --output my_results
+
+# Export to CSV
+python main.py --input path/to/folder --format csv
+```
+
+### Command Line Arguments
+
+- `--input`, `-i`: Path to input file or directory (Required).
+- `--output`, `-o`: Output filename (default: `passport_data`).
+- `--format`, `-f`: Output format: `excel` or `csv` (default: `excel`).
+- `--gpu`: Enable GPU acceleration for OCR (requires CUDA).
+
+## Project Structure
+
+```
+passport-ocr-tool/
+├── src/
+│   ├── extractor.py      # Core extraction logic
+│   ├── utils.py          # Helper functions
+│   ├── validators.py     # Data validation
+│   └── formats.py        # Export handlers
+├── config/
+│   └── settings.py       # Configuration
+├── app.py                # Streamlit Web App
+├── main.py               # CLI Entry point
+└── ...
+```
+
+## Troubleshooting
+
+- **PDF Error**: "Unable to get page count" or "poppler is not installed".
+  - Ensure `poppler` is installed and in your PATH.
+- **OCR Accuracy**:
+  - Ensure images are clear and high resolution.
+  - The MRZ zone (bottom lines) must be visible and unobstructed.

app.py

@@ -0,0 +1,150 @@
+import streamlit as st
+import os
+import tempfile
+import pandas as pd
+import time
+from src.extractor import PassportExtractor
+from src.validators import validate_passport_data
+
+# Set page configuration
+st.set_page_config(
+    page_title="Passport OCR Tool",
+    page_icon="🛂",
+    layout="wide"
+)
+
+# Initialize Extractor (cached to avoid reloading model)
+@st.cache_resource
+def get_extractor():
+    return PassportExtractor(use_gpu=False)
+
+extractor = get_extractor()
+
+def save_uploaded_file(uploaded_file):
+    """Save uploaded file to a temporary location and return the path."""
+    try:
+        suffix = os.path.splitext(uploaded_file.name)[1]
+        with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp_file:
+            tmp_file.write(uploaded_file.getvalue())
+            return tmp_file.name
+    except Exception as e:
+        st.error(f"Error saving file: {e}")
+        return None
+
+def main():
+    st.title("🛂 Passport OCR Extractor")
+    st.markdown("""
+    Upload passport images (JPG, PNG) or PDFs to extract MRZ data automatically.
+    The tool extracts details like Name, Surname, Passport Number, and Date of Birth.
+    """)
+
+    # Sidebar for configuration
+    st.sidebar.header("Configuration")
+    enable_validation = st.sidebar.checkbox("Enable Data Validation", value=True)
+    
+    # File Uploader
+    uploaded_files = st.file_uploader(
+        "Choose passport files", 
+        type=['png', 'jpg', 'jpeg', 'pdf'], 
+        accept_multiple_files=True
+    )
+
+    if uploaded_files:
+        st.info(f"Loaded {len(uploaded_files)} files. Click 'Process Files' to start.")
+        
+        if st.button("Process Files"):
+            results = []
+            progress_bar = st.progress(0)
+            status_text = st.empty()
+            
+            for idx, uploaded_file in enumerate(uploaded_files):
+                status_text.text(f"Processing {uploaded_file.name}...")
+                
+                # Save to temp file because extractor needs a path
+                temp_path = save_uploaded_file(uploaded_file)
+                
+                if temp_path:
+                    try:
+                        ext = os.path.splitext(temp_path)[1].lower()
+                        file_results = []
+                        
+                        if ext == '.pdf':
+                            file_results = extractor.process_pdf(temp_path)
+                        else:
+                            data = extractor.get_data(temp_path)
+                            if data:
+                                file_results = [data]
+                        
+                        # Add validation if enabled
+                        if enable_validation:
+                            for res in file_results:
+                                errors = validate_passport_data(res)
+                                res['validation_errors'] = "; ".join(errors) if errors else "Valid"
+                        
+                        # Add original filename for reference (since we used a temp file)
+                        for res in file_results:
+                            res['original_filename'] = uploaded_file.name
+                            
+                        results.extend(file_results)
+                        
+                    except Exception as e:
+                        st.error(f"Failed to process {uploaded_file.name}: {e}")
+                    finally:
+                        # Cleanup temp file
+                        if os.path.exists(temp_path):
+                            os.remove(temp_path)
+                
+                # Update progress
+                progress_bar.progress((idx + 1) / len(uploaded_files))
+            
+            status_text.text("Processing complete!")
+            
+            if results:
+                st.success(f"Successfully extracted {len(results)} records.")
+                
+                # Create DataFrame
+                df = pd.DataFrame(results)
+                
+                # Reorder columns for better readability if possible
+                cols = ['surname', 'name', 'passport_number', 'nationality', 'date_of_birth', 'sex', 'expiration_date', 'validation_errors', 'original_filename']
+                # Add missing cols to list if they exist in df
+                all_cols = cols + [c for c in df.columns if c not in cols]
+                # Filter valid columns only
+                final_cols = [c for c in all_cols if c in df.columns]
+                
+                df = df[final_cols]
+                
+                # Display Data
+                st.dataframe(df)
+                
+                # Download Buttons
+                col1, col2 = st.columns(2)
+                
+                # CSV Download
+                csv = df.to_csv(index=False).encode('utf-8')
+                col1.download_button(
+                    label="Download CSV",
+                    data=csv,
+                    file_name="passport_data.csv",
+                    mime="text/csv",
+                )
+                
+                # Excel Download (requires openpyxl)
+                # Streamlit might need a BytesIO buffer for Excel
+                import io
+                buffer = io.BytesIO()
+                with pd.ExcelWriter(buffer, engine='openpyxl') as writer:
+                    df.to_excel(writer, index=False, sheet_name='Sheet1')
+                
+                col2.download_button(
+                    label="Download Excel",
+                    data=buffer.getvalue(),
+                    file_name="passport_data.xlsx",
+                    mime="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                )
+                
+            else:
+                st.warning("No data extracted from the provided files.")
+
+if __name__ == "__main__":
+    main()

config/settings.py

@@ -0,0 +1,218 @@
+import os
+
+# Base directory
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# Input/Output directories
+INPUT_DIR = os.path.join(BASE_DIR, 'data', 'input')
+OUTPUT_DIR = os.path.join(BASE_DIR, 'data', 'output')
+TEMP_DIR = os.path.join(BASE_DIR, 'temp_processing')
+
+# Ensure directories exist
+os.makedirs(INPUT_DIR, exist_ok=True)
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+# Allowed file extensions
+ALLOWED_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.pdf'}
+
+# OCR Settings
+OCR_LANGUAGES = ['en']
+USE_GPU = False  # Set to True if you have CUDA installed
+
+# Country Codes (ISO 3166-1 alpha-3)
+# This is a subset. In a real production app, consider loading this from a standard library or full JSON file.
+COUNTRY_CODES = [
+    {"name": "Afghanistan", "alpha-3": "AFG"},
+    {"name": "Albania", "alpha-3": "ALB"},
+    {"name": "Algeria", "alpha-3": "DZA"},
+    {"name": "Andorra", "alpha-3": "AND"},
+    {"name": "Angola", "alpha-3": "AGO"},
+    {"name": "Argentina", "alpha-3": "ARG"},
+    {"name": "Armenia", "alpha-3": "ARM"},
+    {"name": "Australia", "alpha-3": "AUS"},
+    {"name": "Austria", "alpha-3": "AUT"},
+    {"name": "Azerbaijan", "alpha-3": "AZE"},
+    {"name": "Bahamas", "alpha-3": "BHS"},
+    {"name": "Bahrain", "alpha-3": "BHR"},
+    {"name": "Bangladesh", "alpha-3": "BGD"},
+    {"name": "Barbados", "alpha-3": "BRB"},
+    {"name": "Belarus", "alpha-3": "BLR"},
+    {"name": "Belgium", "alpha-3": "BEL"},
+    {"name": "Belize", "alpha-3": "BLZ"},
+    {"name": "Benin", "alpha-3": "BEN"},
+    {"name": "Bhutan", "alpha-3": "BTN"},
+    {"name": "Bolivia", "alpha-3": "BOL"},
+    {"name": "Bosnia and Herzegovina", "alpha-3": "BIH"},
+    {"name": "Botswana", "alpha-3": "BWA"},
+    {"name": "Brazil", "alpha-3": "BRA"},
+    {"name": "Brunei Darussalam", "alpha-3": "BRN"},
+    {"name": "Bulgaria", "alpha-3": "BGR"},
+    {"name": "Burkina Faso", "alpha-3": "BFA"},
+    {"name": "Burundi", "alpha-3": "BDI"},
+    {"name": "Cabo Verde", "alpha-3": "CPV"},
+    {"name": "Cambodia", "alpha-3": "KHM"},
+    {"name": "Cameroon", "alpha-3": "CMR"},
+    {"name": "Canada", "alpha-3": "CAN"},
+    {"name": "Central African Republic", "alpha-3": "CAF"},
+    {"name": "Chad", "alpha-3": "TCD"},
+    {"name": "Chile", "alpha-3": "CHL"},
+    {"name": "China", "alpha-3": "CHN"},
+    {"name": "Colombia", "alpha-3": "COL"},
+    {"name": "Comoros", "alpha-3": "COM"},
+    {"name": "Congo", "alpha-3": "COG"},
+    {"name": "Congo (Democratic Republic of the)", "alpha-3": "COD"},
+    {"name": "Costa Rica", "alpha-3": "CRI"},
+    {"name": "Croatia", "alpha-3": "HRV"},
+    {"name": "Cuba", "alpha-3": "CUB"},
+    {"name": "Cyprus", "alpha-3": "CYP"},
+    {"name": "Czechia", "alpha-3": "CZE"},
+    {"name": "Denmark", "alpha-3": "DNK"},
+    {"name": "Djibouti", "alpha-3": "DJI"},
+    {"name": "Dominica", "alpha-3": "DMA"},
+    {"name": "Dominican Republic", "alpha-3": "DOM"},
+    {"name": "Ecuador", "alpha-3": "ECU"},
+    {"name": "Egypt", "alpha-3": "EGY"},
+    {"name": "El Salvador", "alpha-3": "SLV"},
+    {"name": "Equatorial Guinea", "alpha-3": "GNQ"},
+    {"name": "Eritrea", "alpha-3": "ERI"},
+    {"name": "Estonia", "alpha-3": "EST"},
+    {"name": "Eswatini", "alpha-3": "SWZ"},
+    {"name": "Ethiopia", "alpha-3": "ETH"},
+    {"name": "Fiji", "alpha-3": "FJI"},
+    {"name": "Finland", "alpha-3": "FIN"},
+    {"name": "France", "alpha-3": "FRA"},
+    {"name": "Gabon", "alpha-3": "GAB"},
+    {"name": "Gambia", "alpha-3": "GMB"},
+    {"name": "Georgia", "alpha-3": "GEO"},
+    {"name": "Germany", "alpha-3": "DEU"},
+    {"name": "Ghana", "alpha-3": "GHA"},
+    {"name": "Greece", "alpha-3": "GRC"},
+    {"name": "Grenada", "alpha-3": "GRD"},
+    {"name": "Guatemala", "alpha-3": "GTM"},
+    {"name": "Guinea", "alpha-3": "GIN"},
+    {"name": "Guinea-Bissau", "alpha-3": "GNB"},
+    {"name": "Guyana", "alpha-3": "GUY"},
+    {"name": "Haiti", "alpha-3": "HTI"},
+    {"name": "Honduras", "alpha-3": "HND"},
+    {"name": "Hungary", "alpha-3": "HUN"},
+    {"name": "Iceland", "alpha-3": "ISL"},
+    {"name": "India", "alpha-3": "IND"},
+    {"name": "Indonesia", "alpha-3": "IDN"},
+    {"name": "Iran", "alpha-3": "IRN"},
+    {"name": "Iraq", "alpha-3": "IRQ"},
+    {"name": "Ireland", "alpha-3": "IRL"},
+    {"name": "Israel", "alpha-3": "ISR"},
+    {"name": "Italy", "alpha-3": "ITA"},
+    {"name": "Jamaica", "alpha-3": "JAM"},
+    {"name": "Japan", "alpha-3": "JPN"},
+    {"name": "Jordan", "alpha-3": "JOR"},
+    {"name": "Kazakhstan", "alpha-3": "KAZ"},
+    {"name": "Kenya", "alpha-3": "KEN"},
+    {"name": "Kiribati", "alpha-3": "KIR"},
+    {"name": "Korea (North)", "alpha-3": "PRK"},
+    {"name": "Korea (South)", "alpha-3": "KOR"},
+    {"name": "Kuwait", "alpha-3": "KWT"},
+    {"name": "Kyrgyzstan", "alpha-3": "KGZ"},
+    {"name": "Laos", "alpha-3": "LAO"},
+    {"name": "Latvia", "alpha-3": "LVA"},
+    {"name": "Lebanon", "alpha-3": "LBN"},
+    {"name": "Lesotho", "alpha-3": "LSO"},
+    {"name": "Liberia", "alpha-3": "LBR"},
+    {"name": "Libya", "alpha-3": "LBY"},
+    {"name": "Liechtenstein", "alpha-3": "LIE"},
+    {"name": "Lithuania", "alpha-3": "LTU"},
+    {"name": "Luxembourg", "alpha-3": "LUX"},
+    {"name": "Madagascar", "alpha-3": "MDG"},
+    {"name": "Malawi", "alpha-3": "MWI"},
+    {"name": "Malaysia", "alpha-3": "MYS"},
+    {"name": "Maldives", "alpha-3": "MDV"},
+    {"name": "Mali", "alpha-3": "MLI"},
+    {"name": "Malta", "alpha-3": "MLT"},
+    {"name": "Marshall Islands", "alpha-3": "MHL"},
+    {"name": "Mauritania", "alpha-3": "MRT"},
+    {"name": "Mauritius", "alpha-3": "MUS"},
+    {"name": "Mexico", "alpha-3": "MEX"},
+    {"name": "Micronesia", "alpha-3": "FSM"},
+    {"name": "Moldova", "alpha-3": "MDA"},
+    {"name": "Monaco", "alpha-3": "MCO"},
+    {"name": "Mongolia", "alpha-3": "MNG"},
+    {"name": "Montenegro", "alpha-3": "MNE"},
+    {"name": "Morocco", "alpha-3": "MAR"},
+    {"name": "Mozambique", "alpha-3": "MOZ"},
+    {"name": "Myanmar", "alpha-3": "MMR"},
+    {"name": "Namibia", "alpha-3": "NAM"},
+    {"name": "Nauru", "alpha-3": "NRU"},
+    {"name": "Nepal", "alpha-3": "NPL"},
+    {"name": "Netherlands", "alpha-3": "NLD"},
+    {"name": "New Zealand", "alpha-3": "NZL"},
+    {"name": "Nicaragua", "alpha-3": "NIC"},
+    {"name": "Niger", "alpha-3": "NER"},
+    {"name": "Nigeria", "alpha-3": "NGA"},
+    {"name": "North Macedonia", "alpha-3": "MKD"},
+    {"name": "Norway", "alpha-3": "NOR"},
+    {"name": "Oman", "alpha-3": "OMN"},
+    {"name": "Pakistan", "alpha-3": "PAK"},
+    {"name": "Palau", "alpha-3": "PLW"},
+    {"name": "Panama", "alpha-3": "PAN"},
+    {"name": "Papua New Guinea", "alpha-3": "PNG"},
+    {"name": "Paraguay", "alpha-3": "PRY"},
+    {"name": "Peru", "alpha-3": "PER"},
+    {"name": "Philippines", "alpha-3": "PHL"},
+    {"name": "Poland", "alpha-3": "POL"},
+    {"name": "Portugal", "alpha-3": "PRT"},
+    {"name": "Qatar", "alpha-3": "QAT"},
+    {"name": "Romania", "alpha-3": "ROU"},
+    {"name": "Russia", "alpha-3": "RUS"},
+    {"name": "Rwanda", "alpha-3": "RWA"},
+    {"name": "Saint Kitts and Nevis", "alpha-3": "KNA"},
+    {"name": "Saint Lucia", "alpha-3": "LCA"},
+    {"name": "Saint Vincent and the Grenadines", "alpha-3": "VCT"},
+    {"name": "Samoa", "alpha-3": "WSM"},
+    {"name": "San Marino", "alpha-3": "SMR"},
+    {"name": "Sao Tome and Principe", "alpha-3": "STP"},
+    {"name": "Saudi Arabia", "alpha-3": "SAU"},
+    {"name": "Senegal", "alpha-3": "SEN"},
+    {"name": "Serbia", "alpha-3": "SRB"},
+    {"name": "Seychelles", "alpha-3": "SYC"},
+    {"name": "Sierra Leone", "alpha-3": "SLE"},
+    {"name": "Singapore", "alpha-3": "SGP"},
+    {"name": "Slovakia", "alpha-3": "SVK"},
+    {"name": "Slovenia", "alpha-3": "SVN"},
+    {"name": "Solomon Islands", "alpha-3": "SLB"},
+    {"name": "Somalia", "alpha-3": "SOM"},
+    {"name": "South Africa", "alpha-3": "ZAF"},
+    {"name": "South Sudan", "alpha-3": "SSD"},
+    {"name": "Spain", "alpha-3": "ESP"},
+    {"name": "Sri Lanka", "alpha-3": "LKA"},
+    {"name": "Sudan", "alpha-3": "SDN"},
+    {"name": "Suriname", "alpha-3": "SUR"},
+    {"name": "Sweden", "alpha-3": "SWE"},
+    {"name": "Switzerland", "alpha-3": "CHE"},
+    {"name": "Syria", "alpha-3": "SYR"},
+    {"name": "Taiwan", "alpha-3": "TWN"},
+    {"name": "Tajikistan", "alpha-3": "TJK"},
+    {"name": "Tanzania", "alpha-3": "TZA"},
+    {"name": "Thailand", "alpha-3": "THA"},
+    {"name": "Timor-Leste", "alpha-3": "TLS"},
+    {"name": "Togo", "alpha-3": "TGO"},
+    {"name": "Tonga", "alpha-3": "TON"},
+    {"name": "Trinidad and Tobago", "alpha-3": "TTO"},
+    {"name": "Tunisia", "alpha-3": "TUN"},
+    {"name": "Turkey", "alpha-3": "TUR"},
+    {"name": "Turkmenistan", "alpha-3": "TKM"},
+    {"name": "Tuvalu", "alpha-3": "TUV"},
+    {"name": "Uganda", "alpha-3": "UGA"},
+    {"name": "Ukraine", "alpha-3": "UKR"},
+    {"name": "United Arab Emirates", "alpha-3": "ARE"},
+    {"name": "United Kingdom", "alpha-3": "GBR"},
+    {"name": "United States of America", "alpha-3": "USA"},
+    {"name": "Uruguay", "alpha-3": "URY"},
+    {"name": "Uzbekistan", "alpha-3": "UZB"},
+    {"name": "Vanuatu", "alpha-3": "VUT"},
+    {"name": "Vatican City", "alpha-3": "VAT"},
+    {"name": "Venezuela", "alpha-3": "VEN"},
+    {"name": "Vietnam", "alpha-3": "VNM"},
+    {"name": "Yemen", "alpha-3": "YEM"},
+    {"name": "Zambia", "alpha-3": "ZMB"},
+    {"name": "Zimbabwe", "alpha-3": "ZWE"}
+]

main.py

@@ -0,0 +1,98 @@
+import argparse
+import os
+import sys
+from tqdm import tqdm
+from src.extractor import PassportExtractor
+from src.formats import export_to_spreadsheet
+from src.validators import validate_passport_data
+from src.utils import setup_logger
+from config.settings import ALLOWED_EXTENSIONS
+
+# Setup Logger
+logger = setup_logger()
+
+def is_valid_file(filename):
+    ext = os.path.splitext(filename)[1].lower()
+    return ext in ALLOWED_EXTENSIONS
+
+def main():
+    parser = argparse.ArgumentParser(description="Passport OCR Tool - Extract data from passport images/PDFs.")
+    parser.add_argument('--input', '-i', required=True, help="Path to input file or directory")
+    parser.add_argument('--output', '-o', default='passport_data', help="Output filename (without extension)")
+    parser.add_argument('--format', '-f', choices=['excel', 'csv'], default='excel', help="Output format (excel or csv)")
+    parser.add_argument('--gpu', action='store_true', help="Use GPU for OCR")
+    
+    args = parser.parse_args()
+    
+    input_path = os.path.abspath(args.input)
+    output_path = os.path.abspath(os.path.join('data', 'output', args.output)) # Default to data/output if relative
+    
+    # Adjust output path if user provided a specific path
+    if os.path.dirname(args.output):
+        output_path = os.path.abspath(args.output)
+
+    if not os.path.exists(input_path):
+        logger.error(f"Input path does not exist: {input_path}")
+        sys.exit(1)
+
+    files_to_process = []
+    if os.path.isfile(input_path):
+        if is_valid_file(input_path):
+            files_to_process.append(input_path)
+        else:
+            logger.error(f"Unsupported file format: {input_path}")
+            sys.exit(1)
+    else:
+        for root, _, files in os.walk(input_path):
+            for file in files:
+                if is_valid_file(file):
+                    files_to_process.append(os.path.join(root, file))
+
+    if not files_to_process:
+        logger.warning("No valid files found to process.")
+        sys.exit(0)
+
+    logger.info(f"Found {len(files_to_process)} files to process.")
+
+    # Initialize Extractor
+    extractor = PassportExtractor(use_gpu=args.gpu)
+    
+    extracted_results = []
+    
+    # Process files
+    for file_path in tqdm(files_to_process, desc="Processing files"):
+        ext = os.path.splitext(file_path)[1].lower()
+        
+        try:
+            if ext == '.pdf':
+                results = extractor.process_pdf(file_path)
+                extracted_results.extend(results)
+            else:
+                result = extractor.get_data(file_path)
+                if result:
+                    extracted_results.append(result)
+        except Exception as e:
+            logger.error(f"Failed to process {file_path}: {e}")
+
+    # Validate and Summarize
+    valid_count = 0
+    for res in extracted_results:
+        errors = validate_passport_data(res)
+        if not errors:
+            valid_count += 1
+        else:
+            res['validation_errors'] = "; ".join(errors)
+            # logger.warning(f"Validation issues for {res.get('source_file')}: {errors}")
+
+    logger.info(f"Processing complete. Extracted {len(extracted_results)} records ({valid_count} valid).")
+
+    # Export
+    if extracted_results:
+        success = export_to_spreadsheet(extracted_results, output_path, format=args.format)
+        if success:
+            logger.info(f"Successfully saved data to {output_path}.{args.format if not output_path.endswith(args.format) else ''}")
+    else:
+        logger.warning("No data extracted.")
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,14 @@
+passporteye>=2.1.0
+easyocr>=1.6.0
+matplotlib>=3.5.0
+opencv-python>=4.5.0
+python-dateutil>=2.8.0
+pdf2image>=1.16.0
+pandas>=1.3.0
+openpyxl>=3.0.0
+tqdm>=4.60.0
+Pillow>=9.0.0
+numpy>=1.21.0
+streamlit>=1.25.0
+watchdog>=3.0.0
+pyngrok

setup.py

@@ -0,0 +1,28 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="passport-ocr-tool",
+    version="1.0.0",
+    description="A tool to extract data from passports (Images/PDFs) and export to Excel/CSV.",
+    author="Your Name",
+    packages=find_packages(),
+    install_requires=[
+        'passporteye',
+        'easyocr',
+        'matplotlib',
+        'opencv-python',
+        'python-dateutil',
+        'pdf2image',
+        'pandas',
+        'openpyxl',
+        'tqdm',
+        'Pillow',
+        'numpy'
+    ],
+    entry_points={
+        'console_scripts': [
+            'passport-ocr=main:main',
+        ],
+    },
+    python_requires='>=3.7',
+)

share_app.py

@@ -0,0 +1,37 @@
+import os
+import time
+import threading
+from pyngrok import ngrok
+
+def run_streamlit():
+    os.system("python3 -m streamlit run app.py")
+
+def start_ngrok():
+    print("Starting Streamlit app...")
+    # Give streamlit a moment to start
+    time.sleep(5)
+    
+    try:
+        # Open a HTTP tunnel on the default port 8501
+        public_url = ngrok.connect(8501).public_url
+        print("\n" + "="*60)
+        print(f"  \033[92m>>> YOUR LIVE LINK: {public_url} <<<\033[0m")
+        print("  Share this link with your client. The app must stay running.")
+        print("="*60 + "\n")
+        
+        # Keep the script running
+        input("Press Enter to exit...\n")
+    except Exception as e:
+        print(f"\nError starting ngrok: {e}")
+        print("\nNOTE: You may need a free ngrok account.")
+        print("1. Go to https://dashboard.ngrok.com/signup")
+        print("2. Get your Authtoken")
+        print("3. Run: ngrok config add-authtoken <your_token>")
+
+if __name__ == "__main__":
+    # Start Streamlit in a separate thread
+    thread = threading.Thread(target=run_streamlit)
+    thread.daemon = True
+    thread.start()
+
+    start_ngrok()

src/extractor.py

@@ -0,0 +1,185 @@
+import os
+import cv2
+import numpy as np
+import easyocr
+import warnings
+import ssl
+from passporteye import read_mrz
+from pdf2image import convert_from_path
+from PIL import Image
+import string as st
+
+# Fix for SSL certificate errors on Mac when downloading EasyOCR models
+try:
+    _create_unverified_https_context = ssl._create_unverified_context
+except AttributeError:
+    pass
+else:
+    ssl._create_default_https_context = _create_unverified_https_context
+
+from src.utils import (
+    clean_string, 
+    clean_mrz_line, 
+    parse_date, 
+    get_country_name, 
+    get_sex, 
+    setup_logger
+)
+from config.settings import USE_GPU, OCR_LANGUAGES, TEMP_DIR
+
+# Suppress warnings
+warnings.filterwarnings('ignore')
+
+logger = setup_logger(__name__)
+
+class PassportExtractor:
+    def __init__(self, use_gpu=USE_GPU, languages=None):
+        self.languages = languages if languages else OCR_LANGUAGES
+        
+        # Set model storage directory to project/data/models to avoid permission issues
+        base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        model_dir = os.path.join(base_dir, 'data', 'models')
+        os.makedirs(model_dir, exist_ok=True)
+        
+        logger.info(f"Initializing EasyOCR Reader (GPU={use_gpu})...")
+        self.reader = easyocr.Reader(self.languages, gpu=use_gpu, model_storage_directory=model_dir)
+        logger.info("EasyOCR Reader initialized.")
+
+    def extract_mrz_from_roi(self, img_path):
+        """
+        Extracts MRZ lines using PassportEye to find ROI, then EasyOCR to read text.
+        Returns (line1, line2, mrz_object).
+        """
+        try:
+            # Analyze image with PassportEye
+            mrz = read_mrz(img_path, save_roi=True)
+            
+            if not mrz:
+                logger.warning(f"PassportEye failed to detect MRZ in {img_path}")
+                return None, None, None
+
+            # Get ROI (Region of Interest)
+            roi = mrz.aux['roi']
+            
+            # Ensure ROI is uint8 for OpenCV
+            if roi.dtype != np.uint8:
+                if roi.max() <= 1.0:
+                    roi = (roi * 255).astype(np.uint8)
+                else:
+                    roi = roi.astype(np.uint8)
+
+            # Preprocess ROI for EasyOCR
+            # Original code: saved to tmp.png (gray), read back, resized to (1110, 140)
+            # We will try to do this in memory using OpenCV
+            
+            # roi is likely a numpy array (H, W) or (H, W, C). PassportEye usually returns grayscale for ROI?
+            # Let's normalize to BGR for OpenCV consistency if needed, or keep grayscale.
+            
+            # Resize to improve OCR accuracy as per original code logic
+            # Note: (1110, 140) is the target size (Width, Height)
+            img_resized = cv2.resize(roi, (1110, 140))
+            
+            # Define allowed characters for MRZ
+            allow = st.ascii_letters + st.digits + "< "
+            
+            # Run EasyOCR
+            code = self.reader.readtext(img_resized, detail=0, allowlist=allow)
+
+            if len(code) < 2:
+                logger.warning(f"EasyOCR found fewer than 2 lines in ROI for {img_path}")
+                return None, None, mrz
+
+            line1 = clean_mrz_line(code[0])
+            line2 = clean_mrz_line(code[1])
+
+            # Correct sex at index 20 of line 2 if available from mrz object
+            # MRZ object might have parsed it correctly even if EasyOCR missed it
+            if mrz.sex and len(line2) > 20:
+                l2_list = list(line2)
+                l2_list[20] = mrz.sex
+                line2 = "".join(l2_list)
+
+            return line1, line2, mrz
+
+        except Exception as e:
+            logger.error(f"Error in extract_mrz_from_roi: {e}")
+            return None, None, None
+
+    def get_data(self, img_path):
+        """
+        Extracts full passport data from an image file.
+        Returns a dictionary of extracted fields.
+        """
+        if not os.path.exists(img_path):
+            logger.error(f"File not found: {img_path}")
+            return None
+
+        line1, line2, mrz = self.extract_mrz_from_roi(img_path)
+
+        if mrz is None:
+            return None
+
+        data = {}
+        # Use PassportEye's parsing where possible, fallback/clean as needed
+        data['surname'] = mrz.surname.replace("<<", " ").strip().upper() if mrz.surname else ""
+        data['name'] = mrz.names.replace("<<", " ").strip().upper() if mrz.names else ""
+        data['sex'] = get_sex(mrz.sex)
+        data['date_of_birth'] = parse_date(mrz.date_of_birth) if mrz.date_of_birth else ""
+        data['nationality'] = get_country_name(mrz.nationality)
+        data['passport_type'] = clean_string(mrz.type)
+        data['passport_number'] = clean_string(mrz.number)
+        data['issuing_country'] = get_country_name(mrz.country)
+        data['expiration_date'] = parse_date(mrz.expiration_date)
+        data['personal_number'] = clean_string(mrz.personal_number)
+        
+        # Construct full MRZ string
+        # Prefer the OCR'd lines if they exist, otherwise fallback?
+        # The original code returned (line1 or "") + (line2 or "")
+        data['mrz_full_string'] = (line1 or "") + (line2 or "")
+        data['source_file'] = os.path.basename(img_path)
+
+        return data
+
+    def process_pdf(self, pdf_path):
+        """
+        Converts PDF pages to images and extracts data from each.
+        Returns a list of data dictionaries.
+        """
+        extracted_data = []
+        
+        # Ensure temp dir exists
+        os.makedirs(TEMP_DIR, exist_ok=True)
+        
+        logger.info(f"Processing PDF: {pdf_path}")
+        try:
+            pages = convert_from_path(pdf_path)
+        except Exception as e:
+            logger.error(f"Failed to convert PDF {pdf_path}: {e}")
+            return []
+
+        for i, page in enumerate(pages):
+            temp_img_path = os.path.join(TEMP_DIR, f"temp_page_{i+1}.png")
+            page.save(temp_img_path, "PNG")
+            
+            logger.info(f"Processing page {i+1}...")
+            result = self.get_data(temp_img_path)
+            
+            # Special MRZ fix for PDF from original code
+            # It seems to re-clean the combined string.
+            if result and result.get("mrz_full_string"):
+                full_mrz = result["mrz_full_string"]
+                if len(full_mrz) >= 88: # 44 * 2
+                    l1 = full_mrz[:44]
+                    l2 = full_mrz[44:]
+                    l1 = clean_mrz_line(l1)
+                    l2 = clean_mrz_line(l2)
+                    result["mrz_full_string"] = l1 + l2
+            
+            if result:
+                extracted_data.append(result)
+            
+            # Cleanup temp file
+            if os.path.exists(temp_img_path):
+                os.remove(temp_img_path)
+
+        return extracted_data

src/formats.py

@@ -0,0 +1,41 @@
+import pandas as pd
+import os
+import logging
+
+logger = logging.getLogger(__name__)
+
+def export_to_spreadsheet(data_list, output_file, format='excel'):
+    """
+    Exports a list of dictionaries to a spreadsheet (Excel or CSV).
+    """
+    if not data_list:
+        logger.warning("No data to export.")
+        return False
+
+    try:
+        df = pd.DataFrame(data_list)
+        
+        # Ensure output directory exists
+        os.makedirs(os.path.dirname(output_file), exist_ok=True)
+
+        if format.lower() == 'excel' or output_file.endswith('.xlsx'):
+            if not output_file.endswith('.xlsx'):
+                output_file += '.xlsx'
+            df.to_excel(output_file, index=False)
+            logger.info(f"Data exported to {output_file}")
+            
+        elif format.lower() == 'csv' or output_file.endswith('.csv'):
+            if not output_file.endswith('.csv'):
+                output_file += '.csv'
+            df.to_csv(output_file, index=False)
+            logger.info(f"Data exported to {output_file}")
+            
+        else:
+            logger.error(f"Unsupported format: {format}")
+            return False
+            
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to export data: {e}")
+        return False

src/utils.py

@@ -0,0 +1,72 @@
+import string as st
+from dateutil import parser
+import logging
+import sys
+from config.settings import COUNTRY_CODES
+
+def setup_logger(name=__name__):
+    """Sets up a logger with standard formatting."""
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger
+
+logger = setup_logger(__name__)
+
+def parse_date(date_obj, iob=True):
+    """Parses a date object or string into DD/MM/YYYY format."""
+    try:
+        date_str = date_obj.isoformat() if hasattr(date_obj, 'isoformat') else str(date_obj)
+        # Passport dates are often YYMMDD, but dateutil usually handles it if formatted correctly.
+        # However, MRZ dates are tricky. PassportEye usually returns YYMMDD.
+        # parser.parse might struggle with 2-digit years without context, but let's trust existing logic first.
+        date = parser.parse(date_str, yearfirst=True).date()
+        return date.strftime('%d/%m/%Y')
+    except (ValueError, TypeError) as e:
+        logger.debug(f"Date parsing failed for {date_obj}: {e}")
+        return str(date_obj)
+
+def clean_string(text):
+    """Removes non-alphanumeric characters and converts to uppercase."""
+    if not text:
+        return ""
+    return ''.join(i for i in text if i.isalnum()).upper()
+
+def clean_mrz_line(line: str) -> str:
+    """Fix bad spacing or bad OCR for MRZ lines."""
+    if not line:
+        return ""
+    
+    line = line.upper().replace(" ", "")
+    
+    # Remove accidental characters except allowed
+    allowed = set(st.ascii_uppercase + st.digits + "<")
+    line = "".join([c for c in line if c in allowed])
+
+    # Ensure 44 length (standard TD3 MRZ length)
+    # Note: TD1/TD2 might be different lengths (30 or 36), but this logic enforces 44.
+    # We will keep existing logic for consistency but be aware of other formats.
+    if len(line) < 44:
+        line += "<" * (44 - len(line))
+    return line[:44]
+
+def get_country_name(country_code):
+    """Resolves 3-letter country code to full name."""
+    country_code = str(country_code).upper()
+    for c in COUNTRY_CODES:
+        if c['alpha-3'] == country_code:
+            return c['name'].upper()
+    return country_code
+
+def get_sex(code):
+    """Standardizes sex code."""
+    code = str(code).upper() if code else ''
+    if code in ['M', 'F']:
+        return code
+    if code == '0':
+        return 'M' # Fallback based on existing logic
+    return code

src/validators.py

@@ -0,0 +1,34 @@
+import datetime
+
+def validate_passport_data(data):
+    """
+    Validates extracted passport data.
+    Returns a list of validation warnings/errors.
+    """
+    errors = []
+    
+    if not data:
+        return ["No data to validate"]
+
+    # Check required fields
+    required_fields = ['surname', 'name', 'passport_number', 'nationality']
+    for field in required_fields:
+        if not data.get(field):
+            errors.append(f"Missing required field: {field}")
+
+    # Validate dates (basic check if they look like DD/MM/YYYY)
+    date_fields = ['date_of_birth', 'expiration_date']
+    for field in date_fields:
+        val = data.get(field)
+        if val:
+            try:
+                datetime.datetime.strptime(val, '%d/%m/%Y')
+            except ValueError:
+                errors.append(f"Invalid date format for {field}: {val} (expected DD/MM/YYYY)")
+
+    # Validate MRZ length roughly (should be around 88 chars for TD3)
+    mrz = data.get('mrz_full_string', '')
+    if len(mrz) < 80:
+        errors.append(f"MRZ string seems too short ({len(mrz)} chars)")
+
+    return errors

tests/test_extractor.py

@@ -0,0 +1,20 @@
+import unittest
+import os
+from src.extractor import PassportExtractor
+
+class TestPassportExtractor(unittest.TestCase):
+    def test_initialization(self):
+        """Test if the extractor can be initialized."""
+        try:
+            extractor = PassportExtractor(use_gpu=False)
+            self.assertIsNotNone(extractor.reader)
+        except Exception as e:
+            self.fail(f"Initialization failed: {e}")
+
+    def test_utils_import(self):
+        """Test if utils can be imported correctly."""
+        from src.utils import clean_string
+        self.assertEqual(clean_string("Hello 123!"), "HELLO123")
+
+if __name__ == '__main__':
+    unittest.main()