README.md 4.42 KB
Newer Older
njean42's avatar
njean42 committed
1
2
3
4


# Introduction

njean42's avatar
njean42 committed
5
6
![Kumiko mascot by Cthulhulumaid](artwork/kumiko-big.png "Kumiko mascot by Cthulhulumaid")

7
> Kumiko mascot by [Hurluberlue](https://www.twitch.tv/hurluberlue "twitch link"), [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/ "Creative Commons License")
njean42's avatar
njean42 committed
8
9
10
11
12
13
14
15
16
17
18
19
20
21

*Kumiko, the Comics Cutter* is a set of tools to compute useful information about comic book pages, panels, and more.
Its main strength is to find out the **locations of panels** within a comic's page (image file).
*Kumiko* can also compile information about panels for all pages in a comic book, and present it as one piece of data (JSON-formatted object).

*Kumiko* makes use of the great (freely licensed) [opencv](https://opencv.org/) library, which provides image processing algorithms of all sorts.
Mainly, the contour detection algorithm is used to detect panels within an image.



# Demo

*TL;WR* Too Long; Won't Read the whole doc?

njean42's avatar
njean42 committed
22
A **live demo** is now [available here](https://kumiko.njean.me/demo), where you can try *Kumiko* out and cut your own comic pages into panels.
njean42's avatar
njean42 committed
23
24
25
26
27
28
29
30
31
32
33
34
35



# Philosophy

*Kumiko* aims at being a functional library to extract information from comic pages / books.
The goal is to provide a set of tools that is usable beforehand, to extract all needed information.

External programs can later use the generated information for different purposes: panel-by-panel viewing, actual splitting of an image down into panels, etc.


## Panel-by-panel comic reading

njean42's avatar
njean42 committed
36
Being able to jump from one panel to the next was the original idea behind *Kumiko*.
njean42's avatar
njean42 committed
37

njean42's avatar
njean42 committed
38
39
40
![xkcd #208](doc/img/xkcd.png "xkcd #208")

> [xkcd](https://www.xkcd.com) by Randall Munroe, [#208](https://www.xkcd.com/208/), [CC BY-NC 2.5](https://creativecommons.org/licenses/by-nc/2.5/)
njean42's avatar
njean42 committed
41
42
43
44
45
46
47

Comic viewers usually imply a very common *page-by-page reading paradigm*.
You read a page, possibly zooming on it to be able to read speech bubbles, then click, tap, press a key or swipe to go to the next page.

With knowledge about panels locations, we can imagine a comic reader that also offers *panel-by-panel reading*.
This is especially interesting for **small screens**, on which you probably can't read the texts if a whole page is displayed.

njean42's avatar
njean42 committed
48
Just run `kumiko -i /path/to/comicpage.jpg -b firefox` on your *comicpage.jpg* file, and read it panel-by-panel in your browser!
njean42's avatar
njean42 committed
49
50
51
52


# Requirements

53
`apt-get install python3-opencv` will install the only necessary library needed: *opencv*.
njean42's avatar
njean42 committed
54
55
56
57

This should do the trick for Debian distros and derivatives (Ubuntu, Linux Mint...).
If you successfully use *Kumiko* on any other platform, please let us know!

58
*Kumiko* now uses python3.
njean42's avatar
njean42 committed
59
60
61



62
# Usage & Testing
njean42's avatar
njean42 committed
63
64
65

See the [usage doc](doc/Usage.md) for details on how to use the *Kumiko* tools.

66
Also check the [testing doc](doc/Testing.md) if you want to test modified versions of the code.
67

njean42's avatar
njean42 committed
68
69
70
71
72
73
74
75


# Numbering

The numbering is left to right, top to bottom for now (see roadmap).

Here is an example of how *Kumiko* is going to number panels by default (numbers and red lines not in the original picture).

njean42's avatar
njean42 committed
76
77
78
![Pepper&Carrot](doc/img/numbering.png "Pepper&Carrot")

> [Pepper & Carott](https://www.peppercarrot.com/) by [David Revoy](https://www.davidrevoy.com), [episode 2](https://www.peppercarrot.com/en/article237/episode-2-rainbow-potions), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
njean42's avatar
njean42 committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113



# Limitations

For now, *Kumiko* only deals with **white-ish backgrounds**.
Panels within a comic page will be any "object" that has non-white boundaries (not necessarily vertical or horizontal lines).

If you have ideas on how to programmatically guess the background color of a page, please let us know!



# Short- and longer-term awesome features (roadmap)


## Kumiko library

* be able to detect panel contours on pages with **non-white background**
	* implies being able to determine the background color: histogram, probing of some kind? (worst case: manually?)
* provide an option for **right-to-left numbering**, critical e.g. for mangas


## Back-office (validation / edition tool)

Let's face it: we probably can't ensure that *Kumiko* can perfectly find out the panels in *any* image.
There is a huge diversity of panel boundaries, layouts and whatnot.

This is why we should have some kind of back-office / editing tool that lets a human editor:

* validate pages
* add, delete, move or resize incorrect panels
* report bugs
* ...

Such a tool should edit the JSON file representing a comic book information, for later use by other programs that'll rely on it.