1LAZYGAL(1) LAZYGAL(1)
2
6 lazygal - static web gallery generator
7
9 lazygal -h | -v | options albumdir
10
12 This manual page explains the lazygal program. This program is a stat‐
13 ic web gallery generator written in Python.
14 lazygal works so: you should have an original store of files - possibly
16 containing subdirectories (their names serving as headings if not using
17 the album metadata feature). This is the source file hierarchy. It
18 will never be modified by lazygal. Then, when launching:
19 $ lazygal -o /var/www/MyAlbum /home/user/SourceDir
21 lazygal will analyze the contents of the source hierarchy and will
23 (re)create the target hierarchy, with all the bells and whistles de‐
24 fined by the templates. Only missing parts or parts that are not up to
25 date will be generated. There is a limitation to this mechanism
26 though: although updates in the source directory, in the metadata or in
27 the themes are detected, changes in command line options and configura‐
28 tion files since last generation are not and the user should manually
29 delete files that need to be generated again.
30
32 These programs follow the usual GNU command line syntax, with long op‐
33 tions starting with two dashes (`-'). A summary of options is included
34 below. For a complete description, see the -h switch.
35 -v --version
37 Show program's version number and exit.
38 -h --help
40 Show summary of options.
41 --quiet
43 Don't output anything except for errors.
44 --debug
46 Output everything that lazygal is doing.
47 -o DEST_DIR --output-directory=DEST_DIR
49 Directory where web pages, slides and thumbs will be written
50 (default is current directory).
51 -t THEME --theme=THEME
53 Theme name (looked up in theme directory) or theme full path.
54 --default-style=DEFAULT_STYLE
56 Default style to apply to the theme. This is actually the file‐
57 name (no extension) of the CSS stylesheet of the theme that is
58 not marked as alternate, thus should get used as default or pre‐
59 ferred by the web browser.
60 --template-vars=TPL_VARS
62 Common variables to load all templates with, e.g. --template-
63 vars='footer=foo bar,color=baz'. For longer variable contents,
64 it is easier to use a configuration file (see LAZYGAL-CONF).
65 -f --force-gen-pages
67 Force rebuild of web pages, regardless of the modification times
68 of their dependencies. This is handy when changing a configura‐
69 tion option affecting these (theme, directory flattening, etc.).
70 --clean-destination
72 Clean destination directory of files that should not be there.
73 --preserve=PATTERN
75 Specify a file pattern (or name) which should be ignored during
76 cleanup of the destination. May be specified more than once.
77 Values given here will be in addition to those specified in con‐
78 figuration files.
79 --exclude=PATTERN
81 Specify a file pattern (or name) which should be ignored during
82 processing. May be specified more than once. Values given here
83 will be in addition to those specified in configuration files.
84 --check-all-dirs
86 Exhaustively go through all directories regardless of source
87 modification time.
88 -s IMAGE_SIZE --image-size=IMAGE_SIZE
90 Size of images, define as name=xxy, ..., eg.
91 small=800x600,medium=1024x768. The special dimensions 0x0 use
92 original size. Refer to the IMAGE RESIZE DESCRIPTION section
93 for more information on the available syntax. The number of
94 sizes provided will define the number of sizes that will be gen‐
95 erated: --image-size="medium=800x600" will only generate all im‐
96 ages for a medium size (no small size) --image-
97 size="small=640x480,medium=800x600,large=1024x768" will generate
98 3 sizes for all images (small, medium, large)
99 -T THUMBNAIL_SIZE --thumbnail-size=THUMBNAIL_SIZE
101 Size of thumbnails, eg. 150x113. Refer to the IMAGE RESIZE DE‐
102 SCRIPTION section for more information on the available syntax.
103 -q QUALITY --quality=QUALITY
105 Quality of generated JPEG images (default is 85).
106 -O --original
108 Include original photos in output.
109 --orig-base=RELATIVE_PATH
111 Do not copy original photos in output directory, instead link
112 them using RELATIVE_PATH as base for those links (discarded
113 without -O).
114 --orig-symlink
116 Do not copy original photos in output directory, instead create
117 symlinks to their original locations. This is useful when you
118 plan transferring the whole directory which `generated to some
119 other location, perhaps withrsync`, and you wish to avoid creat‐
120 ing an extra copy of each photo.
121 Caution
123 This option is not available on Windows; if you try to
125 use it on that operating system, lazygal will immediately
126 exit with an exit status of 1.
127 --puburl=PUB_URL
129 Publication URL (only useful for feed generation).
130 -m --generate-metadata
132 Generate metadata description files where they don't exist in
133 the source tree instead of generating the web gallery. This
134 disables all other options.
135 -n THUMBS_PER_PAGE --thumbs-per-page=THUMBS_PER_PAGE
137 Maximum number of thumbs per index page. This enables index
138 pagination (0 is unlimited).
139 --filter-by-tag=TAG
141 If set, lazygal will only export the pictures that have one of
142 their (IPTC) tags matching TAG. It is also possible to use an
143 equivalent of AND and OR boolean tests to filter tags. For more
144 details, read below the section TAG FILTERING.
145 --pic-sort-by=ORDER
147 Sort order for images in a subgallery, among 'mtime', 'file‐
148 name', 'numeric', or 'exif'. (default is 'exif' which is by
149 EXIF date if EXIF data is available, filename otherwise, sorting
150 EXIF-less images before). 'numeric' does a numeric sort on the
151 numeric part of the filename. Add ':reverse' to reverse the
152 sort order (e.g. --pic-sort-by=mtime:reverse).
153 --subgal-sort-by=ORDER
155 Sort order for subgalleries, among 'exif' (EXIF date of the lat‐
156 est picture in sub-gallery), 'mtime', 'dirname', or 'numeric'
157 (default is 'dirname'). 'numeric' does a numeric sort on the
158 numeric part of the dirname. Add ':reverse' to reverse the sort
159 order (e.g. --subgal-sort-by=dirname:reverse).
160 --dir-flattening-depth=LEVEL
162 Level below which the directory tree is flattened. Default is
163 no flattening ('No').
164 This option makes the program include the web gallery index of
166 child galleries in their parent's gallery index, if their level
167 is greater than the supplied LEVEL. The level of the album root
168 is 0.
169 Index pages with multiple galleries (which happens when this
171 section is used) show the pictures links in gallery sections.
172 The following examples show the produced indexes for a sample
174 album (2 sub-galleries, 1 sub-sub-gallery, 1 picture in each one
175 of those).
176 Example 1. –dir-flattening-depth=No (default)
178 index.html <- sub-gallery links
180 subgal1/index.html <- index with img1
181 subgal1/img1.html
182 subgal1/subsubgal1/index.html <- index with img2
183 subgal1/subsubgal1/img2.html
184 subgal2/index.html <- index with img3
185 subgal2/img3.html
186 Example 2. –dir-flattening-depth=0
188 index.html <- contains index for all pics
190 subgal1/img1.html
191 subgal1/subsubgal1/img2.html
192 subgal2/img3.html
193 Example 3. –dir-flattening-depth=1
195 index.html <- contains index for all pics
197 subgal1/index.html <- index with img1 and img2
198 subgal1/img1.html
199 subgal1/subsubgal1/img2.html
200 subgal2/index.html <- index with img3
201 subgal2/img3.html
202 -z --make-dir-zip
204 Make a zip archive of original pictures for each directory.
205 --webalbum-pic-bg=WEBALBUMPIC_BG
207 Webalbum picture background color. Default is transparent, and
208 implies the PNG format. Any other value, e.g. red, white, blue,
209 uses JPEG.
210 --webalbum-pic-type=WEBALBUMPIC_TYPE
212 What type of web album thumbnails to generate. By default,
213 lazygal generates the well-loved "messy" thumbnails with random‐
214 ly selected pictures from the album each rotated by a random
215 amount and pasted together. This default can also be forced by
216 specifying 'messy' as WEBALBUMPIC_TYPE.
217 On the other hand, specifying 'tidy' as the value of this option
219 forces lazygal to skip the rotations, resulting in more regular‐
220 ly shaped thumbnails which can also be more densely packed.
221 This can be an advantage if not all users of your albums have
222 huge screens :-)
223 --keep-gps-data
225 Do not remove GPS data from EXIF tags. By default the location
226 tags are removed for privacy reasons. However, there are situa‐
227 tions when having the location data makes sense and is desired.
228 This is mostly meant to be used with holiday photos.
229 --no-video
231 Do not process videos nor include them in indexes.
232
234 A theme maps to a directory that contains the following items:
235 theme/SHARED_*
237 Files to put in the web gallery directory shared, e.g. CSS,
238 Javascript, images or other resources common to all galleries.
239 theme/browse.thtml
241 The XHTML template for the theme browse page (displaying one
242 picture).
243 theme/dirindex.thtml or theme/dynindex.thtml
245 The XHTML template for the directory index page (pictures and
246 sub-galleries links).
247 Depending on which index file is present, the theme will be:
249 dirindex.thtml: fully static
251 one HTML page per picture, per size and one index per size, or
252 dynindex.thtml: dynamic
254 only one index per directory is to be generated.
255 theme/*.thtml must be valid XML. See http://genshi.edgewall.org/wi‐
257 ki/Documentation/xml-templates.html for syntax. Dependencies for stat‐
258 ically included templates (i.e. with filenames not computed from vari‐
259 ables) are automatically computed: when an included template is modi‐
260 fied, the software will automatically figure out which pages to re-gen‐
261 erate. Missing template files will be searched for in the default
262 theme.
263 theme/SHARED_* files (common resources for the directory shared) are
265 renamed to strip the SHARED_ prefix and:
266 • Processed using the Genshi text template engine (see http://gen‐
268 shi.edgewall.org/wiki/Documentation/text-templates.html for syntax.)
269 if their file extension starts with t,
270 • Copied to the web album destination otherwise.
272 Using the theme manifest theme/manifest.json file, it is possible to
274 include files from other directories to be copied into the web album
275 shared files.
276 {
278 "shared": [
279 # copy as shared/lib.js
280 { "path": "../lib-2.1.js", "dest": "lib.js" },
281 # copy as shared/js/lib-2.1.js
283 { "path": "../lib-2.1.js", "dest": "js/" }
284 # copy first found as shared/lib.js
286 # instruct ./setup.py dl_assets to download it from url otherwise
287 { "path": [ "/usr/share/javascript/lib-2.1.js", "lib.js"],
288 "dest": "lib.js",
289 "url": "https://lib.com/lib-latest.js"
290 },
291 # copy prefixed files in shared/
293 { "path": "SHARED_*" },
294 ]
295 }
296 Please refer to the examples supplied in /usr/share/lazygal/themes.
299
301 If a directory from the source album contains a file named album_de‐
302 scription, it is processed as a source of album metadata. The format
303 is borrowed from another album generating tool - Matew. Each line is
304 treated as one possible tag, unknown lines are simply ignored. Example
305 content of this file follows:
306 Album name "My album"
308 Album description "Description, which can be very long."
309 Album image identifier relative/path/to/image.jpg
310 Otherwise, the user can provide metadata in the following files.
312 SOURCE_DIR/album-name
314 The title to use for this album directory.
315 SOURCE_DIR/album-description
317 The description for this album directory. HTML tags are used
318 verbatim from this file.
319 SOURCE_DIR/album-picture
321 The relative path to the image to use at the top of the album
322 picture stack.
323 SOURCE_DIR/PICTURE_FILENAME.comment
325 The description to use for this particular image. Please note
326 that HTML tags are taken as provided in this file for output in
327 the templates.
328 Lazygal also extracts information from many metadata tags in image
330 files. Regarding image description, Lazygal searches for comments in
331 this order:
332 1. pic.jpeg.comment file
334 2. Exif.Photo.UserComment
336 3. Exif.Image.ImageDescription
338 4. Iptc.Application2.ObjectName
340 5. JPEG comment
342
344 ~/.lazygal
345 User configuration directory.
346 ~/.lazygal/themes
348 User themes directory.
349
351 Multiple configuration files are processed by DHPACKAGE. The configu‐
352 ration is initially set up with the defaults. The defaults can be
353 found in the DHPACKAGE source distribution in lazygal/defaults.json.
354 Then, the configuration files are processed in the following order,
356 each newly defined value overloading formerly defined values.
357 Finally, any command-line-provided parameter takes precedence on any
359 configuration file value.
360 ~/.lazygal/config
362 User configuration file. See LAZYGAL-CONF for format.
363 SOURCE_DIR/.lazygal
365 Album root configuration file. See LAZYGAL-CONF for format.
366 SOURCE_DIR/gal/.lazygal
368 Web gallery configuration file. Only the webgal and template-
369 vars sections are red in these files. The configuration applies
370 to the gallery representing the directory of the configuration
371 file, and all of its sub-directories, unless another configura‐
372 tion file in a sub-directory overloads some of the defined con‐
373 figuration values. See LAZYGAL-CONF for format.
374
376 The size string follows the same syntax as ImageMagick's.
377 scale% Height and width both scaled by specified percentage.
379 xscale%yscale%
381 Height and width individually scaled by specified percentages.
382 width Width given, height automatically selected to preserve aspect
384 ratio.
385 xheight
387 Height given, width automatically selected to preserve aspect
388 ratio.
389 widthxheight
391 Maximum values of height and width given, aspect ratio pre‐
392 served.
393 widthxheight^
395 Minimum values of width and height given, aspect ratio pre‐
396 served.
397 widthxheight!
399 Width and height emphatically given, original aspect ratio ig‐
400 nored.
401 widthxheight>
403 Change as per the supplied dimensions but only if an image di‐
404 mension exceeds a specified dimension.
405 widthxheight<
407 Change dimensions only if both image dimensions exceed specified
408 dimensions.
409 pixels@
411 Resize image to have specified area in pixels. Aspect ratio is
412 preserved.
413
415 Tag filtering supports regular expression matching thanks to the 're'
416 module of Python. All the filter matchings can be indicated to lazygal
417 by successive uses of the 'filter-by-tag' option, or by giving a coma-
418 separated list of keywords.
419 We illustrate here how more elaorated tag filtering can be done.
421 We want to export only the images that have the tags 'lazygal' AND
423 'hiking'.
424 $ lazygal --filter-by-tag=lazygal --filter-by-tag=hiking
426 or:
428 $ lazygal --filter-by-tag=lazygal,hiking
430 We want to export the images that have the tags 'lazygal' OR 'hiking'.
432 $ lazygal --filter-by-tag="(lazygal|hiking)"
434 We want to export the images that have one of the tags 'hiking_2012',
436 'hiking_2013', 'hiking_France', etc.
437 $ lazygal --filter-by-tag="hiking_.*"
439 We want to export the images that have the tag 'lazygal', AND one of
441 the tags 'hiking_2012', 'hiking_2013', 'hiking_France', etc.
442 $ lazygal --filter-by-tag="lazygal,hiking_.*"
444
446 lazygal.conf(5)
447 More information is available on the program website: https://sml.zin‐
449 cube.net/~niol/repositories.git/lazygal/about/.
450
452 This manual page was written for the DEBIAN system (but may be used by
453 others). Permission is granted to copy, distribute and/or modify this
454 document under the terms of the GNU General Public License, Version 2
455 any later version published by the Free Software Foundation.
456 On Debian systems, the complete text of the GNU General Public License
458 can be found in /usr/share/common-licenses/GPL.
459
461 Alexandre Rossi.
462 LAZYGAL(1)