Document Perspective Correction API

Этот проект предоставляет REST API для автоматической коррекции перспективы документов на белой бумаге с использованием компьютерного зрения. Сервис обнаруживает границы документа на изображении, применяет перспективное преобразование и возвращает выровненное изображение документа.

Ключевые возможности

• Автоматическое обнаружение белых листов бумаги на изображениях
• Коррекция перспективы для получения "плоского" вида документа
• Обработка как фотографий, так и сканированных документов
• Поддержка форматов JPEG и PNG
• REST API для интеграции с другими системами

Технологический стек

• Python 3.9+
• OpenCV (компьютерное зрение)
• FastAPI (веб-фреймворк)
• Uvicorn (ASGI-сервер)
• NumPy (математические операции)

Установка и запуск

1. Клонируйте репозиторий:

git clone https://git.ymnuktech.ru/ymnuk/doc-perspective.git
cd doc-perspective

2. Создайте и активируйте виртуальное окружение (рекомендуется):

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate    # Windows

3. Установите зависимости:

pip install -r requirements.txt

4. Запустите сервер:

uvicorn main:app --reload --port 8000

Сервер будет доступен по адресу: http://localhost:8000

Использование API

Основной эндпоинт

Отправьте POST-запрос на /process-document с изображением в теле запроса:

curl -X POST "http://localhost:8000/process-document" \
  -H "accept: image/jpeg" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@document_photo.jpg"

Параметры ответа

• Успешная обработка: Возвращает JPEG изображение с выровненным документом
• Ошибка: Возвращает JSON с описанием ошибки
• Предупреждение: Возвращает оригинальное изображение с заголовком X-Warning

Примеры использования

Python (requests)

import requests

url = "http://localhost:8000/process-document"
files = {"file": open("document.jpg", "rb")}

response = requests.post(url, files=files)

if response.status_code == 200:
    with open("processed.jpg", "wb") as f:
        f.write(response.content)
    print("Document processed successfully")
else:
    print(f"Error: {response.json()['detail']}")

JavaScript (fetch)

const formData = new FormData();
formData.append('file', document.querySelector('input[type="file"]').files[0]);

fetch('http://localhost:8000/process-document', {
  method: 'POST',
  body: formData
})
.then(response => {
  if (response.ok) return response.blob();
  throw new Error('Processing failed');
})
.then(blob => {
  const url = URL.createObjectURL(blob);
  // Отображаем результат
});

Алгоритм работы

1. Обнаружение бумаги:

   • Конвертация в LAB цветовое пространство
   • Адаптивная гистограммная коррекция
   • Бинаризация и морфологические операции

2. Поиск контура:

   • Обнаружение контуров с фильтрацией по размеру
   • Аппроксимация четырехугольника
   • Определение угловых точек

3. Коррекция перспективы:

   • Расчет матрицы преобразования
   • Применение перспективной трансформации
   • Получение выровненного изображения

Лицензия

Этот проект распространяется под лицензией MIT