Computer Vision Team Project: Document Scanner & Enhancer

Selected Theme

Theme 16 — Documents: Document Scanner & Enhancer

This project implements a complete Computer Vision pipeline for detecting a document in a real-world image, correcting its perspective, improving readability, and producing an automatic final decision about whether the document was successfully processed.

The system follows the required course pipeline:

image → enhance → segment → clean → detect → decide

The project is designed for real images such as receipts, invoices, printed pages, and photographed documents.

---

Project Objective

The goal of this project is to build an automatic document scanning and enhancement system. Given an input image, the system should:

1. Load the original image.
2. Improve image quality before processing.
3. Segment the document area from the background.
4. Clean the segmentation mask.
5. Detect the document region.
6. Correct perspective if a document contour is found.
7. Enhance the final scanned document.
8. Save all intermediate pipeline results.
9. Produce an automatic interpretable decision.

The final result is not only an image output, but also a structured decision indicating whether the document was detected successfully.

---

Features

• Automatic batch processing of multiple images.
• Works with real document photos.
• Full five-stage Computer Vision pipeline.
• Image enhancement using denoising, CLAHE, and gamma correction.
• Segmentation using edge detection and threshold-based masking.
• Morphological mask cleaning.
• Document detection using contours and quadrilateral approximation.
• Perspective correction for scanned document output.
• Automatic decision logic with PASS / FAIL result.
• Saves all required intermediate outputs for every test image.
• Generates text and JSON decision files.
• Provides summary output for all processed images.

---

Technologies Used

• Python
• OpenCV
• NumPy
• Pillow
• ReportLab

---

Project Structure

CV_CourseWork/
│
├── data/
│   └── test/
│       ├── invoice.jpg
│       ├── receipt_agr.jpg
│       ├── receipt_swiss.jpg
│       └── SOURCES.md
│
├── outputs/
│   ├── invoice/
│   ├── receipt_agr/
│   ├── receipt_swiss/
│   ├── summary.json
│   └── summary.md
│
├── src/
│   ├── document_scanner.py
│   └── make_report_pdf.py
│
├── contribution_statement.md
├── presentation.md
├── README.md
├── report.md
├── report.pdf
└── requirements.txt

---

Installation

Clone the repository or download the project folder.

Install the required Python packages:

pip install -r requirements.txt

Recommended Python version:

Python 3.10+

---

How to Run

To process the default test images located in data/test/, run:

python src/document_scanner.py --input data/test --output outputs

The system will process all supported images from the input folder and save the results into the outputs/ directory.

Supported input formats:

.jpg, .jpeg, .png, .bmp, .tif, .tiff

---

Running on Custom Images

To test the system on your own document photos:

1. Create a folder with your images.
2. Put real document photos into that folder.
3. Run the script with the path to your folder.

Example:

python src/document_scanner.py --input path/to/your/images --output outputs

For best results, use images where the document is visible, reasonably sharp, and not completely covered by shadows.

---

Pipeline Description

1. Original Image

The system starts by loading the input image and saving a copy of it as the first pipeline output.

Output file:

01_original.jpg

This image is used as the reference for all following stages.

---

2. Enhance Stage

The purpose of this stage is to improve image quality before segmentation and detection.

Methods used:

• image resizing if needed;
• denoising;
• CLAHE contrast enhancement;
• gamma correction;
• luminance enhancement in LAB color space.

This stage makes document borders, text areas, and contrast differences more visible.

Output file:

02_enhanced.jpg

---

3. Segment Stage

The segmentation stage extracts possible document regions from the enhanced image.

Methods used:

• grayscale conversion;
• edge detection;
• thresholding;
• mask generation.

The result is a binary mask where the likely document area is separated from the background.

Output file:

03_segmentation_mask.jpg

---

4. Clean Stage

The raw segmentation mask may contain noise, small disconnected regions, or gaps. This stage improves the mask before detection.

Methods used:

• morphological closing;
• morphological opening;
• connected component filtering;
• removal of small artifacts.

The cleaned mask is used for more stable contour detection.

Output file:

04_cleaned_mask.jpg

---

5. Detect Stage

The detection stage finds the document region in the cleaned mask.

Methods used:

• contour detection;
• contour area filtering;
• polygon approximation;
• quadrilateral detection;
• bounding box visualization.

If a four-corner document contour is detected, the system applies a perspective transform to create a scanned document view.

Output files:

