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