pdf-document-layout-analysis: Docker PDF Layout Service

What HURIDOCS Layout Analysis Is Designed to Process

pdf-document-layout-analysis addresses a specific problem in PDF handling: a PDF stores marks and text on a page, but a downstream application often needs to know what those marks represent. The service identifies page regions such as text, titles, pictures, tables, and formulas, assigns classifications to them, and establishes their reading order. That matters for applications that need more than a flat text dump, such as document conversion, search indexing, archival processing, or later machine analysis.

The repository targets developers and document-processing teams rather than occasional PDF readers. It exposes a FastAPI REST service for integrations and a Gradio interface for interactive uploads and visual inspection. The documented capabilities extend beyond layout classification. They include OCR, table extraction as HTML, formula extraction as LaTeX, table-of-contents extraction, output in JSON, Markdown, and HTML, segmentation overlays, and translation through Ollama.

The service is therefore broader than a classifier with a single prediction endpoint. It is intended to turn pages into structured regions and then pass those regions through extraction or conversion stages. Even so, the README does not define guarantees for unusual page designs, handwriting, mixed-language documents, corrupted PDFs, or region-level confidence thresholds. Those cases need validation against documents from the intended workload rather than reliance on the feature list alone.

VGT, LightGBM, and the PDF Analysis Path

The README presents two analysis choices. VGT is described as the high-accuracy option, while LightGBM models are offered as the faster processing path. Both fit the same service-level purpose: segmenting a PDF and classifying its page elements. The choice is exposed through the analysis request rather than requiring separate applications.

The REST layer runs through Gunicorn with `uvicorn.workers.UvicornWorker`, and the repository entry point is `drivers.rest.app:app` under `src`. The Python dependency set supplies the document and model machinery: PyMuPDF, `pdf-annotate`, `pdf2image`, OpenCV, PyTorch, Transformers, Hugging Face Hub, LightGBM, Shapely, and SciPy. Extraction adds dedicated packages including `rapid-table`, `rapidocr`, `pix2tex`, and `latex2mathml`. Translation uses the Ollama client, while `pypandoc` is listed for document conversion.

This dependency surface indicates a pipeline with rendering, geometry, classification, and format-specific extraction, although the repository files do not expose the complete internal control flow. The README calls the design Clean Architecture and describes a modular service. Operationally, `docker-compose.yml` makes the deployment path explicit: clients send PDF requests to port 5060, the REST container performs analysis, and the Gradio container calls that API through `API_BASE_URL`. The Ollama container is available at port 11434 for translation-related work. Exact intermediate region objects and model checkpoint loading are not documented in the repository files shown here.

Starting the Docker Compose Stack and Sending a PDF

The documented first step assumes Docker, the repository files, and either `make` or `just`. The README requires Docker Desktop 4.25.0 or newer and lists Docker Engine 20.10 and Docker Compose 2.0 or newer. It also states a minimum of 2 GB RAM and 10 GB of disk space for models and dependencies. Python 3.10 or newer applies to local development.

Start the services from the repository root. This invokes the project's defined startup command rather than constructing a custom Docker invocation.

make start

The README states that the Gradio interface becomes available at `http://localhost:7860`, while the REST API listens at `http://localhost:5060`. The Compose file maps those ports from separate containers. The main analysis service waits for Ollama to pass its health check, and the GUI waits for both Ollama and the API service.

Before uploading a document, the documented status request asks the REST service for its information.

curl http://localhost:5060/info

For a first real analysis, submit a local PDF to the REST endpoint.

curl -X POST -F 'file=@/path/to/your/document.pdf' http://localhost:5060

The placeholder path must be replaced with an existing PDF. The README associates this request with VGT analysis. To request the faster LightGBM path, add the documented multipart field.

curl -X POST -F 'file=@/path/to/your/document.pdf' -F "fast=true" http://localhost:5060

Stop the documented stack with the following command when the request is complete.

make stop

CPU Compose Deployment and the Optional GPU Path

The default `docker-compose.yml` selects an Ubuntu 24.04 builder, installs the CPU PyTorch wheel, and sets `FORCE_CUDA` to `0`. This is the relevant path when a workstation does not provide an NVIDIA GPU. The repository also contains `docker-compose-gpu.yml` and `select_gpu_stack.sh`, while the general Dockerfile defaults to a CUDA 12.6 build.

That difference matters because model deployment is not just an API setting. The README lists an optional 5 GB of GPU memory, although it also says processing falls back to CPU when a GPU is unavailable. Multi-core CPUs are recommended. The service should therefore be treated as a containerized analysis workload with model storage and framework dependencies, not as a lightweight text extractor.

The standard Compose file starts three named services: `pdf-document-layout-analysis`, `pdf-document-layout-analysis-gui`, and `ollama`. Ollama exposes `11434:11434`, the API exposes `5060:5060`, and the GUI exposes `7860:7860`. The main service receives `OLLAMA_HOST=http://ollama:11434`; the GUI receives `API_BASE_URL=http://pdf-document-layout-analysis:5060`. All three share a bridge network named `pdf-analysis-network`.

