### Install DocLayout-YOLO via Pip

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Install the library using pip for quick setup.

```bash
# Via pip
pip install doclayout-yolo
```

--------------------------------

### Complete Prediction Pipeline Example

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

A comprehensive example demonstrating the initialization of a YOLOv10 model, creation of a custom predictor, setup of the model and source, and running inference with streaming. This example shows how to access detection results and bounding box information.

```python
from doclayout_yolo import YOLOv10
from doclayout_yolo.engine.predictor import BasePredictor
import cv2

# Initialize model
model = YOLOv10("yolov10n.pt")

# Create custom predictor
predictor = BasePredictor(overrides={
    'conf': 0.5,
    'imgsz': 640,
    'device': 0,
    'save': True,
    'project': 'results',
    'name': 'predictions'
})

# Setup model and source
predictor.setup_model(model.model)
predictor.setup_source("image.jpg")

# Run inference with streaming
for results in predictor.stream_inference(source="image.jpg"):
    print(f"Detections: {len(results)}")
    
    # Access predictions
    for r in results:
        if r.boxes is not None:
            for box in r.boxes:
                print(f"Box: {box.xyxy}, Conf: {box.conf}")
```

--------------------------------

### Install DocLayout-YOLO from Source

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/README.md

Install the package in editable mode after setting up the environment.

```bash
pip install -e .
```

--------------------------------

### Install DocLayout-YOLO via Conda

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Set up a Conda environment and install the library.

```bash
# Via conda
conda create -n doclayout python=3.10
conda activate doclayout
pip install doclayout-yolo
```

--------------------------------

### train()

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Starts the model training process using the provided configuration. It handles the entire training pipeline from setup to saving results.

```APIDOC
## train()

### Description
Starts model training with configuration. This method orchestrates the entire training pipeline, including DDP setup, model and optimizer initialization, and the training loop with validation.

### Method
```python
def train(self) -> None
```

### Returns
None

### Training Pipeline
1. World size detection (single/multi-GPU)
2. DDP setup if multi-GPU
3. Model initialization
4. Optimizer setup
5. Learning rate scheduler configuration
6. Training loop with validation
7. Results saving

### Example
```python
trainer = BaseTrainer(overrides={
    'data': 'coco8.yaml',
    'epochs': 100
})
trainer.train()
```
```

--------------------------------

### Start Model Training

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Initiates the model training process. It handles world size detection, DDP setup, model, optimizer, and scheduler initialization, followed by the training loop and results saving.

```python
trainer = BaseTrainer(overrides={
    'data': 'coco8.yaml',
    'epochs': 100
})
trainer.train()
```

--------------------------------

### Device Specification Examples

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/types.md

Demonstrates how to specify the device for model operations, supporting single GPU, multi-GPU, and CPU.

```python
model.predict("image.jpg", device="cuda:0")  # Single GPU
model.train(data="data.yaml", device=[0, 1])  # Multi-GPU
model.predict("image.jpg", device="cpu")  # CPU-only
```

--------------------------------

### Install DocLayout-YOLO for Inference

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/README.md

If only inference is needed, install the package directly via pip.

```bash
pip install doclayout-yolo
```

--------------------------------

### Install PyMuPDF

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/mesh-candidate_bestfit/README.md

Install the PyMuPDF library, which is required for rendering operations. Ensure you are in the correct directory before running the command.

```bash
cd mesh-candidate_bestfit
pip install pymupdf==1.23.7
```

--------------------------------

### Setup Training Environment

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Configures the training environment including model, optimizer, scheduler, and other necessary components. This is typically called automatically during the training process.

```python
# Called automatically during train()
trainer._setup_train(rank=0)
```

--------------------------------

### SDK Prediction Example

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/README.md

Example demonstrating how to use the DocLayout-YOLO SDK for image prediction, including loading the model, performing prediction, and saving the annotated result.

```python
import cv2
from doclayout_yolo import YOLOv10

# Load the pre-trained model
model = YOLOv10("path/to/provided/model")

# Perform prediction
det_res = model.predict(
    "path/to/image",   # Image to predict
    imgsz=1024,        # Prediction image size
    conf=0.2,          # Confidence threshold
    device="cuda:0"    # Device to use (e.g., 'cuda:0' or 'cpu')
)

# Annotate and save the result
annotated_frame = det_res[0].plot(pil=True, line_width=5, font_size=20)
cv2.imwrite("result.jpg", annotated_frame)
```

--------------------------------

### Install for CPU Only

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Install PyTorch for CPU-only execution and the doclayout-yolo package. This is suitable for systems without a compatible GPU.

```bash
pip install torch torchvision torchaudio
pip install doclayout-yolo
```

--------------------------------

### Instantiate BaseTrainer

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Example of how to instantiate the BaseTrainer with specific configuration overrides for model, data, epochs, batch size, and device.

```python
from doclayout_yolo.engine.trainer import BaseTrainer

trainer = BaseTrainer(overrides={
    'model': 'yolov10n.pt',
    'data': 'coco8.yaml',
    'epochs': 100,
    'batch': 16,
    'device': 0
})
```

--------------------------------

### Setup YOLO Model

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Initializes the YOLO model with a specified path or module and optionally prints model information. Use this to load your trained model weights.

