A fast, transparent vehicle damage inspection tool and collision repair cost estimator. Upload a photo of a damaged car panel, and ClaimScope detects scratches, dents, and paint abrasions using OpenCV, measures the damaged area, and generates an itemized repair appraisal based on standard collision repair rates.
No GPU required, no external API keys, and no black-box predictions.
ClaimScope is an open-source InsurTech tool designed to take the guesswork out of vehicle repair estimates after minor accidents. By analyzing photos of damaged car panels, it maps out scratches, dents, and surface abrasions, calculates physical damaged area in square centimeters, and generates an itemized repair cost breakdown based on audited US collision repair rates.
| Engineering Dimension | Implementation & Standard |
|---|---|
| Computer Vision Engine | 100% Classical OpenCV (Bilateral Filtering, Canny Calculus, CIE LAB Contrast) |
| Estimating Standard | US Industry Collision Standards (Mitchell / CCC ONE guidelines) |
| Execution Latency | Sub-85ms on everyday standard CPU (zero GPU servers needed) |
| Concurrency Model | Non-blocking CPU offloading via asyncio.to_thread |
| Caching & Deduplication | Cryptographic SHA-256 + 64-bit Perceptual Difference Hash (dHash) with exact parameter precision |
| Memory Protections | Memory-bounded chunked streaming (15MB max) and 4096px / 16MP decompression bomb defense |
| Regional Wage Indexing | Dynamic 5-digit US ZIP lookup across 5 metropolitan wage tiers |
| Quality Verification | 41 automated tests (pytest) + Ruff static analysis, formatting, and ground-truth benchmarks |
- Vehicle Owners: Get an immediate, realistic estimate before visiting a body shop or deciding whether to file an insurance claim.
- Insurance Adjusters & Appraisers: Quickly triage claims during First Notice of Loss (FNOL) with a preliminary, mathematically explainable damage assessment.
- Collision Repair Shops: Run quick preliminary audits and produce standardized, customer-facing appraisal sheets.
- Simplicity Over Complexity: Instead of deploying a heavy neural network that requires a GPU server and hundreds of megabytes of model weights, it uses reliable, classical computer vision (OpenCV).
- Deterministic & Auditable: Every dollar amount on the invoice connects back to measurable defect area, standardized body labor hours, paint refinish formulas, and OEM/aftermarket parts catalog pricing.
- Zero Overhead: Runs entirely in memory on any everyday CPU in less than 90 milliseconds, with zero API subscription costs.
For an executive overview of the project's background, problem statement, and solution design, see ABOUT.md.
If you have ever been in a minor car accident or scraped a bumper in a parking lot, you know how frustrating the repair process can be. You take photos, wait days for an insurance adjuster or body shop to get back to you, and when you finally receive an estimate, it is rarely clear how they calculated the numbers.
Most tech demos in this space try to solve this by immediately throwing a massive deep-learning model at the problem. But in the insurance and collision repair industry, explainability matters just as much as detection:
- If an adjuster marks a door panel for a $700 replacement instead of a $250 repair, they need to justify why (e.g. damage exceeds 28% of the surface area or involves structural tearing).
- If a customer asks how paint labor was estimated, the shop needs to point to standardized refinish formulas, not a neural network confidence score.
ClaimScope bridges that gap:
- It uses classical computer vision (edge detection, color space thresholding, and contour analysis) to find visible surface defects in under 90ms on standard CPUs.
- It feeds those measurements directly into an actuarial pricing engine based on standard US collision repair guidelines (Mitchell / CCC ONE), producing a transparent line-item invoice and downloadable PDF appraisal report.
┌─────────────────┐ ┌────────────────────────┐ ┌────────────────────────┐ ┌────────────────────────┐
│ Vehicle Photo │ ────> │ Pre-Flight Validation │ ────> │ OpenCV Vision Engine │ ────> │ Actuarial Cost Engine │
│ (JPEG / PNG) │ │ • Vehicle Panel Check │ │ • Canny Edge Calculus │ │ • Labor & Parts Rate │
└─────────────────┘ │ • Damage Presence │ │ • LAB Shadow Gradients│ │ • Repair vs. Replace │
│ • Reject Selfies/Docs │ │ • Contour Area (cm²) │ │ • Deductible Math │
└────────────────────────┘ └────────────────────────┘ └────────────────────────┘
│
▼
┌────────────────────────┐
│ Output & Appraisal │
│ • Visual Mask Studio │
│ • Itemized Claim Sheet│
│ • Official PDF Report │
└────────────────────────┘
Before processing an image, ClaimScope validates that the upload is a clear photo of a vehicle body panel with visible damage:
- Vehicle Panel Only: Verifies automotive paint continuity and chrominance consistency in LAB color space, blocking non-automotive images like domestic rooms, furniture, pets, or clothing.
- Damage Presence Check: Verifies that the photo actually contains detectable surface anomalies (scratches, dents, cracks, or paint chips). Completely undamaged cars or flat textures are caught upfront.
- Bumper Section Awareness: Specifically checks bumper properties (flexible molded polyurethane plastic vs. sheet metal) to ensure the photo matches the selected repair section.
- Smart Guardrails: Automatically blocks selfies, paper invoices, screenshots, extreme lighting (pitch black or blown out), and blurry photos before they can enter the appraisal pipeline.
- Paint-Aware Focus: Distinguishes between flat paper documents and glossy white car paint, ensuring clean white bumpers with damage are accepted seamlessly.
- Contrast Normalization: Applies Contrast-Limited Adaptive Histogram Equalization (CLAHE) on the L-channel in CIE LAB color space to reveal faint scrapes under harsh sunlight or shadows.
- Scratch Detection: Bilateral filtering smooths flat car paint while preserving sharp surface fractures. Directional Canny edge detection and morphological kernels connect broken scratch strokes into continuous lines.
- Dent & Deformity Detection: Uses localized gradient shading and color deviation to identify concave shadows and reflection shifts caused by dented metal or plastic.
- Metric Extraction:
cv2.findContoursmaps boundary polygons and computes calibrated surface area in square centimeters (cm²), assigning severity tiers (Minor, Moderate, Severe).
The pricing engine uses standardized US collision repair rules:
- The 28% Rule (Repair vs. Replace): If the damaged area covers 28% or more of the panel's total surface area (or if severe tearing is detected), the engine recommends a complete panel replacement. Otherwise, it recommends sheet metal repair and refinishing.
- Mitchell 50% Adjacent Panel Blend Rule: In real-world collision repairs, adjacent panels require a 50% clearcoat blend to prevent visible paint tone mismatch at panel seams.
- Regional Prevailing Wage Adjustment: Supports 5-digit US ZIP code lookup, adjusting body & paint labor rates according to local metropolitan prevailing wages (e.g., $91/hr in Pacific Metro CA/WA vs. $65/hr baseline).
- Material-Specific Tooling Multipliers: Applies specialized labor rate surcharges for structural aluminum panels (1.25x) and high-strength boron steel (1.15x).
- Glass Exception: Damaged windshields are always marked for replacement to comply with automotive safety standards.
- Itemized Costs: Calculates body repair labor, paint refinish spray hours, paint supplies ($38/hr), EPA hazardous waste disposal fees, and state sales tax on parts.
- Net Insurance Payout: Deducts the policyholder's deductible to show the exact expected insurance settlement.
- 🛡️ Vehicle & Damage Pre-Flight Guardrails: Ensures only authentic vehicle body panels with real damage can be uploaded. Blocks selfies, documents, blur, domestic clutter, and undamaged cars right at upload time.
- 📐 Mitchell / CCC ONE Actuarial Precision: Incorporates the 50% adjacent panel clearcoat blend rule, regional prevailing wage ZIP lookup, and aluminum/steel material multipliers.
- ⚡ High-Concurrency Backend Performance: All heavy OpenCV and PDF operations are non-blocking via
asyncio.to_thread(), keeping the FastAPI event loop instantly responsive. - 🚀 Sub-Millisecond Perceptual Caching: Computes a 64-bit difference hash (dHash) on upload; duplicate or near-identical photos return cached appraisal reports in < 2ms.
- 🎯 100% Explainable: Every dollar on the estimate links to measurable contour coordinates, calibrated surface area, and standardized hourly rates.
- 🖥️ Interactive Web Studio: Clean, responsive web dashboard with 1-click test scenarios, real-time sensitivity sliders, ZIP code wage adjustment, adjacent blend toggles, and cache latency indicators.
- 💻 Terminal CLI Tool: Built-in command-line interface (
cli.py) supporting--zipand--blendflags for adjusters who prefer terminal workflows. - 📑 Formal PDF Generation: Exports a formatted Motor Vehicle Damage Appraisal Report matching US insurance adjuster standards.
- 🔌 Pluggable Architecture: Implements the Strategy Pattern with an abstract
BaseDamageDetectorinterface, making it easy to drop in a fine-tuned YOLO or segmentation model in the future without changing the pricing engine or UI. - 🧪 28 Automated Tests: Complete
pytesttest suite verifying API schemas, regional rates, blend rules, caching, image validation, edge detection, and PDF generation.
claimscope/
├── app/
│ ├── main.py # FastAPI web server and REST endpoints
│ ├── core/
│ │ ├── cache.py # 64-bit dHash perceptual caching & thread pool
│ │ └── config.py # Hourly rates, tax rates, and thresholds
│ ├── cv_engine/
│ │ ├── base.py # Abstract detector interface & Pydantic schemas
│ │ ├── classical_detector.py# OpenCV edge detection & color segmentation
│ │ ├── future_ai_detector.py# Extension stub for ML models
│ │ └── image_validator.py # Pre-flight vehicle surface validation filter
│ ├── estimator/
│ │ ├── cost_engine.py # Actuarial repair calculation engine
│ │ ├── parts_catalog.py # OEM vs aftermarket parts & material multipliers
│ │ └── regional_rates.py # 5-digit US ZIP code prevailing wage index
│ ├── reports/
│ │ └── pdf_generator.py # PDF appraisal report generator (fpdf2)
│ ├── schemas/
│ │ ├── __init__.py # Centralized schema exports
│ │ └── api.py # Pydantic request/response models for all endpoints
│ └── static/ # Web dashboard (HTML, Tailwind CSS, JS)
├── tests/ # Pytest test suite (28 automated tests)
│ ├── conftest.py # Test path setup
│ ├── test_api_schemas.py # REST endpoint schemas and serialization tests
│ ├── test_cv_detector.py # OpenCV detection & determinism tests
│ ├── test_estimator.py # Repair vs replace & pricing logic tests
│ ├── test_pdf.py # PDF compilation tests
│ ├── test_performance_and_actuarial.py # Regional rates, blend rule, dHash cache
│ └── test_validator.py # Vehicle image validation & guardrail tests
├── cli.py # Command-line inspection tool (--zip, --blend)
├── generate_samples.py # Generates sample damage images for testing
├── Dockerfile # Multi-stage Docker container build
├── requirements.txt # Python dependencies
├── pytest.ini # Test configuration
└── run.py # Local development launcher
- Python 3.10+
- Git
-
Clone the repository:
git clone https://github.com/Devops-de/claimscope.git cd claimscope -
Install dependencies:
pip install -r requirements.txt
-
(Optional) Generate the built-in test sample images:
python generate_samples.py
-
Start the application:
python run.py
Open your browser to:
- Web UI: http://localhost:8000
- API Documentation: http://localhost:8000/docs
The repository includes a dedicated CLI tool for terminal users:
# Run inspection on an image and print the estimate breakdown
python cli.py inspect app/static/sample_images/sample_bumper_scratch.jpg --panel FRONT_BUMPER
# Run inspection and save the official PDF report
python cli.py inspect app/static/sample_images/sample_door_dent.jpg --panel DRIVER_FRONT_DOOR --pdf estimate.pdf
# List all supported vehicle panels, materials, and catalog rates
python cli.py list-panelsClaimScope maintains rigorous automated testing, static type checks, and formatting standards:
# 1. Run full unit, integration, and ground-truth benchmark suite
pytest -v
# 2. Run Ruff linter and static analysis
ruff check .
# 3. Verify code formatting
ruff format --check .All 41 tests run locally in ~2–3 seconds, verifying API schemas, regional wage rates, Mitchell blend rules, collision-resistant perceptual caching, memory bounds, image validation guardrails, edge extraction, PDF generation, and labeled ground-truth actuarial benchmarks.
Build and run the containerized application using a clean, multi-stage production container:
docker build -t claimscope .
docker run -p 8000:8000 claimscopeThe production container runs under an unprivileged claimscope user, installs only runtime dependencies (excluding test harnesses), and delivers a minimal, secure attack surface.
- Architectural Patterns & Complexity: See ARCHITECTURE.md for data flows, time/space complexity analysis, and memory management.
- Operational Design Domain & Actuarial Calibration: See VALIDATION.md for heuristic boundaries, physical limitations of classical CV, and calibration evidence against Mitchell collision repair standards.
This project is dual-licensed under either the MIT License or the Apache License 2.0. You may choose either license at your option.