$Id: Utilities.txt,v 1.13 2000/12/18 07:27:11 dan Exp $



BUNDLED UTILITIES
-----------------

  mkGallery	- Create a "gallery" from images in the current directory.

  jhead		- Extracts EXIF header information from JPEG files.
	(Note that jhead is not for direct use - it is called by mkGallery
	when mkGallery is invoked with the "-e" flag).

convert-metafiles and mf_conv.pl are deprecated - they can be found in the
contrib directory at

  http://tangledhelix.com/softare/mig/downloads/contrib/


###########################################################################

mkGallery
---------

mkGallery can do three things:

1. Take a directory full of images and create thumbnails for them.

2. Read EXIF header information from image files and cache it in
   a text file for MiG to use.

3. Create blank comment templates in mig.cf files.

It can do all of them at the same time, too, if you want.  You can specify
which image(s) to work with, or just tell it to process every image in the
current directory.

**                                                                  **
**  Note that mkGallery requires ImageMagick and Perl.  Neither of  **
**  those is required for MiG itself - they are required only if    **
**  you want to use the mkGallery utility.                          **
**                                                                  **

mkGallery uses the following Perl modules.  On my system, using Perl
5.005_03, these are all included.  You probably will not have to install
any of them.  If you find any of them are missing, and you are not running
with at least Perl 5.005_03 you might want to upgrade your Perl install.

    strict
    Cwd
    File::Basename
    File::Find
    Getopt::Std

mkGallery has NOT been tested under Windows.


Usage:
   mkGallery [ -h ] [ -a ] [ -w ] [ -t ] [ -e ] [ -c ] [ -i ]
        [ -s <size> ] [ -q <quality> ] [ -M <type> ] [ -m <label> ]
        [ -n ] [ -r ] [ -d ] [ -D <dir> ] [ -E <ext> ]
        [ <file1> <file2> <...> ]

      -h : Prints this help message.
      -a : Process all image files in current directory.
      -w : Turn over-write on.  By default, files written such
           as the EXIF file will be appended to rather than
           over-written.  Using "-w" indicates the file should
           be over-written instead.
      -t : Generate thumbnail images.
      -e : Build "exif.inf" file.
           See the file docs/Utilities.txt - you must build the jhead
           utility (included) before you can use the -e option.
      -c : Generate blank comments for uncommented images.
      -i : "Interactive" mode for comments (see docs/Utilities.txt).
      -s : Set pixel size for thumbnails.  See the file docs/Utilities.txt.
      -q : Set quality level for thumbnails.  See the file docs/Utilities.txt.
      -M : Define type of "prefix" or "suffix".
      -m : thumbnail marker label (default "th").  See the file
           docs/Utilities.txt for more information.
      -n : Only process thumbnails that don't exist (new-only).
           Will also process thumbnails which are older than the
           full-size images they are associated with.
      -r : Recursive mode - process this folder as well as any
           folders and subfolders beneath it.
      -d : Use thumbnail subdirectories (instead of using _th, etc).
           See docs/Utilities.txt for more.
      -D : Name of thumbnail subdirectory to use (default is "thumbs" or
           whatever is in your mig.cfg file).  See docs/Utilities.txt.
      -E : File extension to use for thumbnails.  See docs/Utilities.txt.


 * If creating thumbnails, "convert" must be in your $PATH.
 * This program supports JPEG, PNG and GIF formats.
 * The "-e" feature only supports JPEG files.
   MiG - http://tangledhelix.com/software/mig/ - dan@tangledhelix.com


A note about pixel sizes
------------------------

If you specify "-s 250" for instance, ImageMagick will be handed a geometry
size of 250x250.  This means it will create a thumbnail image where the
maximum value of height (or the maximum value of width) is 250 pixels.  It
will not exceed that value for either width or height.  However, it will
maintain the aspect ratio of your image, so you will not end up with a
250x250 pixel image (well, not usually).

Here are some examples I got from testing using the default setting which
is '100'.

Original size		Thumbnail size

 1280x960		100x75
 505x250		100x49
 347x202		100x58
 160x205		78x100


A note about quality levels
---------------------------

Some image formats such as JPEG can have varying quality levels.  The
default level is "50" but you can use any number from 1 to 100.  The
higher the number, the better the quality of the thumbnail.  I have found
that 50 is a good number and produces a fairly clear thumbnail from even
large detailed photographs yet still keeping a very good file size
(usually below 2.5K).

You can specify a quality level with "-q <number>".