```python
predictor.setup_model("yolov10n.pt", verbose=True)
```

--------------------------------

### Log Batch Statistics Output

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Example output format for logging batch training statistics during training.

```bash
# Output during training
Epoch 1/100 [64/625] Loss: 2.34 | LR: 0.01 | ETA: 12:34
```

--------------------------------

### Initialize YOLOv10 Model

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/yolov10.md

Examples demonstrating how to initialize a YOLOv10 model instance from different sources like local checkpoints, Hugging Face Hub, or configuration files. Supports verbose output.

```python
from doclayout_yolo import YOLOv10

# Load from local checkpoint
model = YOLOv10("yolov10n.pt")

# Load from Hugging Face
model = YOLOv10("juliozhao/DocLayout-YOLO-DocStructBench")

# Load from configuration file
model = YOLOv10("config.yaml")

# With verbose output
model = YOLOv10("yolov10m.pt", verbose=True)
```

--------------------------------

### Install with GPU Support

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Install PyTorch with CUDA 11.8 support and the doclayout-yolo package. Ensure your system has compatible NVIDIA drivers and CUDA toolkit installed.

```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install doclayout-yolo
```

--------------------------------

### Complete YOLOv10 Training Example

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Demonstrates a full training cycle with YOLOv10, including model initialization, defining a custom epoch logging callback, and accessing final training results. Use this for standard training tasks.

```python
from doclayout_yolo import YOLOv10

# Initialize model
model = YOLOv10("yolov10n.pt")

# Define custom callback
def log_epoch(trainer):
    print(f"\nEpoch {trainer.epoch + 1}/{trainer.epochs}")
    if trainer.metrics:
        metrics = trainer.metrics
        if 'box' in metrics:
            print(f"  mAP50: {metrics['box']['map50']:.3f}")
            print(f"  Loss: {trainer.loss:.3f}")

# Train with custom settings
metrics = model.train(
    data="coco8.yaml",
    epochs=100,
    batch=32,
    imgsz=640,
    device=0,
    patience=50,
    augment=True,
    lr0=0.01
)

# Access training results
print(f"Final metrics: {metrics}")
print(f"Best model: {model.ckpt_path}")
```

--------------------------------

### Setup Inference Source

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Configures the input source for inference, which can be a single image, a list of images, or a video file. This method also sets up internal dataset and source type attributes.

```python
predictor.setup_source("image.jpg")
```

```python
predictor.setup_source(["img1.jpg", "img2.jpg"])
```

```python
predictor.setup_source("video.mp4")
```

--------------------------------

### Get or Create Model

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Loads a pretrained model or initializes a new one from a configuration file. Use for loading weights, specifying model architecture, or for transfer learning.

```python
model = trainer.get_model(weights='yolov10n.pt')

# Load from configuration
model = trainer.get_model(cfg='yolov10m.yaml')

# Transfer learning
model = trainer.get_model(weights='pretrained.pt')
```

--------------------------------

### Image Size (imgsz) Specification Examples

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/types.md

Illustrates different ways to specify image dimensions for model processing, including square, custom, and string formats.

```python
results = model.predict("image.jpg", imgsz=640)
results = model.predict("image.jpg", imgsz=(1024, 768))
results = model.predict("image.jpg", imgsz=1280)
```

--------------------------------

### Instantiate Results Class Directly

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/results.md

Example demonstrating how to directly instantiate the Results class with inference data. This is typically handled internally by model prediction methods.

```python
# Typically created by model.predict(), but can be instantiated directly
from doclayout_yolo.engine.results import Results
import numpy as np

img = np.random.randint(0, 255, (640, 640, 3), dtype=np.uint8)
results = Results(
    orig_img=img,
    path="image.jpg",
    names={0: "text", 1: "figure"},
    boxes=torch.tensor([[100, 100, 200, 200, 0.95, 0]])
)
```

--------------------------------

### Multithreaded YOLO Tracking Example

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/doclayout_yolo/trackers/README.md

This script demonstrates how to load two different YOLO models, assign them to track objects in two separate video files concurrently using threads, and then wait for both threads to complete before closing the display windows. Ensure the video files and model paths are correctly specified.

```Python
# Load the models
model1 = YOLO("yolov8n.pt")
model2 = YOLO("yolov8n-seg.pt")

# Define the video files for the trackers
video_file1 = "path/to/video1.mp4"
video_file2 = "path/to/video2.mp4"

# Create the tracker threads
tracker_thread1 = threading.Thread(
    target=run_tracker_in_thread, args=(video_file1, model1), daemon=True
)
tracker_thread2 = threading.Thread(
    target=run_tracker_in_thread, args=(video_file2, model2), daemon=True
)

# Start the tracker threads
tracker_thread1.start()
tracker_thread2.start()

# Wait for the tracker threads to finish
tracker_thread1.join()
tracker_thread2.join()

# Clean up and close windows
cv2.destroyAllWindows()
```

--------------------------------

### Document Extraction Pipeline

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/yolov10.md

A complete example demonstrating the document layout analysis and element extraction pipeline, from model initialization to processing detections.

