-- Usage



General Procedures
The most important things you need to use BBGallery are jpeg images. Once you got those the rest is easy. BBGallery only looks for imges with the extension .jpg. Not the lower case. Included is a little utility to rename *.JPG files to *.jpg: JPG2jpg. Just run it in the image directory and all your JPG extensions will be moved to lower case.

Now run bbgallery to create the galleries. Without any parameters it will use the following default values:

  • Look for images in the default directory
  • Create index pages with up to 25 thumbnails
  • Have up to five thumbnails in one row
  • Use Gallery as title for the index pages
  • Be quiet. Don't produce any output on SDTOUT
  • Delay pages in the slide show for 15 seconds
  • Create links to the meta index
  • Thumbnails are scalled to 100 pixels
  • Images are scaled to 800 pixels
  • Short descriptions in the index page
  • The default template will be used
Later you'll see how all those defaults can be overwritten with the appropriate comand line switches.

After the script is finished you will notice two new subdirectories: scaled and thumbs. The scaled images are stored in scaled and the thumbnails are in thumbs. Who would have guessed? You'll also see a ton of HTML files. There are two HTML files for each image. One for the scaled image and one for the slide show. The index files are named index_n.html, where n starts at zero. The number of index files depends on the number of images. Now open index_0.html in your web browser and you'll see you image gallery. Can it be more easy... :)

If you don't want to go with the defaults use the command line switches to specify your needs:

 bbgallery [options]
-v --verbose Be verbose [no]
-f --force Force the (re)creation of thumb nails and
scaled images [no]
-s --scale <n> Scale images to <n> pixels
(n=0 disables scaling) [800]
--thumb <n> Make thumbnails <n> pixels big [100]
--no-short-dsc Disable short descriptions. By default the
first line of the description (if present)
is used as caption. With this option the
filename will always be used.
-c --cols <n> Create index pages with <n> columns [5]
-m --max <n> Maximal <n> thumb nails on one index
page [25]
-t --title <s> Use <s> as title [Gallery]
-d --directory <s> Create gallery for images in directory <s> [.]
-T --template <s> Name of templates to use [default]
-w --wait <n> Delay between slides in slide show is set to
<n> seconds [15]
-M --meta Create meta index instead of image and index
-h --help Show this help screen
-L --metalink Enable link to meta index in gallery index [yes]
-V --version Print version number and exit
-I --ImageMagick Use ImageMagick instead of Gimp to scale images
-q --quality <1-100> JPEG quality of scaled images [100]
--raw-caption Use filename as is for image captions. By default
underscores and dashes are replaced with spaces
and the extension is stripped
--no-save Do not save configuration in image direcorty
A word on scaling. When images are scaled (either to smaller/bigger images or to thumbnails) the aspect ration is always preserved. You can only specify one number for scaling with -s or --thumb. This number will be the length of the longer side of the scaled image (width for landscape, or height for portrait style images). The image quality will also be preserved, no smoothing or additional compression is used. Scaling is only performed when either no scaled image/thumbnail is found, or when the image file is more recent than the scaled version or thumbnail. Use -f to enforce scaling.

Since Version 1.01 scaling can be done either using The Gimp (default) or by ImageMagick. To use ImageMagick specify '-I' on the commandline. Make sure you have 'convert' and 'identify' (part of ImageMagick) installed on your system.

Descriptive Text
If you like to add some explaning text or maybe just labels to your images or the index pages all you have to do is to create test files containing this text. For the index pages name the file index.txt. Rerun bbgallery and you'll see the text on the index page. You can make full use of HTML in this file. Just keep in mind that the contents of this file will end up in a table cell.

Adding text to the image pages is equalliy simple. Create a text file with the base name as the image, but use the extension .txt instead of .jpg. Rerun bbgallery and you have your text on the image page.

The first line of this text file is used as a "short description" and is shown in the index if you leave the mouse cursor on top of an image. If you don't like it, leave the first line blank or use --no-small-dsc to disable it entirely.

You can choose between different page designs by selecting a set of page templates.  Currently there are two set of templates provided with BBGallery: oldstyle and monochrome. Oldstyle mimics the latout of pre 1.2 versions of BBGallery and is a rather plain design. The new default monochrome uses CSS, has icons for navigation and has a nive an clean layout. Read the templates page to learn more about templates and how to create your own design.

Meta Index
Imagine you have a set of image directories all in the same subdirectory. Now you generate a gallery for each image directory. Now wouldn't it be nice to have a master page linking to all the individual galleries? That's what a meta index is about. Just call bbgallery -M in the master directory (and add a title with -t if you like) and you'll get that master page. There will be a thumbnail for each gallery (the first image in the gallery) and links to each gallery.

Note that this only works if you create the galleries from the 'top-level' directory as well. If you cd'ed into the image directories to create the galleries the meta index generation will fail. For example if you have three image directories named 'Car', 'Bike', 'Wife' you have to use the following command sequence to create the galleries and the meta index:

    > bbgallery -L -t Car  -d Car
> bbgallery -L -t Bike -d Bike
> bbgallery -L -t Wife -d Wife
> bbgallery -M -t "My Dearest Assets"
Persistent Settings, Defaults
Since release 1.1 bbgallery writes the file '.bbgallery' into the image directory. All settings specified on the commandline along with the default settings are saved this way. If you rerun the script there is no need to specify all settings again, unless you want to change something. BBGallery also looks for configuration files in your home directory and in the directory it's called from. This is usefull to preset defaults (ie. alway use ImageMagick).

The order in which the configuration settings are applied is as follows:

  1. Read ~/.bbgallery
  2. Read ./.bbgallery
  3. Read image-dir/.bbgallery
  4. Read command line settings
Non existent files are skipped and each step overwrites the previous one. Meaning that the settings made on the commandline have the highest priority and pretty much everything else overwrites settings made in your home directory.
This site is Copyright (c) 2003 by Bodo Bauer. Hosting is provided by
All trademarks, service marks, and copyrights are property of their respective owners.