igal2.1

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH igal2 1 "June 2024" "Version 3.2" "Version 3.2"

.SH NAME
igal2 \- online Image GALlery generator
.SH SYNOPSIS
.B igal2
.I [-option1 -option2 ...]
.SH DESCRIPTION
.B igal2
is a quick and easy program for placing your images online with just
one command-line invocation.  It generates a pretty good-looking set of W3-compliant
static HTML slides even with its default settings.  To try it out just run 
.B igal2 
in a directory with
.IR jpg ", " gif " or " png
files and check the output in a web browser.  You can adjust the
appearance of the image gallery with the many options listed below or
(if you know a bit of HTML) by modifying the
.IR ".indextemplate.html" , " .slidetemplate.html " and " igal2.css"
files that 
.B igal2 
creates in your image directory.
.B igal2
also checks for the existence of a
.I "$HOME/.igal2"
directory where users can store their own templates, overriding
the site-wide 
.IR "/usr/local/share/igal2" .

.BR igal2 " needs " Perl
to run and it also relies on a few other programs that come standard
with most Linux distributions.  It relies on the
.B ImageMagick
package first if available, otherwise it falls back onto
.BR cjpeg "/" djpeg "/" pnmscale " for processing"
.IR jpg " files.  The command "
.BR convert " of the " ImageMagick " package is required to process"
.IR gif " and " png
files and the
.BR identify " command enables " igal2
to include IMG HEIGHT and WIDTH tags in the HTML it generates.
.BR If you would like to show the EXIF headers of the images 
(option -e) Image::ExifTools is needed

