1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
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
114
115
116
117
118
119
120
121
122
123
124
|
Overview
========
Before setting up **hircine** it is important to understand its choice of
technologies as well as its design goals and core concepts. This will allow you
to make an informed decision on whether or not it is the right solution for
you.
.. _overview-technologies:
Technologies
------------
**hircine** consists of two core parts: a `Python <https://www.python.org>`_
backend that exposes a `GraphQL <https://graphql.org>`_ API and a `SvelteKit
<https://kit.svelte.dev>`_ frontend written in `TypeScript
<https://www.typescriptlang.org>`_ that communicates with it. Data is stored in
an `SQLite <https://www.sqlite.org/index.html>`_ database.
Image processing is done using `Pillow
<https://pillow.readthedocs.io/en/stable>`_. hircine uses the `BLAKE3 Python
bindings <https://pypi.org/project/blake3>`_ to build hashes used for file
identification and deduplication.
The web application is designed to be the canonical user interface, but any
program may freely use the :doc:`provided API </advanced/api>`.
.. _overview-goals:
Design goals
------------
**hircine** is designed to organize a large personal collection of comics and
make it easily queryable. It provides a set of concepts and tools that allows
categorization and classification of comics and comes with a powerful filtering
system.
Whilst **hircine** does have basic support for categories of metadata such as
artists or characters, it is mostly concerned with classifying the *content* of
a comic through user-defined namespaces and tags. The primary goal is to find
something you are in the mood to read, and not to provide a full archival
system where you keep track of the minute details of a comic's publication or
creation.
As such, it is designed to tackle large and diverse collections of comics,
manga, or doujin where the story, art, and characters are the primary appeal.
.. _overview-concepts:
Core concepts
-------------
Archives
^^^^^^^^
**hircine** reads image files from *ZIP* archives. Loose image files are
**not** supported. Usually an archive contains a single comic (or chapter), but
it may also contain a whole volume - once imported, an archive can be split
into multiple comics in the web application.
Comics
^^^^^^
A comic is a logical grouping of pages (image files) that can be annotated with
metadata. Most of the functionality in the web application pertains to
organizing, querying, and reading comics.
Comics are created by collating a sequence of pages from a single archive. This
sequence is exclusive, meaning that a page may only ever be allocated to a
single comic. Not all pages of an archive have to be used.
Metadata
^^^^^^^^
A fair chunk of comic metadata is self-explanatory. For example, a comic may be
annotated with the date of its publication, the language it is written in, or
what kind of censorship is in use. There also exist a number of well-defined
categories of metadata that are managed by the user:
+------------+-------------------------------------------------------------------------+
| Category | Description |
+============+=========================================================================+
| Artists | A person involved in the creating of a comic. |
+------------+-------------------------------------------------------------------------+
| Circles | A group of people involved in the publishing or translation of a comic. |
+------------+-------------------------------------------------------------------------+
| Characters | A fictional character portrayed in a comic. |
+------------+-------------------------------------------------------------------------+
| Worlds | A fictional world portrayed in a comic. |
+------------+-------------------------------------------------------------------------+
.. _overview-tags:
Namespaces & Tags
^^^^^^^^^^^^^^^^^
Alongside those well-defined categories, **hircine** supports user-defined
namespaces and tags. The latter is a familiar concept: a tag is a simple piece
of information that is attached to an object of interest.
Namespaces enhance that concept by introducing a context in which the tag is
placed. Let's say we want to keep track of the gender of a story's love
interest. We may solve this using tags alone, like ``male love interest`` or
``female love interest``, but this is quite unwieldy. Namespaces instead allow
us to create a ``male`` and ``female`` namespace and a single tag ``love
interest`` which can then be combined with either namespace.
**hircine** requires the use of namespaces when tagging comics. A tag cannot be
applied to a comic unless it is paired with a namespace. Such a pairing is
called a *qualified tag*. When filtering, either the namespace or tag is
optional: you may decide to exclude comics with any ``love interest``, or
filter for comics that only have tags in the ``female`` namespace.
.. _overview-object-store:
Object store
^^^^^^^^^^^^
**hircine** keeps all processed images files in a a `content-addressable
filesystem <https://en.wikipedia.org/wiki/Content-addressable_storage>`_ called
the object store. The purpose of the store is twofold: Firstly, if multiple
archives contain the same image, it only needs to be stored once in the object
store. Secondly, the object store allows the application to used without having
to serve potentially large image files.
|