```APIDOC
## Document Extraction Pipeline

### Description
Complete example for document layout analysis and element extraction.

### Method Signature
`YOLOv10.from_pretrained(model_name)` and `model.predict(source, ...)`

### Parameters
- **model_name** (str): The name of the pre-trained model to load (e.g., "juliozhao/DocLayout-YOLO-DocStructBench").
- **source** (str): Path to the document image.
- **imgsz** (int): Image size for processing.
- **conf** (float): Confidence threshold for detections.

### Request Example
```python
from doclayout_yolo import YOLOv10
from pathlib import Path

# Initialize model
model = YOLOv10.from_pretrained("juliozhao/DocLayout-YOLO-DocStructBench")

# Process documents
doc_dir = Path("documents/")
for doc_path in doc_dir.glob("*.jpg"):
    # Perform detection
    results = model.predict(str(doc_path), imgsz=1024, conf=0.25)
    
    for r in results:
        # Get detected elements
        detections = {
            'file': str(doc_path),
            'elements': []
        }
        
        for box in r.boxes:
            element = {
                'type': r.names[int(box.cls)],
                'confidence': float(box.conf),
                'bbox': box.xyxy.squeeze().tolist()
            }
            detections['elements'].append(element)
        
        # Process detections
        print(f"Found {len(detections['elements'])} elements in {doc_path.name}")
```

### Response
- **detections** (dict): A dictionary containing information about the detected elements in a document:
  - `file` (str): The path to the processed document.
  - `elements` (list): A list of detected elements, where each element is a dictionary with:
    - `type` (str): The type of the detected element (e.g., 'paragraph', 'title').
    - `confidence` (float): The confidence score of the detection.
    - `bbox` (list): The bounding box coordinates [x1, y1, x2, y2] of the element.
```

--------------------------------

### Load YOLOv10 Model Variants

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/yolov10.md

Examples for loading different YOLOv10 model variants, such as nano, large, and extra-large, suitable for various performance and accuracy needs.

```python
# Nano model for edge devices
model_nano = YOLOv10("yolov10n.pt")

# Large model for high accuracy
model_large = YOLOv10("yolov10l.pt")

# Extra large for maximum accuracy
model_xlarge = YOLOv10("yolov10x.pt")
```

--------------------------------

### Train YOLOv10 Model via CLI

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/configuration.md

Use this command to start training a YOLOv10 detection model. Specify dataset, model, epochs, image size, batch size, and device.

```bash
yolo detect train data=coco8.yaml model=yolov8n.pt epochs=100 imgsz=640 batch=16 device=0
```

--------------------------------

### Use Custom Tracker Configuration via CLI

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/doclayout_yolo/trackers/README.md

Execute the tracker from the command line, specifying a custom YAML configuration file for advanced tracking setups. Ensure the YAML file exists and is correctly formatted.

```bash
# Load the model and run the tracker with a custom configuration file using the command line interface
yolo track model=yolov8n.pt source="https://youtu.be/LNwODJXcvt4" tracker='custom_tracker.yaml'
```

--------------------------------

### Get Model Information

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/model.md

Logs or returns model information. Can display detailed architecture or a summary, and either print to console or return as a list.

```python
model.info(detailed=False, verbose=True)
```

```python
info = model.info(detailed=True, verbose=False)
```

```python
model.info(detailed=True, verbose=True)
```

--------------------------------

### Configuration Reference

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

A comprehensive guide to all configuration parameters used in DocLayout-YOLO, covering training hyperparameters, validation settings, prediction parameters, export options, dataset formats, and command-line usage.

```APIDOC
## Configuration Reference

### Description
Complete guide to all configuration parameters.

### Topics
- Training hyperparameters
- Validation settings
- Prediction/inference parameters
- Export options
- Dataset YAML format
- Command-line usage
- Environment variables
```

--------------------------------

### YAML Configuration for DocLayout-YOLO Training

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/configuration.md

Define training parameters, dataset paths, class information, and hyperparameters using a YAML configuration file. This allows for structured and reproducible training setups.

```yaml
# Training configuration
path: /path/to/datasets
train: train/images
val: val/images

nc: 10  # number of classes
names: # class names
  0: text
  1: figure
  2: table
  3: heading
  # ... more classes

# Training hyperparameters
epochs: 100
batch: 32
imgsz: 640
device: 0
optimizer: SGD
lr0: 0.01
lrf: 0.01
momentum: 0.937
weight_decay: 0.0005

# Augmentation
augment: true
hsv_h: 0.015
hsv_s: 0.7
hsv_v: 0.4
degrees: 10
translate: 0.1
scale: 0.5
fliplr: 0.5
flipud: 0
mosaic: 1.0
```

--------------------------------

### Run YOLOv10 System Checks

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

Execute system checks for the YOLOv10 environment using the 'yolo checks' command. This helps identify potential issues with the installation or dependencies.

```bash
yolo checks  # Run system checks
```

--------------------------------

### Apply Function to Model Tensors

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/model.md

Demonstrates how to apply a function to the model's tensors that are not parameters or registered buffers. Includes examples for moving to CPU, GPU, or a specific device with a specified data type.

```python
# Move model to CPU
model = model.cpu()

# Move to GPU
model = model.cuda()

# Move to specific device with specific dtype
model = model.to('cuda:0', torch.float16)
```

--------------------------------

### setup_source

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Sets up the input source for inference, which can be an image, a list of images, a video, or a numpy array. It also configures the inference mode.