.SH OPTIONS
.TP
.B -a
Write image dimensions and sizes under each thumbnail on the index page.
This only works if the ImageMagick command
.BR identify " is present."
.TP
.B --ad
Like
.B -a
but write only the image dimensions.
.TP
.B --as
Like
.B -a
but write only the image sizes.
.TP
.BI --bigy " <n>"
Like
.B -y
but operates on the image slides, not the thumbnails.  Scales image
slides to some medium height (e.g.
.IR 400 "),"
adjusting their width accordingly.  Useful if your digital camera
spits out large images, like 1600x1200.  The originals aren't affected,
but scaled copies of your images are stored with the 
.I ".slide"
prefix and thumbnails link to these copies.  Clicking on the scaled
copies in the HTML slides lets users see the full unscaled images.
You must use
.B -f
between two consecutive runs when you've changed the value of
.BR "--bigy" .
.TP
.BI -c
First generate and then publish image slide captions. The first invocation of
.B igal2 -c
generates a
.I .captions
file that you may edit.  The format of this file is very simple.
You should only have to enter your captions after the
.I ----
separator.  You may rearrange the image order at this point and 
also leave out some pictures by simply placing a pound
.RI ( # )
sign at the beginning of their respective lines.  A second invocation of
.B igal2 -c
will read your
.I .captions
file, include your captions in the slides and rearrange them if necessary.
.TP
.BI -C
.RI Like " -c"
but preserve file names as captions when generating the
.I .captions
file (strips file name suffix).
.TP
.BI --con " options"
Command line options to pass on to
.BR convert " or " cjpeg
internally (see their man pages).  This affects all thumbnails
and, if
.BI --bigy
is given, the medium-size slides too.  You can set the
.I -quality
or go crazy with
.IR -negate ", " -noise ", etc."
(the last two only work with
.BR convert " if " ImageMagick " is installed."
.TP
.BI -d " <dir>"
Operate on image files in directory
.IR <dir> ,
which is also where the HTML and thumbnail files will be generated.
The default is the current directory.
.TP
.BI -e
Extract all EXIF tags from the images and display them on the image slides.
This option needs Image::ExifTool to be installed
.TP
.BI -f
Force thumbnail regeneration.  Also forces medium-slide regeneration if
.BI --bigy
is given.  Otherwise
.B igal2
will not regenerate these files if they already exist, and you may
end up with stale copies.  Definitely use
.BI -f
between two runs where you've changed the value of 
.BR --bigy " or " --con "."
.TP
.BI -h
Display brief help, same as
.BR "--help" .
.TP
.BI --help
Display brief help, same as
.BR "-h" .
.TP
.BI -i " <file>"
Name of the main thumbnail index file.  The default is
.IR index.html ,
as desirable for most web servers.
.TP
.BI -k
Use the image captions for the HTML slide titles.
The default behavior is to use the image names.
.TP
.BI -m " <watermarkfile>"
Add a watermark to each file. The parameter specified is another image file
which will be overlayed in the top left of the image with some transparency
applied. This option requires ImageMagick. The original images will be left
in place with a '.unmarked' extension. You may wish to delete those
afterwards. If this option is specified on two consecutive runs, igal2 will
detect the .unmarked versions and not run it through the watermarking
process again. Transparent GIF files work well for this option.
.TP
.BI -n
Use the image file names for the HTML slide files.  Otherwise
the default behavior is to simply name your slides
.IR 1.html ", " 2.html ", "
and so on.
.TP
.BI -o " <URL>"
Use this option if you are hosting the index files in a different location
(e.g. a different server) from the back end images/slides. This option adds
the specified prefix into the URLs of the slides. If you use this option,
remember that until you move the files into the resulting location, the
gallery won't work properly.
.TP
.BI -p " <n>"
The cellpadding value of the thumbnail index tables.
The default is 3.
.TP
.BI -r
Omit the film reel effect altogether.  For a simpler look you
can also set the thumbnail background to be the same as the main
index page background with the tile background-color option in the
.IR igal2.css " file."
.TP
.B -s
For the simplest setup, omit all HTML slides.  Clicking the thumbnails on 
the main page will just take users to the plain image files.
.TP
.BI -t " <n>"
Height (in pixels) of the tiled image used to simulate the top
and bottom "film reel" effect on the thumbnail index page.  This
is 21 for the default
.I .tile.png
image used, but you should set it otherwise if you replace that
file with your own design.
.TP
.BI -u
Write image captions under each thumbnail on the index page.
If you have a
.I .captions
file (see options -c or -C) then the captions are read from there,
else the file names are used (but the file extension is stripped).
.TP
.BI --pagination " <n>" 
Maximum number of images on one page.
If the given number of images is reached a new page 
is started. Pagination number n should be a multiple 
of parameter -w (default 5).
Default 0 - means no pagination at all.
.TP
.BI -w " <n>"
Set the thumbnail rows to be
.I <n>
images wide in the main index file.  Default is 5.
.TP
.BI -x
Omit the image count from the captions.
.TP
.BI -y " <n>"
Scale all thumbnails to the same height of 
.IR <n> " pixels."
The default is 75 pixels.
.TP
.BI --xy " <n>"
Scale thumbnails to
.I <n>
pixels along their longest dimension.  This value is passed to
.B pnmscale
and only works properly for
.I jpg
images.
.TP
.BI --www
Make all
.B igal2
files world-readable.
.TP
.BI --dest " <dir>"
Per default igal2 places all igal2 helper files (thumbnails, 
slidefiles, CSS, etc) in the directory where the image files reside.
With this option these files can be placed in a subdirectory of the
image directory.
.TP
.BI --AddSubdir
If igal2 finds subdirectories below your image directory it will add
links to this directories in the index.html file. This is useful if
you've a tree of image directories.

 Example:
 !
 + Vacation_Vienna (Image Directory)
   !
   + .igal2-stuff (igal2 helper files)
   + Videos
   + Documents_of_interest

 igal2 -d Vacation_Vienna --dest .igal2-stuff --AddSubdir

will put all helper files in .igal2-stuff, and generate links to the 
subdirectories "Videos" and "Documents_of_interest" in the
index.html file.

Note: igal2 will not work recursively, it just adds HREF links to the 
found directories.
.TP
.BI --igaldir
Use custom templates from this directory
.RI ( $HOME/.igal2 )

.SH FILES
.I /usr/local/share/igal2/indextemplate2.html
.RS
The default index template file.
.RE
.I /usr/local/share/igal2/slidetemplate2.html
.RS
The default file used to generate slides.
.RE
.I /usr/local/share/igal2/igal2/igal2.css
.RS
The default style sheet template.
.RE
.I /usr/local/share/igal2/igal2/tile.png
.RS
The tiled image used for the "film reel" effect.
.RE
.I /usr/local/share/igal2/directoryline2.html
.RS
The default file used to generate directory links in index.html. If 
this file is changed, the index.html has to be regenerated by running
igal2 again.
.RE
All five files are copied to your image directory as dotfiles the
first time you run
.BR igal2 .
Modify the local copies (but keep their names) if you need to further 
alter the appearance of your slide show (also see
.BR "-t" ")."
.B igal2
also checks for the existence of a
.I "$HOME/.igal2"
directory where users can store their own templates, overriding
the site-wide 
.IR "/usr/local/share/igal2/igal2" .
.SH EXAMPLES
Run
.B igal2
in a directory with 
.IR jpg " or " gif
images to see what it does.  Then
play with the options described above and use
.B -h
if you need a quick listing.  Also see
.I http://igal.trexler.at/
for online examples.
.SH BUGS
There are always some.  If you find any let me know.
I don't have much time to keep tweaking
.B igal2
but if any major bugs pop up I probably ought to fix them.
.SH AUTHORS
Eric Pop <epop@stanford.edu>
.br
Wolfgang Trexler <wt-igal@trexler.at>
.br
Johnny A. Solbu <johnny@solbu.net>
.SH "SEE ALSO"
.BR cjpeg ", " djpeg ", " pnmscale ", " identify ", " convert ". "
If they didn't come standard with your Linux distribution
you can find them at
.I rpmfind.net
(inside libjpeg and libgr-progs) and at 
.IR "imagemagick.org" ,
respectively.  Also try
.I www.ijg.org
and
.IR "netpbm.sourceforge.net" .