### End-to-End RapidLayout Example

Source: https://context7.com/rapidai/rapidlayout/llms.txt

A comprehensive example demonstrating the full workflow: installation, batch processing of images, accessing structured results, and saving visualizations.

```python
from pathlib import Path
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

# 初始化引擎（推荐使用 doclayout_docstructbench 模型）
cfg = RapidLayoutInput(
    model_type=ModelType.DOCLAYOUT_DOCSTRUCTBENCH,
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,
    iou_thresh=0.5,
)
engine = RapidLayout(cfg=cfg)

# 批量处理图像
image_paths = [
    "tests/test_files/layout.jpg",
    "tests/test_files/PMC3576793_00004.jpg",
    "tests/test_files/pp_doc_layoutv2_layout.jpg",
]

for img_path in image_paths:
    results = engine(img_path)

    if results.boxes is None:
        print(f"{img_path}: 未检测到版面元素")
        continue

    print(f"\n图像: {img_path}")
    print(f"  检测元素数量: {len(results.boxes)}")
    print(f"  推理耗时: {results.elapse:.3f}s")

    for i, (box, cls, score) in enumerate(
        zip(results.boxes, results.class_names, results.scores)
    ):
        x1, y1, x2, y2 = [round(v, 1) for v in box]
        print(f"  [{i+1}] {cls:20s} score={score:.2f}  box=({x1},{y1},{x2},{y2})")

    # 保存可视化结果
    save_path = Path(img_path).stem + "_vis.jpg"
    results.vis(save_path)
    print(f"  可视化已保存: {save_path}")

# 示例输出：
# 图像: tests/test_files/layout.jpg
#   检测元素数量: 14
#   推理耗时: 0.048s
#   [1] title                score=0.94  box=(50.1,30.2,400.3,80.4)
#   [2] text                 score=0.89  box=(50.1,90.5,600.2,200.3)
#   [3] table                score=0.91  box=(50.1,210.0,650.0,480.5)
#   ...
```

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

### Install RapidLayout and ONNX Runtime

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/quickstart.md

Install the core RapidLayout library and the ONNX Runtime engine. For OpenVINO support, install the `openvino` package separately.

```bash
pip install rapid-layout onnxruntime
```

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

### Install and Use OpenVINO

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/how_to_use_other_engine.md

Install RapidLayout and OpenVINO, then configure RapidLayout to use the OpenVINO engine for inference. Device and thread configurations are detailed in engine_cfg.yaml.

```bash
pip install rapid-layout onnxruntime openvino
```

```python
from rapid_layout import EngineType, ModelType, RapidLayout

layout_engine = RapidLayout(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.OPENVINO,
)
img_path = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### Install Rapid Layout (OpenVINO Inference)

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Install the core package along with ONNX Runtime and OpenVINO for inference.

```bash
pip install rapid-layout onnxruntime openvino
```

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

### Configure RapidLayout with Different Engines

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Demonstrates initializing `RapidLayout` with ONNX Runtime (CPU, CUDA, NPU) and OpenVINO engines. Ensure OpenVINO is installed if using that engine.

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

# EngineType.ONNXRUNTIME - 默认引擎，支持 CPU/CUDA/DirectML/CANN
# EngineType.OPENVINO    - Intel OpenVINO 引擎

# 使用 ONNX Runtime（默认 CPU）
engine_cpu = RapidLayout(engine_type=EngineType.ONNXRUNTIME)

# 使用 ONNX Runtime + CUDA GPU
cfg_cuda = RapidLayoutInput(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    engine_cfg={
        "use_cuda": True,
        "cuda_ep_cfg": {"device_id": 0}  # 多卡时指定 GPU 卡号
    },
)
engine_gpu = RapidLayout(cfg=cfg_cuda)

# 使用 ONNX Runtime + NPU (CANN，华为昇腾)
cfg_npu = RapidLayoutInput(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    engine_cfg={
        "use_cann": True,
        "cann_ep_cfg": {"device_id": 0}
    },
)
engine_npu = RapidLayout(cfg=cfg_npu)

# 使用 OpenVINO（需先 pip install openvino）
engine_vino = RapidLayout(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.OPENVINO,
    # engine_cfg 可设置 device、inference_num_threads 等
)

img_url = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = engine_vino(img_url)
print(results.elapse)  # 输出推理耗时，如 0.032
```

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

