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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
# Kona: An Imageboard Engine
Kona is a lightweight Danbooru-style imageboard engine for the purposes of
self-hosting a tagged image gallery. It lacks many of the features one would
expect of such an application (particularly use rauthentication), so if you have
a use case other than being able to search through your pictures when you are
not at home, you would be better off looking at an established solution such as
[Danbooru](https://github.com/danbooru/danbooru).
This is a _very_ early release. Perhaps pre-alpha, if there is no stage earlier
in the software release life cycle. Use at your own risk.
If you are brave enough to give this a try, however, feedback of any sort would
be greatly appreciated. The command-line interface and web UI are designed
around my specific use case, but I would ideally like for this to be usable by
the general public.
## Features
- A command-line tool for interacting with the tag database.
- A web interface for querying and viewing files in the tag database.
## Usage
### Command-Line
There are two ways of interacting with бирка-тян: through the `kona-cli`
command-line tool (i), and through the web interface (ii).
The inclusion of (i) is in consideration for this being, essentially, a personal
image gallery. One likely has a loosely-organized collection of images already;
the command-line tool enables her to import images en masse with the full
capabilities of the Unix shell at her fingertips. A brief summary of the
command-line interface follows.
Images are introduced to the database with the `add` command, which takes zero
or more tags following the path of an image. The path is automatically
canonicalized, so relative names are perfectly acceptable.
```sh
$ kona-cli add Cat.jpeg animal cat cute
```
Ah, drat. We should have tagged that image with "photograph", too.
```sh
$ kona-cli add_tags Cat.jpeg photograph
```
On second thought, that wasn't a particularly cute picture.
```sh
$ kona-cli remove_tags Cat.jpeg cute
```
Now, let's see all of the photographs in the tag database tagged with
"photograph".
```sh
$ kona-cli query photograph
/home/jakob/Camera/Cat.jpeg
```
The `query` command outputs a line-separated list of paths to any images
satisfying the query string. The semantics are similar to that of Danbooru,
except that the logical disjunction operator ('~') is unsupported. As a
convenience, the 'query' command can be invoked without a query string, to list
all paths indexed by the database.
```sh
$ kona-cli query
...
```
The tag database is stored in a file, and the path of that file is dependent on
how the program is invoked. If, when parsing the command-line arguments,
`kona-cli` sees a `-o` or `--output` argument, the path following that argument
will be used. Alternatively, the `TB_PATH` environment variable can be
specified, but `-o` takes a higher precedence. If neither are specified,
"kona.db" in the current directory is used.
A few other things that can be done from the command-line:
Removing an image can be done with 'remove'.
```sh
$ kona-cli remove Cat.jpeg
```
Getting the tags in the database:
```sh
$ kona-cli tags
...
```
### Web-Interface (API)
The web interface for бирка-тян exposes a RESTful API for remotely interacting
with the tag database. At the time of writing, this API is __not__ stabilized.
Expect to rewrite any code depending on this API in the near future, in part
because these will all be put behind a `/v1/` specifier.
Suppose we denote the following shape of JSON object as a `ImageResult`.
```
{
"id": number,
"filename": string,
"thumb_filename": string,
"orig_filename": string,
"tags": [string, ...],
}
```
The images in the tag database can be enumerated with the 'posts' endpoint,
which takes two parameters: `query`, a query string, and `last`, which is the
last `ImageResult` identifier which was seen. This endpoint will return, at
most, 50 entries, which is why the `last` parameter is necessary.
```
GET /api/posts?last=number,query=string
[zero or more ImageResult]
```
Information about a specific image in the database can be obtained with the
following endpoint, where `id` is the identifier (number) of the image in the
database:
```
GET /api/posts/[id]
ImageResult
```
To add tags to an image, POST a comma-separated list of new tags to the same
endpoint.
To upload an image to the database, post a multipart/form-data encoded message
to the following endpoint with the following fields: `tags`, a comma-separated
list of tags for the files, and `image`, the file to be uploaded.
```
POST /api/posts/[filename]
```
## TODO
There are a few things I'd like to push off 'till later, since this is working
for me right now.
- [kona-cli] Improve the `kona-cli add` interface, allowing multiple files to
be indexed and tagged in the same invocation.
- [kona-web js] Implement a dynamic "endless scroll" view.
- [kona-web js] Implement a mass-tagger tool in the web interface.
|
