diff options
Diffstat (limited to 'devdoc')
-rw-r--r-- | devdoc/design-notes.md | 305 | ||||
-rw-r--r-- | devdoc/viewer_index_v2.1.md | 167 |
2 files changed, 472 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 | --- | ||
2 | title: ldgallery design notes | ||
3 | author: pacien | ||
4 | date: 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 | ||
14 | together, 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 | |||
29 | The compiler takes a source directory as input which shall contain item | ||
30 | resource files and associated metadata sidecar files. Those items may be | ||
31 | recursively grouped into multiple levels of sub-directories. | ||
32 | |||
33 | Example source directory structure: | ||
34 | |||
35 | ``` | ||
36 | example-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 | |||
50 | Metadata associated to items are stored in YAML sidecar files of the same name, | ||
51 | with the `.yaml` extension appended. The use of plain text sidecar files allow | ||
52 | for easier editing without any special tool in a unified manner for multiple | ||
53 | types of files (pictures, videos, ebooks, ...). The metadata contained within | ||
54 | item files are simply ignored. | ||
55 | |||
56 | Tags are given with a group hierarchy separated by `.`, which allows generic | ||
57 | searches as well as implicit disambiguation. | ||
58 | |||
59 | Example metadata sidecar file: | ||
60 | |||
61 | ```yaml | ||
62 | title: Some title | ||
63 | |||
64 | date: 2019-12-20T16:51:52+00:00 | ||
65 | |||
66 | description: > | ||
67 | Some multiline description | ||
68 | that may contain some markdown later. | ||
69 | |||
70 | tags: | ||
71 | - photographer.someone | ||
72 | - location.france.paris | ||
73 | - monochromatic | ||
74 | ``` | ||
75 | |||
76 | Possible 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 | |||
89 | The gallery YAML configuration file contains the __compiler__'s and the | ||
90 | __viewer__'s settings in two different sections. | ||
91 | |||
92 | Proposed configuration file, named `gallery.yaml` at the root of the source | ||
93 | directory: | ||
94 | |||
95 | ```yaml | ||
96 | compiler: | ||
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 | |||
113 | viewer: | ||
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 | ``` | ||
125 | data | ||
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 | |||
144 | The content of the `viewer` section of the gallery configuration file is used, | ||
145 | without any transformation by the __compiler__, to generate the `viewer.json` | ||
146 | file located at the root of the output directory. | ||
147 | |||
148 | |||
149 | #### Gallery items index | ||
150 | |||
151 | The __compiler__ generates a global index file `index.json` aggregating the | ||
152 | metadata of all the source sidecar files as a tree of items as described below. | ||
153 | Its root node is a directory item. The type of each property node is marked by | ||
154 | its `type` field. | ||
155 | |||
156 | Directory items aggregate their tags from the items below it in order to be | ||
157 | displayed in search results. | ||
158 | |||
159 | Resource paths are rooted with respect to the data output directory which | ||
160 | serves as the base path. | ||
161 | |||
162 | Serialised 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 | |||
211 | Gallery items are normalised and made available in the `items` sub-directory of | ||
212 | the data output directory. Normalisation consists of optional transcoding and | ||
213 | other transforms as configured by the user in the compiler part of the | ||
214 | `gallery.yaml` configuration file. | ||
215 | |||
216 | Thumbnails are also generated for those items and are placed in the | ||
217 | `thumbnails` sub-directory. Thumbnails of pictures in particular are resized | ||
218 | using ~~Lanczos~~ (not available) bilinear resampling. Directory thumbnails | ||
219 | may later be generated by picking or assembling one or multiple of its items, | ||
220 | or defined explicitely by the user. | ||
221 | |||
222 | The structure of the input directory is kept in both those output | ||
223 | sub-directories. Input item files and directories also keep their original | ||
224 | names. | ||
225 | |||
226 | |||
227 | ## Gallery viewer | ||
228 | |||
229 | The __viewer__ is a single-page web application which displays the gallery's | ||
230 | content. | ||
231 | |||
232 | It runs fully on the client's side and remains usable without any back-end. It | ||
233 | renders the compiled resources from the `data` directory, placed at its root, | ||
234 | generated by the __compiler__. | ||
235 | |||
236 | |||
237 | ### URL anchor | ||
238 | |||
239 | The page anchor is updated and used by the application to reflect the state of | ||
240 | its current state in such a way that any view can be shared and loaded back by | ||
241 | copying the URL and its anchor. It should in particular contain the current | ||
242 | directory or item, as well as the filtering query. | ||
243 | |||
244 | |||
245 | ### Directory/collection/grid view | ||
246 | |||
247 | The application starts by showing a grid view of the root directory of the | ||
248 | gallery. | ||
249 | |||
250 | This combined view offers the possiblity to the user to navigate to other items | ||
251 | and to search recursively through the current directory. | ||
252 | |||
253 | |||
254 | #### Directory breadcrumbs | ||
255 | |||
256 | The directory view displays the current dire |