### Install Rapid Layout (GPU Inference with CUDA)

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Install the core package and the GPU-enabled ONNX Runtime engine. Ensure the `onnxruntime-gpu` version matches your CUDA version.

```bash
pip install rapid-layout
# Ensure onnxruntime-gpu version matches CUDA version
# See: https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html
pip install onnxruntime-gpu
```

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

### RapidLayout Command-Line Interface (CLI)

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Usage examples for the `rapid_layout` CLI tool for processing single images. Shows basic usage, specifying models and thresholds, and saving visualizations.

```bash
# 基本用法（使用默认模型 pp_layout_cdla）
rapid_layout tests/test_files/layout.jpg

# 指定模型与阈值
rapid_layout tests/test_files/layout.jpg -m doclayout_docstructbench --conf_thresh 0.6 --iou_thresh 0.5

# 同时保存可视化结果到 layout_vis.jpg
rapid_layout tests/test_files/layout.jpg -m pp_layout_cdla --conf_thresh 0.5 -v

# 所有可用参数：
# img_path          必填，图像路径（本地或 URL）
# -m/--model_type   模型类型，默认 pp_layout_cdla
# --conf_thresh     置信度阈值，默认 0.5
# --iou_thresh      IoU 阈值，默认 0.5
# -v/--vis          是否保存可视化结果

# 输出示例（print results）：
# RapidLayoutOutput(boxes=[[50.0, 30.0, 400.0, 80.0], ...], class_names=['title', 'text', ...], scores=[0.93, 0.87, ...], elapse=0.045)
```

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

### Python: Default Layout Analysis

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/usage.md

Use the default model and engine for layout analysis. Ensure the RapidLayout library is installed.

```python
from rapid_layout import RapidLayout

layout_engine = RapidLayout()
img_path = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### Install ONNX Runtime GPU

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/how_to_use_other_engine.md

Install the onnxruntime-gpu package to enable GPU acceleration with ONNX Runtime. Ensure compatibility with your CUDA version.

```bash
pip install rapid_layout
# 请确保 onnxruntime-gpu 与当前 GPU/CUDA 版本对应
# 参见 https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html#requirements
pip install onnxruntime-gpu
```

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

### Use ONNX Runtime with GPU (CUDA)

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/how_to_use_other_engine.md

Configure RapidLayout to use ONNX Runtime with CUDA for GPU inference. Specify the device ID for multi-GPU setups.

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

cfg = RapidLayoutInput(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    engine_cfg={"use_cuda": True, "cuda_ep_cfg": {"device_id": 0}},
)
layout_engine = RapidLayout(cfg=cfg)

img_path = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### RapidLayout Initialization

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Demonstrates various ways to initialize the RapidLayout engine, including default settings, keyword arguments, configuration objects, and mixed approaches.

```APIDOC
## RapidLayout Initialization

`RapidLayout` is the core entry class. It loads the specified model and inference engine upon initialization. You can call the instance to perform layout detection on input images, returning a `RapidLayoutOutput` object. Initialization supports keyword arguments, `RapidLayoutInput` configuration objects, or a mix of both (kwargs override cfg fields).

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

# Method 1: Default initialization (model pp_layout_cdla + onnxruntime)
layout_engine = RapidLayout()

# Method 2: Keyword arguments initialization
layout_engine = RapidLayout(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,   # Confidence threshold [0, 1]
    iou_thresh=0.5,    # IoU threshold [0, 1]
)

# Method 3: Using a configuration object
cfg = RapidLayoutInput(
    model_type=ModelType.DOCLAYOUT_DOCSTRUCTBENCH,  # Recommended general model
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,
    iou_thresh=0.5,
)
layout_engine = RapidLayout(cfg=cfg)

