<p align="center"> <img src="assets/images/logo.png" alt="OdinsList logo" width="100%" /> </p>

OdinsList

OdinsList is an automated comic cataloging tool with an interactive TUI built on OpenTUI. (TUI screenshots available in /assets/images) It identifies issues directly from cover images using a vision-language model, then cross-references results with the Grand Comics Database and ComicVine to generate structured, high-confidence collection data with minimal manual entry.

Version: 0.2.5

How It Works

• Vision-based extraction — Uses a vision-language model to read comic covers and extract metadata
• Multi-database verification — Checks the local GCD SQLite database first, then uses ComicVine when needed. OdinsList can run with either source independently, but best accuracy and coverage come from enabling both
• Visual cover matching — Compares your cover image against database cover art during ComicVine validation for tougher matches
• Confidence scoring — Each result is labeled high, medium, or low (see Confidence Levels)
• Batch processing — Processes full collections organized into box folders
• Resume capability — Pause anytime and resume from any existing TSV
• Multi-format image support — Supports .jpg, .jpeg, .png, .tiff, .tif, .webp, and .bmp

Requirements

• Linux or macOS (x64 or arm64) for release binaries
• Python 3.10+ (required for backend setup on first run)
• A running OpenAI-compatible VLM API endpoint (for example: http://127.0.0.1:8000/v1)
• ComicVine API key (free at comicvine.gamespot.com/api)
• GCD SQLite .db file (free at comics.org/download)
• chafa (optional, for higher-fidelity ANSI image previews in the TUI; OdinsList includes a built-in preview fallback. chafa )

For best results, enable both GCD and ComicVine. The local GCD database provides fast offline lookups for the majority of matches, while ComicVine handles edge cases and confirms uncertain matches through visual cover comparison.

Quick Start

1. Install OdinsList:

curl -fsSL https://raw.githubusercontent.com/boyobob/OdinsList/main/install.sh | bash

2. Start your VLM server (VLM Configuration Note: OdinsList sends each image as an independent, single-turn request with no conversation history. For best results, disable any multi-modal KV cache on your VLM server (e.g., --mm-processor-cache-gb 0 in vLLM) so each cover is evaluated fresh, cached multi-modal context can degrade accuracy.)

3. Launch OdinsList:

odinslist

4. On first launch, complete backend setup if prompted, then open Settings to configure:

   A fresh install starts with blank settings. The home screen will show red warnings until you fill these in.

   • VLM API endpoint (vlm_base_url) ex: (http://127.0.0.1:8000/v1)
   • Model name (vlm_model) ex: (Qwen/Qwen3-VL-8B-Instruct-FP8)
   • ComicVine API key
   • GCD SQLite DB local path (If you place this in your images parent directory the program will autodetect it, you can place it anywhere so long as you define the path in settings/config)

5. Select Start New Run and choose your parent image directory (example: ~/Desktop/Comic_Photos).

Note: For the program to recognize your image folders you must use the Box_## naming convention for folders in parent directory. The parent directory can be named anything.

/path/to/comics/
├── Box_01/
│   ├── 0001.jpg
│   └── 0002.png
├── Box_02/
│   └── 0001.webp
└── my_gcd.db

6. Choose mode:

   • Single Box — process one folder such as ~/Desktop/Comic_Photos/Box_01
   • Batch — process all valid box folders under the parent directory

7. Pick the output TSV path/name (default is pre-filled, but editable), review the pre-run summary, and start.

8. During an active run:

   | Key | Action | |-----|--------| | P | Pause the run | | Enter | Resume from pause | | B | Toggle browse mode to review results as they arrive | | Esc Esc | Exit to main menu |

   You can safely exit the program at any time — your progress is saved. To pick up where you left off, select Resume Run from the main menu and select which TSV you would like to resume from.

Directory Structure

Organize your comic photos in box folders. Folders must use the Box_XX naming convention. The parent directory can be named anything.

/path/to/comics/
├── Box_01/
│   ├── 0001.jpg
│   └── 0002.png
├── Box_02/
│   └── 0001.webp
└── my_gcd.db

Headless CLI Usage/Reference

Use --box or --batch to run without the TUI.

Batch Scan All Boxes

odinslist \
  --images /path/to/comics \
  --batch \
  --out /path/to/comics/All_Boxes.tsv \
  --vlm-url http://127.0.0.1:8000/v1 \
  --vlm-model Qwen/Qwen3-VL-8B-Instruct-FP8

Single Box Scan

odinslist \
  --images /path/to/comics \
  --box Box_01 \
  --out /path/to/comics/Box_01.tsv \
  --vlm-url http://127.0.0.1:8000/v1 \
  --vlm-model Qwen/Qwen3-VL-8B-Instruct-FP8

Resume Previous TSV

odinslist \
  --images /path/to/comics \
  --batch \
  --out /path/to/comics/All_Boxes.tsv \
  --resume

CLI Reference

| Flag | Description | Default | |------|-------------|---------| | --images | Parent directory with Box_XX folders | required | | --box | Process a single box | (mutually exclusive with --batch) | | --batch | Process all Box_XX folders | false | | --out | Output TSV path | auto-generated in images dir | | --resume | Skip high-confidence matches from previous runs | false | | --gcd-db | Path to GCD SQLite database | auto-detect *.db in images dir | | --vlm-url | VLM API base URL | none (configure in Settings/config.toml or pass explicitly) | | --vlm-model | VLM model name | from config | | --no-gcd | Disable GCD lookups | false | | --no-comicvine | Disable ComicVine lookups | false | | --ipc | Run JSONL IPC mode (used by the TUI backend) | false |

If --gcd-db is omitted, OdinsList auto-detects the newest .db file in the images root when possible.

Configuration File

OdinsList stores config at ~/.config/odinslist/config.toml:

[paths]
input_root_dir = "/path/to/comics"
output_tsv_path = "/path/to/comics/All_Boxes.tsv"
gcd_db = "/path/to/gcd.db"

[vlm]
base_url = "http://127.0.0.1:8000/v1" # example only; blank until configured
model = "Qwen/Qwen3-VL-8B-Instruct-FP8" (Note: Use the model's exact full name identifier being pushed by server) 

[comicvine]
api_key = "your_ComicVine_API_key"

[features]
gcd_enabled = true
comicvine_enabled = true

[run]
run_mode = "batch"
single_box_dir = ""

Output

Results are written as TSV with columns:

| Column | Description | |--------|-------------| | title | Comic series title | | issue_number | Issue number (e.g., 142) | | month | Cover month as 3-letter abbreviation (e.g., MAR) | | year | Publication year | | publisher | Publisher name (normalized) | | box | Box folder name | | filename | Original image filename | | notes | Empty — reserved for your manual annotations | | confidence | Match confidence: high, medium, or low |

When rerunning with the same output TSV, rows are updated by (box, filename) so scans can be resumed without duplicate lines.

Confidence Levels

| Level | Score | Meaning | |-------|-------|---------| | high | >= 40 | Strong match, likely correct | | medium | 21-39 | Probable match missing signals, recommend verifying | | low | <= 20 | Uncertain, manual review recommended |

Supported Models

Any vision-capable model served via an OpenAI-compatible API:

| Model | Notes | |-------|-------| | *Qwen3-VL-8B-Instruct | (Recommended) Tested with vLLM backend in FP8 and NVFP4. Best results, 97% High confidence matches over a 2,992 comic book dataset with GCD and ComicVine enabled | | Qwen3-VL-2B-Instruct | Similar results to 8B with degradation, tested with LMStudio/llama.cpp backend with Q4_K_M GGUF quant. Non-GGUF may perform better in vLLM | | LFM2.5-VL-1.6B | Tested with LMStudio/llama.cpp backend with Q4_K_M GGUF quant. Suprisingly good results. | | Qwen3.5-0.8B/2B/4B | Promising, further testing needed. Mixed results. |

Set the model via --vlm-model flag or vlm.model in your config file or settings menu.

Tips for Better Results

• Take photos in good lighting with minimal glare
• Capture the full cover including edges
• Avoid extreme angles
• Higher resolution photos improve OCR accuracy
• When all signals (title, issue#, month, price, publisher) are visible on the cover the program is most accurate. Comics with no signals will likely fail.
• Choose a model with strict instruction following like Qwen3-VL-Instruct

Data Sources

• Grand Comics Database (GCD) — comics.org — CC BY 3.0
• ComicVine — comicvine.gamespot.com — Free API tier (200 requests/hour)

Contributing

Contributions welcome! Areas where help is needed:

• Testing with different vision models and model prompting/schema (located in vlm.py)
• Improving title matching algorithms
• Adding support for non-US and oddball comics
• Documentation and examples
• Integrating a small bundled OCR/VLM model while maintaining accuracy
• Support for variant classification (Newstand etc.)

License

MIT. See LICENSE.

Acknowledgments

• Grand Comics Database for their comprehensive open data
• ComicVine for their API and cover images
• The open-source VLM community

---

Let the all-seeing eye of Odin simplify cataloging your comics