Skip to content

Open ComicBookDS (.cbds) books - #634

Open
svabi79 wants to merge 13 commits into
YACReader:developfrom
svabi79:feature/native-cbds-support
Open

svabi79 wants to merge 13 commits into
YACReader:developfrom
svabi79:feature/native-cbds-support

Conversation

@svabi79

@svabi79 svabi79 commented Oct 28, 2026

Copy link
Copy Markdown

Draft for discussion, see the proposal in #633. Happy to change the approach if you prefer something different.

Closes #633 (proposal and discussion).

Motivation

ComicBookDS was a homebrew comic reader for the Nintendo DS. Its books (.cbds, made with PictoDS or cbdsconv) are still around in old collections. They are plain ZIP archives, so the decompression backends can open them already. But next to the pages they contain four resized copies of every page, so YACReader showed a 50-page book as 250 pages, with previews and rotated thumbnails mixed in.

Format

ComicBookDS_book.ini      credits, reading direction, page count, image sizes
IMAGE/1.jpg ... N.jpg     pages
NAME/1.txt  ... N.txt     original file name of each page
SMALL_N/ SMALL_R/         previews, normal / rotated 90°
THMB_N/  THMB_R/          thumbnails, normal / rotated 90°

Details, sources and the open questions are in docs/CBDS_FORMAT.md.

Changes

  • common/comic.cpp: cbds added to the comic extension lists, for every backend. Open dialog, drag & drop, folder opening and the library scanner all use these lists.
  • common/cbds_page_index.{h,cpp} (new, a small static library like epub_page_index): YACReaderCbds::pageCandidates() limits the page candidates of a ComicBookDS book to the entries directly inside the root IMAGE/ folder. An archive counts as a book when it has a .cbds suffix or a root ComicBookDS_book.ini (not a directory of that name), so a book renamed to .cbz also works. For any other archive the file list is returned unchanged.
  • FileComic::process() and InitialComicInfoExtractor::extract() pass the archive file list through pageCandidates() (via FileComic::cbdsPageCandidates(), which hands in the supported image formats like the EPUB helpers do) before FileComic::filter(). These are the only two callers of filter(). A book without any image in IMAGE/ falls back to the regular behaviour.
  • For ComicBookDS books the reader and the library both sort with YACReaderCbds::sortPages(): natural order of the normalized names, without the spread heuristic. Page names are plain sequence numbers, so a page named 1011.jpg is not a spread of pages 10 and 11, and mixed spellings such as image\1.jpg and IMAGE/2.jpg still sort by number.
  • .cbds gets the zip comic icon in the library list. Changelog entries are under 10.4.0.

Not done, on purpose:

  • The ini file is not parsed. The page list comes from the archive. NbPages is unreliable in real files (cbdsconv writes N+1 and leaves gaps when a page fails to convert), and not reading the ini means a broken or huge ini can't affect anything.
  • No LeftToRight → manga mapping. All books I have are left to right, so I couldn't verify it. This could be a follow-up.
  • No installer, .desktop or Info.plist associations. This matches .cb7/.cbt, which aren't associated either. Happy to add them if you want.
  • Archives that contain several .cbds files are not read directly.

Known limitations:

  • The unarr backend leaves empty entries out of its file list, so a book renamed to another extension and with an empty ini is read as a regular archive with unarr. Files with the .cbds extension are not affected.
  • In the Linux 7zip CI job the integration test skips (with a message), because the 7zip backend loads 7z.so from the install path and the workflow doesn't install it before ctest. The unit test still runs there, and the libarchive job runs the integration test. If you want, I can add a step to the workflow that stages dependencies/7zip/linux/x86_64/7z.so and make the test fail instead of skip.

Noticed but not touched, because it already happens on develop for every archive: FileComic::process() maps page names back to archive indexes with indexOf(), so an archive with two entries of the same name shows the first one twice.

Tests

New automated tests:

  • cbds_page_index_test (unit): detection by suffix or root ini; a directory named like the ini is not a book; only IMAGE/ entries kept; names returned exactly as the archive lists them (backslashes, case, leading /); nested, .., drive-letter and directory entries never treated as pages; fallback when there is no IMAGE/ folder or no image in it; non-CBDS archives untouched; numeric sort order independent of the path spelling.
  • cbds_comic_test (integration, QTEST_GUILESS_MAIN): writes synthetic books at test time (generated PNG pages, no copyrighted data) and opens them through the configured backend:
    • reader (FileComic): 12 pages in reading order, no previews, with both stored entries and PictoDS-style Deflate entries with data descriptors;
    • reader and library agree on the order when a page is named 1011 and when the entries use mixed path spellings;
    • a book whose IMAGE/ folder holds no images falls back to the images at the root;
    • library (InitialComicInfoExtractor): page count, cover = page 1, custom cover page;
    • missing, broken and 8 MiB ini files;
    • book renamed to .cbz;
    • regular CBZ files keep every image;
    • corrupt, empty, zero-byte and ini-only files report an error and never crash;
    • truncated books (central directory replaced by zeros, as in real damaged files);
    • LibraryCreator: import, cover on disk, rescan keeps the same comic id with no duplicates.
    • The 7zip backend loads its library from utils/ next to the executable, so on Windows (architecture picked with yacreader_get_windows_arch_subdir()) and macOS the test target copies 7z.dll/7z.so there. On Linux the 7zip backend loads the installed library; if it can't be loaded, the test skips with a message instead of failing.