# Method 4: Mixed cfg + kwargs (kwargs override cfg fields)
cfg_base = RapidLayoutInput(model_type=ModelType.PP_LAYOUT_CDLA, conf_thresh=0.5)
layout_engine = RapidLayout(cfg=cfg_base, conf_thresh=0.4)  # conf_thresh is overridden to 0.4
```
```

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

### 本地预览文档

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

修改 `docs/` 下内容后，使用 MkDocs 和 Material 主题进行本地预览。安装依赖后运行 `mkdocs serve`。

```bash
pip install mkdocs mkdocs-material
mkdocs serve
```

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

### Initialize RapidLayout Engine

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Demonstrates different ways to initialize the `RapidLayout` engine, including default settings, keyword arguments, configuration objects, and mixed configurations. Default model is `pp_layout_cdla` with ONNX Runtime.

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

# Method 1: Default initialization (model pp_layout_cdla + onnxruntime)
layout_engine = RapidLayout()

# Method 2: Keyword arguments initialization
layout_engine = RapidLayout(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,   # Confidence threshold [0, 1]
    iou_thresh=0.5,    # IoU threshold [0, 1]
)

# Method 3: Using a configuration object
cfg = RapidLayoutInput(
    model_type=ModelType.DOCLAYOUT_DOCSTRUCTBENCH,  # Recommended general model
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,
    iou_thresh=0.5,
)
layout_engine = RapidLayout(cfg=cfg)

# Method 4: cfg + kwargs mix (kwargs override cfg fields)
cfg_base = RapidLayoutInput(model_type=ModelType.PP_LAYOUT_CDLA, conf_thresh=0.5)
layout_engine = RapidLayout(cfg=cfg_base, conf_thresh=0.4)  # conf_thresh is overridden to 0.4
```

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

### Run Layout Analysis with Configuration Object

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/quickstart.md

Initialize RapidLayout using a configuration object for a more structured approach to setting parameters like model and engine types.

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

cfg = RapidLayoutInput(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
)
layout_engine = RapidLayout(cfg=cfg)
img_path = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### Configure RapidLayout with RapidLayoutInput

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Shows how to use `RapidLayoutInput` for detailed configuration, including specifying model paths, confidence thresholds, and using `normalize_kwargs` for automatic type conversion.

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput
from pathlib import Path

# 完整配置示例
cfg = RapidLayoutInput(
    model_type=ModelType.DOCLAYOUT_DOCSTRUCTBENCH,  # 模型类型
    model_dir_or_path=None,          # None 表示自动下载，也可指定本地路径
    engine_type=EngineType.ONNXRUNTIME,
    engine_cfg={},                   # 引擎额外配置（CPU 默认为空）
    conf_thresh=0.5,                 # 置信度阈值，越高过滤越严
    iou_thresh=0.5,                  # NMS IoU 阈值
)
engine = RapidLayout(cfg=cfg)

# 使用本地模型文件（离线部署）
cfg_local = RapidLayoutInput(
    model_type=ModelType.PP_LAYOUT_CDLA,
    model_dir_or_path=Path("/models/layout_cdla.onnx"),  # 本地 ONNX 文件路径
)
engine_local = RapidLayout(cfg=cfg_local)

# normalize_kwargs：字符串自动转枚举（内部调用，也可手动使用）
normalized = RapidLayoutInput.normalize_kwargs({
    "model_type": "pp_layout_cdla",       # str → ModelType.PP_LAYOUT_CDLA
    "engine_type": "onnxruntime",          # str → EngineType.ONNXRUNTIME
    "conf_thresh": 0.6,
    "unknown_key": "ignored",              # 非法字段自动忽略
})
print(normalized)
# {'model_type': <ModelType.PP_LAYOUT_CDLA: 'pp_layout_cdla'>, 'engine_type': <EngineType.ONNXRUNTIME: 'onnxruntime'>, 'conf_thresh': 0.6}
```

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