```APIDOC
## setup_source(source)

### Description
Sets up source and inference mode.

### Method Signature
```python
def setup_source(
    self,
    source: str | Path | list | np.ndarray | torch.Tensor
) -> None
```

### Parameters
#### Arguments
- **source** (str | Path | list | np.ndarray | torch.Tensor) - Required - Input image(s) or video.

### Returns
None

### Sets
- `imgsz` (tuple) — Validated image size
- `dataset` (Dataset) — Loaded inference dataset
- `source_type` (SourceType) — Type of input source
- `transforms` (dict) — Applied transformations

### Example
```python
predictor.setup_source("image.jpg")
predictor.setup_source(["img1.jpg", "img2.jpg"])
predictor.setup_source("video.mp4")
```
```

--------------------------------

### Dynamic Training Configuration Updates

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/configuration.md

This Python snippet shows how to dynamically update training configurations by calling the `train` method multiple times with different parameters. Setting `resume=False` ensures a fresh start with the new configuration.

```python
from doclayout_yolo import YOLOv10

model = YOLOv10("yolov10n.pt")

# Train with initial config
model.train(
    data="dataset.yaml",
    epochs=100,
    lr0=0.01
)

# Later training with different config
model.train(
    data="dataset2.yaml",
    epochs=50,
    lr0=0.001,
    resume=False  # Start fresh with new config
)
```

--------------------------------

### _setup_train

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Sets up the training environment, including the model, optimizer, scheduler, and other necessary components.

```APIDOC
## _setup_train(rank)

### Description
Setup training environment (model, optimizer, scheduler, etc.).

### Method
`_setup_train`

### Parameters
#### Path Parameters
- **rank** (int) - Optional - DDP rank (-1 for non-DDP)

### Request Example
```python
# Called automatically during train()
trainer._setup_train(rank=0)
```

### Response
#### Success Response
- **None** — None

### Initialization Details
- Move model to device
- Setup optimizer
- Configure learning rate scheduler
- Enable AMP if needed
- Initialize EMA
- Setup validators
```

--------------------------------

### ImportError Example - Missing Dependencies

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

Shows an ImportError when required dependencies for specific features or models are not installed. It provides bash commands to install the necessary packages.

```text
ImportError: 'hub-sdk>=0.0.6' is required for Ultralytics HUB models
```

```bash
# Install missing dependencies
pip install hub-sdk>=0.0.6

# Or install with all extras
pip install doclayout-yolo[export]  # For export features
pip install doclayout-yolo[explorer]  # For Explorer GUI
```

--------------------------------

### Thread-Safe Prediction Example

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Demonstrates how multiple threads can safely call the predict method concurrently using a threading lock. Ensure the model is initialized before running this example.

```python
# Multiple threads can safely call predict
import threading

def predict_image(path):
    results = model.predict(path)
    print(f"Processed {path}")

threads = [
    threading.Thread(target=predict_image, args=(f"img{i}.jpg",))
    for i in range(10)
]
for t in threads:
    t.start()
for t in threads:
    t.join()
```

--------------------------------

### Perform Tracking via Command Line Interface (CLI)

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/doclayout_yolo/trackers/README.md

Shows how to initiate tracking for various YOLO models (Detect, Segment, Pose, custom) and specify trackers like ByteTrack directly from the command line.

```bash
# Perform tracking with various models using the command line interface
yolo track model=yolov8n.pt source="https://youtu.be/LNwODJXcvt4"  # Official Detect model
yolo track model=yolov8n-seg.pt source="https://youtu.be/LNwODJXcvt4"  # Official Segment model
yolo track model=yolov8n-pose.pt source="https://youtu.be/LNwODJXcvt4"  # Official Pose model
yolo track model=path/to/best.pt source="https://youtu.be/LNwODJXcvt4"  # Custom trained model

# Track using ByteTrack tracker
yolo track model=path/to/best.pt tracker="bytetrack.yaml"
```

--------------------------------

### ImportError: Missing Export Dependencies

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

This error indicates that a required package for a specific export format is not installed. Install the necessary tools using pip for the desired export format.

```bash
# Install export tools for specific formats
pip install onnx           # ONNX export
pip install tensorflow     # TensorFlow exports
pip install openvino       # OpenVINO export
pip install coremltools    # CoreML export (macOS only)

```

--------------------------------

### ValueError: Invalid Export Format

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

This error is raised when an unsupported export format is requested or if required export dependencies are not installed. Use one of the supported formats and ensure necessary packages are installed.

```python
# Valid export formats
valid_formats = {
    'torchscript', 'onnx', 'openvino', 'coreml', 
    'tflite', 'pb', 'paddle', 'ncnn'
}

# Install export dependencies
pip install onnx openvino tensorflow  # For all formats

# Export to supported format
model.export(format='onnx', imgsz=640)

```

--------------------------------

### setup_model

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Initializes the YOLO model with specified parameters and sets it to evaluation mode. It can load a model from a path or use an existing module instance.

