koharu-layout-rfdetr

KoharuLayout-RFDETR-2XL (768px CPU-Optimized ONNX Export)

Model Summary

This repository provides an optimized ONNX Runtime export of KoharuLayout-RFDETR-2XL, configured for efficient execution in comic and manga translation pipelines, such as XianScan.

The model is derived from the upstream reference checkpoint mayocream/koharu-layout-rfdetr-seg-2xl-1152 by mayocream. It localizes primary document layout elements across comic pages, specifically dialogue text, speech bubbles, sound effects, and comic panel boundaries.

To optimize for resource-constrained environments and local desktop runtimes, this export incorporates two structural modifications:

1. Spatial Resolution Scaling: Native input resolution was adapted from 1152x1152 to 768x768 via 2D bicubic interpolation of the vision backbone patch position embeddings (from a 96x96 grid down to a 64x64 grid).
2. Computational Graph Pruning: The unused instance segmentation decoder branch (117 operations, including pixel decoders and mask feature projections) was pruned from the graph. The model exclusively evaluates bounding box coordinates (dets) and classification logits (labels), reducing inference latency by ~20% to 25% compared to the unpruned 768px model and ~4x compared to the 1152px baseline on CPU.

---

Architectural Comparison

The following table summarizes the structural and operational differences between the upstream reference checkpoint and this optimized export:

---

CPU Performance Profile

Depending on CPU architecture, clock frequencies, thermal limits, and available threads (typically 4 to 8 physical cores on consumer hardware), expected inference latency ranges are as follows:

(Empirical reference: on an 8-core / 16-thread AMD Ryzen 7 5700G, warm inference averages ~1.64s for the pruned model versus ~2.12s for the unpruned 768px model and ~6.82s for the 1152px baseline).

Key Factors:

• Spatial scaling (1152px $\to$ 768px) yields a ~3x speedup by reducing the vision transformer self-attention token sequence from 9,217 to 4,097 tokens ($(96/64)^2 = 2.25\times$) along with smaller intermediate feature maps.
• Graph pruning (removing mask branch) provides an additional ~20% to 25% reduction in latency (saving roughly 0.4s to 0.6s per page on CPU) by eliminating 117 mask-specific operations and their memory buffers.
• Total end-to-end speedup over the full-resolution baseline is approximately 4x faster on CPU.

---

Target Classes and Semantics

The model predicts 300 object queries mapped across four functional layout categories:

Note: The model is strictly a layout detection system. It does not perform optical character recognition (OCR) or predict semantic reading sequences.

---

Tensor Signatures

Input Specification

• Tensor Name: input
• Data Type: float32
• Shape: [1, 3, 768, 768] (Batch, Channels, Height, Width)
• Color Format: RGB
• Normalization: Standard ImageNet channel distribution: $$\text{Pixel}_{\text{norm}} = \frac{\frac{\text{Pixel}}{255.0} - \mu}{\sigma}$$ where $\mu = [0.485, 0.456, 0.406]$ and $\sigma = [0.229, 0.224, 0.225]$.

Output Specifications

1. dets

   • Data Type: float32
   • Shape: [1, 300, 4]
   • Format: Normalized center coordinates and box dimensions [cx, cy, w, h] bounded within [0.0, 1.0]. Absolute pixel boundaries are recovered via: $$x_1 = (cx - 0.5 \cdot w) \cdot W_{\text{orig}}, \quad y_1 = (cy - 0.5 \cdot h) \cdot H_{\text{orig}}$$ $$x_2 = (cx + 0.5 \cdot w) \cdot W_{\text{orig}}, \quad y_2 = (cy + 0.5 \cdot h) \cdot H_{\text{orig}}$$

2. labels

   • Data Type: float32
   • Shape: [1, 300, 5]
   • Format: Unnormalized classification logits corresponding to indices [0: text, 1: onomatopoeia, 2: bubble, 3: panel, 4: background]. Probabilities are derived using the standard sigmoid function: $$P(\text{class}_c) = \frac{1}{1 + e^{-\text{logit}_c}}$$

---

File Size Note

• Hugging Face Display (SI Decimal, Base 10): 136 MB ($136,227,882 \div 1,000,000 = 136.23\text{ MB}$)
• Binary Filesystem (IEC Binary, Base 2 / Windows Explorer): 129.9 MiB ($136,227,882 \div 1,048,576 = 129.92\text{ MiB}$)
• For comparison, the unpruned 768px model was 140.5 MB ($134.03\text{ MiB}$ / $140,535,993\text{ bytes}$). Pruning the mask head saved approximately 4.3 MB (4.1 MiB).

---

Minimal Working Example (Python)

import numpy as np
import onnxruntime as ort
from PIL import Image

# Initialize runtime session
session = ort.InferenceSession(
    "rfdetr-seg-2xlarge.onnx",
    providers=["CPUExecutionProvider"]
)

# Load and prepare image
image = Image.open("manga_page.webp").convert("RGB")
orig_w, orig_h = image.size
resized = image.resize((768, 768), Image.Resampling.BILINEAR)

# Normalize using ImageNet statistics
img_arr = np.array(resized, dtype=np.float32) / 255.0
mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
norm_arr = (img_arr - mean) / std
input_tensor = np.transpose(norm_arr, (2, 0, 1))[np.newaxis, ...]

# Execute inference
dets_out, labels_out = session.run(["dets", "labels"], {"input": input_tensor})
dets = dets_out[0]      # shape: (300, 4)
labels = labels_out[0]  # shape: (300, 5)

# Extract and filter candidate predictions
thresholds = {0: 0.25, 1: 0.20, 2: 0.50, 3: 0.50}
class_names = {0: "text", 1: "onomatopoeia", 2: "bubble", 3: "panel"}

results = []
for q in range(300):
    cx, cy, bw, bh = dets[q]
    x1 = float((cx - 0.5 * bw) * orig_w)
    y1 = float((cy - 0.5 * bh) * orig_h)
    x2 = float((cx + 0.5 * bw) * orig_w)
    y2 = float((cy + 0.5 * bh) * orig_h)

    for c in range(4):
        confidence = float(1.0 / (1.0 + np.exp(-labels[q][c])))
        if confidence >= thresholds[c]:
            results.append({
                "class": class_names[c],
                "score": round(confidence, 3),
                "bbox": [round(x1, 1), round(y1, 1), round(x2, 1), round(y2, 1)]
            })

print(f"Localized {len(results)} layout elements.")

---

Provenance and Credits

All credit for the original underlying model architecture, training, and supervision belongs to:

• Principal Author: mayocream
• Original Project: Koharu (Manga Translation Studio)
• Source Weights: mayocream/koharu-layout-rfdetr-seg-2xl-1152
• Underlying Training Set: Manga109 Segmentation v2.0.0

Licensing and Use Constraints

1. Software License: The RF-DETR architecture and runtime export code are distributed under the Apache-2.0 license.
2. Dataset Terms: Because model parameters were fine-tuned on the Manga109 dataset, usage must comply with Manga109 academic and non-commercial guidelines. This repository adheres to the upstream custom/other license designation.