### Perform Layout Detection with RapidLayout

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Shows how to use the `RapidLayout` engine's `__call__` method with various input formats including local file paths, URLs, NumPy arrays, PIL Images, and raw bytes. It also demonstrates how to access the detection results.

```python
from pathlib import Path
import numpy as np
from PIL import Image
from rapid_layout import RapidLayout

layout_engine = RapidLayout()

# Input method 1: Local file path (str or Path)
results = layout_engine("tests/test_files/layout.jpg")
results = layout_engine(Path("tests/test_files/layout.jpg"))

# Input method 2: Network URL
img_url = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_url)

# Input method 3: numpy array (BGR, H x W x C)
img_array = np.zeros((1024, 768, 3), dtype=np.uint8)
results = layout_engine(img_array)

# Input method 4: PIL Image
pil_img = Image.open("tests/test_files/layout.jpg")
results = layout_engine(pil_img)

# Input method 5: bytes
with open("tests/test_files/layout.jpg", "rb") as f:
    results = layout_engine(f.read())

# Access result fields
print(results.boxes)        # List[List[float]], format [[x1,y1,x2,y2], ...]
print(results.class_names)  # List[str], e.g. ['title', 'text', 'table', ...]
print(results.scores)       # List[float], confidence scores list
print(results.elapse)       # float, inference time (seconds)

# Example output:
# boxes: [[50.0, 30.0, 400.0, 80.0], [50.0, 90.0, 600.0, 500.0]]
# class_names: ['title', 'text']
# scores: [0.93, 0.87]
# elapse: 0.045
```

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

### 克隆 Rapid Layout 源码

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

克隆主仓库到本地，并进入项目目录。若网络受限，可先 Fork 到个人账号再克隆。

```bash
git clone https://github.com/RapidAI/RapidLayout.git
cd RapidLayout
```

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

### Run Layout Analysis from Terminal

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/quickstart.md

Execute RapidLayout directly from the terminal to analyze images. Options include specifying the image path, model type, and confidence threshold.

```bash
rapid_layout test_images/layout.png
```

```bash
rapid_layout test_images/layout.png -m pp_layout_cdla --conf_thresh 0.5
```

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

### RapidLayout.__call__ - Performing Layout Detection

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Explains how to use the `RapidLayout` instance to perform layout detection on various image input formats and how to access the results.

```APIDOC
## `RapidLayout.__call__` — Perform Layout Detection

Accepts images in various formats and returns a `RapidLayoutOutput` object containing detection boxes, class names, confidence scores, and processing time. Supports input from local paths, URLs, numpy arrays, PIL.Image, and bytes.

```python
from pathlib import Path
import numpy as np
from PIL import Image
from rapid_layout import RapidLayout

layout_engine = RapidLayout()

# Input Method 1: Local file path (str or Path)
results = layout_engine("tests/test_files/layout.jpg")
results = layout_engine(Path("tests/test_files/layout.jpg"))

# Input Method 2: Network URL
img_url = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_url)

# Input Method 3: Numpy array (BGR, H x W x C)
img_array = np.zeros((1024, 768, 3), dtype=np.uint8)
results = layout_engine(img_array)

# Input Method 4: PIL Image
pil_img = Image.open("tests/test_files/layout.jpg")
results = layout_engine(pil_img)

# Input Method 5: Bytes
with open("tests/test_files/layout.jpg", "rb") as f:
    results = layout_engine(f.read())

# Accessing result fields
print(results.boxes)        # List[List[float]], format [[x1,y1,x2,y2], ...]
print(results.class_names)  # List[str], e.g., ['title', 'text', 'table', ...]
print(results.scores)       # List[float], confidence scores list
print(results.elapse)       # float, inference time (seconds)

# Example Output:
# boxes: [[50.0, 30.0, 400.0, 80.0], [50.0, 90.0, 600.0, 500.0]]
# class_names: ['title', 'text']
# scores: [0.93, 0.87]
# elapse: 0.045
```
```

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