```APIDOC
## setup_model(model, verbose)

### Description
Initialize YOLO model with given parameters and set it to evaluation mode.

### Method Signature
```python
def setup_model(
    self,
    model: str | nn.Module = None,
    verbose: bool = True
) -> None
```

### Parameters
#### Arguments
- **model** (str | nn.Module) - Optional - Model path or module instance. Defaults to None.
- **verbose** (bool) - Optional - Print model information. Defaults to True.

### Returns
None

### Example
```python
predictor.setup_model("yolov10n.pt", verbose=True)
```
```

--------------------------------

### device

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Gets the device the model is running on (CPU or GPU). This property is useful for checking hardware utilization.

```APIDOC
## device

### Description
Get the device the model is running on.

### Returns
`torch.device` — Current device (CPU/GPU)

### Example
```python
print(predictor.device)  # device(type='cuda', index=0)
```
```

--------------------------------

### Load YOLO Models and Perform Tracking in Python

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/doclayout_yolo/trackers/README.md

Demonstrates how to load different YOLO models (Detect, Segment, Pose, custom) and perform tracking on a video source using the default tracker or a specified tracker like ByteTrack.

```python
from doclayout_yolo import YOLO

# Load an official or custom model
model = YOLO("yolov8n.pt")  # Load an official Detect model
model = YOLO("yolov8n-seg.pt")  # Load an official Segment model
model = YOLO("yolov8n-pose.pt")  # Load an official Pose model
model = YOLO("path/to/best.pt")  # Load a custom trained model

# Perform tracking with the model
results = model.track(
    source="https://youtu.be/LNwODJXcvt4", show=True
)  # Tracking with default tracker
results = model.track(
    source="https://youtu.be/LNwODJXcvt4", show=True, tracker="bytetrack.yaml"  # Tracking with ByteTrack tracker
)
```

--------------------------------

### Predictor Engine

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/SUMMARY.txt

The Predictor class handles the low-level details of the inference engine, managing model setup and execution for predictions.

```APIDOC
## Predictor Class

### Description
The `BasePredictor` class provides the core functionality for the inference engine, responsible for setting up the model and executing predictions efficiently.

### Methods
- **setup_model**: Initializes and configures the model for inference.
- **predict**: Executes the prediction process on input data.
- **stream_inference**: Handles inference for streaming data sources.

### Parameters
(Detailed parameter tables for each method are available in `api-reference/predictor.md`)

### Request Example
```python
from autodocs.doclayout_yolo import Predictor

predictor = Predictor(model='yolov10s.pt')
results = predictor.predict('video.mp4')
```

### Response
- **results**: The output of the inference process, typically an iterable of prediction results.
```

--------------------------------

### Trainer Engine

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/INDEX.md

The training engine responsible for managing the training process, including dataset handling, model setup, optimization, and validation.

```APIDOC
## Trainer Engine

### Description
The `BaseTrainer` class orchestrates the model training process, handling data loading, model configuration, optimization, and evaluation.

### Constructor
- `__init__(cfg, overrides, callbacks)`: Initializes the trainer with configuration and callbacks.

### Methods
- `train(epochs, ...)`: Starts the training process for a specified number of epochs.
- `_do_train()`: Internal method to perform a single training epoch.
- `get_dataset(dataset_path, ...)`: Retrieves and prepares the training dataset.
- `build_dataset(dataset_path, ...)`: Constructs the dataset object.
- `get_model(cfg)`: Retrieves and configures the model for training.
- `_setup_train()`: Internal method to set up the training environment.
- `build_optimizer(model)`: Builds the optimizer for training.
- `build_scheduler(optimizer)`: Builds the learning rate scheduler.
- `validate()`: Performs validation on the training model.
- `save_model(path)`: Saves the trained model weights.
- `resume_training(path)`: Resumes training from a checkpoint.
- `add_callback(callback)`: Adds a callback to the trainer.
- `set_callback(event_name, callback)`: Sets a specific callback for an event.
- `run_callbacks(event_name)`: Executes registered callbacks.

### Properties
- `metrics`: Access to training and validation metrics.
```

--------------------------------

### Accessing Configuration Arguments with SimpleNamespace

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/types.md

Illustrates how to use Python's `SimpleNamespace` to access configuration arguments via attributes and how to convert the namespace object to a dictionary.

```python
from types import SimpleNamespace

# Access via attribute
args = SimpleNamespace(imgsz=640, conf=0.5)
print(args.imgsz)  # 640

# Convert to dict
config_dict = vars(args)
print(config_dict)  # {'imgsz': 640, 'conf': 0.5}
```

--------------------------------

### imgsz

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Gets the validated image size (height, width) used by the model. This property is useful for understanding input image dimensions.

```APIDOC
## imgsz

### Description
Get the validated image size.

### Returns
`tuple` — Image size (height, width)

### Example
```python
print(predictor.imgsz)  # (640, 640) or (1024, 1024)
```
```

--------------------------------

### Programmatic Configuration with SimpleNamespace

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/configuration.md

Create and validate configuration arguments programmatically using Python's SimpleNamespace. This is useful for setting up training parameters dynamically before passing them to the configuration system.

```python
from types import SimpleNamespace
from doclayout_yolo.cfg import get_cfg

# Create configuration
args = SimpleNamespace(
    model="yolov10m.pt",
    data="coco8.yaml",
    epochs=100,
    batch=32,
    imgsz=640,
    device=0
)

# Convert to validated config
config = get_cfg(vars(args))
```

--------------------------------

