BBGallery
=========

>> What is it? 

   BBGallery is a small Perl script generating a number of
   HTML files from jpeg images that make up a image gallery to browse
   with any html browser. It uses The Gimp and Gimp-Perl to create
   thumbnails and to scale the images. It offers the following features:

     * Thumbnail creation (size can be configured)
     * Scaling images to a configurable size (optional)
     * Links to full size image
     * Meta galleries (optional)
       (Galleries of galleries)
     * Labels, title or text can be assigned to images and/or galleries using
       simple text files.
     * Easy installation and use
     * No extra software needed to view galleries and images on any
       plattform (ideal for archiving images)
     * Automatic slideshow
     * Support of the <LINK> tag for easy navigation in modern browsers
       
   A sample gallery can be seen at 
   http://www.bb-zone.com/BBGallery/SampleGallery/index_0.html
   
>> Why do you need it? 

   Sure enough there are plenty of programs available
   creating all kinds of galleries. Most of them however make use of
   dynamic content and require a Web server with PHP, Zope, python,
   you-name-it installed. Not everybody has the resources to get all
   tyhose things up and running in order to create a gallery. Also for
   archiving images this is not really a solution.
   
   My focus while writing BBGallery was to create a tool that allows for
   easy achival of a large number of images. I wanted something that can
   generate galleries and doesn't any other input than a directory full
   of jpegs. The generated galleries should be easy to browse and have a
   static structure to use them on read only medias such as CDs.
   
   And that's what BBGallery offers. Just cd into your image directory
   and run bbgallery. If you don't want any fancy labes or explaining
   text that's all you need to do. Text and labels can be added later
   very quick and easy by creating text files and rerunning bbgallery.
   It's even gonna be a lot faster the second time around as all the
   scaling has already be done.
   
   If you look for a quick solution to get you images organized BBGallery
   is for you.
   
>> Where to get it? 

   BBGallery is available as compressed tar archive, RPM
   or source RPM package. To download the latest version use one of the
   following links:
     Compressed tar archive
     ftp://ftp.bb-zone.com/pub/bbgallery/bbgallery.tar.bz2

     RPM package
     ftp://ftp.bb-zone.com/pub/bbgallery/bbgallery.rpm

     Source RPM package
     ftp://ftp.bb-zone.com/pub/bbgallery/bbgallery.spm

   To get an older version go to the ftp directory
   ftp://ftp.bb-zone.com/pub/bbgallery and pick whatever you desire.

>> Installation

   How to install it? Installation is fairly easy. But before you start
   installing BBGallery make sure you have The Gimp and Gimp-Perl
   installed on your system. The exact insatllation procedure depends
   whether use use the RPM or the tar archive for installation.
   
   * Installing the RPM
   This is the easiest way to get BBGallery. Download the RPM and run (as
   root):
   
     rpm -Uvh bbgallery.rpm
     
   That's all there is to it.
   
   * Installing the tar archive
   If your system doesn't support RPM, you may need to use the tar
   archive for installation. Download the file and unpack the archive
   using:
   
     bzcat bbgallery.tar.bz2 | tar xvf -
     
   Now change into the new created directory bbgallery-version and use make to 
   build and install it:
   
	make bbgallery
	make install
     
   This will install BBGallery into /usr/bin and /usr/lib. If you want
   another destination set prefix in the make commandline accordingly. I.e.
      
	make install prefix=/usr/local

   will install in /usr/local/bin and /usr/local/lib
   
   Not too though either, is it?

>> How to use it? 

   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 .jpeg: 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
     * Do not create links to the meta index
     * Thumbnails are scalled to 100 pixels
     * Images are scaled to 800 pixels
     * Short descriptions in the index page       

   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:

    -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]
        --thumb-only      Disable scaling, use thumbnails only [no]
        --no-short-dsc    Disable short descriptions
    -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 for index pages
	                  [Gallery]
    -d  --directory <s>   Create gallery for images in directory <s> [.]
    -w  --wait <n>        Delay between slides in slide show is
                          <n> seconds [15]
    -M  --meta            Create meta index
    -h  --help            Show this help screen
    -L  --metalink        Enable link to meta index in gallerie [no]
    -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 caprions. By default 
                          underscores are replaced with spaces and the 
                          extension is stripped
        --no-save         Do not save configuration in image direcorty

>> Scaling   

   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.

>> Custom Header

   You can also create a file called header.txt in the same directory as the
   images. The text in this file will be copied into the header of
   each image html file. This is perfect for a css style description,
   for example: you can then change the style of your whole collection
   just by modifying one file. Even better, make header.txt contain a
   reference to your css file, with the command: 
   <LINK REL=StyleSheet HREF="header.css" TITLE="My_Style">
   You can safely ignore this if you don't want to mess with CSS, but
   it's a powerful way to style your image descriptions.   

>> Meta Index

   The last thing to talk about are meta indexes. 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 tith -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"

   I guess that's all there is for now. If you have problems or crave for
   more features please let me know and we'll see what we can do.

>> Persistent Settings
  
   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).

   If you edit the configuration file you can actually modify more stuff than possible
   on the command line. There are settings for almost all colors used to generate the
   gallery pages. The format is very simple. The file consists of one line assignements.
   Just look at it and you will see... :)

   The order in which the configuration setting are applies 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.
   
>> What now? 

   This is the second generation of BBGallery. I was quite surprised how many users
   this little utility found. Most of the features added in 1.1 were suggestions I got 
   from users. There are still some features missing (like full blown page templates and 
   cascaded meta galleries). I don't know when or if I'll get to do those, but I'll keep
   trying.

   If you like BBGallery, need help or have suggestions please subscribe to the mailinglists
   I set up. Subscription is Web based and can be done at

     -> http://mailman.bb-zone.com/mailman/listinfo

   Enjoy BBGallery!
   
   BBgallery is (C) 2001 Bodo Bauer, All Rights Reserved for information on
   distribution colsult the file COPYING in this directory.