### Run Layout Analysis with Custom Model and Engine

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/quickstart.md

Specify custom model type, engine type, and confidence threshold when initializing RapidLayout. This allows for fine-tuning the analysis process.

```python
from rapid_layout import EngineType, ModelType, RapidLayout

layout_engine = RapidLayout(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,
)
img_path = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### RapidLayoutOutput.vis - Visualizing Detection Results

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Details on how to use the `vis` method of `RapidLayoutOutput` to visualize detection results on the image, either by saving to a file or returning a numpy array.

```APIDOC
## `RapidLayoutOutput.vis` — Visualize Detection Results

Draws detection boxes with labels on the original image (semi-transparent fill + border + class name and confidence). Returns the visualized numpy array and can optionally save it to a file.

```python
from rapid_layout import RapidLayout

layout_engine = RapidLayout()
img_url = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_url)

# Save visualization results to a file
vis_img = results.vis("layout_res.png")
# layout_res.png will display detection boxes with colored blocks and labels (e.g., "title 93%")

# Get only the visualization array, without saving to file
vis_img = results.vis()      # Returns np.ndarray (BGR), or None if no detections

# Usage with OpenCV
import cv2
if vis_img is not None:
    cv2.imshow("Layout Detection", vis_img)
    cv2.waitKey(0)
```
```

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

### Terminal: Basic Layout Analysis

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/usage.md

Run layout analysis directly from the terminal using the default model and engine. Provide the path to the image file.

```bash
rapid_layout test_images/layout.png
```

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

### Use ONNX Runtime with NPU (CANN)

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/how_to_use_other_engine.md

Configure RapidLayout to use ONNX Runtime with CANN for NPU inference. Refer to engine_cfg.yaml for detailed configuration parameters.

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

cfg = RapidLayoutInput(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    engine_cfg={"use_cann": True, "cann_ep_cfg": {"device_id": 0}},
)
layout_engine = RapidLayout(cfg=cfg)

img_path = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### Python: Use Configuration Object

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/usage.md

Configure layout analysis using a dedicated configuration object for clarity and reusability. This is equivalent to specifying parameters directly in the constructor.

```python
from rapid_layout import EngineType, ModelType, RapidLayout, RapidLayoutInput

cfg = RapidLayoutInput(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,
    iou_thresh=0.5,
)
layout_engine = RapidLayout(cfg=cfg)
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### 安装和使用 pre-commit 钩子

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

安装 pre-commit 工具，并在仓库根目录启用 Git 提交前钩子，以自动进行代码格式检查和整理。

```bash
pip install pre-commit
pre-commit install

# 手动运行所有文件的检查
pre-commit run --all-files
```

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

### 推送代码到个人 Fork

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

添加个人 Fork 为远程仓库，创建新分支，添加并提交修改，然后推送到个人 Fork 的对应分支。

```bash
# 在项目根目录 RapidLayout 下执行
git remote add myfork https://github.com/你的用户名/RapidLayout.git

# 创建分支（推荐为每个 issue/功能单独分支）
git checkout -b fix/xxx   # 或 feat/xxx、docs/xxx

# 添加并提交修改
git add .
git status   # 确认只提交预期文件
git commit -m "fix: 简短描述"

# 推送到你的 fork
git push myfork fix/xxx
```

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

### 配置 Python 开发环境

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

使用 venv 或 conda 创建虚拟环境，并激活。安装项目依赖，包括开发依赖和可编辑安装。

```bash
# 使用 venv
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# 或使用 conda
conda create -n rapidlayout python=3.10
conda activate rapidlayout

pip install -r requirements.txt
pip install pytest   # 运行单元测试需要
pip install -e .
```

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

### Visualize Layout Detection Results

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Use the `vis` method of `RapidLayoutOutput` to draw bounding boxes with labels on the original image. The result can be saved to a file or returned as a NumPy array for further processing, such as with OpenCV.