### Display Core Training Parameters

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Print key training parameters such as current epoch, total epochs, loss, best fitness, device, and save directory.

```python
print(f"Epoch {trainer.epoch}/{trainer.epochs}")
print(f"Loss: {trainer.loss:.3f}")
print(f"Best fitness: {trainer.best_fitness:.3f}")
print(f"Device: {trainer.device}")
print(f"Save dir: {trainer.save_dir}")
```

--------------------------------

### FileNotFoundError Example

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

Illustrates a FileNotFoundError when a model file is not found or inaccessible. It shows how to check for file existence and use absolute paths to resolve this error.

```text
FileNotFoundError: [Errno 2] No such file or directory: 'nonexistent_model.pt'
```

```python
from pathlib import Path

# Check if file exists before loading
model_path = Path("model.pt")
if not model_path.exists():
    print(f"Model not found: {model_path}")
    # Download or create model

# Use absolute path
from doclayout_yolo import YOLOv10
model = YOLOv10(str(model_path.absolute()))
```

--------------------------------

### Get Model Class Names

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/model.md

Retrieve and iterate through the class names associated with the loaded model. This is useful for understanding the model's output categories.

```python
# Get class names
if model.names:
    for idx, name in model.names.items():
        print(f"Class {idx}: {name}")
```

--------------------------------

### Resume Training from Checkpoint

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Resume training from a specified checkpoint file using resume_training. This restores model weights, optimizer state, and training progress.

```python
trainer.resume_training('runs/detect/train/weights/last.pt')
```

--------------------------------

### Get Verbose Detection Summary

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/results.md

Use the `verbose()` method to obtain a human-readable string that summarizes the detections made. This is helpful for quick inspection and logging.

```python
# Get verbose description
description = results[0].verbose()
print(description)
# Output: "2 texts, 1 figure, "
```

--------------------------------

### Modify YOLO Settings Programmatically

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/configuration.md

This Python snippet shows how to get and update YOLO settings programmatically. Ensure you call SETTINGS.save() to persist changes.

```python
from doclayout_yolo.utils import SETTINGS

# Get setting
datasets_dir = SETTINGS['datasets_dir']

# Update setting
SETTINGS['datasets_dir'] = '/new/path'
SETTINGS.save()
```

--------------------------------

### resume_training(last_ckpt)

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Resumes training from a specified checkpoint file, restoring model weights, optimizer state, and other training configurations.

```APIDOC
## resume_training(last_ckpt)

### Description
Resumes training from a specified checkpoint file, restoring model weights, optimizer state, and other training configurations.

### Method
`resume_training(self, last_ckpt: str | Path) -> None`

### Parameters
#### Path Parameters
- **last_ckpt** (str | Path) - Required - Path to the checkpoint file to resume training from.

### Returns
None

### Restoration
- Model weights
- Optimizer state
- Learning rate scheduler state
- Epoch counter
- Metrics history

### Example
```python
trainer.resume_training('runs/detect/train/weights/last.pt')
```
```

--------------------------------

### Complete YOLOv10 Workflow

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/results.md

Demonstrates a full workflow including model initialization, prediction, visualization, exporting detections to JSON, saving element crops, saving in YOLO format, and retrieving inference statistics.

```python
from doclayout_yolo import YOLOv10
from pathlib import Path
import json

# Initialize model
model = YOLOv10("juliozhao/DocLayout-YOLO-DocStructBench")

# Process single image
results = model.predict("document.jpg", imgsz=1024, conf=0.25)
r = results[0]

# Visualize results
annotated = r.plot(line_width=2, font_size=12, pil=True)
annotated.save("annotated.jpg")

# Export detections
summary = r.summary(normalize=True)
with open("detections.json", "w") as f:
    json.dump(summary, f, indent=2)

# Save crops of detected elements
r.save_crop("extracted_elements/")

# Save in YOLO format for training
r.save_txt("labels.txt", save_conf=True)

# Get statistics
print(f"Image size: {r.orig_shape}")
print(f"Detections: {len(r)}")
print(f"Inference speed: {r.speed['inference']:.1f}ms")
```

--------------------------------

### Load Category Names from JSON

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/mesh-candidate_bestfit/visualize.ipynb

Loads category names from a JSON annotation file. This is used to get a list of names for drawing labels on images.

```python
json_path = './annotation_file.json'  # dataset original annotation file
category_list = json.load(open(json_path))['categories']
name_list = [category_list[idx]['name'] for idx in range(len(category_list))] # category names
name_num = len(name_list)  # category number
print(name_num)
```

--------------------------------

### preprocess

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Prepares input images by stacking them into a batch, converting color spaces and formats, moving them to the appropriate device, and normalizing pixel values.

```APIDOC
## preprocess(im)

### Description
Prepares input image before inference.

### Method Signature
```python
def preprocess(
    self,
    im: torch.Tensor | list[np.ndarray]
) -> torch.Tensor
```

### Parameters
#### Arguments
- **im** (torch.Tensor | list[np.ndarray]) - Required - Input images (BCHW tensor or list of HWC arrays).

### Returns
`torch.Tensor` — Preprocessed tensor on correct device/dtype

### Processing
- Stack images into batch
- Convert BGR→RGB, BHWC→BCHW
- Move to device (CPU/GPU)
- Normalize to FP16/FP32
- Scale pixel values (0-255 → 0.0-1.0)

### Example
```python
import torch
import cv2

