{"id":29258738,"url":"https://github.com/huridocs/pdf-document-layout-analysis","last_synced_at":"2026-01-17T16:39:55.797Z","repository":{"id":238511610,"uuid":"796611485","full_name":"huridocs/pdf-document-layout-analysis","owner":"huridocs","description":"A Docker-powered service for PDF document layout analysis. This service provides a powerful and flexible PDF analysis service. The service allows for the segmentation and classification of different parts of PDF pages, identifying the elements such as texts, titles, pictures, tables and so on.","archived":false,"fork":false,"pushed_at":"2025-12-15T14:54:45.000Z","size":4378,"stargazers_count":1015,"open_issues_count":12,"forks_count":116,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-12-18T19:43:22.353Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/huridocs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://huridocs.org/donate/"]}},"created_at":"2024-05-06T09:36:50.000Z","updated_at":"2025-12-18T18:14:35.000Z","dependencies_parsed_at":"2025-12-15T21:19:54.849Z","dependency_job_id":null,"html_url":"https://github.com/huridocs/pdf-document-layout-analysis","commit_stats":null,"previous_names":["huridocs/pdf-document-layout-analysis"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/huridocs/pdf-document-layout-analysis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huridocs%2Fpdf-document-layout-analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huridocs%2Fpdf-document-layout-analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huridocs%2Fpdf-document-layout-analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huridocs%2Fpdf-document-layout-analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huridocs","download_url":"https://codeload.github.com/huridocs/pdf-document-layout-analysis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huridocs%2Fpdf-document-layout-analysis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28511868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-04T06:02:11.199Z","updated_at":"2026-01-17T16:39:55.784Z","avatar_url":"https://github.com/huridocs.png","language":"Python","funding_links":["https://huridocs.org/donate/"],"categories":["光学字符识别OCR","Python","Parsers, OCR and extraction"],"sub_categories":["资源传输下载"],"readme":"\u003ch1 align=\"center\"\u003ePDF Document Layout Analysis\u003c/h1\u003e\n\u003cp align=\"center\"\u003eA Docker-powered microservice for intelligent PDF document layout analysis, OCR, and content extraction\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.10+-blue.svg\" alt=\"Python Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/FastAPI-0.111.1-green.svg\" alt=\"FastAPI\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Docker-Ready-blue.svg\" alt=\"Docker\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/GPU-Supported-orange.svg\" alt=\"GPU Support\"\u003e\n\u003c/p\u003e\n\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\u003cstrong\u003eBuilt with ❤️ by \u003ca href=\"https://huridocs.org\"\u003eHURIDOCS\u003c/a\u003e\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/huridocs/pdf-document-layout-analysis\"\u003e⭐ Star us on GitHub\u003c/a\u003e •\n    \u003ca href=\"https://hub.docker.com/r/huridocs/pdf-document-layout-analysis\"\u003e🐳 Pull from Docker Hub\u003c/a\u003e •\n    \u003ca href=\"https://huggingface.co/HURIDOCS/pdf-document-layout-analysis\"\u003e🤗 View on Hugging Face\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n---\n\n## 🚀 Overview\n\nThis project provides a powerful and flexible PDF analysis microservice built with **Clean Architecture** principles. The service enables OCR, segmentation, and classification of different parts of PDF pages, identifying elements such as texts, titles, pictures, tables, formulas, and more. Additionally, it determines the correct reading order of these identified elements and can convert PDFs to various formats including Markdown and HTML with **automatic translation support** powered by Ollama.\n\nThe service offers both a **user-friendly Gradio web interface** for interactive use and a **comprehensive REST API** for programmatic access and integration.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/huridocs/pdf-document-layout-analysis/main/images/ui.png\" alt=\"Gradio Web UI\" width=\"800\"/\u003e\n  \u003cp\u003e\u003cem\u003eGradio Web Interface - Easy-to-use UI for PDF analysis, conversion, and translation\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## 🚀 Quick Start\n\n### 1. Start the Service\n\n```bash\nmake start # or `just start` (https://github.com/casey/just)\n```\n\nThe service provides two interfaces:\n- **🎨 Web UI (Gradio)**: `http://localhost:7860` - User-friendly interface for all features\n- **🔌 REST API**: `http://localhost:5060` - Programmatic access for integrations\n\n**See all available commands:**\n```bash\nmake --list\n```\n\n**Check service status:**\n\n```bash\ncurl http://localhost:5060/info\n```\n\n### 2. Using the Web UI\n\nSimply open your browser and navigate to `http://localhost:7860` to access the intuitive web interface. The UI provides:\n\n- 📄 **PDF Analysis** - Upload and analyze PDFs with visual results\n- 🔄 **Format Conversion** - Convert to Markdown or HTML\n- 🌍 **Translation** - Translate documents to multiple languages\n- 👁️ **Visualization** - View segmentation overlays on your PDFs\n- 🔍 **OCR Processing** - Apply OCR to scanned documents\n- 📑 **TOC Extraction** - Extract table of contents\n\n### 3. Using the REST API\n\n**Analyze a PDF document (VGT model - high accuracy):**\n```bash\ncurl -X POST -F 'file=@/path/to/your/document.pdf' http://localhost:5060\n```\n\n**Fast analysis (LightGBM models - faster processing):**\n```bash\ncurl -X POST -F 'file=@/path/to/your/document.pdf' -F \"fast=true\" http://localhost:5060\n```\n\n### 4. Stop the Service\n\n```bash\nmake stop\n```\n\n\u003e 💡 **Tip**: The Web UI at `http://localhost:7860` is the easiest way to get started. For automation and integration, use the REST API at `http://localhost:5060`.\n\n---\n\n## ✨ Key Features\n\n- 🎨 **User-Friendly Web UI** - Intuitive Gradio interface for easy PDF processing\n- 🔍 **Advanced PDF Layout Analysis** - Segment and classify PDF content with high accuracy\n- 🖼️ **Visual \u0026 Fast Models** - Choose between VGT (Vision Grid Transformer) for accuracy or LightGBM for speed\n- 📝 **Multi-format Output** - Export to JSON, Markdown, HTML, and visualize PDF segmentations\n- 🌍 **Automatic Translation** - Translate documents to multiple languages using Ollama models\n- 🌐 **OCR Support** - 150+ language support with Tesseract OCR\n- 📊 **Table \u0026 Formula Extraction** - Extract tables as HTML and formulas as LaTeX\n- 🏗️ **Clean Architecture** - Modular, testable, and maintainable codebase\n- 🐳 **Docker-Ready** - Easy deployment with GPU support\n- ⚡ **RESTful API** - Comprehensive API with 10+ endpoints\n\n### 📸 Example Results\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/huridocs/pdf-document-layout-analysis/main/images/vgtexample1.png\"/\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/huridocs/pdf-document-layout-analysis/main/images/vgtexample2.png\"/\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/huridocs/pdf-document-layout-analysis/main/images/vgtexample3.png\"/\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/huridocs/pdf-document-layout-analysis/main/images/vgtexample4.png\"/\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 🔗 Project Links\n\n- **GitHub**: [pdf-document-layout-analysis](https://github.com/huridocs/pdf-document-layout-analysis)\n- **HuggingFace**: [pdf-document-layout-analysis](https://huggingface.co/HURIDOCS/pdf-document-layout-analysis)\n- **DockerHub**: [pdf-document-layout-analysis](https://hub.docker.com/r/huridocs/pdf-document-layout-analysis/)\n\n---\n\n## 📋 Table of Contents\n\n- [🚀 Overview](#-overview)\n- [🚀 Quick Start](#-quick-start)\n- [✨ Key Features](#-key-features)\n- [⚙️ Dependencies](#-dependencies)\n- [📋 Requirements](#-requirements)\n- [📚 API Reference](#-api-reference)\n- [💡 Usage Examples](#-usage-examples)\n  - [Translation Features](#translation-features)\n- [🏗️ Architecture](#-architecture)\n- [🤖 Models](#-models)\n- [📊 Data](#-data)\n- [🔧 Development](#-development)\n- [📈 Benchmarks](#-benchmarks)\n  - [Performance](#performance)\n  - [Speed](#speed)\n- [🌐 Installation of More Languages for OCR](#-installation-of-more-languages-for-ocr)\n- [🔗 Related Services](#-related-services)\n- [🤝 Contributing](#-contributing)\n\n\n\n## ⚙️ Dependencies\n\n### Required\n- **Docker Desktop 4.25.0+** - [Installation Guide](https://www.docker.com/products/docker-desktop/)\n- **Python 3.10+** (for local development)\n\n### Optional\n- **NVIDIA Container Toolkit** - [Installation Guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) (for GPU support)\n\n## 📋 Requirements\n\n### System Requirements\n- **RAM**: 2 GB minimum\n- **GPU Memory**: 5 GB (optional, will fallback to CPU if unavailable)\n- **Disk Space**: 10 GB for models and dependencies\n- **CPU**: Multi-core recommended for better performance\n\n### Docker Requirements\n- Docker Engine 20.10+\n- Docker Compose 2.0+\n\n## 📚 API Reference\n\nThe service provides a comprehensive RESTful API with the following endpoints:\n\n### Core Analysis Endpoints\n\n| Endpoint | Method | Description | Parameters |\n|----------|--------|-------------|------------|\n| `/` | POST | Analyze PDF layout and extract segments | `file`, `fast`, `parse_tables_and_math` |\n| `/save_xml/{filename}` | POST | Analyze PDF and save XML output | `file`, `xml_file_name`, `fast` |\n| `/get_xml/{filename}` | GET | Retrieve saved XML analysis | `xml_file_name` |\n\n### Content Extraction Endpoints\n\n| Endpoint | Method | Description | Parameters |\n|----------|--------|-------------|------------|\n| `/text` | POST | Extract text by content types | `file`, `fast`, `types` |\n| `/toc` | POST | Extract table of contents | `file`, `fast` |\n| `/toc_legacy_uwazi_compatible` | POST | Extract TOC (Uwazi compatible) | `file` |\n\n### Format Conversion Endpoints\n\n| Endpoint | Method | Description | Parameters |\n|----------|--------|-------------|------------|\n| `/markdown` | POST | Convert PDF to Markdown (includes segmentation data in zip) | `file`, `fast`, `extract_toc`, `dpi`, `output_file`, `target_languages`, `translation_model` |\n| `/html` | POST | Convert PDF to HTML (includes segmentation data in zip) | `file`, `fast`, `extract_toc`, `dpi`, `output_file`, `target_languages`, `translation_model` |\n| `/visualize` | POST | Visualize segmentation results on the PDF | `file`, `fast` |\n\n### OCR \u0026 Utility Endpoints\n\n| Endpoint | Method | Description | Parameters |\n|----------|--------|-------------|------------|\n| `/ocr` | POST | Apply OCR to PDF | `file`, `language` |\n| `/info` | GET | Get service information | - |\n| `/` | GET | Health check and system info | - |\n| `/error` | GET | Test error handling | - |\n\n### Common Parameters\n\n- **`file`**: PDF file to process (multipart/form-data)\n- **`fast`**: Use LightGBM models instead of VGT (boolean, default: false)\n- **`parse_tables_and_math`**: Apply OCR to table regions (boolean, default: false) and convert formulas to LaTeX\n- **`language`**: OCR language code (string, default: \"en\")\n- **`types`**: Comma-separated content types to extract (string, default: \"all\")\n- **`extract_toc`**: Include table of contents at the beginning of the output (boolean, default: false)\n- **`dpi`**: Image resolution for conversion (integer, default: 120)\n- **`target_languages`**: Comma-separated list of target languages for translation (e.g. \"Turkish, Spanish, French\")\n- **`translation_model`**: Ollama model to use for translation (string, default: \"gpt-oss\")\n\n## 💡 Usage Examples\n\n### Basic PDF Analysis\n\n**Standard analysis with VGT model:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  http://localhost:5060\n```\n\n**Fast analysis with LightGBM models:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  -F 'fast=true' \\\n  http://localhost:5060\n```\n\n**Analysis with table and math parsing:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  -F 'parse_tables_and_math=true' \\\n  http://localhost:5060\n```\n\n### Text Extraction\n\n**Extract all text:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  -F 'types=all' \\\n  http://localhost:5060/text\n```\n\n**Extract specific content types:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  -F 'types=title,text,table' \\\n  http://localhost:5060/text\n```\n\n### Format Conversion\n\n**Convert to Markdown:**\n```bash\ncurl -X POST http://localhost:5060/markdown \\\n  -F 'file=@document.pdf' \\\n  -F 'extract_toc=true' \\\n  -F 'output_file=document.md' \\\n  --output 'document.zip'\n```\n\n**Convert to HTML:**\n```bash\ncurl -X POST http://localhost:5060/html \\\n  -F 'file=@document.pdf' \\\n  -F 'extract_toc=true' \\\n  -F 'output_file=document.md' \\\n  --output 'document.zip'\n```\n\n**Convert to Markdown with Translation:**\n```bash\ncurl -X POST http://localhost:5060/markdown \\\n  -F 'file=@document.pdf' \\\n  -F 'output_file=document.md' \\\n  -F 'target_languages=Turkish, Spanish' \\\n  -F 'translation_model=gpt-oss' \\\n  --output 'document.zip'\n```\n\n**Convert to HTML with Translation:**\n```bash\ncurl -X POST http://localhost:5060/html \\\n  -F 'file=@document.pdf' \\\n  -F 'output_file=document.md' \\\n  -F 'target_languages=French, Russian' \\\n  -F 'translation_model=huihui_ai/hunyuan-mt-abliterated' \\\n  --output 'document.zip'\n```\n\n\u003e **📋 Segmentation Data \u0026 Translations**: Format conversion endpoints automatically include detailed segmentation data in the zip output. The resulting zip file contains:\n\u003e - **Original file**: The converted document in the requested format\n\u003e - **Segmentation data**: `{filename}_segmentation.json` file with information about each detected document segment:\n\u003e   - **Coordinates**: `left`, `top`, `width`, `height`\n\u003e   - **Page information**: `page_number`, `page_width`, `page_height` \n\u003e   - **Content**: `text` content and segment `type` (e.g., \"Title\", \"Text\", \"Table\", \"Picture\")\n\u003e - **Translated files** (if `target_languages` specified): `{filename}_{language}.{extension}` for each target language\n\u003e - **Images** (if present): `{filename}_pictures/` directory containing extracted images\n\n### Translation Features\n\nThe `/markdown` and `/html` endpoints support automatic translation of the converted content into multiple languages using Ollama models.\n\n**Translation Requirements:**\n- The specified translation model must be available in Ollama\n- An `output_file` must be specified (translations are only included in zip responses)\n\n**Supported Translation Models:**\n- Any Ollama-compatible model (e.g., `gpt-oss`, `llama2`, `mistral`, etc.)\n- Models are automatically downloaded if not present locally\n\n**Translation Process:**\n1. The service checks if the specified model is available in Ollama\n2. If not available, it attempts to download the model using `ollama pull`\n3. For each target language, the content is translated while preserving:\n   - Original formatting and structure\n   - Markdown/HTML syntax\n   - Links and references\n   - Image references and tables\n4. Translated files are named: `{filename}_{language}.{extension}`\n\n_**Note that the quality of translations mostly depends on the models used. When using smaller models, the output may contain many unexpected or undesired elements. For regular users, we aimed for a balance between performance and quality, so we tested with different models with a reasonable size. The results for `gpt-oss` were satisfactory, which is why we set it as the default model. If you need something smaller you can also try `huihui_ai/hunyuan-mt-abliterated`, we saw it gives decent results especially if the text does not have much styling.**_\n\n**Example Translation Output:**\n```\ndocument.zip\n├── document.md                   # Source text with markdown/html styling\n├── document_Spanish.md           # Spanish translation  \n├── document_French.md            # French translation\n├── document_Turkish.md           # Turkish translation\n├── document_segmentation.json    # Segmentation information\n└── document_pictures/       # (if images present)\n    ├── document_1_1.png\n    └── document_1_2.png\n```\n\n### OCR Processing\n\n**OCR in English:**\n```bash\ncurl -X POST \\\n  -F 'file=@scanned_document.pdf' \\\n  -F 'language=en' \\\n  http://localhost:5060/ocr \\\n  --output ocr_processed.pdf\n```\n\n**OCR in other languages:**\n```bash\n# French\ncurl -X POST \\\n  -F 'file=@document_french.pdf' \\\n  -F 'language=fr' \\\n  http://localhost:5060/ocr \\\n  --output ocr_french.pdf\n\n# Spanish\ncurl -X POST \\\n  -F 'file=@document_spanish.pdf' \\\n  -F 'language=es' \\\n  http://localhost:5060/ocr \\\n  --output ocr_spanish.pdf\n```\n\n### Visualization\n\n**Generate visualization PDF:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  http://localhost:5060/visualize \\\n  --output visualization.pdf\n```\n\n### Table of Contents Extraction\n\n**Extract structured TOC:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  http://localhost:5060/toc\n```\n\n### XML Storage and Retrieval\n\n**Analyze and save XML:**\n```bash\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  http://localhost:5060/save_xml/my_analysis\n```\n\n**Retrieve saved XML:**\n```bash\ncurl http://localhost:5060/get_xml/my_analysis.xml\n```\n\n### Service Information\n\n**Get service info and supported languages:**\n```bash\ncurl http://localhost:5060/info\n```\n\n**Health check:**\n```bash\ncurl http://localhost:5060/\n```\n\n### Response Format\n\nMost endpoints return JSON with segment information:\n\n```json\n[\n  {\n    \"left\": 72.0,\n    \"top\": 84.0,\n    \"width\": 451.2,\n    \"height\": 23.04,\n    \"page_number\": 1,\n    \"page_width\": 595.32,\n    \"page_height\": 841.92,\n    \"text\": \"Document Title\",\n    \"type\": \"Title\"\n  },\n  {\n    \"left\": 72.0,\n    \"top\": 120.0,\n    \"width\": 451.2,\n    \"height\": 200.0,\n    \"page_number\": 1,\n    \"page_width\": 595.32,\n    \"page_height\": 841.92,\n    \"text\": \"This is the main text content...\",\n    \"type\": \"Text\"\n  }\n]\n```\n\n### Supported Content Types\n\n- `Caption` - Image and table captions\n- `Footnote` - Footnote text\n- `Formula` - Mathematical formulas\n- `List item` - List items and bullet points\n- `Page footer` - Footer content\n- `Page header` - Header content\n- `Picture` - Images and figures\n- `Section header` - Section headings\n- `Table` - Table content\n- `Text` - Regular text paragraphs\n- `Title` - Document and section titles\n\n\n## 🏗️ Architecture\n\nThis project follows **Clean Architecture** principles, ensuring separation of concerns, testability, and maintainability. The codebase is organized into distinct layers:\n\n### Directory Structure\n\n```\nsrc/\n├── domain/                 # Enterprise Business Rules\n│   ├── PdfImages.py       # PDF image handling domain logic\n│   ├── PdfSegment.py      # PDF segment entity\n│   ├── Prediction.py      # ML prediction entity\n│   └── SegmentBox.py      # Core segment box entity\n├── use_cases/             # Application Business Rules\n│   ├── pdf_analysis/      # PDF analysis use case\n│   ├── text_extraction/   # Text extraction use case\n│   ├── toc_extraction/    # Table of contents extraction\n│   ├── visualization/     # PDF visualization use case\n│   ├── ocr/              # OCR processing use case\n│   ├── markdown_conversion/ # Markdown conversion use case (with translation)\n│   └── html_conversion/   # HTML conversion use case (with translation)\n├── adapters/              # Interface Adapters\n│   ├── infrastructure/    # External service adapters\n│   ├── ml/               # Machine learning model adapters\n│   ├── storage/          # File storage adapters\n│   └── web/              # Web framework adapters\n├── ports/                 # Interface definitions\n│   ├── services/         # Service interfaces\n│   └── repositories/     # Repository interfaces\n└── drivers/              # Frameworks \u0026 Drivers\n    └── web/              # FastAPI application setup\n```\n\n### Layer Responsibilities\n\n- **Domain Layer**: Contains core business entities and rules independent of external concerns\n- **Use Cases Layer**: Orchestrates domain entities to fulfill specific application requirements\n- **Adapters Layer**: Implements interfaces defined by inner layers and adapts external frameworks\n- **Drivers Layer**: Contains frameworks, databases, and external agency configurations\n\n### Key Benefits\n\n- 🔄 **Dependency Inversion**: High-level modules don't depend on low-level modules\n- 🧪 **Testability**: Easy to unit test business logic in isolation\n- 🔧 **Maintainability**: Changes to external frameworks don't affect business rules\n- 📈 **Scalability**: Easy to add new features without modifying existing code\n\n  \n## 🤖 Models\n\nThe service offers two complementary model approaches, each optimized for different use cases:\n\n### 1. Vision Grid Transformer (VGT) - High Accuracy Model\n\n**Overview**: A state-of-the-art visual model developed by Alibaba Research Group that \"sees\" the entire page layout.\n\n**Key Features**:\n- 🎯 **High Accuracy**: Best-in-class performance on document layout analysis\n- 👁️ **Visual Understanding**: Analyzes the entire page context including spatial relationships\n- 📊 **Trained on DocLayNet**: Uses the comprehensive [DocLayNet dataset](https://github.com/DS4SD/DocLayNet)\n- 🔬 **Research-Backed**: Based on [Advanced Literate Machinery](https://github.com/AlibabaResearch/AdvancedLiterateMachinery)\n\n**Resource Requirements**:\n- GPU: 5GB+ VRAM (recommended)\n- CPU: Falls back automatically if GPU unavailable\n- Processing Speed: ~1.75 seconds/page (GPU [GTX 1070]) or ~13.5 seconds/page (CPU [i7-8700])\n\n### 2. LightGBM Models - Fast \u0026 Efficient\n\n**Overview**: Lightweight ensemble of two specialized models using XML-based features from Poppler.\n\n**Key Features**:\n- ⚡ **High Speed**: ~0.42 seconds per page on CPU (i7-8700)\n- 💾 **Low Resource Usage**: CPU-only, minimal memory footprint\n- 🔄 **Dual Model Approach**:\n  - **Token Type Classifier**: Identifies content types (title, text, table, etc.)\n  - **Segmentation Model**: Determines proper content boundaries\n- 📄 **XML-Based**: Uses Poppler's PDF-to-XML conversion for feature extraction\n\n**Trade-offs**:\n- Slightly lower accuracy compared to VGT\n- No visual context understanding\n- Excellent for batch processing and resource-constrained environments\n\n### OCR Integration\n\nBoth models integrate seamlessly with OCR capabilities:\n\n- **Engine**: [Tesseract OCR](https://github.com/tesseract-ocr/tesseract)\n- **Processing**: [ocrmypdf](https://ocrmypdf.readthedocs.io/en/latest/index.html)\n- **Languages**: 150+ supported languages\n- **Output**: Searchable PDFs with preserved layout\n\n### Model Selection Guide\n\n| Use Case | Recommended Model | Reason |\n|----------|------------------|---------|\n| High accuracy requirements | VGT | Superior visual understanding |\n| Batch processing | LightGBM | Faster processing, lower resources |\n| GPU available | VGT | Leverages GPU acceleration |\n| CPU-only environment | LightGBM | Optimized for CPU processing |\n| Real-time applications | LightGBM | Consistent fast response times |\n| Research/analysis | VGT | Best accuracy for detailed analysis |\n\n## 📊 Data\n\n### Training Dataset\n\nBoth model types are trained on the comprehensive [DocLayNet dataset](https://github.com/DS4SD/DocLayNet), a large-scale document layout analysis dataset containing over 80,000 document pages.\n\n### Document Categories\n\nThe models can identify and classify 11 distinct content types:\n\n| ID | Category | Description |\n|----|----------|-------------|\n| 1 | **Caption** | Image and table captions |\n| 2 | **Footnote** | Footnote references and text |\n| 3 | **Formula** | Mathematical equations and formulas |\n| 4 | **List item** | Bulleted and numbered list items |\n| 5 | **Page footer** | Footer content and page numbers |\n| 6 | **Page header** | Header content and titles |\n| 7 | **Picture** | Images, figures, and graphics |\n| 8 | **Section header** | Section and subsection headings |\n| 9 | **Table** | Tabular data and structures |\n| 10 | **Text** | Regular paragraph text |\n| 11 | **Title** | Document and chapter titles |\n\n### Dataset Characteristics\n\n- **Domain Coverage**: Academic papers, technical documents, reports\n- **Language**: Primarily English with multilingual support\n- **Quality**: High-quality annotations with bounding boxes and labels\n- **Diversity**: Various document layouts, fonts, and formatting styles\n\nFor detailed information about the dataset, visit the [DocLayNet repository](https://github.com/DS4SD/DocLayNet).\n\n## 🔧 Development\n\n### Local Development Setup\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/huridocs/pdf-document-layout-analysis.git\n   cd pdf-document-layout-analysis\n   ```\n\n2. **Create virtual environment:**\n   ```bash\n   make install_venv\n   ```\n\n3. **Activate environment:**\n   ```bash\n   source .venv/bin/activate\n   ```\n\n4. **Install dependencies:**\n   ```bash\n   make install\n   ```\n\n### Code Quality\n\n**Format code:**\n```bash\nmake formatter\n```\n\n**Check formatting:**\n```bash\nmake check_format\n```\n\n### Testing\n\n**Run tests:**\n```bash\nmake test\n```\n\n**Integration tests:**\n```bash\n# Tests are located in src/tests/integration/\npython -m pytest src/tests/integration/test_end_to_end.py\n```\n\n### Docker Development\n\n**Build and start:**\n```bash\n# Standard start (includes translation features)\nmake start\n\n# Start without translation support\nmake start_no_translation\n\n# Start in detached mode (API only, no UI)\nmake start_detached\n\n# Start in detached mode with GPU (API only, no UI)\nmake start_detached_gpu\n\n# Force CPU mode with translation\nmake start_no_gpu\n```\n\n**Clean up Docker resources:**\n```bash\n# Stop all services\nmake stop\n\n# Remove containers\nmake remove_docker_containers\n\n# Remove images\nmake remove_docker_images\n```\n\n### Project Structure\n\n```\npdf-document-layout-analysis/\n├── src/                    # Source code\n│   ├── domain/            # Business entities\n│   ├── use_cases/         # Application logic\n│   ├── adapters/          # External integrations\n│   ├── ports/             # Interface definitions\n│   ├── drivers/           # Framework configurations\n│   ├── app.py             # FastAPI application\n│   └── gradio_app.py      # Gradio web interface\n├── test_pdfs/             # Test PDF files\n├── models/                # ML model storage\n├── docker-compose.yml     # Docker configuration\n├── Dockerfile             # FastAPI container definition\n├── Dockerfile.gradio      # Gradio container definition\n├── justfile              # Development commands (just)\n├── pyproject.toml        # Python project configuration\n└── requirements.txt      # Python dependencies\n```\n\n### Environment Variables\n\nKey configuration options:\n\n```bash\n# OCR configuration\nOCR_SOURCE=/tmp/ocr_source\n\n# Model paths (auto-configured)\nMODELS_PATH=./models\n\n# Service configuration  \nHOST=0.0.0.0\nPORT=5060\n\n# Translation configuration (when using translation features)\nOLLAMA_HOST=http://ollama:11434  # Ollama service endpoint\n```\n\n### Adding New Features\n\n1. **Domain Logic**: Add entities in `src/domain/`\n2. **Use Cases**: Implement business logic in `src/use_cases/`\n3. **Adapters**: Create integrations in `src/adapters/`\n4. **Ports**: Define interfaces in `src/ports/`\n5. **Controllers**: Add endpoints in `src/adapters/web/`\n\n### Debugging\n\n**View logs:**\n```bash\ndocker compose logs -f\n```\n\n**Access container:**\n```bash\ndocker exec -it pdf-document-layout-analysis /bin/bash\n```\n\n**Free up disk space:**\n```bash\nmake free_up_space\n```\n\n### Order of Output Elements\n\nThe service returns SegmentBox elements in a carefully determined reading order:\n\n#### Reading Order Algorithm\n\n1. **Poppler Integration**: Uses [Poppler](https://poppler.freedesktop.org) PDF-to-XML conversion to establish initial token reading order\n2. **Segment Averaging**: Calculates average reading order for multi-token segments\n3. **Type-Based Sorting**: Prioritizes content types:\n   - **Headers** placed first\n   - **Main content** in reading order\n   - **Footers and footnotes** placed last\n\n#### Non-Text Elements\n\nFor segments without text (e.g., images):\n- Processed after text-based sorting\n- Positioned based on nearest text segment proximity\n- Uses spatial distance as the primary criterion\n\n### Advanced Table and Formula Extraction\n\n#### Default Behavior\n- **Formulas**: Automatically extracted as LaTeX format in the `text` property\n- **Tables**: Basic text extraction included by default\n\n#### Enhanced Table Extraction\n\nParse tables and extract them in HTML format by setting `parse_tables_and_math=true`:\n\n```bash\ncurl -X POST -F 'file=@document.pdf' -F 'parse_tables_and_math=true' http://localhost:5060\n```\n\n\n#### Extraction Engines\n- **Formulas**: [LaTeX-OCR](https://github.com/lukas-blecher/LaTeX-OCR)\n- **Tables**: [RapidTable](https://github.com/RapidAI/RapidTable)\n\n\n## 📈 Benchmarks\n\n### Performance\n\nVGT model performance on PubLayNet dataset:\n\n| Metric | Overall | Text | Title | List | Table | Figure |\n|--------|---------|------|-------|------|-------|--------|\n| **F1 Score** | **0.962** | 0.950 | 0.939 | 0.968 | 0.981 | 0.971 |\n\n\u003e 📊 **Comparison**: View comprehensive model comparisons at [Papers With Code](https://paperswithcode.com/sota/document-layout-analysis-on-publaynet-val)\n\n### Speed\n\nPerformance benchmarks on 15-page academic documents:\n\n| Model | Hardware | Speed (sec/page) | Use Case |\n|-------|----------|------------------|----------|\n| **LightGBM** | CPU (i7-8700 3.2GHz) | **0.42** | Fast processing |\n| **VGT** | GPU (GTX 1070) | **1.75** | High accuracy |\n| **VGT** | CPU (i7-8700 3.2GHz) | 13.5 | CPU fallback |\n\n### Performance Recommendations\n\n- **GPU Available**: Use VGT for best accuracy-speed balance\n- **CPU Only**: Use LightGBM for optimal performance\n- **Batch Processing**: LightGBM for consistent throughput\n- **High Accuracy**: VGT with GPU for best results\n\n\n## 🌐 Installation of More Languages for OCR\n\nThe service uses Tesseract OCR with support for 150+ languages. The Docker image includes only common languages to minimize image size.\n\n### Installing Additional Languages\n\n#### 1. Access the Container\n```bash\ndocker exec -it --user root pdf-document-layout-analysis /bin/bash\n```\n\n#### 2. Install Language Packs\n```bash\n# Install specific language\napt-get update\napt-get install tesseract-ocr-[LANGCODE]\n```\n\n#### 3. Common Language Examples\n\n```bash\n# Korean\napt-get install tesseract-ocr-kor\n\n# German  \napt-get install tesseract-ocr-deu\n\n# French\napt-get install tesseract-ocr-fra\n\n# Spanish\napt-get install tesseract-ocr-spa\n\n# Chinese Simplified\napt-get install tesseract-ocr-chi-sim\n\n# Arabic\napt-get install tesseract-ocr-ara\n\n# Japanese\napt-get install tesseract-ocr-jpn\n```\n\n#### 4. Verify Installation\n\n```bash\ncurl http://localhost:5060/info\n```\n\n### Language Code Reference\n\nFind Tesseract language codes in the [ISO to Tesseract mapping](https://github.com/huridocs/pdf-document-layout-analysis/blob/main/src/adapters/infrastructure/ocr/languages.py).\n\n### Supported Languages\n\nCommon language codes:\n- `eng` - English\n- `fra` - French  \n- `deu` - German\n- `spa` - Spanish\n- `ita` - Italian\n- `por` - Portuguese\n- `rus` - Russian\n- `chi-sim` - Chinese Simplified\n- `chi-tra` - Chinese Traditional\n- `jpn` - Japanese\n- `kor` - Korean\n- `ara` - Arabic\n- `hin` - Hindi\n\n### Usage with Multiple Languages\n\n```bash\n# OCR with specific language\ncurl -X POST \\\n  -F 'file=@document.pdf' \\\n  -F 'language=fr' \\\n  http://localhost:5060/ocr \\\n  --output french_ocr.pdf\n```\n\n\n## 🔗 Related Services\n\nExplore our ecosystem of PDF processing services built on this foundation:\n\n### [PDF Table of Contents Extractor](https://github.com/huridocs/pdf-table-of-contents-extractor)\n🔍 **Purpose**: Intelligent extraction of structured table of contents from PDF documents\n\n**Key Features**:\n- Leverages layout analysis for accurate TOC identification\n- Hierarchical structure recognition\n- Multiple output formats supported\n- Integration-ready API\n\n### [PDF Text Extraction](https://github.com/huridocs/pdf-text-extraction)\n📝 **Purpose**: Advanced text extraction with layout awareness\n\n**Key Features**:\n- Content-type aware extraction\n- Preserves document structure\n- Reading order optimization\n- Clean text output with metadata\n\n### Integration Benefits\n\nThese services work seamlessly together:\n- **Shared Analysis**: Reuse layout analysis results across services\n- **Consistent Output**: Standardized JSON format for easy integration\n- **Scalable Architecture**: Deploy services independently or together\n- **Docker Ready**: All services containerized for easy deployment\n\n## 🤝 Contributing\n\nWe welcome contributions to improve the PDF Document Layout Analysis service!\n\n### How to Contribute\n\n1. **Fork the Repository**\n   ```bash\n   git clone https://github.com/your-username/pdf-document-layout-analysis.git\n   ```\n\n2. **Create a Feature Branch**\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n\n3. **Set Up Development Environment**\n   ```bash\n   make install_venv\n   make install\n   ```\n\n4. **Make Your Changes**\n   - Follow the Clean Architecture principles\n   - Add tests for new features\n   - Update documentation as needed\n\n5. **Run Tests and Quality Checks**\n   ```bash\n   make test\n   make check_format\n   ```\n\n6. **Submit a Pull Request**\n   - Provide clear description of changes\n   - Include test results\n   - Reference any related issues\n\n### Contribution Guidelines\n\n#### Code Standards\n- **Python**: Follow PEP 8 with 125-character line length\n- **Architecture**: Maintain Clean Architecture boundaries\n- **Testing**: Include unit tests for new functionality\n- **Documentation**: Update README and docstrings\n\n#### Areas for Contribution\n\n- 🐛 **Bug Fixes**: Report and fix issues\n- ✨ **New Features**: Add new endpoints or functionality\n- 📚 **Documentation**: Improve guides and examples\n- 🧪 **Testing**: Expand test coverage\n- 🚀 **Performance**: Optimize processing speed\n- 🌐 **Internationalization**: Add language support\n\n#### Development Workflow\n\n1. **Issue First**: Create or comment on relevant issues\n2. **Small PRs**: Keep pull requests focused and manageable\n3. **Clean Commits**: Use descriptive commit messages\n4. **Documentation**: Update relevant documentation\n5. **Testing**: Ensure all tests pass\n\n### Getting Help\n\n- 📚 **Documentation**: Check this README and inline docs\n- 💬 **Issues**: Search existing issues or create new ones\n- 🔍 **Code**: Explore the codebase structure\n- 📧 **Contact**: Reach out to maintainers for guidance\n\n---\n\n### License\n\nThis project is licensed under the terms specified in the [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuridocs%2Fpdf-document-layout-analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuridocs%2Fpdf-document-layout-analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuridocs%2Fpdf-document-layout-analysis/lists"}