Gallery Mage User ManualWilliam Denniss Abstract:
Gallery Mage is a digital photography processing system for users of digital cameras and scanners.
It enables galleries of photographs to be renamed, captioned, rotated, cropped and uploaded - without altering
the original picture files.
Copyright ©2004-2005 William Denniss. All Rights Reserved.
|
Gallery Mage is a digital photography processing system. Users are able to rename, resize, crop, rotate, caption, their photos, and ultimately export selected photos for
publishing on the Internet or emailing to friends. Unlike many image tools
however, Gallery Mage is designed to never overwrite the original files (unless you tell it to). All operations and captioning is stored as textual data files in the gallery
directory. Gallery Mage can export to a variety of formats for easy publishing on the internet including SPGM![[*]](footnote.png)
(Simple Picture Gallery Manager) and plain HTML.
To install, open (mount) the downloaded DMG disk image and drag the ``Gallery Mage'' folder into your ``Applications'' folder (it is important to drag the entire folder, not just the Gallery Mage application as the folder contains settings and an example gallery.
Once installed, simply open the Gallery Mage folder and double click the Gallery Mage icon (pictured below) to start.
Download and run the installer EXE. This should install Gallery Mage into your
``Program Files'' directory, and create links in your start menu. Launch Gallery Mage
by clicking on the ``Gallery Mage'' link in your start menu. If nothing happens,
try the ``Gallery Mage Debug'' link to see the troubleshooting output (you can get help in the Gallery Mage forums, linked
to from the Web Site Help->Web Site). Make sure
Java 1.4 or better is installed (download from http://java.com/).
The following installation instructions should work on any Java 1.4 enabled platform including Linux, some Unixes, Mac OS X, and Windows.
Extract the downloaded .tar.gz file. Launch gallery mage by running the command java -Xms32m -Xmx512m -jar gallmage.jar from the Gallery Mage directory (or use the included Gallmage2 and Gallmage2.bat scripts). NOTE: This command must be run from the gallery mage directory or else Gallery Mage will not be able to locate its configuration files.
If you are going to be displaying your photos on the internet, before you start you need to choose your display method. There exist many good open source and free PHP gallery display scripts, such as SPGM and Singapore. These provide dynamic gallery displaying, one can just upload the photos and the script does the rest. If you don't have access to PHP hosting, plain HTML exporting is one option and just exporting the pictures (so you can email them etc.) is a second.
If you are seeking SPGM hosting, Delta IT provides a fully supported SPGM and Gallery Mage solution. Delta IT is owned by William Denniss, the author of Gallery Mage, and all profits help support its continued development. For more information, please visit http://deltait.com.au/spgm
Alternatively, Gallery Mage can simply be used as a fast way to process your images.
The following is a list of supported gallery display scripts. The ones which fully support gallery mage are marked with an asterix (*).
The following is a guide on how one typically processes a gallery using Gallery Mage. These points are summerised in a single pintable page in the latter section named ``Workflow - JPEG''.
To load in a photo gallery, select Gallery->Open from the menu bar. This brings up a folder selection dialog box which allows you to chose the directory containing the photos. Simply pick your galleries' directory and click ``Open Gallery''. This will load all of the JPEG image files found in that directory into Gallery Mage.
The loading of the display thumbnails is performed in the background, so you can start processing your images as soon as you want (generally it's a good idea to wait for the first page to load). If you don't need to see your photos (e.g. if you just want to export them, or just want to upload exported images), you can click the ``Cancel'' button to stop the images loading. To restart the loading at any time, simply select Options->Load Display Images from the menu bar.
It is a good idea as the first thing you do to name your gallery. This name is used later when renaming and uploading images. Simply select Gallery->Set Gallery Name from the menu bar and give it a name (e.g. 2005-03-31_MyPictures).
Often, photos are downloaded from your camera with meaningless names such as ``DSCF_0001.JPG''. It's a good idea to rename these images into something more meaningful so you can easily locate them in the future.
Select Gallery->Rename Pictures from the menu bar to bring up the rename dialog. By default, the Gallery Name that you gave earlier is used. When you are happy, click ``Rename''. It is not recommended to have spaces in your file names.
NOTE: This is one of the few Gallery Mage operations that actually modifies the original files (however, it's not modifying the data within the files, just the file's name), and once renamed there is no easy way to revert them back so please take care.
In this step, choose the photos you wish to display to the world. Either go though un-ticking the ones you don't like, or select Edit->Deselect All Images and go though ticking the ones you do like.
Left clicking on an image will open the image up in a larger view for closer scrutiny. While viewing an image in this mode, you can crop the image by clicking on the top left corner of the area you wish to crop, and dragging the mouse to the bottom right corner. A red box should appear to indicate the selected crop area. Optionally, hold down CTRL while moving the mouse to lock the selection to the picture's original aspect ratio. Note: As mentioned earlier, the actual crop operation is only performed when exporting, your original image file is not altered.
In the text box below the image, you can type a short caption which will be shown with your image (assuming your display method supports this).
Right click (or Shift+Click if you are using a one button mouse) an image to rotate it 90 degrees. Keep clicking till it's the right way round (generally one click is all that is needed).
One can also choose what size the image will be when exported. There is a drop down box which initially is set to ``Default''. One can chose a preset size from the drop down list, or type in a custom one in the format ``WxH'' where W is the width in pixels and H is the height. The special ``No Change'' size indicates the image will be exported without scaling. NOTE: Only use this setting for images which are the exception to the rule. To change the export size of all images, see the latter section on ``Changing the Output Settings''
If desired you can give the gallery itself a caption by selecting Gallery->Set Gallery Caption from the menu bar.
When the gallery is ready, you need to export the pictures. Exporting copies all of the images into the chosen export directory, scales them for better internet viewing, and applies all the operations such as rotating and cropping. It also generates thumbnails and creates a file with all of the captions, designed for use by your display library.
To export, select Export from the menu bar, and choose the correct export plugin for your chosen display method (e.g. SPGM). By default, the gallery is exported into a sub-directory of the gallery directory named export.
Once exported, if you wish to display your gallery online, it will need to be uploaded.
Assuming your are using a display option like SPGM whereby you can simply upload the entire export directory to a directory on the server, then you can use Gallery Mage's inbuilt FTP directory upload feature.
Simply select Upload->Upload Export Directory from the menu bar. On the FTP Upload screen, you need to select your export directory (the last exported directory will be selected by default). The option directly below this (a text box labeled ``Remote Gallery Directory Name'' is where you can specify the name of the directory that will be created.
The ``FTP Server Settings'' section is where you need to specify all of your FTP settings. These settings
normally do not change and as such are stored for next time. Your host should have provided you with your
FTP server, username and password details. ``Remote Gallery Directory'' is where the new directory will be created
(of the name, specified in the ``Remote Gallery Directory Name'') and the files uploaded.
If you are using SPGM, this should be your ``gal'' directory (e.g. ``/public_html/spgm/gal''). It is the same directory path that you would
see if you used an FTP client to
log into your account and go into that directory. If you have any troubles, please ask for help in the Gallery Mage
forums.
When all the details are entered, simply click ``Export''.
NOTE: You must have exported your gallery prior to uploading!
For future galleries, so long as you are naming the gallery (see the prior section, ``Naming your Gallery''), and your FTP details have been saved, you can simply click ``Upload'' - too easy!
The Export and Upload steps can be combined by checking the Options->Upload after Export check box in menu bar prior to exporting.
These steps are if you wish to change the size of your exported images. By default, they are scaled to fit inside a 800x600 pixel box, which makes them a great size for people with screen resolutions 1024x768 and above, and still viewable for those with 800x600 screens. At 80% JPEG compression, it also works out to about 100KB per file which is fairly small.
Select Options->Edit Export Settings from the menu bar.
The export settings are in the section titled ``Export'', which should already be selected. These settings relate to the picture export.
From the drop down list of attributes, select the attribute parameter you wish to alter. Below the drop down list is the value of that attribute and below that, a description of what it does. The most popular ones to change are Height, Width and JPEGQuality.
Changing the ``Section'' to ``Thumbs'' allows you to alter the thumbnail export settings. Popular choices are Height, Width and ExportThumbs. Note that setting the width to -1 means that the thumbnails will all be the same height and the width will be scaled to match.
When closing this window, ensure you save so that the settings are retained for next time. There is no need to restart gallery mage, it will automatically use the modified settings.
NOTE: It is important not to accidentally add non-numeric characters to a number field. If this occurs, an error message will be printed at run time, and the value will revert to its hard coded default.
The plugin settings are stored in .INI formatted files in the conf/plugins directory. These files can be edited in text editor such as jEdit (http://jedit.org/), or using the included Ini Editor utility. NOTE: regardless of the method used, Gallery Mage must should not be running while it's settings (other than the General Export Settings from the previous section) are altered.
In addition to the custom plugin attributes, a specific plugin config can override the export settings stored in the conf/export.ini file (the one edited in the previous section). To do this, an attribute of the same name as the one you wish to override should be created in a section named ``Export''. For example this can be used not to export thumbnails for certainly display software that generates thumbnails automatically (such as Coppermine), while still exporting thumbnails for ones that don't generate thumbnails (such as SPGM). It can also be useful if you process some galleries differently, even if the target viewing program (eg. SPGM) is the same. Simply make a copy of the desired plugin config, and edit it (make sure you change the ``Name'' attribute so it will show up in the Gallery Mage export menu as a separate item).
The following is a list of the more notable options residing in the conf/gallmage.ini config file.
Gallery Mage is an Open Source, GPL licensed . Java Programmers are able to make changes
and distribute those changes provided they are also open source and licensed under the GPL.
You need the Java SDK installed to compile,
and Apache Ant to use the build file
(strongly recommended).
Ensure you have the .tar.gz release (not the Windows Install) and decompress it to a directory.
To compile, simply type ant. If LaTeX is installed and on your system (as it is with many Linux
distros), you can run ant pdf and ant html to create the documentation PDF and HTML respectively.
To release a build, run ant rel. To make the Windows installer, run the Gallery Mage .nsi script though
the NSIS installation builder. To
create a Mac application, run ant mac, and the DMG disk image, ant mac-dmg (Note: you can only
run this command on a Mac).
Creating a custom export plugin if you are knowledgeable about Java is not a difficult task. Plugins must implement the interface com.tanksoftware.gallerymage.ExportPlugin and its one methods
void exportGallery (com.tanksoftware.gallmage.gui.GalleryDisplay frame, Gallery toExport, net.jtank.io.Ini exportSettings) throws ExportCancelledException;
The GalleryDisplay class represents the GalleryMage frame GUI. The ``Gallery'' is a data structure which represents the gallery you wish to export. The ``Ini'' file contains the users export settings (i.e. thumbnail size, etc...).
With this in mind, the best idea is to look at source of the existing plugins that come with Gallery Mage such as FileExport and SPGMExport and code by example.