images = [cv2.imread("img1.jpg"), cv2.imread("img2.jpg")]
preprocessed = predictor.preprocess(images)  # Returns BCHW tensor
print(preprocessed.shape)  # (2, 3, 640, 640)
```
```

--------------------------------

### Download and Load YOLOv10 Model using hf_hub_download

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/yolov10.md

Download model weights from Hugging Face Hub using `hf_hub_download` and then load the model using its local file path. This provides more control over the download process.

```python
from huggingface_hub import hf_hub_download
from doclayout_yolo import YOLOv10

# Download model weights
filepath = hf_hub_download(
    repo_id="juliozhao/DocLayout-YOLO-DocStructBench",
    filename="doclayout_yolo_docstructbench_imgsz1024.pt"
)

# Load the downloaded model
model = YOLOv10(filepath)
```

--------------------------------

### Minimal YOLOv10 Configuration

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Initialize YOLOv10 model and perform basic prediction on an image.

```python
model = YOLOv10("yolov10n.pt")
results = model.predict("image.jpg")
```

--------------------------------

### Get Number of Detections

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/results.md

The `__len__()` method returns the total count of detections within a Results object. Use this to quickly determine how many items were detected.

```python
# Get detection count
num_detections = len(results[0])
print(f"Found {num_detections} elements")
```

--------------------------------

### Validate Model Metrics

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Call the validate method to get model performance metrics on the validation dataset. This returns a dictionary containing mAP and fitness scores.

```python
metrics = trainer.validate()
print(f"mAP50: {metrics['box']['map50']:.3f}")
print(f"mAP50-95: {metrics['box']['map50-95']:.3f}")
```

--------------------------------

### Basic Model Training

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/model.md

Initiates a basic training process using a specified dataset, number of epochs, image size, batch size, and device.

```python
# Basic training
metrics = model.train(
    data="coco8.yaml",
    epochs=100,
    imgsz=640,
    batch=16,
    device=0
)
```

--------------------------------

### Add Custom Callback to Training

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Integrate custom logic into the training process by adding a callback function. This example prints a message at the end of every 10th epoch.

```python
def my_callback(trainer):
    if trainer.epoch % 10 == 0:
        print(f"Checkpoint at epoch {trainer.epoch}")

model.add_callback('on_train_epoch_end', my_callback)
```

--------------------------------

### Configure YOLOv10 Settings

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

Retrieve and print all configuration arguments for the YOLOv10 model using the get_cfg function. This helps in understanding the current settings.

```python
from doclayout_yolo.cfg import get_cfg

args = get_cfg({'epochs': 100, 'batch': 16})
print(vars(args))  # Print all configuration
```

--------------------------------

### ValueError Example - Invalid Model

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

Demonstrates a ValueError for an invalid model file format or malformed configuration. It includes checks for valid file extensions and YAML syntax.

```text
ValueError: Model 'invalid.txt' is not a valid YOLO model
```

```python
# Ensure correct file extensions
valid_formats = ('.pt', '.yaml', '.yml')
if not model_path.suffix in valid_formats:
    raise ValueError(f"Model must be .pt or .yaml, got {model_path.suffix}")

# Validate YAML syntax
from doclayout_yolo.utils import yaml_load
try:
    config = yaml_load("config.yaml")
except Exception as e:
    print(f"Invalid YAML: {e}")
```

--------------------------------

### Download Model

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Use the download utility to fetch a model from a given URL. This is useful when the model is not automatically found.

```python
from doclayout_yolo.utils.downloads import download
download("https://example.com/model.pt")
```

--------------------------------

### Access Predictor Image Size

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/predictor.md

Get the validated image size (height, width) used by the predictor. This property reflects the input dimensions the model is configured to process.

```python
print(predictor.imgsz)  # (640, 640) or (1024, 1024)
```

--------------------------------

### Training YOLOv8 with Half Precision

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/types.md

Shows how to initiate YOLOv8 training using half-precision (FP16) for faster training and reduced VRAM usage.

```python
# Train with half precision (faster, less VRAM)
model.train(data="data.yaml", epochs=100, half=True)
```

--------------------------------

### Fine-tune Model on Custom Dataset

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/model.md

Fine-tunes a model on a custom dataset with specific training parameters including epochs, batch size, image size, learning rate, and multi-GPU setup.

```python
# Fine-tune on custom dataset
results = model.train(
    data="custom_data.yaml",
    epochs=50,
    batch=32,
    imgsz=1024,
    lr0=0.0001,
    device=[0, 1],  # Multi-GPU
    patience=20
)
```

--------------------------------

### Load Model from Hugging Face Hub

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/README.md

Load a model fine-tuned on DocStructBench directly from the Hugging Face Hub using hf_hub_download.

```python
filepath = hf_hub_download(repo_id="juliozhao/DocLayout-YOLO-DocStructBench", filename="doclayout_yolo_docstructbench_imgsz1024.pt")
model = YOLOv10(filepath)
```

--------------------------------

### Build Learning Rate Scheduler

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Initializes the learning rate scheduler. Supports one-cycle, cosine annealing, and linear warmup strategies. The scheduler updates the learning rate each epoch.

