YOLOv8 for document region detection — synthetic training data

What YOLOv8 is — and why document teams use it

The bounding-box data problem

The YOLO label format, briefly

The YOLO label format is designed to be trivially human-readable. Each image has a sibling .txt file containing one line per object — no XML, no JSON, no nested structures.

<class_id> <center_x> <center_y> <width> <height>

class_id — zero-indexed integer matching the names list in your data.yaml.

center_x, center_y — box center, normalized to [0, 1] against the image width and height.

width, height — box dimensions, also normalized to [0, 1].

Pairing the labels.txt with a data.yaml that points at your train/ and val/ image directories is the full dataset contract. That's the whole interface — which is what makes YOLOv8 datasets so portable and what makes them easy for us to emit mechanically.

From our WordAnnotation to YOLO format

Internally SymageDocs represents every rendered field as a WordAnnotation with pixel-space x, y, width, height. Converting to YOLOv8's normalized center-xywh format is five lines — here's the exact snippet our fixture generator uses:

# From our WordAnnotation (pixel coords) to YOLOv8 normalized labels.
PAGE_W, PAGE_H = 612.0, 792.0  # US Letter points
for w in words:
    cx = (w.x + w.width / 2) / PAGE_W
    cy = (w.y + w.height / 2) / PAGE_H
    nw, nh = w.width / PAGE_W, w.height / PAGE_H
    print(f"{CLASS_MAP[w.field_type]} {cx:.6f} {cy:.6f} {nw:.6f} {nh:.6f}")

That's it. The CLASS_MAP keys come from each WordAnnotation's field_type, so you can taxonomize regions however your downstream extractor expects them.

Training YOLOv8 on your synthetic dataset

Once you've generated a batch and written out the labels, training is a one-liner in the Ultralytics Python API. Point model.train at the data.yaml we emitted in the tabs above and kick it off:

from ultralytics import YOLO

# Start from a pretrained YOLOv8 nano backbone — swap for yolov8s/m/l/x as needed.
model = YOLO("yolov8n.pt")

# Train on the synthetic document-region dataset emitted by SymageDocs.
results = model.train(
    data="data.yaml",
    epochs=100,
    imgsz=1280,       # documents benefit from higher input resolution
    batch=16,
    patience=20,
)

For document images, imgsz=1280 is usually the right default — tiny fields like invoice numbers and decimal-point totals get squashed at the 640 default. If training hardware is the bottleneck, drop to yolov8n.pt as the backbone; if you have the GPU budget, yolov8l.pt is the sweet spot for document-region accuracy in our benchmarks.

When you take the trained model to real documents, hold out a few hundred hand-labeled real pages as your validation split. Synthetic training data is a powerful prior, but the sim-to-real gap is real — tracking mAP on a real validation set from day one is the difference between a detector that looks great in Tensorboard and one that actually ships. Most teams iterate by mixing a small real-document seed set with the bulk of the synthetic data and annealing the synthetic ratio down over training.

Two-stage pipelines: YOLO regions, then transformer extraction

Frequently asked questions

How many synthetic YOLOv8 training examples can I generate?

There is no per-dataset cap. Each generated document produces one image plus a matching YOLO labels.txt with every field region annotated. Teams typically start with 2,000–10,000 pages per form type for a solid first-stage region detector, then scale to tens of thousands as they add layout variants.

What's the license on SymageDocs-generated YOLOv8 training data?

You own the output. Generated documents and their bounding-box labels are yours to train on, redistribute internally, or ship as part of a derived model. There are no data-use clawbacks, no royalty obligations, and no clauses restricting commercial use of downstream models.

Which YOLO class taxonomy should I use for document region detection?

Our fixture uses a compact six-class schema — party, header, line_item, total, date, other — which maps cleanly to invoice, receipt, and form layouts. You can refine this by swapping the CLASS_MAP in the conversion step to match your own downstream extractor's region vocabulary.

How many epochs should I train YOLOv8 on synthetic document data?

Start with 100 epochs at imgsz=1280 with early stopping (patience=20). Synthetic data converges faster than real annotated documents because the labels are noise-free; most teams see validation mAP@0.5 plateau between epochs 40 and 80. Hold a small real-document validation split to track the sim-to-real gap.

Does this work with Ultralytics YOLOv9, YOLOv10, or YOLOv11?

Yes. The YOLO labels.txt format and data.yaml schema are shared across the Ultralytics family, so the same SymageDocs output drops into YOLOv8, YOLOv9, YOLOv10, and YOLOv11 training loops with no changes. Swap the pretrained weights file (e.g. yolov10n.pt) and the rest of the pipeline is identical.