```python
from rapid_layout import RapidLayout

layout_engine = RapidLayout()
img_url = "https://raw.githubusercontent.com/RapidAI/RapidLayout/718b60e927ab893c2fad67c98f753b2105a6f421/tests/test_files/layout.jpg"
results = layout_engine(img_url)

# Save visualization result to file
vis_img = results.vis("layout_res.png")
# layout_res.png will display bounding boxes with color blocks and labels (e.g., "title 93%")

# Get visualization array only, without saving to file
vis_img = results.vis()      # Returns np.ndarray (BGR), or None if no bounding boxes are found

# Combine with OpenCV
import cv2
if vis_img is not None:
    cv2.imshow("Layout Detection", vis_img)
    cv2.waitKey(0)
```

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

### Specify Model Type with ModelType Enum

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Demonstrates how to specify different pre-trained models using the `ModelType` enumeration or by string name when initializing `RapidLayout`. Models are automatically downloaded from the Modao platform on first use.

```python
from rapid_layout import ModelType, RapidLayout

# All available model types
# PP Series (PaddleOCR)
# ModelType.PP_DOC_LAYOUTV3      - Document layout (25 classes, recommended, requires rapid_layout>=1.2.0)
# ModelType.PP_DOC_LAYOUTV2      - Document layout (25 classes, requires rapid_layout>=1.1.0)
# ModelType.PP_LAYOUT_CDLA       - Chinese layout (10 classes, default)
# ModelType.PP_LAYOUT_PUBLAYNET  - English layout (5 classes)
# ModelType.PP_LAYOUT_TABLE      - Table detection (1 class)
#
# YOLOv8n Series (360LayoutAnalysis)
# ModelType.YOLOV8N_LAYOUT_PAPER     - Academic paper (9 classes)
# ModelType.YOLOV8N_LAYOUT_REPORT    - Financial report (9 classes)
# ModelType.YOLOV8N_LAYOUT_PUBLAYNET - English layout (5 classes)
# ModelType.YOLOV8N_LAYOUT_GENERAL6  - General 6 classes
#
# DocLayout-YOLO Series (Recommended, highest precision)
# ModelType.DOCLAYOUT_DOCSTRUCTBENCH - General document (10 classes)
# ModelType.DOCLAYOUT_D4LA           - General document (26 classes)
# ModelType.DOCLAYOUT_DOCSYNTH       - General document (11 classes)

# Using enumeration
engine = RapidLayout(model_type=ModelType.DOCLAYOUT_DOCSTRUCTBENCH)

# Using string (equivalent)
engine = RapidLayout(model_type="doclayout_docstructbench")

# Document layout analysis (25 classes, including formulas, stamps, etc.)
engine_v3 = RapidLayout(model_type=ModelType.PP_DOC_LAYOUTV3)
results = engine_v3("tests/test_files/pp_doc_layoutv2_layout.jpg")
print(results.class_names)
```

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

### Python: Specify Model and Engine

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/usage.md

Customize layout analysis by specifying the model type, inference engine, confidence threshold, and IoU threshold.

```python
from rapid_layout import EngineType, ModelType, RapidLayout

layout_engine = RapidLayout(
    model_type=ModelType.PP_LAYOUT_CDLA,
    engine_type=EngineType.ONNXRUNTIME,
    conf_thresh=0.5,
    iou_thresh=0.5,
)
results = layout_engine(img_path)
print(results)
results.vis("layout_res.png")
```

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

### ModelType Enum

Source: https://context7.com/rapidai/rapidlayout/llms.txt

Lists and explains the available model types for layout analysis, including their categories and recommended usage.

```APIDOC
## `ModelType` — Model Type Enumeration

Defines all built-in pre-trained models. You can specify models using enum values or strings. Models are automatically downloaded from the ModelScope platform on first use.

```python
from rapid_layout import ModelType, RapidLayout

