cbxy

cbxy is a sidecar format for comic panel geometry.

Try the demo.

A Brief Introduction

A .cbxy file is a ZIP archive of JSON files (same idea as CBZ, but metadata instead of images).

book.cbz                         book.cbxy
├── page-001.jpg                 ├── page-001.json
├── page-002.jpg                 ├── page-002.json
└── Art/page-003.png             └── Art/page-003.json

Coordinates are normalized fractions of the page (0–1), so they survive resize. Array order is reading order.

{
  "page": "page-001.jpg",
  "width": 1680,
  "height": 2583,
  "panels": [
    { "x": 0.035, "y": 0.058, "w": 0.388, "h": 0.286 },
    { "x": 0.437, "y": 0.058, "w": 0.526, "h": 0.287 }
  ]
}

For a full specification, see the latest version of the spec.

About This Repository

This repository is a Python reference implementation of the cbxy format and tools. It is meant to be a showcase for the format and tools.

Installation

Install using pip:

pip install cbxy

or uv:

uv tool install cbxy

Tools

Once installed, three command-line tools are available:

• cbxy-detect: Detects panels in a comic and writes a .cbxy sidecar beside it.
• cbxy-reader: Opens a comic in the browser with optional guided panel view.
• cbxy-editor: Visual editor for creating or fixing panel boxes.

cbxy-detect

Detects panels in a comic archive and writes a .cbxy sidecar next to it (OpenCV by default, with ML fallback for irregular layouts).

cbxy-detect path/to/book.cbz

Engines

--engine chooses how panels are found. Most of the time auto is enough; pick cv or ml when you know the page style.

The ML path uses Ultralytics YOLO with the pretrained comic-panel weights mosesb/best-comic-panel-detection (downloaded on first ML run).

cbxy-reader

Opens a comic in the browser. If a sibling .cbxy is present, supports guided panel-by-panel view; otherwise pages only.

cbxy-reader path/to/book.cbz

cbxy-editor

Browser UI to create or edit panel boxes and save a .cbxy beside the comic.

cbxy-editor path/to/book.cbz