book-image-renamer
Identify book photos, extract visible metadata with local OCR, use a local multimodal model to correct OCR ambiguity, and build safe rename plans in the format 原書作者-書名-出版社-年分_ISBN. Use when Codex need
SKILL.mdregistry/skills/book-image-renamer/SKILL.md
GitHubBook Image Renamer
Overview
Scan a folder of book images, extract OCR text with local PaddleOCR, and build a safe rename plan before any file is renamed.
Use this skill when the folder contains mixed images and only some of them are books, or when multiple shots of the same book need grouped suffixes.
Workflow
- Run a scan first:
python "$env:USERPROFILE\.codex\skills\book-image-renamer\scripts\book_image_renamer.py" scan "<folder>" --output book_rename_scan.json
- Review
book_rename_scan.json. - Copy
metadata_templateinto a separate metadata file and fill only verified edition metadata. - Build a rename plan:
python "$env:USERPROFILE\.codex\skills\book-image-renamer\scripts\book_image_renamer.py" plan book_rename_scan.json metadata.json --output book_rename_plan.json
- Inspect
book_rename_plan.json. - Apply only from the plan:
python "$env:USERPROFILE\.codex\skills\book-image-renamer\scripts\book_image_renamer.py" apply book_rename_plan.json --output book_rename_applied.json
Current Pipeline
The current implementation is intentionally staged:
scan- Preprocess each image into a stable temporary JPEG before OCR.
- Run local
PaddleOCR. - Produce
ocr_lines, a fast route (candidate / review / skip), and coarse book/title/author/ISBN hints.
curated metadata- Do not trust raw OCR for edition metadata.
- Keep verified author, title, publisher, year, and ISBN in a separate curated JSON file.
- Alias group keys may point multiple OCR variants back to the same verified book.
plan- Match each candidate image against curated metadata.
- Re-evaluate image role using the OCR text only:
front_plainfront_with_obibackspineinterior
- Sort same-book images by role before assigning filenames.
- Avoid collisions by skipping to the next available suffix when a target name already exists.
apply- Rename only items with a generated
suggested_target_name. - Leave unmatched items unchanged.
- Rename only items with a generated
Decision Points
- Ask for confirmation only if the user wants to rename images that contain multiple clearly visible books. The default is to leave them unresolved.
- If OCR produces a plausible title and author but publisher, year, or ISBN are still missing, do not rename yet. Record the candidate and continue.
- If the same verified book appears in multiple files, keep the most cover-like image as the base filename and suffix the others.
- Prefer
front_plainoverfront_with_obi, thenback,spine, andinterior. - If no verified metadata match exists, stop at
planand keep the original filename.
Active Handling Policy
Use these rules when the user wants aggressive progress without external ISBN lookup:
書名最重要- Prioritize extracting and matching the title above all other fields.
- If title OCR is clear enough to identify a known book, continue even when author OCR is weak.
多本書 = 捨棄不處理- Any image with more than one clearly visible book should be skipped from rename planning.
非書封 = 不處理- Magazine pages, catalog pages, interiors without a clear cover, event photos, and non-book images should be skipped.
In this mode, the skill should spend effort on:
- Clear single-book front covers
- Back covers with a matching single-book title signal
- Alias cleanup for noisy OCR title variants
It should not spend effort on:
- Multi-book scenes
- Non-cover documents or magazine-like pages
- Weak matches based only on publisher, translator, or generic promo copy
Matching Strategy
- Use OCR only to find candidate title, author, ISBN, and role hints.
- Use curated metadata as the source of truth for edition-level filename fields.
- Reuse verified metadata across OCR group variants only when the title/author signal is strong enough.
- Do not auto-promote weak fuzzy matches into rename candidates.
Manual Alias Playbook
Use this when many images remain at No verified metadata match but the photographed book is still recognizable.
- Open the current plan JSON and group the unresolved items by
candidate_group_key. - Inspect only the first few
ocr_linesof each group. - Look for one of these high-signal patterns:
- Clear title line
- Clear author line
- Back-cover ISBN that already belongs to a verified edition
- Distinctive subtitle or promo line that obviously belongs to one verified book
- Add a new alias entry to the curated metadata JSON using the unresolved
candidate_group_keyas the key. - Point that alias entry to an already verified metadata record by copying the exact
author,title,publisher,year, andisbn. - Re-run
plan. - Only
applyafter checking that the new targets are book-consistent and collision-free.
Good alias cases
- Front cover OCR is noisy, but the title line is still recognizable.
- Back cover contains a matching ISBN for an already verified edition.
- A book with obi and a plain cover were split into different OCR groups.
- OCR captured a distinctive subtitle that uniquely identifies one verified book.
Bad alias cases
- Only publisher or imprint is readable.
- Only translator name is readable.
- OCR text could fit multiple books by the same author.
- The image might be a magazine page, catalog page, or multi-book scene.
Preferred workflow for unresolved batches
- Rebuild a current scan JSON filtered to files still present in the folder.
- Run
planagainst the current curated metadata file. - Count unresolved
candidateitems. - Add only a few high-confidence aliases at a time.
- Re-run
planafter each small alias batch. - Apply only the newly safe renames.
Local Dependencies
PaddleOCRwithlang='ch'is the primary OCR path. It handles mixed Traditional Chinese and Japanese book text better than the lighter OCR path used during evaluation.Hereticis optional auxiliary help for ambiguous cases. This skill expects an OpenAI-compatible endpoint athttp://127.0.0.1:1234/v1with modelgemma-4-e4b-it-heretic.- Online metadata verification may still be used when the user explicitly wants it, but the core skill must also work in a no-search mode using only the existing curated metadata file.
Files
scripts/book_image_renamer.py: scans, groups, builds plans, and applies verified renames.references/decision-rules.md: stable rules for eligibility, metadata, and suffix handling.
Read references/decision-rules.md when deciding whether a candidate image is safe to rename.