README

   1 NAME
   2     Apache::Gallery - mod_perl handler to create an image gallery
   3
   4 SYNOPSIS
   5     See the INSTALL file in the distribution for installation instructions.
   6
   7 DESCRIPTION
   8     Apache::Gallery creates an thumbnail index of each directory and allows
   9     viewing pictures in different resolutions. Pictures are resized on the
  10     fly and cached. The gallery can be configured and customized in many
  11     ways and a custom copyright image can be added to all the images without
  12     modifying the original.
  13
  14 CONFIGURATION
  15     In your httpd.conf you set the global options for the gallery. You can
  16     also override each of the options in .htaccess files in your gallery
  17     directories.
  18
  19     The options are set in the httpd.conf/.htaccess file using the syntax:
  20     PerlSetVar OptionName 'value'
  21
  22     Example: PerlSetVar GalleryCacheDir '/var/tmp/Apache-Gallery/'
  23
  24     GalleryAutoRotate
  25         Some cameras, like the Canon G3, can detect the orientation of a the
  26         pictures you take and will save this information in the
  27         'Orientation' EXIF field. Apache::Gallery will then automatically
  28         rotate your images.
  29
  30         This behavior is default but can be disabled by setting
  31         GalleryAutoRotate to 0.
  32
  33     GalleryCacheDir
  34         Directory where Apache::Gallery should create its cache with scaled
  35         pictures. The default is /var/tmp/Apache-Gallery/ . Here, a
  36         directory for each virtualhost or location will be created
  37         automaticly. Make sure your webserver has write access to the
  38         CacheDir.
  39
  40     GalleryTemplateDir
  41         Full path to the directory where you placed the templates. This
  42         option can be used both in your global configuration and in
  43         .htaccess files, this way you can have different layouts in
  44         different parts of your gallery.
  45
  46         No default value, this option is required.
  47
  48     GalleryInfo
  49         With this option you can define which EXIF information you would
  50         like to present from the image. The format is: '<MyName =>
  51         KeyInEXIF, MyOtherName => OtherKeyInEXIF'
  52
  53         Examples of keys: ShutterSpeedValue, ApertureValue, SubjectDistance,
  54         and Camera
  55
  56         You can view all the keys from the EXIF header using this
  57         perl-oneliner:
  58
  59         perl "-e" 'use Data::Dumper; use Image::Info qw(image_info); print
  60         Dumper(image_info(shift));' filename.jpg
  61
  62         Default is: 'Picture Taken => DateTimeOriginal, Flash => Flash'
  63
  64     GallerySizes
  65         Defines which widths images can be scaled to. Images cannot be
  66         scaled to other widths than the ones you define with this option.
  67
  68         The default is '640 800 1024 1600'
  69
  70     GalleryThumbnailSize
  71         Defines the width and height of the thumbnail images.
  72
  73         Defaults to '100x75'
  74
  75     GalleryThumbnailSizeLS
  76         If set to '1', GalleryThumbnailSize is the long and the short side
  77         of the thumbnail image instead of the width and height.
  78
  79         Defaults to '0'.
  80
  81     GalleryCopyrightImage
  82         Image you want to blend into your images in the lower right corner.
  83         This could be a transparent png saying "copyright my name 2001".
  84
  85         Optional.
  86
  87     GalleryWrapNavigation
  88         Make the navigation in the picture view wrap around (So Next at the
  89         end displays the first picture, etc.)
  90
  91         Set to 1 or 0, default is 0
  92
  93     GalleryAllowOriginal
  94         Allow the user to download the Original picture without resizing or
  95         putting the CopyrightImage on it.
  96
  97         Set to 1 or 0, default is 0
  98
  99     GallerySlideshowIntervals
 100         With this option you can configure which intervals can be selected
 101         for a slideshow. The default is '3 5 10 15 30'
 102
 103     GallerySortBy
 104         Instead of the default filename ordering you can sort by any stat
 105         attribute. For example size, atime, mtime, ctime.
 106
 107     GalleryDirSortBy
 108         Set this variable to sort directories differently than other items,
 109         can be set to size, atime, mtime and ctime; setting any other value
 110         will revert to sorting by name.
 111
 112     GalleryMemoize
 113         Cache EXIF data using Memoize - this will make Apache::Gallery
 114         faster when many people access the same images, but it will also
 115         cache EXIF data until the current Apache child dies.
 116
 117     GalleryUseFileDate
 118         Set this option to 1 to make A::G show the files timestamp instead
 119         of the EXIF value for "Picture taken".
 120
 121     GallerySelectionMode
 122         Enable the selection mode. Select images with checkboxes and get a
 123         list of filenames.
 124
 125     GalleryEXIFMode
 126         You can choose how Apache::Gallery should display EXIF info from
 127         your images.
 128
 129         The default setting is 'namevalue'. This setting will make
 130         Apache::Gallery print out the names and values of the EXIF values
 131         you configure with GalleryInfo. The information will be parsed into
 132         $INFO in pictureinfo.tpl.
 133
 134         You can also set it to 'values' which will make A::G parse the
 135         configured values into the var $EXIFVALUES as 'value | value |
 136         value'
 137
 138         If you set this option to 'variables' the items you configure in
 139         GalleryInfo will be available to your templates as $EXIF_<KEYNAME>
 140         (in all uppercase). That means that with the default setting
 141         "Picture Taken => DateTimeOriginal, Flash => Flash" you will have
 142         the variables $EXIF_DATETIMEORIGINAL and $EXIF_FLASH avilable to
 143         your templates. You can place them anywhere you want.
 144
 145     GalleryRootPath
 146         Change the location of gallery root. The default is ""
 147
 148     GalleryRootText
 149         Change the name that appears as the root element in the menu. The
 150         default is "root:"
 151
 152     GalleryMaxThumbnailsPerPage
 153         This options controls how many thumbnails should be displayed in a
 154         page. It requires $BROWSELINKS to be in the index.tpl template file.
 155
 156     GalleryImgFile
 157         Pattern matching the files you want Apache::Gallery to view in the
 158         index as thumbnails.
 159
 160         The default is '\.(jpe?g|png|tiff?|ppm)$'
 161
 162     GalleryDocFile
 163         Pattern matching the files you want Apache::Gallery to view in the
 164         index as normal files. All other filetypes will still be served by
 165         Apache::Gallery but are not visible in the index.
 166
 167         The default is
 168         '\.(mpe?g|avi|mov|asf|wmv|doc|mp3|ogg|pdf|rtf|wav|dlt|html?|csv|eps)
 169         $'
 170
 171     GalleryTTFDir
 172         To use the GalleryCopyrightText feature you must set this option to
 173         the directory where your True Type fonts are stored. No default is
 174         set.
 175
 176         Example:
 177
 178                 PerlSetVar      GalleryTTFDir '/usr/share/fonts/'
 179
 180     GalleryTTFFile
 181         To use the GalleryCopyrightText feature this option must be set to
 182         the name of the True Type font you wish to use. Example:
 183
 184                 PerlSetVar      GalleryTTFFile 'verdanab.ttf'
 185
 186     GalleryTTFSize
 187         Configure the size of the CopyrightText that will be inserted as
 188         copyright notice in the corner of your pictures.
 189
 190         Example:
 191
 192                 PerlSetVar      GalleryTTFSize '10'
 193
 194     GalleryCopyrightText
 195         The text that will be inserted as copyright notice.
 196
 197         Example:
 198
 199                 PerlSetVar      GalleryCopyrightText '(c) Michael Legart'
 200
 201     GalleryCopyrightColor
 202         The text color of your copyright notice.
 203
 204         Examples:
 205
 206         White: PerlSetVar GalleryCopyrightColor '255,255,255,255'
 207
 208         Black: PerlSetVar GalleryCopyrightColor '0,0,0,255'
 209
 210         Red: PerlSetVar GalleryCopyrightColor '255,0,0,255'
 211
 212         Green: PerlSetVar GalleryCopyrightColor '0,255,0,255'
 213
 214         Blue: PerlSetVar GalleryCopyrightColor '0,0,255,255'
 215
 216         Transparent orange: PerlSetVar GalleryCopyrightColor '255,127,0,127'
 217
 218     GalleryCopyrightBackgroundColor
 219         The background-color of a GalleryCopyrightText
 220
 221         r,g,b,a - for examples, see GalleryCopyrightColor
 222
 223     GalleryQuality
 224         The quality (1-100) of scaled images
 225
 226         This setting affects the quality of the scaled images. Set this to a
 227         low number to reduce the size of the scaled images. Remember to
 228         clear out your cache if you change this setting. Quality seems to
 229         default to 75, at least in the jpeg and png loader code in Imlib2
 230         1.1.0.
 231
 232         Examples:
 233
 234         Quality at 50: PerlSetVar GalleryQuality '50'
 235
 236     GalleryUnderscoresToSpaces
 237         Set this option to 1 to convert underscores to spaces in the listing
 238         of directory names.
 239
 240     GalleryCommentExifKey
 241     Set this option to e.g. ImageDescription to use this field as comments
 242     for images.
 243
 244     GalleryEnableMediaRss
 245     Set this option to 1 to enable generation of a media RSS feed. This can
 246     be used e.g. together with the PicLens plugin from http://piclens.com
 247
 248 FEATURES
 249     Rotate images
 250         Some cameras, like the Canon G3, detects the orientation of a
 251         picture and adds this info to the EXIF header. Apache::Gallery
 252         detects this and automaticly rotates images with this info.
 253
 254         If your camera does not support this, you can rotate the images
 255         manually, This can also be used to override the rotate information
 256         from a camera that supports that. You can also disable this behavior
 257         with the GalleryAutoRotate option.
 258
 259         To use this functionality you have to create file with the name of
 260         the picture you want rotated appened with ".rotate". The file should
 261         include a number where these numbers are supported:
 262
 263                 "1", rotates clockwise by 90 degree
 264                 "2", rotates clockwise by 180 degrees
 265                 "3", rotates clockwise by 270 degrees
 266
 267         So if we want to rotate "Picture1234.jpg" 90 degrees clockwise we
 268         would create a file in the same directory called
 269         "Picture1234.jpg.rotate" with the number 1 inside of it.
 270
 271     Comments
 272         To include comments for a directory you create a <directory>.comment
 273         file where the first line can contain "TITLE: New title" which will
 274         be the title of the page, and a comment on the following lines. To
 275         include comments for each picture you create files called
 276         picture.jpg.comment where the first line can contain "TITLE: New
 277         title" which will be the title of the page, and a comment on the
 278         following lines.
 279
 280         Example:
 281
 282                 TITLE: This is the new title of the page
 283                 And this is the comment.<br />
 284                 And this is line two of the comment.
 285
 286         The visible name of the folder is by default identical to the name
 287         of the folder, but can be changed by creating a file
 288         <directory>.folder with the visible name of the folder.
 289
 290         It is also possible to set GalleryCommentExifKey to the name of an
 291         EXIF field containing the comment, e.g. ImageDescription. The EXIF
 292         comment is overridden by the .comment file if it exists.
 293
 294 DEPENDENCIES
 295     Perl 5
 296     Apache with mod_perl
 297     URI::Escape
 298     Image::Info
 299     Image::Size
 300     Text::Template
 301     Image::Imlib2
 302     X11 libraries (ie, XFree86)
 303     Imlib2 Remember the -dev package when using rpm, deb or other package
 304     formats!
 305
 306 AUTHOR
 307     Michael Legart <michael@legart.dk>
 308
 309 COPYRIGHT AND LICENSE
 310     Copyright (C) 2001-2005 Michael Legart <michael@legart.dk>
 311
 312     Templates designed by Thomas Kjaer <tk@lnx.dk>
 313
 314     Apache::Gallery is free software and is released under the Artistic
 315     License. See http://www.perl.com/language/misc/Artistic.html for
 316     details.
 317
 318     The video icons are from the GNOME project. http://www.gnome.org/
 319
 320 THANKS
 321     Thanks to Thomas Kjaer for templates and design of
 322     http://apachegallery.dk Thanks to Thomas Eibner and other for patches.
 323     (See the Changes file)
 324
 325 SEE ALSO
 326     perl, mod_perl, Image::Imlib2, CGI::FastTemplate, Image::Info, and
 327     Image::Size.
 328