1=head1 NAME 2 3imageindex - a digital photo gallery tool 4 5=head1 SYNOPSIS 6 7Imageindex is a digital picture gallery program. It provides automatic 8generation of thumbnails and other size views of the images and video files, 9and W3C compliant HTML to allow viewing of the thumbnails and images or videos. 10It also creates montages of all images in a given directory to be used in 11directory entries within the HTML. 12 13=head1 DESCRIPTION 14 15Imageindex has evolved from a simple thumbnail-generation program into a 16full-blown gallery application. With it you can create static thumbnails and 17"medium" views (good for dial-up web viewers) along with static HTML which 18presents the images in chronological order (based upon the date in the Exif 19header or date stamp of the file itself). Support has now been added for 20animated GIFs and video files (we support whatever file formats your 21installation of mplayer supports). 22 23Imageindex creates static rather than dynamic content for many reasons. First 24and foremost it is much easier to archive pictures onto CD-ROMs on a periodic 25basis when the content is just "there" rather than "trapped" in a database of 26some sort. You create your own "database" with your own directories and let 27imageindex handle the presentation of the images to the world. Imageindex will 28use "montages" (or thumbnails of all your thumbnails crammed together) of 29subdirectories if they occur alongside images (see the the sample pages on the 30imageindex website - http://www.edwinh.org/imageindex/sample.html). 31 32There are four basic "views" that imageindex creates (enabled by default). The 33"index" view shows thumbnails of all images in a directory in a basic table 34format (defaults to 3 columns). Within each cell of the table basic information 35such as the date/time of the picture are given as well as any comment (or 36caption) present in the image. Links to the various sizes of image and other 37views for the image are also presented by default. 38 39The second view presented is the "slide show" view. In this view the "medium" 40sized image is presented along with information such as date/time, any caption 41embedded in the image, etc. Currently for video files, the 'medium' slides only 42point to the actual video file processed. Future versions will allow for direct 43playback inside the browser (much like YouTube). There are "previous" and 44"next" links on each page which let the viewer quickly cycle through each 45"medium" image without having to constantly invoke the browser's "back" button. 46 47Captions for video files can be created by creating a file with the same 48basename as the original video file but having ".txt" as the extension. The 49contents of this file will be used just like captions embedded in formats like 50JPG when processing the resultant HTML. 51 52In conjunction with the "slide show" view there is a "frame view". When enabled 53a link to the frame view appears at the top of the index view's page. When the 54frame view is visited, the browser's pane splits into two portions. On the left 55all the thumbnails are lined up close together. On the right hand portion the 56same "slide show" pages are loaded. As the user clicks on a thumbnail on the 57left, it's "slide" view (including the "medium" image) is displayed in the 58right had side of the frame. This creates a very convenient mechanism for 59browsing through many images. 60 61Finally a "details" view exists. This details view is much like the index view 62as the thumbnails (reduced in size further) are presented in a table format, 63but much more information is presented in each cell. This is very useful for 64images that come from digital cameras where Exif headers have filled with lots 65of neat information. 66 67The HTML output of imageindex can be customized by creating a 68".imageindexrc" in your $HOME directory and placing certain variables (see 69VARIABLES section) in that file and editing to your taste. One of the variables 70controls the output of a cascading style sheet which ultimately directs your 71browser how to render the HTML. All color, font, indenting, etc. changes you 72wish to make can be done in this style sheet variable. 73 74=head1 VARIABLES 75 76When you create your ".imageindexrc" file in your $HOME directory, you can put 77any or all of the following variables in there and tweak as needed. This is 78Perl code itself and is subsequently "included" into imageindex as it runs. 79 80You B<must> end the file by putting a "1;" at the end of it. It's a Perl thing! 81 82The values you see in these examples are the program defaults. If you like the 83default value of a particular variable you don't need to include it in your 84".imageindexrc" file. 85 86Name of the directory that holds thumbnail images 87 88 $thumbnail_dir = 'thumbnail'; 89 90Size of the thumbnail images in the "x" direction (pixels). Note that 91imageindex preserves the aspect ratio of an image when it is reduced from its 92original size to form a thumbnail image. So, if the "x" dimension is smaller 93than the "y" dimension, a thumbnail might have an "x" size smaller than 94$default_thumbnail_x. 95 96 $default_thumbnail_x = 200; 97 98Size of the thumbnail images in the "y" direction (pixels). Again, note that 99imageindex preserves the aspect ratio of an image when it is reduced from its 100original size to form a thumbnail image. So, if the "y" dimension is smaller 101than the "x" dimension, a thumbnail might have an "y" size smaller than 102$default_thumbnail_y. 103 104 $default_thumbnail_y = 200; 105 106If both dimensions of the original are within this much of the thumbnail 107dimensions we will skip the thumbnail and just use the original as the 108"thumbnail." 109 110 $thumbnail_threshold = 1.0; 111 112Size of the "medium" images in the "x" direction (pixels). Note that 113imageindex preserves the aspect ratio of an image when it is reduced from its 114original size to form a "medium" image. So, if the "x" dimension is smaller 115than the "y" dimension, a "medium" image might have an "x" size smaller than 116$med_x. 117 118 $med_x = 800; 119 120Size of the "medium" images in the "y" direction (pixels). Note that 121imageindex preserves the aspect ratio of an image when it is reduced from its 122original size to form a "medium" image. So, if the "y" dimension is smaller 123than the "x" dimension, a "medium" image might have an "y" size smaller than 124$med_y. 125 126 $med_y = 600; 127 128Name of the directory that holds "medium" images 129 130 $med_dir = 'medium'; 131 132If both dimensions of the original are within this much of the "medium" 133dimensions we will skip creating the medium-size format and just use the 134original. This saves needless creating a "medium" image if it's close in size 135to the original already. 136 137 $med_threshold = 1.6; 138 139Automatically recurse into subdirectories? Set to 1 to enable. 140 141 $do_recurse = 0; 142 143Generate "medium" images at all? Set to 1 to enable. 144 145 $do_medium = 1; 146 147Generate the "slide show" and frame view? Set to 1 to enable. 148 149 $do_slide = 1; 150 151Generate the "details" view? Set to 1 to enable. 152 153 $do_captions = 1; 154 155Use/display caption info stored in images? Set to 1 to enable. 156 157 $do_detail = 1; 158 159Process subdirectories as entries in the normal "index" and "details" views? 160Set to 1 to enable. If an entire directory hierarchy has been processed with 161$do_montage set to 1 (see below), the montage file for a given directory will 162be used as the "thumbnail" for a subdirectory. 163 164 $do_dirs = 1; 165 166Create a montage of all the images? When enabled all of the images that are 167processed are turned into an NxM montage of very small thumbnails in a tiled 168pattern. The resulting image is shrunk to the $default_thumbnail_x x 169$default_thumbnail_y dimensions and stored in the $thumbnail_dir directory. The 170size of the tiles grows as the number of images in a directory increase, but 171can be bounded by variables outlined below. Set to 1 to enable. 172 173 $do_montage = 1; 174 175Map ASCII "smiley" patterns embedded within an image's comment into real 176"emoticon" images? When enabled the ASCII smiley faces such as :) and :-), the 177winks ;) and ;-), and the frowns :( and :-( are mapped to small PNG images that 178display the emotion conveyed. Set to 1 to enable. 179 180 $do_emoticons = 1; 181 182Sort timestamps in reverse order. 183 184 $do_reverse = 1; 185 186Process video files. This relies on a fairly recent version of mplayer being 187installed on your system. We've tested with up to 0.99.8. The kind of video 188files that are supported are up to the codecs that are compiled and used with 189mplayer installation on your system. 190 191 $do_video_files = 1; 192 193Overlay a small icon into one of the corners of the thumbnail and medium views 194when processing the first frame of a video file. This gives a "visual cue" that 195the file being represented in your browser is a video file and not a still 196image. 197 198 $do_video_thumbnail_icons = 1; 199 200Use the following as a regular expression to identify video files by their 201extension. For certain technical reasons it was more feasible to rely upon this 202quick and effective method. If files from your camera (or whatever) end in a 203different extension, just put that extension here too. 204 205 $video_regexp = '(avi|mov|mpg|mpeg|mjpeg|m1v|m2v|wmv|fli|nuv|vob|ogm|vcd|svcd|mp4|qt)'; 206 207If you enable the "visual cue" icons for video files mentioned above, the 208following variable determines which corner it is placed. Acceptable values are: 209SouthWest, NorthWest, NorthEast, SouthEast (case sensitive!). 210 211 $video_icon_gravity = 'SouthWest'; 212 213If you enable the "visual cue" icons for video files mentioned above, there are 214two to pick from (currently). Set to 1 (default) for a yellow dot with a 'play' 215arrow. Set to 2 for a purplish icon of a video camera. More of these will be 216created in further releases. 217 218 $video_icon = 1; 219 220The following three variables control what hyperlinks in the HTML output 221"point" to. They can be set to the following: 222 223 index : points to the name reference for an image in the index view 224 fullsize : points to the actual image itself 225 medium : points to the "medium" version of an image 226 thumbnail : points to the thumbnail version of an image 227 slide : points to the "slide show" HTML page written for an image 228 details : points to the name reference for an image in the details 229 view 230 231The folling variable controls what the hyperlink for the thumbnail image in the 232index view points to: 233 234 $index_linkto = 'slide'; 235 236The folling variable controls what the hyperlink for the thumbnail image in the 237details view points to: 238 239 $details_linkto = 'index'; 240 241The folling variable controls what the hyperlink for the "medium" image in the 242slide view points to: 243 244 $slide_linkto = 'fullsize'; 245 246Default number of columns to use in the index and detail views 247 248 $default_columns = 3; 249 250Set the orientation of slide frame - 'horizontal' or 'vertical'. When 'vertical' 251the browser pane will split vertically with all the thumbnails towards the 252left. When 'horizontal' the browser pane splits horizontally with the 253thumbnails arranged in the upper portion 254 255 $frame_orient = 'vertical'; 256 257The following two variables can be set to any of the following three values: 258 259 top : put the item in question at the top of the page when rendered 260 bottom : put the item in question at the bottom of the page when 261 rendered 262 none : omit the item from the HTML output 263 264Controls if an image caption (or comment) embedded in the image will be 265retrieved and written into the HTML output. By default it is written above the 266"medium" image presented in the "slide" view. 267 268 $slide_caption = 'top'; 269 270Controls if the date/time of an image is written into the HTML output. By 271default it is written below the "medium" image presented in the "slide" view. 272 273 $slide_date = 'bottom'; 274 275In the "detail" view, the thumbnail images are shrunk to a size smaller than 276the normal thumbnails (to conserve valueable space). This sets the number of 277times they are shrunk. By default it is shrunk by a factor of 2. 278 279 $detailshrink = 2; 280 281The thumbnail and "medium" images are written out as JPEG files (even if the 282original images were not JPEG's). The following two variables control the 283"quality" for generated images. The value can range from 0 to 100 where 100 284means "don't lose any quality in favor of file size." 285 286Adjust the quality of the thumbnails being written out 287 288 $thumb_quality = 50; 289 290Adjust the quality of the "medium" images written out 291 292 $med_quality = 80; 293 294Adjust the minimum number of tiles that will be found in a montage image. If 295the number of images in a directory is lower than this value, images will 296either be repeated or blanks will be inserted (see $montage_fill). 297 298 $montage_min = 4; 299 300Adjust the maximum number of tiles that will be found in a montage. If the 301number of images in a directory is higher than this number, the montage will be 302made by "evenly picking" $montage_max images in the directory and only using 303those. 304 305 $montage_max = 36; 306 307Adjust the space between montage images (pixels). 308 309 $montage_whitespace = 2; 310 311When there is not a "even" number of images in a directory and a complete NxM 312tile montage cannot be formed, images can be used again or empty space can be 313used. Set to 'repeat' to re-use images and 'blank' to use empty space. 314 315 $montage_fill = 'blank'; 316 317The following variable controls all aspects of how the HTML output is rendered 318in standards compliant browsers. The contents of this variable will be written 319out into a cascading style sheet and the properties found within it will govern 320how the HTML is rendered. All color, font, size, alignment, etc. property 321changes can take place. This might require some knowledge of cascading style 322sheets. A good primer can be found here: 323 324 http://www.w3schools.com/css/css_reference.asp 325 326 $stylesheet = ' 327 body { color: black; background: white; } 328 329 /* Fonts in the title */ 330 h1.title { font-family: "Comic Sans MS",Helvetica,sans-serif; 331 font-size: 200%; font-weight: bold; text-align: center; } 332 h2.daterange { font-family: Arial,Helvetica,sans-serif; 333 font-size: 125%; text-align: center; } 334 h3 { font-family: Arial,Helvetica,sans-serif; font-size: 90%; 335 text-align: center; } 336 337 /* Photo captions & Directory titles */ 338 div.caption { font-family: Arial,Helvetica,sans-serif; 339 font-size: 100%; font-weight: bold; margin: 1em; } 340 341 /* Overall fonts on the index and details page */ 342 div.index { font-family: Arial,Helvetica,sans-serif; 343 font-size: 80%; } 344 div.detail { font-family: Arial,Helvetica,sans-serif; 345 font-size: 80%; } 346 div.credits { font-family: Arial,Helvetica,sans-serif; 347 font-size: 80%; text-align: right; margin: 10px } 348 349 /* Table attributes */ 350 table.index { background: #ffffff; border: none; 351 border-spacing: 8px; } 352 td.index { border: none; padding: 3px } 353 table.frame { background: #ffffff; border: none } 354 td.frame { border: none; padding: 0px } 355 356 /* Image attributes */ 357 img.index { border: none; } 358 img.slide { border: none; } 359 img.frame { border: none; } 360 361 /* Link attributes */ 362 a:link { color: blue; } 363 a:visited { color: green; } 364 a:hover { color: red; } 365 a:active { color: red; } 366 367 '; 368 369 370Adjust what is presented in "empty" table cells when there are not an "even" 371number of images in a directory. 372 373 $emptycell = "<I>empty</I>"; 374 375Control the text of a hyperlink to a parent directory. If you do not desire 376that this link be present in the index and "details" views "undef" the variable 377(undef $updirtext;) 378 379 $updirtext = "up one directory"; 380 381Control the text of a hyperlink to the frame view. If you do not desire 382that this link be present in the index and "details" views "undef" the variable 383(undef $framelinktext;) 384 385 $framelinktext = "slideshow view (frames)"; 386 387Control the text of a hyperlink to the detail view. If you do not desire 388that this link be present in the index view "undef" the variable 389(undef $detaillinktext;) 390 391 $detaillinktext = "details index"; 392 393Control the text of a hyperlink to the index view. If you do not desire 394that this link be present in the detail view "undef" the variable 395(undef $indexlinktext;) 396 397 $indexlinktext = "main index"; 398 399Control the default TITLE string written out in the HTML for a given 400directory. This is most usually given on a per-directory basis via the command 401line and "remembered" within META data inside the index HTML file itself. 402 403 $default_titletext = "Image directory"; 404 405The following five variables control the TITLE attribute on anchor constructs 406in the index and frame views. When TITLE attributes are given they are usually 407rendered as "tooltip" bubbles that show text when a cursor hovers and stops 408over the active link. We use them here to give a visual cue about the image. 409These variables work much like printf(1) strings. The values that can be 410interpolated for a given image are: 411 412 %f => replaced with the filename of the image 413 %d => replaced with the date/time of the image (or mtime of the file) 414 %s => replaced with the size of the file (in Kb) 415 %r => replaced with the resolution (XxY) of the original image 416 %c => replaced with the image's caption (if stored with one) 417 %% => replaced with a literal '%' character 418 419The following codes are interpolated when directories are processed and a 420montage of that directory is used as the thumbnail of the subdirectory. 421 422 %n => replaced with number of images in a directory 423 %b => replaced with the "begin" date from a directory of images 424 %e => replaced with the "end" date from a directory of images 425 %t => replaced with the "title" from a directory of images 426 427Other characters (including spaces) are literal. "undef" these in your 428".imageindexrc" file if you don't want the TITLE attributes to be written into 429the HTML. The "date/time" related constructs are interpolated using the 430date/time format variables defined below. 431 432Control the TITLE attributes for hyperlinks to thumbnail images within the 433frame view. The default is "<filename> - <date>" for an image 434 435 $framethumbtitle = "%f - %d"; 436 437Control the TITLE attributes for hyperlinks to thumbnail images within the 438index view. The default is "<filename> (<size>)" for an image 439 440 $indexthumbtitle = "%f (%s)"; 441 442Control the TITLE attributes for hyperlinks to thumbnail images within the 443slide view. The default is "<filename> (<size>)" for an image 444 445 $slidethumbtitle = "%f (%s)"; 446 447Control the TITLE attributes for hyperlinks to thumbnail images within the 448detail view. The default is caption (or comment) of an image if one was 449embedded within it. 450 451 $detailthumbtitle = "%c"; 452 453Control the TITLE attributes for hyperlinks to montage images within the 454index view when a subdirectory is being presented. The default is to show how 455many images the subdirectory had and the date range that is spanned. 456 457 $montagetitle = "%n images %b through %e"; 458 459The following eight variables control how dates and times are formatted when 460written into the HTML. Again we're using printf(1)-like variables where codes 461are interpolated according to a user's taste. 462 463The definitions of the escape sequences come from the POSIX strftime(3) 464definitions. NOT ALL of strftime(3) are supported for obvious reasons. 465 466 %S is replaced by the second as a decimal number (00-60). 467 %M is replaced by the minute as a decimal number (00-59). 468 %I is replaced by the hour (12-hour clock) as a decimal number (01-12). 469 %H is replaced by the hour (24-hour clock) as a decimal number (00-23). 470 %p is replaced by national representation of either "ante meridiem" or 471 "post meridiem" as appropriate (currently only U.S. "am" or "pm") 472 %R is equivalent to "%H:%M" (in *timeformat variables only). 473 %r is equivalent to "%I:%M:%S %p" (in *timeformat variables only). 474 475 %Y is replaced by the year with century as a decimal number. 476 %y is replaced by the year without century as a decimal number (00-99). 477 %m is replaced by the month as a decimal number (01-12). 478 %d is replaced by the day of the month as a decimal number (01-31). 479 %F is equivalent to "%Y-%m-%d" (in *dateformat variables only). 480 %D is equivalent to "%m/%d/%y" (in *dateformat variables only). 481 %% is replaced by a literal "%". 482 483Control the way the date is formed in the frame view 484 485 $framedateformat = "%m/%d/%Y"; 486 487Control the way the time is formed in the frame view 488 489 $frametimeformat = "%r"; 490 491Control the way the date is formed in the index view 492 493 $indexdateformat = "%m/%d/%Y"; 494 495Control the way the time is formed in the index view 496 497 $indextimeformat = "%r"; 498 499Control the way the date is formed in the slide view 500 501 $slidedateformat = "%m/%d/%Y"; 502 503Control the way the time is formed in the slide view 504 505 $slidetimeformat = "%r"; 506 507Control the way the date is formed in the detail view 508 509 $detaildateformat = "%m/%d/%Y"; 510 511Control the way the date is formed in the detail view 512 513 $detailtimeformat = "%I:%M %p"; 514 515Control what the index view's HTML filename will be 516 517 $indexfile = 'index.html'; 518 519Control what the detail view's HTML filename will be 520 521 $detailfile = 'details.html'; 522 523Control what the frame view's HTML filename will be 524 525 $framefile = 'frame.html'; 526 527Control what the slide view's HTML filename will be 528 529 $slidefile = 'slides.html'; 530 531Control the name of the directory where all the "slide view" HTML files will be 532deposited (one per image) 533 534 $slide_dir = 'slides'; 535 536Control the name of the cascading style sheet written out in each directory 537 538 $stylefile = 'style.css'; 539 540Control the name of the montage image if enabled 541 542 $montagefile = 'montage.jpg'; 543 544Control the prefix of the emoticon PNG image filenames 545 546 $emoticonprefix = 'ii_'; 547 548=head1 EXAMPLES 549 550As an example, suppose you just want to change some date/time format strings. A 551complete ".imageindexrc" file in this case would be: 552 553 $framedateformat = "%F"; 554 $frametimeformat = "%R"; 555 556 $indexdateformat = "%F"; 557 $indextimeformat = "%R"; 558 559 $slidedateformat = "%F"; 560 $slidetimeformat = "%R"; 561 562 $detaildateformat = "%m/%y"; 563 564 1; # don't for get this as the last line in the file! 565 566=head1 ACKNOWLEDGMENTS 567 568We would like to thank Larry Wall, creator of Perl for his "swiss army 569chainsaw" of a scripting language (as well as all those who have hacked on Perl 570throughout the years). We would also like to thank all who have contributed to 571ImageMagick and its companion module PerlMagick. Without PerlMagick this 572software would be exceedingly less robust. Additionally we would like to thank 573the creators of mplayer (and all contributors). Without mplayer the support 574introduced for video files would never have come about. 575 576=head1 AUTHORS 577 578 Edwin Huffstutler <edwinh at edwinh dot org> 579 John Reynolds <johnjen at reynoldsnet dot org> 580 581 582 583