# All available model types:
# PP Series (PaddleOCR)
# ModelType.PP_DOC_LAYOUTV3      - Document Layout (25 classes, recommended, requires rapid_layout>=1.2.0)
# ModelType.PP_DOC_LAYOUTV2      - Document Layout (25 classes, requires rapid_layout>=1.1.0)
# ModelType.PP_LAYOUT_CDLA       - Chinese Layout (10 classes, default)
# ModelType.PP_LAYOUT_PUBLAYNET  - English Layout (5 classes)
# ModelType.PP_LAYOUT_TABLE      - Table Detection (1 class)
#
# YOLOv8n Series (360LayoutAnalysis)
# ModelType.YOLOV8N_LAYOUT_PAPER     - Academic Paper (9 classes)
# ModelType.YOLOV8N_LAYOUT_REPORT    - Financial Report (9 classes)
# ModelType.YOLOV8N_LAYOUT_PUBLAYNET - English Layout (5 classes)
# ModelType.YOLOV8N_LAYOUT_GENERAL6  - General 6 Classes
#
# DocLayout-YOLO Series (Recommended, highest precision)
# ModelType.DOCLAYOUT_DOCSTRUCTBENCH - General Document (10 classes)
# ModelType.DOCLAYOUT_D4LA           - General Document (26 classes)
# ModelType.DOCLAYOUT_DOCSYNTH       - General Document (11 classes)

# Using the enum
engine = RapidLayout(model_type=ModelType.DOCLAYOUT_DOCSTRUCTBENCH)

# Using a string (equivalent)
engine = RapidLayout(model_type="doclayout_docstructbench")

# Document layout analysis (25 classes, including formulas, stamps, etc.)
engine_v3 = RapidLayout(model_type=ModelType.PP_DOC_LAYOUTV3)
results = engine_v3("tests/test_files/pp_doc_layoutv2_layout.jpg")
print(results.class_names)
```
```

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

### Commit 信息规范示例

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

按约定式提交规范（Conventional Commits）书写 commit 信息，便于维护者阅读与自动生成 Changelog。

```text
<类型>[可选范围]: <简短描述>

[可选正文]
[可选脚注]

常用类型示例：

| 类型       | 说明                   |
|------------|------------------------|
| `feat`     | 新功能                 |
| `fix`      | Bug 修复               |
| `docs`     | 文档变更               |
| `style`    | 代码格式（不影响逻辑） |
| `refactor` | 重构                   |
| `test`     | 测试相关               |
| `chore`    | 构建 / 工具等            |

示例：`fix: 修复某条件下版面结果为空`、`feat: 支持 xxx 输入格式`、`docs: 更新安装说明`。
```

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

### 运行单元测试

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

在仓库根目录使用 pytest 运行单元测试。可运行全部测试、部分测试文件，或查看测试覆盖率。

```bash
# 运行全部测试
pytest tests/ -v

# 仅运行部分测试文件
pytest tests/test_main.py -v

# 查看测试覆盖率（需先安装 pytest-cov）
pytest tests/ -v --cov=rapid_layout
```

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

### Terminal: Advanced Layout Analysis

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/install_usage/usage.md

Execute terminal commands with specific model, confidence threshold, and IoU threshold for customized layout analysis.

```bash
rapid_layout test_images/layout.png -m pp_layout_cdla --conf_thresh 0.5 --iou_thresh 0.5
```

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

### 编写单元测试示例

Source: https://github.com/rapidai/rapidlayout/blob/main/docs/contributing.md

在 `tests/` 目录下编写单元测试，命名为 `test_*.py`。使用 pytest 编写用例，并参考现有测试文件。

```python
# tests/test_xxx.py
import pytest
from pathlib import Path

cur_dir = Path(__file__).resolve().parent
root_dir = cur_dir.parent
test_dir = cur_dir / "test_files"

def get_engine():
    from rapid_layout import RapidLayout
    return RapidLayout()

def test_your_new_feature():
    engine = get_engine()
    img_path = test_dir / "layout.jpg"
    result = engine(img_path)
    assert result is not None
    # 更多断言...
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.