IMAGEINDEX(1)

📦
version 1.1 · 3 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

✨ NAME ✨

imageindex — a digital photo gallery tool 🖼️💖

(and yes bestie, this is section 1 of the manual, filed under User Contributed Perl Documentation, because that's the ✨iconic✨ energy we're serving today)

🌸 SYNOPSIS 🌸

okay so Imageindex is a digital picture gallery program. It provides automatic generation of thumbnails and other size views of the images and video files, plus W3C compliant HTML so you can actually look at all those thumbnails and images/videos. It also creates montages of all images in a given directory, which then get used in directory entries inside the HTML. 🎀

🦋 DESCRIPTION 🦋

Imageindex has evolved from a simple thumbnail-generation program into a full-blown gallery application. Not me saying glow-up 💅. With it you can create static thumbnails and "medium" views (those are the ones that are good for dial-up web viewers, iykyk) along with static HTML which presents the images in chronological order — based upon the date in the Exif header or the date stamp of the file itself. Support has now been added for animated GIFs and video files (we support whatever file formats your installation of mplayer supports, no cap).

Why static and not dynamic, you ask? Imageindex creates static rather than dynamic content for many reasons. First and foremost it is much easier to archive pictures onto CD-ROMs on a periodic basis when the content is just "there" rather than "trapped" in a database of some sort. You create your own "database" with your own directories and let imageindex handle the presentation of the images to the world. Imageindex will use "montages" (or thumbnails of all your thumbnails crammed together) of subdirectories if they occur alongside images (see the sample pages on the imageindex website — http://www.edwinh.org/imageindex/sample.html). 🫶

There are four basic "views" that imageindex creates (all enabled by default):

  1. The "index" view shows thumbnails of all images in a directory in a basic table format (defaults to 3 columns). Within each cell of the table, basic information such as the date/time of the picture is given, as well as any comment (or caption) present in the image. Links to the various sizes of image and other views for the image are also presented by default.
  2. The "slide show" view. In this view the "medium" sized image is presented along with information such as date/time, any caption embedded in the image, etc. Currently for video files, the 'medium' slides only point to the actual video file processed. Future versions will allow for direct playback inside the browser (much like YouTube). There are "previous" and "next" links on each page which let the viewer quickly cycle through each "medium" image without having to constantly invoke the browser's "back" button. 🔥
  3. The "frame view", which lives in conjunction with the "slide show" view. When enabled, a link to the frame view appears at the top of the index view's page. When the frame view is visited, the browser's pane splits into two portions. On the left, all the thumbnails are lined up close together. On the right hand portion, the same "slide show" pages are loaded. As the user clicks on a thumbnail on the left, its "slide" view (including the "medium" image) is displayed in the right hand side of the frame. This creates a very convenient mechanism for browsing through many images. ✨
  4. The "details" view. This one is much like the index view, since the thumbnails (reduced in size further) are presented in a table format, but much more information is presented in each cell. This is very useful for images that come from digital cameras where Exif headers have filled with lots of neat information. 📸

💜 Captions for video files

Captions for video files can be created by creating a file with the same basename as the original video file but having .txt as the extension. The contents of this file will be used just like captions embedded in formats like JPG when processing the resultant HTML. 🍓

💅 Making it yours

The HTML output of imageindex can be customized by creating a .imageindexrc in your $HOME directory and placing certain variables (see VARIABLES section) in that file and editing to your taste. One of the variables controls the output of a cascading style sheet which ultimately directs your browser how to render the HTML. All color, font, indenting, etc. changes you wish to make can be done in this style sheet variable. Obsessed, honestly. 💖

🌈 VARIABLES 🌈

When you create your .imageindexrc file in your $HOME directory, you can put any or all of the following variables in there and tweak as needed. This is Perl code itself and is subsequently "included" into imageindex as it runs. 🧚

⚠️ You must end the file by putting a 1; at the end of it. It's a Perl thing!

The values you see in these examples are the program defaults. If you like the default value of a particular variable you don't need to include it in your .imageindexrc file. Easy.

$thumbnail_dir — Name of the directory that holds thumbnail images.

$thumbnail_dir = 'thumbnail';

$default_thumbnail_x — Size of the thumbnail images in the "x" direction (pixels). Note that imageindex preserves the aspect ratio of an image when it is reduced from its original size to form a thumbnail image. So, if the "x" dimension is smaller than the "y" dimension, a thumbnail might have an "x" size smaller than $default_thumbnail_x.

$default_thumbnail_x = 200;

$default_thumbnail_y — Size of the thumbnail images in the "y" direction (pixels). Again, note that imageindex preserves the aspect ratio of an image when it is reduced from its original size to form a thumbnail image. So, if the "y" dimension is smaller than the "x" dimension, a thumbnail might have a "y" size smaller than $default_thumbnail_y.

$default_thumbnail_y = 200;

$thumbnail_threshold — If both dimensions of the original are within this much of the thumbnail dimensions we will skip the thumbnail and just use the original as the "thumbnail."

$thumbnail_threshold = 1.0;

$med_x — Size of the "medium" images in the "x" direction (pixels). Note that imageindex preserves the aspect ratio of an image when it is reduced from its original size to form a "medium" image. So, if the "x" dimension is smaller than the "y" dimension, a "medium" image might have an "x" size smaller than $med_x.

$med_x = 800;

$med_y — Size of the "medium" images in the "y" direction (pixels). Note that imageindex preserves the aspect ratio of an image when it is reduced from its original size to form a "medium" image. So, if the "y" dimension is smaller than the "x" dimension, a "medium" image might have a "y" size smaller than $med_y.

$med_y = 600;

$med_dir — Name of the directory that holds "medium" images.

$med_dir = 'medium';

$med_threshold — If both dimensions of the original are within this much of the "medium" dimensions we will skip creating the medium-size format and just use the original. This saves needlessly creating a "medium" image if it's close in size to the original already.

$med_threshold = 1.6;

$do_recurse — Automatically recurse into subdirectories? Set to 1 to enable.

$do_recurse = 0;

$do_medium — Generate "medium" images at all? Set to 1 to enable.

$do_medium = 1;

$do_slide — Generate the "slide show" and frame view? Set to 1 to enable.

$do_slide = 1;

$do_captions — Generate the "details" view? Set to 1 to enable.

$do_captions = 1;

$do_detail — Use/display caption info stored in images? Set to 1 to enable.

$do_detail = 1;

$do_dirs — Process subdirectories as entries in the normal "index" and "details" views? Set to 1 to enable. If an entire directory hierarchy has been processed with $do_montage set to 1 (see below), the montage file for a given directory will be used as the "thumbnail" for a subdirectory.

$do_dirs = 1;

$do_montage — Create a montage of all the images? When enabled, all of the images that are processed are turned into an NxM montage of very small thumbnails in a tiled pattern. The resulting image is shrunk to the $default_thumbnail_x x $default_thumbnail_y dimensions and stored in the $thumbnail_dir directory. The size of the tiles grows as the number of images in a directory increase, but can be bounded by variables outlined below. Set to 1 to enable.

$do_montage = 1;

$do_emoticons — Map ASCII "smiley" patterns embedded within an image's comment into real "emoticon" images? When enabled, the ASCII smiley faces such as :) and :-), the winks ;) and ;-), and the frowns :( and :-( are mapped to small PNG images that display the emotion conveyed. Set to 1 to enable. 😭

$do_emoticons = 1;

$do_reverse — Sort timestamps in reverse order.

$do_reverse = 1;

$do_video_files — Process video files. This relies on a fairly recent version of mplayer being installed on your system. We've tested with up to 0.99.8. The kind of video files that are supported are up to the codecs that are compiled and used with the mplayer installation on your system.

$do_video_files = 1;

$do_video_thumbnail_icons — Overlay a small icon into one of the corners of the thumbnail and medium views when processing the first frame of a video file. This gives a "visual cue" that the file being represented in your browser is a video file and not a still image. 🎬

$do_video_thumbnail_icons = 1;

$video_regexp — Use the following as a regular expression to identify video files by their extension. For certain technical reasons it was more feasible to rely upon this quick and effective method. If files from your camera (or whatever) end in a different extension, just put that extension here too.

$video_regexp = '(avi|mov|mpg|mpeg|mjpeg|m1v|m2v|wmv|fli|nuv|vob|ogm|vcd|svcd|mp4|qt)';

$video_icon_gravity — If you enable the "visual cue" icons for video files mentioned above, the following variable determines which corner it is placed. Acceptable values are: SouthWest, NorthWest, NorthEast, SouthEast (case sensitive!).

$video_icon_gravity = 'SouthWest';

$video_icon — If you enable the "visual cue" icons for video files mentioned above, there are two to pick from (currently). Set to 1 (default) for a yellow dot with a 'play' arrow. Set to 2 for a purplish icon of a video camera. More of these will be created in further releases.

$video_icon = 1;

The following three variables control what hyperlinks in the HTML output "point" to. They can be set to the following:

  • index — points to the name reference for an image in the index view
  • fullsize — points to the actual image itself
  • medium — points to the "medium" version of an image
  • thumbnail — points to the thumbnail version of an image
  • slide — points to the "slide show" HTML page written for an image
  • details — points to the name reference for an image in the details view

$index_linkto — The folling variable controls what the hyperlink for the thumbnail image in the index view points to:

$index_linkto = 'slide';

$details_linkto — The folling variable controls what the hyperlink for the thumbnail image in the details view points to:

$details_linkto = 'index';

$slide_linkto — The folling variable controls what the hyperlink for the "medium" image in the slide view points to:

$slide_linkto = 'fullsize';

$default_columns — Default number of columns to use in the index and detail views.

$default_columns = 3;
  • $frame_orient — sets which way the slide frame is oriented, bestie. Your options are literally just 'horizontal' or 'vertical'. When it's 'vertical', the browser pane splits vertically and all the thumbnails go down the left side. When it's 'horizontal', the browser pane splits horizontally and the thumbnails hang out in the upper portion. Pick your vibe:
$frame_orient = 'vertical';

The next two variables can be set to any of these three values, no cap:

  • top — puts the item in question at the top of the page when rendered
  • bottom — puts the item in question at the bottom of the page when rendered
  • none — omits the item from the HTML output entirely
  • $slide_caption — controls whether an image caption (or comment) embedded in the image gets retrieved and written into the HTML output. By default it's written above the "medium" image presented in the "slide" view. 💖
$slide_caption = 'top';
  • $slide_date — controls whether the date/time of an image gets written into the HTML output. By default it's written below the "medium" image presented in the "slide" view.
$slide_date = 'bottom';
  • $detailshrink — okay so in the "detail" view, the thumbnail images get shrunk down smaller than the normal thumbnails (to conserve valuable space, periodt). This sets how many times they get shrunk. By default it's shrunk by a factor of 2.
$detailshrink = 2;

The thumbnail and "medium" images get written out as JPEG files (yes, even if the originals were not JPEGs, wild right?). The next two variables control the "quality" for generated images. The value can range from 0 to 100, where 100 means "don't lose any quality in favor of file size."

  • $thumb_quality — adjusts the quality of the thumbnails being written out.
$thumb_quality = 50;
  • $med_quality — adjusts the quality of the "medium" images written out.
$med_quality = 80;
  • $montage_min — adjusts the minimum number of tiles that will be found in a montage image. If the number of images in a directory is lower than this value, images will either be repeated or blanks will be inserted (peep $montage_fill for that one).
$montage_min = 4;
  • $montage_max — adjusts the maximum number of tiles that will be found in a montage. If the number of images in a directory is higher than this number, the montage gets made by "evenly picking" $montage_max images in the directory and only using those. 💅
$montage_max = 36;
  • $montage_whitespace — adjusts the space between montage images (in pixels).
$montage_whitespace = 2;
  • $montage_fill — when there isn't an "even" number of images in a directory and a complete NxM tile montage can't be formed, images can be used again or empty space can be used. Set it to 'repeat' to re-use images, and 'blank' to use empty space.
$montage_fill = 'blank';
  • $stylesheet — this one variable controls all aspects of how the HTML output is rendered in standards compliant browsers, iykyk. Whatever's inside this variable gets written out into a cascading style sheet, and the properties found within it govern how the HTML is rendered. All color, font, size, alignment, etc. property changes can take place. This might require some knowledge of cascading style sheets. A good primer can be found right here:
http://www.w3schools.com/css/css_reference.asp

And here's the default, verbatim, don't touch my formatting:

$stylesheet = '
body { color: black; background: white; }

/* Fonts in the title */
h1.title { font-family: "Comic Sans MS",Helvetica,sans-serif;
           font-size: 200%; font-weight: bold; text-align: center; }
h2.daterange { font-family: Arial,Helvetica,sans-serif;
               font-size: 125%; text-align: center; }
h3 { font-family: Arial,Helvetica,sans-serif; font-size: 90%;
     text-align: center; }

/* Photo captions & Directory titles */
div.caption { font-family: Arial,Helvetica,sans-serif;
              font-size: 100%; font-weight: bold; margin: 1em; }

/* Overall fonts on the index and details page */
div.index { font-family: Arial,Helvetica,sans-serif;
            font-size: 80%; }
div.detail { font-family: Arial,Helvetica,sans-serif;
             font-size: 80%; }
div.credits { font-family: Arial,Helvetica,sans-serif;
              font-size: 80%; text-align: right; margin: 10px }

/* Table attributes */
table.index { background: #ffffff; border: none;
              border-spacing: 8px; }
td.index { border: none; padding: 3px }
table.frame { background: #ffffff; border: none }
td.frame { border: none; padding: 0px }

/* Image attributes */
img.index { border: none; }
img.slide { border: none; }
img.frame { border: none; }

/* Link attributes */
a:link { color: blue; }
a:visited { color: green; }
a:hover { color: red; }
a:active { color: red; }

';
  • $emptycell — adjusts what gets presented in "empty" table cells when there isn't an "even" number of images in a directory.
$emptycell = "<I>empty</I>";
  • $updirtext — controls the text of a hyperlink to a parent directory. If you do not want this link present in the index and "details" views, "undef" the variable (undef $updirtext;).
$updirtext = "up one directory";
  • $framelinktext — controls the text of a hyperlink to the frame view. If you do not want this link present in the index and "details" views, "undef" the variable (undef $framelinktext;).
$framelinktext = "slideshow view (frames)";
  • $detaillinktext — controls the text of a hyperlink to the detail view. If you do not want this link present in the index view, "undef" the variable (undef $detaillinktext;).
$detaillinktext = "details index";
  • $indexlinktext — controls the text of a hyperlink to the index view. If you do not want this link present in the detail view, "undef" the variable (undef $indexlinktext;).
$indexlinktext = "main index";
  • $default_titletext — controls the default TITLE string written out in the HTML for a given directory. This is most usually given on a per-directory basis via the command line and "remembered" within META data inside the index HTML file itself.
$default_titletext  = "Image directory";

The following five variables control the TITLE attribute on anchor constructs in the index and frame views. When TITLE attributes are given they're usually rendered as "tooltip" bubbles that show text when a cursor hovers and stops over the active link. We use them here to give a visual cue about the image. These variables work much like printf(1) strings. The values that can be interpolated for a given image are:

  • %f => replaced with the filename of the image
  • %d => replaced with the date/time of the image (or mtime of the file)
  • %s => replaced with the size of the file (in Kb)
  • %r => replaced with the resolution (XxY) of the original image
  • %c => replaced with the image's caption (if stored with one)
  • %% => replaced with a literal '%' character

The following codes are interpolated when directories are processed and a montage of that directory is used as the thumbnail of the subdirectory. 🦋

  • %n => replaced with number of images in a directory
  • %b => replaced with the "begin" date from a directory of images
  • %e => replaced with the "end" date from a directory of images
  • %t => replaced with the "title" from a directory of images

Other characters (including spaces) are literal. "undef" these in your .imageindexrc file if you don't want the TITLE attributes to be written into the HTML. The "date/time" related constructs are interpolated using the date/time format variables defined below. 👑

  • $framethumbtitle — controls the TITLE attributes for hyperlinks to thumbnail images within the frame view. The default is "<filename> - <date>" for an image.
$framethumbtitle  = "%f - %d";
  • $indexthumbtitle — controls the TITLE attributes for hyperlinks to thumbnail images within the index view. The default is "<filename> (<size>)" for an image.
$indexthumbtitle  = "%f (%s)";
  • $slidethumbtitle — controls the TITLE attributes for hyperlinks to thumbnail images within the slide view. The default is "<filename> (<size>)" for an image.
$slidethumbtitle  = "%f (%s)";
  • $detailthumbtitle — controls the TITLE attributes for hyperlinks to thumbnail images within the detail view. The default is the caption (or comment) of an image if one was embedded within it.
$detailthumbtitle = "%c";
  • $montagetitle — controls the TITLE attributes for hyperlinks to montage images within the index view when a subdirectory is being presented. The default is to show how many images the subdirectory had and the date range that is spanned.
$montagetitle = "%n images %b through %e";
  • $file_charset — controls which charset the generated html pages should have. This defaults to UTF-8, but can either be ISO-8859-1 or any other encoding:
$file_charset = "ISO-8859-1";

The following eight variables control how dates and times are formatted when written into the HTML. Again we're using printf(1)-like variables where codes are interpolated according to a user's taste. 🌸

The definitions of the escape sequences come from the POSIX strftime(3) definitions. NOT ALL of strftime(3) are supported, for obvious reasons.

  • %S is replaced by the second as a decimal number (00-60).
  • %M is replaced by the minute as a decimal number (00-59).
  • %I is replaced by the hour (12-hour clock) as a decimal number (01-12).
  • %H is replaced by the hour (24-hour clock) as a decimal number (00-23).
  • %p is replaced by national representation of either "ante meridiem" or "post meridiem" as appropriate (currently only U.S. "am" or "pm").
  • %R is equivalent to "%H:%M" (in *timeformat variables only).
  • %r is equivalent to "%I:%M:%S %p" (in *timeformat variables only).
  • %Y is replaced by the year with century as a decimal number.
  • %y is replaced by the year without century as a decimal number (00-99).
  • %m is replaced by the month as a decimal number (01-12).
  • %d is replaced by the day of the month as a decimal number (01-31).
  • %F is equivalent to "%Y-%m-%d" (in *dateformat variables only).
  • %D is equivalent to "%m/%d/%y" (in *dateformat variables only).
  • %% is replaced by a literal "%".
  • $framedateformat — controls the way the date is formed in the frame view.
$framedateformat = "%m/%d/%Y";
  • $frametimeformat — controls the way the time is formed in the frame view.
$frametimeformat = "%r";
  • $indexdateformat — controls the way the date is formed in the index view.
$indexdateformat = "%m/%d/%Y";
  • $indextimeformat — controls the way the time is formed in the index view.
$indextimeformat = "%r";
  • $slidedateformat — controls the way the date is formed in the slide view.
$slidedateformat = "%m/%d/%Y";
  • $slidetimeformat — controls the way the time is formed in the slide view.
$slidetimeformat = "%r";
  • $detaildateformat — controls the way the date is formed in the detail view.
$detaildateformat = "%m/%d/%Y";
  • $detailtimeformat — controls the way the date is formed in the detail view.
$detailtimeformat = "%I:%M %p";
  • $indexfile — controls what the index view's HTML filename will be.
$indexfile = 'index.html';
  • $detailfile — controls what the detail view's HTML filename will be.
  • $detailfile = 'details.html'; — controls what the detail view's HTML file is gonna be called 💖
  • $framefile = 'frame.html'; — controls what the frame view's HTML filename is gonna be, bestie ✨
  • $slidefile = 'slides.html'; — controls what the slide view's HTML filename is gonna be 🎀
  • $slide_dir = 'slides'; — controls the name of the directory where ALL the "slide view" HTML files get dropped (and it's one per image, no cap) 🦋
  • $stylefile = 'style.css'; — controls the name of the cascading style sheet that gets written out in each directory 🌸
  • $montagefile = 'montage.jpg'; — controls the name of the montage image, but only if it's enabled 👑
  • $emoticonprefix = 'ii_'; — controls the prefix on the emoticon PNG image filenames 💅

🌈 EXAMPLES 🌈

Okay so picture this: you literally just wanna change some date/time format strings. Nothing wild. In that case a complete .imageindexrc file looks like this, and it's giving minimal queen energy:

$framedateformat = "%F";
$frametimeformat = "%R";

$indexdateformat = "%F";
$indextimeformat = "%R";

$slidedateformat = "%F";
$slidetimeformat = "%R";

$detaildateformat = "%m/%y";

1; # don't for get this as the last line in the file!
Not me pointing out that the comment says "don't for get this" — that's exactly how it's written in the original, typos and all, and I am NOT touching it. 🫶 Anyway bestie the important bit: that trailing 1; line is mandatory, it's the last line, do not forget it. 😭

💜 ACKNOWLEDGMENTS 💜

Big shoutout time, because we did not build this alone:

  • We wanna thank Larry Wall, creator of Perl, for his "swiss army chainsaw" of a scripting language — iconic, legendary, no notes 🔥 — plus literally everyone who's hacked on Perl over the years.
  • We also wanna thank all who have contributed to ImageMagick and its companion module PerlMagick. Fr fr, without PerlMagick this software would be exceedingly less robust. 💀
  • And additionally we wanna thank the creators of mplayer (and all its contributors). Without mplayer, the support that got introduced for video files would never have come about. Periodt. ✨

🎀 AUTHORS 🎀

  • Edwin Huffstutler <edwinh at edwinh dot org>
  • John Reynolds <johnjen at reynoldsnet dot org>

And that's the whole page, bestie! 🦋 This one came from perl v5.28.1, dated 2019-01-12, and it's the IMAGEINDEX(1) manual — you read the entire thing, which is honestly main character energy. Go forth and index some images, you absolute icon. 💖✨🌸

📦 where this page comes from