Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IMAGEINDEX(1)	      User Contributed Perl Documentation	 IMAGEINDEX(1)

NAME
       imageindex - a digital photo gallery tool

SYNOPSIS
       Imageindex is a digital picture gallery program.	It provides automatic
       generation of thumbnails	and other size views of	the images and video
       files, and W3C compliant	HTML to	allow viewing of the thumbnails	and
       images or videos.  It also creates montages of all images in a given
       directory to be used in directory entries within	the HTML.

DESCRIPTION
       Imageindex has evolved from a simple thumbnail-generation program into
       a full-blown gallery application. With it you can create	static
       thumbnails and "medium" views (good for dial-up web viewers) along with
       static HTML which presents the images in	chronological order (based
       upon the	date in	the Exif header	or 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).

       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 the sample pages	on the imageindex
       website - http://www.edwinh.org/imageindex/sample.html).

       There are four basic "views" that imageindex creates (enabled by
       default). 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 are 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.

       The second view presented is 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.

       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.

       In conjunction with the "slide show" view there is a "frame 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, it's "slide"
       view (including the "medium" image) is displayed	in the right had side
       of the frame. This creates a very convenient mechanism for browsing
       through many images.

       Finally a "details" view	exists.	This details view is much like the
       index view as 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.

       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.

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.

       Name of the directory that holds	thumbnail images

	    $thumbnail_dir = 'thumbnail';

       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;

       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
       an "y" size smaller than	$default_thumbnail_y.

	    $default_thumbnail_y = 200;

       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;

       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;

       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 an "y" size	smaller	than $med_y.

	    $med_y = 600;

       Name of the directory that holds	"medium" images

	    $med_dir = 'medium';

       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	needless creating a "medium" image if it's
       close in	size to	the original already.

	    $med_threshold = 1.6;

       Automatically recurse into subdirectories? Set to 1 to enable.

	    $do_recurse	= 0;

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

	    $do_medium = 1;

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

	    $do_slide =	1;

       Generate	the "details" view? Set	to 1 to	enable.

	    $do_captions = 1;

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

	    $do_detail = 1;

       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;

       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;

       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;

       Sort timestamps in reverse order.

	    $do_reverse	= 1;

       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 mplayer installation on your system.

	    $do_video_files = 1;

       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;

       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)';

       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';

       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

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

	    $index_linkto = 'slide';

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

	    $details_linkto = 'index';

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

	    $slide_linkto = 'fullsize';

       Default number of columns to use	in the index and detail	views

	    $default_columns = 3;

       Set the orientation of slide frame - 'horizontal' or 'vertical'.	When
       'vertical' the browser pane will	split vertically with all the
       thumbnails towards the left. When 'horizontal' the browser pane splits
       horizontally with the thumbnails	arranged in the	upper portion

	    $frame_orient = 'vertical';

       The following two variables can be set to any of	the following three
       values:

	 top : put the item in question	at the top of the page when rendered
	 bottom	: put the item in question at the bottom of the	page when
		  rendered
	 none :	omit the item from the HTML output

       Controls	if an image caption (or	comment) embedded in the image will be
       retrieved and written into the HTML output. By default it is written
       above the "medium" image	presented in the "slide" view.

	    $slide_caption = 'top';

       Controls	if the date/time of an image is	written	into the HTML output.
       By default it is	written	below the "medium" image presented in the
       "slide" view.

	    $slide_date	= 'bottom';

       In the "detail" view, the thumbnail images are shrunk to	a size smaller
       than the	normal thumbnails (to conserve valueable space). This sets the
       number of times they are	shrunk.	By default it is shrunk	by a factor of
       2.

	    $detailshrink = 2;

       The thumbnail and "medium" images are written out as JPEG files (even
       if the original images were not JPEG's).	The following 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."

       Adjust the quality of the thumbnails being written out

	    $thumb_quality = 50;

       Adjust the quality of the "medium" images written out

	    $med_quality = 80;

       Adjust 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 (see
       $montage_fill).

	    $montage_min = 4;

       Adjust 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 will be made by "evenly picking"	$montage_max images in the
       directory and only using	those.

	    $montage_max = 36;

       Adjust the space	between	montage	images (pixels).

	    $montage_whitespace	= 2;

       When there is not a "even" number of images in a	directory and a
       complete	NxM tile montage cannot	be formed, images can be used again or
       empty space can be used.	Set to 'repeat'	to re-use images and 'blank'
       to use empty space.

	    $montage_fill = 'blank';

       The following variable controls all aspects of how the HTML output is
       rendered	in standards compliant browsers. The contents of this variable
       will be written out into	a cascading style sheet	and the	properties
       found within it will 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 here:

		   http://www.w3schools.com/css/css_reference.asp

	    $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; }

	    ';

       Adjust what is presented	in "empty" table cells when there are not an
       "even" number of	images in a directory.

	    $emptycell = "<I>empty</I>";

       Control the text	of a hyperlink to a parent directory. If you do	not
       desire that this	link be	present	in the index and "details" views
       "undef" the variable (undef $updirtext;)

	    $updirtext = "up one directory";

       Control the text	of a hyperlink to the frame view. If you do not	desire
       that this link be present in the	index and "details" views "undef" the
       variable	(undef $framelinktext;)

	    $framelinktext = "slideshow	view (frames)";

       Control the text	of a hyperlink to the detail view. If you do not
       desire that this	link be	present	in the index view "undef" the variable
       (undef $detaillinktext;)

	    $detaillinktext = "details index";

       Control the text	of a hyperlink to the index view. If you do not	desire
       that this link be present in the	detail view "undef" the	variable
       (undef $indexlinktext;)

	    $indexlinktext = "main index";

       Control 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 are 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.

       Control the TITLE attributes for	hyperlinks to thumbnail	images within
       the frame view. The default is "<filename> - <date>" for	an image

	   $framethumbtitle  = "%f - %d";

       Control the TITLE attributes for	hyperlinks to thumbnail	images within
       the index view. The default is "<filename> (<size>)" for	an image

	   $indexthumbtitle  = "%f (%s)";

       Control the TITLE attributes for	hyperlinks to thumbnail	images within
       the slide view. The default is "<filename> (<size>)" for	an image

	   $slidethumbtitle  = "%f (%s)";

       Control the TITLE attributes for	hyperlinks to thumbnail	images within
       the detail view.	The default is caption (or comment) of an image	if one
       was embedded within it.

	   $detailthumbtitle = "%c";

       Control 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";

       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 "%".

       Control the way the date	is formed in the frame view

	   $framedateformat = "%m/%d/%Y";

       Control the way the time	is formed in the frame view

	   $frametimeformat = "%r";

       Control the way the date	is formed in the index view

	   $indexdateformat = "%m/%d/%Y";

       Control the way the time	is formed in the index view

	   $indextimeformat = "%r";

       Control the way the date	is formed in the slide view

	   $slidedateformat = "%m/%d/%Y";

       Control the way the time	is formed in the slide view

	   $slidetimeformat = "%r";

       Control the way the date	is formed in the detail	view

	   $detaildateformat = "%m/%d/%Y";

       Control the way the date	is formed in the detail	view

	   $detailtimeformat = "%I:%M %p";

       Control what the	index view's HTML filename will	be

	   $indexfile =	'index.html';

       Control what the	detail view's HTML filename will be

	   $detailfile = 'details.html';

       Control what the	frame view's HTML filename will	be

	   $framefile =	'frame.html';

       Control what the	slide view's HTML filename will	be

	   $slidefile =	 'slides.html';

       Control the name	of the directory where all the "slide view" HTML files
       will be deposited (one per image)

	   $slide_dir =	'slides';

       Control the name	of the cascading style sheet written out in each
       directory

	   $stylefile =	'style.css';

       Control the name	of the montage image if	enabled

	   $montagefile	= 'montage.jpg';

       Control the prefix of the emoticon PNG image filenames

	   $emoticonprefix = 'ii_';

EXAMPLES
       As an example, suppose you just want to change some date/time format
       strings.	A complete ".imageindexrc" file	in this	case would be:

	 $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!

ACKNOWLEDGMENTS
       We would	like to	thank Larry Wall, creator of Perl for his "swiss army
       chainsaw" of a scripting	language (as well as all those who have	hacked
       on Perl throughout the years). We would also like to thank all who have
       contributed to ImageMagick and its companion module PerlMagick. Without
       PerlMagick this software	would be exceedingly less robust. Additionally
       we would	like to	thank the creators of mplayer (and all contributors).
       Without mplayer the support introduced for video	files would never have
       come about.

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

perl v5.14.4			  2007-03-30			 IMAGEINDEX(1)

NAME | SYNOPSIS | DESCRIPTION | VARIABLES | EXAMPLES | ACKNOWLEDGMENTS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=imageindex&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help