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 Mig-contrib package in the download section on the Mig site:

    http://mig.sourceforge.net/


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 Microsoft 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 config.php 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://mig.sourceforge.net/

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
    1280 x 960        100 x  75
     505 x 250        100 x  49
     347 x 202        100 x  58
     160 x 205         78 x 100

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

(As of 1.3.1, thumbnail subdirectories are the default - unless you've got them turned off, they will take precedence).

The -M and -m options are new in 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 use mkGallery -M prefix to create thumbnails like th_myHouse.JPG and th_myGarden.JPG instead.

If you choose to use prefixes and not suffixes, and/or a different label name, you must make the associated changes to config.php. Otherwise Mig will not know what to look for. Changing config.php has a side effect, too - mkGallery reads it to set defaults for -m and -M, so if your config.php 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 config.php.default or config.php. $markerType equates to -M and $markerLabel equates to -m.

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

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 config.php, and the -E option to mkGallery. If you define $thumbExt in config.php, 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 config.php file. You can also use the -d and -D options to mkGallery to override what config.php has configured.

(As of 1.3.1, thumbnail subdirectories are the default)

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 the -r flag 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 flag.