Labels, prefixes, and suffixes
------------------------------

The -M and -m options are new to 0.90.  In previous versions, all
thumbnails were built with the pattern "filename_th.ext" so that an image
named "myHouse.JPG" would have a thumbnail called "myHouse_th.JPG".

That's been changed.  You can now use any text you want for the "label",
not just "th".  So you could have "mkGallery -m mini" create thumbnails for
you like "myHouse_mini.JPG" and "myGarden_mini.JPG" instead.

Also, you can use a prefix rather than the default (a suffix).  So you
could have "mkGallery -M prefix" go ahead and create thumbnails like
"th_myHouse.JPG" and "th_myGarden.JPG" instead.

If you choose to use prefixes not suffixes, and/or a different label name,
you must make the associated changes to mig.cfg!  Otherwise MiG will not
know what to look for!  Changing mig.cfg has a side effect, too - mkGallery
reads it to set defaults for -m and -M, so if your mig.cfg is set to what
you want, you shouldn't have to worry about -m or -M when running
mkGallery.

Look at $markerType and $markerLabel in mig.cfg.default or mig.cfg.
$markerType equates to "-M" and $markerLabel equates to "-m".

Values in mig.cfg are used, but if you invoke command-line options to
mkGallery, -m and -M will override the values in mig.cfg.

As of version 1.1, you can also use a thumbnail extension type.  This is
basically in case you have mutiple types of images such as JPGs, GIFs, etc,
but you want all thumbnails to be a particular type (say, all GIFs).

See both the $thumbExt option in mig.cfg, and the -E option to mkGallery.
If you define $thumbExt in mig.cfg, mkGallery will use that value as the
default.

(You can also use subdirectories for thumbnails and avoid all this prefix
and suffix nonsense altogether... see the next section).


Using thumbnail subdirectories
------------------------------

Not all users want their thumbnails littering up their folders.  As such,
MiG has an option which lets you put thumbnails into a subdirectory
instead.  To do this, set the $useThumbSubdir and $thumbSubdir options in
the mig.cfg file.  You can also use the -d and -D options to mkGallery to
override what mig.cfg has configured.

Then you might have files like "AUT_1015.JPG", "AUT_1019.JPG" and in a
subdirectory "thumbs/AUT_1015.JPG", "thumbs/AUT_1019.JPG" ... so they are
the same filename for both, just in different directories.  Many people
view this as cleaner (I've converted my own gallery over to this method).

You don't have to create the directories ahead of time - mkGallery will
create any directories which are not already there.


"Interactive" mode
------------------

If using the "-c" option to generate comment fields in mig.cf, you can also
optionally specify "-i" or "Interactive" mode.  Basically all this will do
is prompt you for each image which does not already have a comment, and you
can (optionally) type in a comment for that image.  If you don't want to do
so, just hit Enter and that image will be skipped - mkGallery will move
along to the next one in the list.


"New-only" mode
---------------

The new-only mode (-n) basically follows this set of rules.

 1. If an image file exists without a thumbnail associated with it,
    generate a thumbnail for it.

 2. If an image file exists, has a thumbnail, but is newer than its
    thumbnail file, re-generate the thumbnail.

If you do not specify "-n" then all images will get new thumbnails.


"Recursive" mode
----------------

Recursive mode makes it simpler to do big chunks of an album.  You can just
load up a bunch of folders and pass mkGallery a "-r" and it will go to
every folder from the point you are currently at, and do all of the
subfolders too.  New users can simply go to the "albums" directory and let
loose a "mkGallery -art" and it will generate thumbnails for everything it
finds.  Personally I find "mkGallery -rant" the most useful combination for
general purposes, as well as "rant" being easy to remember :-)

Recursive mode works with all of the action modes (-c, -e, -t).


###########################################################################

jhead
-----

jhead was written by Matthias Wandel and can be found at:
    http://www.sentex.net/~mwandel/jhead/index.html

It is included here but I take no credit for the code.  Matthias however
deserves lots of credit for it, as it's incredibly useful!  Feel free to
drop Matthias a line and let him know his code is appreciated.  His email
address is available at the URL listed above.

You will need to build jhead in order to use it.  To build on most systems
just type "make" in the util/jhead subdirectory.  If you don't have gcc
you'll need to edit Makefile to point to your compiler.

This should work as-is on most Unix or Unix-like platforms.  I can attest
to its working with Linux.

jhead is not something you need to run directly - it is used by mkGallery
if you invoke mkGallery with the "-e" option.


###########################################################################