Mutation checks, each done separately, each making the named test(s) fail: pageCandidates() returning everything (both tests), the spread heuristic for ComicBookDS (cbds_comic_test), accepting directory entries (cbds_page_index_test), sorting the raw names instead of the normalized ones (both tests), and the old fallback that ignores the image filter (both tests).

Results

Platform Backend Build ctest cbds_comic_test
Windows x64, MSVC 2022, Qt 6.9.3, Release 7zip ✅ 13/13 15/15 passed (QtTest totals), no skips
Windows x64, MSVC 2022, Qt 6.9.3, Release unarr ✅ 13/13 15/15 passed (QtTest totals), no skips
Linux x86_64 (Ubuntu 24.04, GCC 13, Qt 6.9.3, PDF_BACKEND=no_pdf), Release, no display libarchive 3.7.2 ✅ 13/13 15/15 passed (QtTest totals), no skips
macOS, Windows ARM64 – not tested

I also tested locally with 25 real .cbds books I own (not included anywhere). With each of the three backends, for the 21 intact books the library page count equals the number of IMAGE/ entries and the cover is IMAGE/1. With 7zip, every page that FileComic delivered was compared by hash against IMAGE/N: all pages in reading order, no preview images. Re-scanning the library kept the same comic ids. Four of the books are truncated (the central directory is replaced by zeros). They never crash; how much of them opens depends on the backend (7zip recovers the readable pages, libarchive counts the pages but has no cover, unarr skips them). I also ran 5 real CBR files (RAR4 and RAR5) through the library with 7zip as a regression check: page counts unchanged. The source files were byte-identical (SHA-256) before and after all runs. These real-file checks were done on the first revision. The follow-up commits only change the order of names with four or more digits or mixed path spellings, directory entries, the fallback for books without images in IMAGE/, and the tests; none of these books have such names or layouts. The installer built from the final revision opens the same books.

In the built reader (Windows, 7zip) I checked a real book by hand: it shows 1/50 pages, the cover is page 1, and "Go to" reports 50 pages. Paging, first/last page, double page mode, zoom and original size (native 700 px page, so not a preview image) all work. A bookmark and the reading position survive closing and reopening the book.

clang-format 23.1.3 was run on the changed files.

AI assistance

This change was developed with AI assistance (Claude Code): format analysis, implementation, tests and this description. Two other AI models (Codex and Grok) reviewed it independently in several rounds, and the findings that held up are fixed in the follow-up commits. I have reviewed the code and verified the results listed above before opening this PR.

🤖 Generated with Claude Code

@svabi79
svabi79 marked this pull request as ready for review October 28, 2026 16:31
svabi79 and others added 8 commits October 29, 2026 02:58
ComicBookDS books are zip archives made for a Nintendo DS reader. Next to
the pages in IMAGE/ they store four resized copies of every page, so they
used to open with five times the real page count.

Add .cbds to the supported comic extensions and, for archives that are
ComicBookDS books (.cbds suffix or a root ComicBookDS_book.ini), only use
the IMAGE/ entries as page candidates, both in the reader and when the
library extracts covers and page counts. Any other archive keeps its
current behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Builds synthetic .cbds books at test time and opens them through the
configured decompression backend, FileComic, InitialComicInfoExtractor
and LibraryCreator (import and rescan). Covers broken, huge and missing
ini files, corrupt, empty and truncated archives and regular CBZ files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Run the integration test without a GUI application (QTEST_GUILESS_MAIN)
  so it works on headless CI like the other tests.
- Sort ComicBookDS pages numerically in the reader. Page names are plain
  sequence numbers, the spread heuristic could reorder a page named 1011
  and disagree with the order the library uses.
- Never treat directory entries as the book marker or as pages.
- Deploy 7z.so next to the integration test on macOS too.
- Test PictoDS style archives (Deflate with data descriptors) and the
  numeric page order.
- Library icon for .cbds, changelog entries, and documentation of how
  entry names are matched and of the unarr empty entry limitation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The page selection accepts IMAGE/ entries written with either separator,
in any case and with a leading separator, but the reader and the library
sorted the original names, so mixed spellings gave a different page order
and cover. Add YACReaderCbds::sortPages(), which compares the normalized
names, and use it in FileComic::process() and InitialComicInfoExtractor.

Also pick the 7z.dll for the integration test with the existing
yacreader_get_windows_arch_subdir() helper, which handles ARM64 cross
builds, and update the format notes on NbPages and damaged books.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pageCandidates() only fell back to the whole archive when there were no
IMAGE/ entries at all, so a book whose IMAGE/ folder held only non-image
files opened as an empty comic. Take an image filter, like the EPUB page
index does, and fall back when no IMAGE/ entry is an image. The reader and
the library pass the supported image formats through the new
FileComic::cbdsPageCandidates().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add the project website as a source: PictoDS is a Java program for
Windows, Linux and macOS, writes .cbds since 2.0 beta 4 (January 2007),
and the reader's user guide explains what the preview folders and the
LeftToRight setting are used for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10.4.0 has been released, so the entries belong to the next version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@svabi79
svabi79 force-pushed the feature/native-cbds-support branch from aeddcf9 to 1f7a16e Compare October 29, 2026 02:06
svabi79 and others added 5 commits October 29, 2026 17:13
10.5.0 has been released, so the entries belong to the next version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: support ComicBookDS (.cbds) comics

1 participant