The repository supports Windows-oriented files through `run.bat` and `run.ps1`, but the README's quick start is based on `make`. It does not document every host prerequisite for ARM64 or Grace-Blackwell systems, so a non-x86 deployment should begin by checking `select_gpu_stack.sh` and the GPU Compose file rather than assuming the CPU configuration applies.

Layout Models as a Speed and Accuracy Trade-Off

The most concrete choice inside this project is between VGT and LightGBM. VGT is presented as the accuracy-oriented model, while LightGBM is presented as the faster route. That difference gives evaluators a practical way to split testing: compare output quality on representative pages before treating latency as the deciding criterion, then repeat with the `fast=true` option after establishing a baseline.

The README does not publish latency figures, memory consumption for individual documents, or an accuracy table in its features section. It labels model areas as benchmarks elsewhere in its table of contents, but the actual benchmark data is not included in the README excerpt. Consequently, there is no supported basis for promising a processing time or a fixed accuracy gain.

This distinction matters for document-processing pipelines with different costs for errors. A pipeline that indexes search results may tolerate some classification mistakes, while one that extracts formulas or tables for downstream publication may need closer review. A faster model can also change the capacity of an online API, but no throughput measurement is documented, so such an inference should not be treated as confirmed.

VGT and LightGBM are real alternatives within the same project, not merely naming options. VGT is a Vision Grid Transformer path, while LightGBM represents a tree-based classification path. The public interface remains the PDF upload endpoint in both cases. That makes it possible to keep storage, API integration, and downstream parsing code stable while changing the analysis mode during evaluation.

OCR, Extraction, Translation, and Boundary Cases

OCR support is listed as covering more than 150 languages through Tesseract OCR, although the Python dependency list also includes `rapidocr`. The README also advertises table extraction as HTML and formula extraction as LaTeX. These are useful distinctions, but the documentation does not specify how detected regions are routed to each extractor, how extraction errors are represented in API responses, or whether every layout class can be converted directly into every output format.

Translation depends on Ollama. The Compose configuration starts an Ollama service and injects `OLLAMA_HOST`, so translation is integrated into the deployment rather than being a fully independent text-processing operation. The README does not name the required Ollama model, model configuration, or language-selection mechanism. A deployment that expects automatic translation must therefore verify that the appropriate Ollama model is present; the Compose file does not itself show a model download command.

OCR and scanned-document conversion also introduce failure boundaries. Missing OCR language data, unusual layouts, embedded images with weak text contrast, and pages that mix text with diagrams can affect extraction even when layout detection succeeds. The README does not document confidence scores, retry behavior, page limits, upload limits, request authentication, or multi-document batch processing. It also does not state whether submitted PDFs are written to disk or retained by a container. Those omissions should limit production claims until they are resolved directly against the service configuration.

The Apache-2.0 license supports reuse and modification under its terms, but this review does not interpret those terms. Organizations should preserve the license file and review dependency licenses separately, particularly because the image includes numerous Python packages, model assets, and a pinned Git dependency named `pdf-features`.

Maintenance Signals, Version Pinning, and Upgrade Cost

The repository is not archived. Its last push was on 2026-10-06, and release `v0.0.37` carries the same date. The project version in `pyproject.toml` is `2026.04.28.01`, which differs from the release tag. That distinction matters for automated tooling: the Python package metadata and release artifacts are not represented by one obvious shared version string.

The project uses exact dependency pins rather than broad ranges. Examples include `fastapi==0.136.1`, `pydantic==2.13.3`, `torch==2.11.0`, `transformers==5.6.2`, and `lightgbm==4.6.0`. It also pins `pdf-features` to the Git revision dated `2026.4.27.1`. Reproducibility improves because builds select known versions, but upgrades require deliberate work. A framework update can affect model loading, PDF rendering, OCR, extraction, or API behavior, and the repository files do not provide an explicit compatibility matrix.

Container images also carry a model and dependency footprint. The README calls for 10 GB of disk space and describes Docker Desktop as the normal installation route. Rebuilding images, downloading model assets, and validating a new version adds operational work beyond changing an application dependency. The presence of `dev-requirements.txt`, `pyproject.toml`, a `Makefile`, a `justfile`, and GitHub configuration indicates separate development and deployment workflows, but the README does not give the complete release or rollback procedure.

For adoption, verify the `LICENSE`, pinned `requirements.txt`, container definitions, and model requirements as one upgrade unit. The specific boundary is clear: a source update is not automatically an image upgrade because model assets and compiled packages must also resolve in the intended CPU or GPU stack.

Editorial conclusion

Adopt this service when a Python or container-based workflow needs classified PDF regions, reading order, OCR, or structured extraction. Do not adopt it if a single small script or CPU-only environment without container support is the primary requirement. Before adoption, verify the VGT versus LightGBM choice against representative documents, confirm available RAM, disk, and optional GPU capacity, and inspect the Apache-2.0 files that your distribution process must retain.

Frequently asked questions

Official sources

1. huridocs/pdf-document-layout-analysis on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases