YAG-OSDL homepage


YAG-OSDL is a GPL'd cross-platform tool which generates a static website from a set of image files, in order to build a full web gallery allowing to look at the pictures pleasantly. Hierarchical thematical sort and comments are supported [see example of result].

More in-depth informations

More specifically, YAG-OSDL is made of a set of python scripts which scan a directory tree containing images (ex: JPEG files), and construct out of them a set of HTML pages with thumbnails, offering the possibility to look at the pictures, with a standard browser, according to two different ways:

Gallery authors are provided with a way of adding their comments for any picture, and with a way of describing to which theme(s) a picture belongs.

YAG-OSDL is fully customizable, thanks to its configuration file, whose default name is yag-osdl.conf. Everything can be generated, the portal page included, with comments and term of use. Web themes ("skins" for galleries, not to be confused with content themes) are supported, and give their full power thanks to CSS (Cascading Style Sheets).

We developed YAG-OSDL since we needed a tool which would archive our graphical resources so that we could browse quickly through them and select the content suited for our video game: another way of describing YAG-OSDL is indeed: "a media content browser". We plan to add sound archiving support, as soon as we feel enough need for such a feature.

Current version of YAG-OSDL is 0.6.

YAG-OSDL has been inspired from YAG, a previous work from Stas Z (thanks !).

Step-by-step mini user's guide


You have a directory tree (possibly only a directory, preferably a pre-sorted tree) of image files, such as:

|-- GoldWashing
|   |-- 200407-Chilhac-0096.jpeg
|   |-- 200407-Chilhac-0099.jpeg
|   |-- 200407-Chilhac-0103.jpeg
|   |-- 200407-Chilhac-0113.jpeg
|   |-- 200407-Chilhac-0114.jpeg
|   |-- 200407-Chilhac-0115.jpeg
|   |-- 200407-Chilhac-0116.jpeg
|   `-- 200407-Chilhac-0117.jpeg
`-- InsideVillage
    |-- 200407-Chilhac-0087.jpeg
    |-- 200407-Chilhac-0088.jpeg
    |-- 200407-Chilhac-0089.jpeg
    |-- 200407-Chilhac-0090.jpeg
    `-- 200407-Chilhac-0091.jpeg

You want to generate a full web gallery out of it, and you are using GNU/Linux (the Windows platform cannot benefit from helper shell scripts, which will ease the work of the gallery author).

You might have interesting overall (general) gallery informations to give, let's suppose you wrote them down in a text file (ex: MyInfos.txt). If your gallery is to be put online, you might have thought to a license and term of use, that you would have written in another text file (ex: MyLicence.txt).

What to do

Step one: install the tool

First, retrieve and install prerequesites: python, version 2.2.3 or higher (most Linux distributions have it, check your version with: python -V; users of Debian-based distributions can enter apt-get install python), and the Python Image Library (PIL, installed the Debian way thanks to apt-get install python-imaging).

Then, retrieve YAG-OSDL from here, and extract it (tar xvjf yag-osdl-0.6.tar.bz2). Alternatively, you can get latest YAG-OSDL version from SVN thanks to:

svn co http://osdl.svn.sourceforge.net/svnroot/osdl/Tools/yag .

Step two: edit the YAG-OSDL configuration file

Go into the yag-osdl-0.6 (for SVN: go to the yag directory), and edit your own configuration file, that you may copy from sample: cp yag-osdl.conf.sample myProject.conf. We hope the sample is self-describing enough for most users, yours could be edited that way:


# This must be a valid filename (no white-space, no special character)
project_name          = MyBeautifulProject

content_directory     = /home/john/MySnapshots
resource_directory    = /home/john/WhereIExtractedYAG-OSDL/yag-osdl-0.6/Resources

output_in_content     = True
output_directory      = "Does not matter"

theme                 = OSDL-theme

thumbsize             = 120
images_by_row         = 4
images_by_column      = 4
dash_is_space_in_menu = True

author                = John Doe
author_mail           = John.Doe@esperide.com

gallery_license_file  = MyLicense.txt
gallery_info_file     = MyInfos.txt

Step three: annotate the images, thanks to our helper script

If we launch YAG-OSDL now, no comment nor theme information will be available. If one wants to have them, just enter from the directory where you extracted YAG-OSDL:

annotate-images.sh <your root content tree>
(ex: annotate-images.sh /home/john/MySnapshots)

We hereby suppose that two really common tools are available on your computer, nedit (a text editor), and xv (xview) or eog (eye of gnome), most common image viewers. If you do not have them and do not want to install them, or if you prefer using other tools, just update accordingly the two helper scripts handleGalleryDirectory.sh and handleImage.sh.

The annotate-images.sh script will output informations about what to do, and will trigger the appropriate tools. That is, it will first fire a text editor for each encountered gallery when scanning your content tree. On this example, it would be first MySnapshots, then GoldWashing, and then InsideVillage. In each file, feel free to give overall informations relative to the images in that directory.

After this gallery-commenting phase, the next phase will be the per image commenting. For each image of the content tree, annotate-images.sh will launch the specified image viewer so that the picture is displayed, and then a first text editor where you may put comments reminded thanks to the image viewing (the files dedicated for comments have the .txt extension). When writing is over, just close the text editor, and another instance of it will be triggered. This time, enter the theme informations for this image, as explained further.

How to specify that your image belongs to themes 'Surf' and 'Hawaï', and that the theme 'Surf' is a sub-theme of theme 'My favorite sports' ? Simply, in the spawn theme file, enter in first line: My favorite sport: Surf and in the second Hawaii. That's it, YAG-OSDL has all the informations it needs to do its work.

You can therefore close the image window (you have finished with that one) and this theme file, and repeat the process:

  1. view the current image
  2. enter its comment (if any) and close the text editor
  3. enter its theme informations (if any) and close the image viewer and the text editor. Repeat from point 1
until annotate-images.sh stops with Annotations finished !, which will mean that you went successfully through the whole comment and thematical sort process.

Note that you can at any time stop the annotation script, you will not loose any entered informations, and by re-launching the script the same way you launched it, you will be able first to validate or update every already available information you gave, until you reach the point where you stopped. You will then just have to continue the indexing process as before.

Another way of dealing with theme hierarchy

There is a complementary method in order to define you theme tree: instead of specifying the link between themes relatively to an image, you can use too a standalone theme file whose name is yag-overall-themes.thm. This file should be placed at the root of your content, and might have the usual structure <father-theme>: <a-child-theme>, as shown here:

My favorite sports: sailing
My favorite sports: surf
My favorite sports: yoga

surf: Hawaii-2003
surf: Hawaii-2004
surf: Snapshots Of The Shark That Ate My Board 
This stand-alone theme file proved useful, since, that way, all the theme tree can be defined and understood in one place. However, any combination of theme specifications will work: one can both use image theme files and the standalone theme file.

Step four: launch YAG-OSDL

Still following the example, one just have to run

run-yag-osdl.sh -rc myProject.conf

If it fails (ex: PIL not found), update yag-osdl-environment.sh accordingly.

Processing informations will be displayed and, if everything went right (the usual case) you should end up with something like:

You can browse your new gallery from file:///home/john/MySnapshots/MainMyBeautifulProject.html. Enjoy !

Step five: admire the result

Use your browser to inspect your new gallery, improve comments and themes if necessary and, if you feel like it should be put online, copy the whole content directory to a webserver, add a link to the gallery main page and tell all your friends about it !

Please react !

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, or if you would like to contribute and help us, even a little bit, drop us a line !


Last update: Monday, March 3, 2008