```python
trainer.build_scheduler()
# Scheduler updates learning rate each epoch
```

--------------------------------

### Prepare Data Directory Structure

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/README.md

This bash script outlines the expected directory structure for D4LA and DocLayNet datasets after preparation for YOLO format. Ensure your downloaded data follows this structure.

```bash
bash
./layout_data
├── D4LA
│   ├── images
│   ├── labels
│   ├── test.txt
│   └── train.txt
└── doclaynet
    ├── images
    ├── labels
    ├── val.txt
    └── train.txt
```

--------------------------------

### Configure Tracking Arguments in Python

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/doclayout_yolo/trackers/README.md

Use this snippet to set tracking parameters like confidence and IOU threshold when running the tracker in Python. Ensure the YOLO model is loaded first.

```python
from doclayout_yolo import YOLO

# Configure the tracking parameters and run the tracker
model = YOLO("yolov8n.pt")
results = model.track(
    source="https://youtu.be/LNwODJXcvt4", conf=0.3, iou=0.5, show=True
)
```

--------------------------------

### Check and Move Model Device

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/model.md

Inspect the current device of the model (CPU or GPU) and demonstrate how to move the model to a specific device, such as 'cuda:0'.

```python
# Check model device
print(model.device)  # cuda:0 or cpu

# Move model to specific device
model = model.to('cuda:0')
```

--------------------------------

### YOLOv10 Constructor

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/yolov10.md

Initializes a YOLOv10 model instance. You can load models from local checkpoints, Hugging Face Hub, or configuration files.

```APIDOC
## YOLOv10 Constructor

### Description
Initializes a YOLOv10 model instance. You can load models from local checkpoints, Hugging Face Hub, or configuration files.

### Method
__init__

### Parameters
#### Path Parameters
- **model** (str) - Required - Model path (.pt), YAML configuration, or Hugging Face model ID
- **task** (str) - Optional - Task type (detect). Auto-detected from model if None
- **verbose** (bool) - Optional - Enable verbose output

### Request Example
```python
from doclayout_yolo import YOLOv10

# Load from local checkpoint
model = YOLOv10("yolov10n.pt")

# Load from Hugging Face
model = YOLOv10("juliozhao/DocLayout-YOLO-DocStructBench")

# Load from configuration file
model = YOLOv10("config.yaml")

# With verbose output
model = YOLOv10("yolov10m.pt", verbose=True)
```

### Response
#### Success Response
Returns None. Initializes the YOLOv10 model instance.

#### Error Handling
- `FileNotFoundError`: Model file not found
- `ValueError`: Invalid model format
```

--------------------------------

### Correcting ValueError for Configuration Ranges

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

This snippet shows how to resolve ValueErrors by ensuring configuration parameters fall within their valid ranges. It includes examples for confidence thresholds, momentum, epochs, and batch size.

```python
# Correct value ranges
config = {
    'iou': 0.6,           # 0.0 ≤ value ≤ 1.0
    'conf': 0.5,          # 0.0 ≤ value ≤ 1.0
    'momentum': 0.937,    # 0.0 ≤ value ≤ 1.0
    'epochs': 100,        # ≥ 1
    'batch': 16           # ≥ 1
}
```

--------------------------------

### Generate and Combine Layouts

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/mesh-candidate_bestfit/README.md

Generate diverse layouts using the Mesh-candidate Bestfit algorithm and then combine the separately saved results into a single JSON file. Adjust --n_jobs to manage multiprocessing.

```bash
python bestfit_generator.py --generate_num 100 --n_jobs 5 --json_path ./annotation_file.json --output_dir ./generated_layouts/seperate
python combine_layouts.py --seperate_layouts_dir ./generated_layouts/seperate --save_path ./generated_layouts/combined_layouts.json
```

--------------------------------

### Get Detection Summary

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/results.md

Converts detection results into a summarized dictionary format. Useful for programmatic access to detection details like class, confidence, and bounding box. Coordinates can be normalized to a 0-1 range.

```python
summary = results[0].summary(normalize=False)
for detection in summary:
    print(f"{detection['name']}: {detection['confidence']:.2f}")
    print(f"  Box: {detection['box']}")

summary_norm = results[0].summary(normalize=True)
```

--------------------------------

### BaseTrainer Constructor

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/api-reference/trainer.md

Initializes the BaseTrainer class with configuration, overrides, and callbacks. Use this to set up a new training instance.

```python
def __init__(
    self,
    cfg: str = DEFAULT_CFG,
    overrides: dict = None,
    _callbacks: dict = None
) -> None
```

--------------------------------

### Inspect YOLOv10 Model Architecture

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/errors.md

Get detailed information about the YOLOv10 model's architecture by calling the info method with detailed and verbose flags set to True. This is helpful for understanding model structure.

```python
model.info(detailed=True, verbose=True)
```

--------------------------------

### Enable Automatic Multi-GPU Training

Source: https://github.com/opendatalab/doclayout-yolo/blob/main/_autodocs/README.md

Configure the model for multi-GPU training by providing a list of available GPU devices. The training process will automatically distribute across these GPUs.

```python
# Automatic multi-GPU
model.train(data="data.yaml", device=[0, 1, 2, 3])
```