05_detection_result.jpg
06_scanned_document.jpg

The detection result image shows the detected document region, bounding box, contour, and processing status.

---

6. Decide Stage

The final stage produces an automatic interpretable decision.

The decision logic is based on:

• whether a document contour was detected;
• detected document area ratio;
• confidence score;
• whether perspective correction was possible.

Possible final decisions:

PASS
FAIL

A PASS decision means that the system successfully detected a valid document region and produced a scanned output.

A FAIL decision means that the system could not confidently detect a document region. This may happen because of poor lighting, low contrast, strong shadows, background clutter, or incomplete document visibility.

Output files:

decision.txt
decision.json

---

Output Files Per Image

For each input image, the system creates a separate output folder.

Example:

outputs/invoice/

Each folder contains:

01_original.jpg
02_enhanced.jpg
03_segmentation_mask.jpg
04_cleaned_mask.jpg
05_detection_result.jpg
06_scanned_document.jpg
decision.txt
decision.json

These files correspond directly to the required pipeline stages:

File	Meaning
01_original.jpg	Original input image
02_enhanced.jpg	Improved image after enhancement
03_segmentation_mask.jpg	Raw segmentation mask
04_cleaned_mask.jpg	Cleaned mask after morphology
05_detection_result.jpg	Detection visualization with document region
06_scanned_document.jpg	Final perspective-corrected document
decision.txt	Human-readable final decision
decision.json	Structured final decision data

---

Example Decision Output

Example decision.txt:

Image: invoice.jpg
Decision: PASS
Document detected: yes
Confidence: 0.87
Detected area ratio: 0.42
Perspective correction: applied
Final output: 06_scanned_document.jpg

Example decision.json:

{
  "image": "invoice.jpg",
  "decision": "PASS",
  "document_detected": true,
  "confidence": 0.87,
  "area_ratio": 0.42,
  "perspective_corrected": true
}

---

Test Images

The project includes at least three real test images:

invoice.jpg
receipt_agr.jpg
receipt_swiss.jpg

These images are used to demonstrate that the system works on real document photos rather than artificial examples.

The outputs for these images are saved in the outputs/ directory.

---

Summary Output

After processing all images, the system creates summary files:

outputs/summary.json
outputs/summary.md

These files contain the overall results for the processed dataset, including the number of processed images and the decision for each image.

---

Arteom Ponomarev: Lead CV Engineer Aliaksei Nikitsenkau: Image Processing Specialist / Morphology & Report Lead

Report and Presentation

The repository includes supporting materials for the final submission:

report.md
report.pdf
presentation.md
contribution_statement.md

The report includes:

• problem description;
• team roles and task division;
• pipeline design;
• methods used;
• stage-by-stage results;
• failure cases;
• conclusion.

The presentation includes:

• motivation;
• pipeline walkthrough;
• demo description;
• results;
• limitations;
• Q&A preparation.

---

Failure Cases and Limitations

The system may fail or produce lower-quality results in the following cases:

• document borders are not visible;
• document color is too similar to the background;
• image is very dark or overexposed;
• document is heavily rotated or partly outside the image;
• strong shadows cover the document;
• background contains many rectangular objects;
• image is blurred;
• document is folded or curved;
• only part of the document is visible.

These limitations are expected for a classical Computer Vision approach based on contours and thresholding.

---

Possible Improvements

Possible future improvements include:

• adding adaptive parameter tuning for different lighting conditions;
• improving shadow removal;
• adding automatic blur detection;
• adding text readability scoring;
• using OCR to validate the scanned document;
• comparing multiple segmentation methods;
• adding a simple graphical user interface;
• adding real-time camera input.

---

Reproducibility

To reproduce the results:

1. Install dependencies:

pip install -r requirements.txt

2. Run the pipeline:

python src/document_scanner.py --input data/test --output outputs

3. Open the outputs/ directory.

4. Check each image folder for stage-by-stage outputs and final decision files.

---

Course Requirement Compliance

This project satisfies the main Computer Vision course project requirements:

• complete five-stage pipeline;
• real image input;
• automatic processing;
• intermediate stage outputs;
• final interpretable decision;
• at least three test images;
• team role division;
• report and presentation materials;
• reproducible code execution.

---

Final Goal

The final goal of this project is to demonstrate a complete, interpretable, and reproducible Computer Vision system that can process real document images, enhance them, detect document regions, correct perspective, and produce an automatic decision.