aboutsummaryrefslogtreecommitdiff
path: root/devdoc
diff options
context:
space:
mode:
Diffstat (limited to 'devdoc')
-rw-r--r--devdoc/design-notes.md305
1 files changed, 305 insertions, 0 deletions
diff --git a/devdoc/design-notes.md b/devdoc/design-notes.md
new file mode 100644
index 0000000..b6ea37a
--- /dev/null
+++ b/devdoc/design-notes.md
@@ -0,0 +1,305 @@
1---
2title: ldgallery design notes
3author: pacien
4date: 2020-02-25
5---
6
7__Warning: this document is severely outdated.__
8
9---
10
11# ldgallery design notes
12
13_ldgallery_ consists of two main components that are packaged and distributed
14together, but are otherwise functionally independent:
15
16* a __compiler__ which turns a collection of pictures and sidecar metadata
17 files into their compressed/normalised and aggregated versions respectively,
18 and
19* a web __viewer__ in the form of a single-page application, rendering the
20 output of the compiler as a searchable picture gallery.
21
22
23## Gallery compiler
24
25### Input
26
27#### Directory structure
28
29The compiler takes a source directory as input which shall contain item
30resource files and associated metadata sidecar files. Those items may be
31recursively grouped into multiple levels of sub-directories.
32
33Example source directory structure:
34
35```
36example-gallery-source
37├── _DSC8808-1.jpg -- a picture
38├── _DSC8808-1.jpg.yaml -- its associated sidecar metadata file
39└── Glacier 3000 -- a directory grouping gallery items
40 ├── thumbnail.jpg -- optional directory thumbnail
41 ├── _DSC5475.jpg
42 ├── _DSC5475.jpg.yaml
43 ├── _DSC5542.jpg
44 └── _DSC5542.jpg.yaml
45```
46
47
48#### Metadata sidecar file
49
50Metadata associated to items are stored in YAML sidecar files of the same name,
51with the `.yaml` extension appended. The use of plain text sidecar files allow
52for easier editing without any special tool in a unified manner for multiple
53types of files (pictures, videos, ebooks, ...). The metadata contained within
54item files are simply ignored.
55
56Tags are given with a group hierarchy separated by `.`, which allows generic
57searches as well as implicit disambiguation.
58
59Example metadata sidecar file:
60
61```yaml
62title: Some title
63
64date: 2019-12-20T16:51:52+00:00
65
66description: >
67 Some multiline description
68 that may contain some markdown later.
69
70tags:
71 - photographer.someone
72 - location.france.paris
73 - monochromatic
74```
75
76Possible evolutions:
77
78* Fallback values may later be defined for each field, making them optional.
79* The description field could be allowed to contain markdown-formatted content,
80 which would be rendered by the __viewer__ app.
81* Other keys could be added to allow the definition of specific
82 transform/compilation/displaying parameters on a particular file.
83* Metadata sidecar files could be added for directories as well in some
84 `index.yaml` file.
85
86
87#### Gallery configuration file
88
89The gallery YAML configuration file contains the __compiler__'s and the
90__viewer__'s settings in two different sections.
91
92Proposed configuration file, named `gallery.yaml` at the root of the source
93directory:
94
95```yaml
96compiler:
97 galleryName: My Little Gallery
98 ignoreFiles: .*\.txt # to ignore text files
99 implicitDirectoryTag: false # default
100
101 thumbnailMaxResolution:
102 width: 400 # default
103 height: 400 # default
104
105 pictureMaxResolution: # or unspecified to copy files as is
106 width: 1024
107 height: 768
108
109 # format normalisation?
110 # item compression?
111
112
113viewer:
114 # TODO: configuration options to be defined
115 # separately shown tags and their colours
116 # use hash in URL (useful for use without webserver url rewrite)?
117```
118
119
120### Output
121
122#### Directory structure
123
124```
125data
126├── items -- original/normalised item directory
127│ ├── _DSC8808-1.jpg
128│ └── Glacier 3000
129│ ├── _DSC5475.jpg
130│ └── _DSC5542.jpg
131├── thumbnails -- item thumbnails directory
132│ ├── _DSC8808-1.jpg
133│ └── Glacier 3000
134│ ├── thumbnail.jpg
135│ ├── _DSC5475.jpg
136│ └── _DSC5542.jpg
137├── index.json -- content index file
138└── viewer.json -- viewer configuration file
139```
140
141
142#### Viewer configuration file
143
144The content of the `viewer` section of the gallery configuration file is used,
145without any transformation by the __compiler__, to generate the `viewer.json`
146file located at the root of the output directory.
147
148
149#### Gallery items index
150
151The __compiler__ generates a global index file `index.json` aggregating the
152metadata of all the source sidecar files as a tree of items as described below.
153Its root node is a directory item. The type of each property node is marked by
154its `type` field.
155
156Directory items aggregate their tags from the items below it in order to be
157displayed in search results.
158
159Resource paths are rooted with respect to the data output directory which
160serves as the base path.
161
162Serialised item structure:
163
164```json
165{
166 "_comment": "common fields",
167
168 "title": "Some title",
169 "date": "2019-12-20T16:51:52+00:00",
170 "description": "Some multiline description\nthat may contain some markdown later.",
171
172 "tags": [
173 "photographer.someone",
174 "location.france.paris",
175 "monochromatic"
176 ],
177
178 "path": "[resource path]",
179
180 "thumbnail": null | {
181 "resource": "[resource path]",
182 "resolution": {
183 "width": 400,
184 "height": 200
185 }
186 },
187
188
189 "_comment": "type-dependent",
190
191 "properties": {
192 "type": "picture",
193 "resource": "[resource url]"
194 },
195
196 "properties": {
197 "type": "other",
198 "resource": "[resource url]"
199 },
200
201 "properties": {
202 "type": "directory",
203 "items": [ { "_comment": "item objects..." } ]
204 }
205}
206```
207
208
209#### Normalised items and thumbnails
210
211Gallery items are normalised and made available in the `items` sub-directory of
212the data output directory. Normalisation consists of optional transcoding and
213other transforms as configured by the user in the compiler part of the
214`gallery.yaml` configuration file.
215
216Thumbnails are also generated for those items and are placed in the
217`thumbnails` sub-directory. Thumbnails of pictures in particular are resized
218using ~~Lanczos~~ (not available) bilinear resampling. Directory thumbnails
219may later be generated by picking or assembling one or multiple of its items,
220or defined explicitely by the user.
221
222The structure of the input directory is kept in both those output
223sub-directories. Input item files and directories also keep their original
224names.
225
226
227## Gallery viewer
228
229The __viewer__ is a single-page web application which displays the gallery's
230content.
231
232It runs fully on the client's side and remains usable without any back-end. It
233renders the compiled resources from the `data` directory, placed at its root,
234generated by the __compiler__.
235
236
237### URL anchor
238
239The page anchor is updated and used by the application to reflect the state of
240its current state in such a way that any view can be shared and loaded back by
241copying the URL and its anchor. It should in particular contain the current
242directory or item, as well as the filtering query.
243
244
245### Directory/collection/grid view
246
247The application starts by showing a grid view of the root directory of the
248gallery.
249
250This combined view offers the possiblity to the user to navigate to other items
251and to search recursively through the current directory.
252
253