Using the Lophty Photoindexer
Producing sorted thumbnail index pages of directories of JPEGs, PNGs, and GIFs
Bug reports (check your directory and file permissions and the troubleshooting section first), feature requests, and comments can be directed to the author at photoindexer-technical@lophty.com.
About the Photoindexer
# top The Lophty Photoindexer offers an extremely quick and simple way
to present a page of thumbnails of larger images residing within a
directory on a web server.
Images are sorted first by format (all of the JPEGs will precede any
PNGs, for instance .... bob.png coming after zac.jpeg, etc.) and then
by file name.
The Lophty Photoindexer is available as Free Software under the GNU
General Public License.
Several months ago, when I was looking for a no-frills way of putting
some of my photos online, I found a large number of existing solutions,
but most had features that I didn't particularly need (or want) and,
at the same time, were lacking others that I considered essential.
As is the case with the Photoindexer, many of these applications were
licensed under the GPL or GPL-compatible licenses,
so I might have been able to customize one of the already available
options to my needs, but I elected to write something of my own.
I'd already written a PHP class for presenting an ordered list of
the files within a directory, the
Lophty Directory Indexer (lophty_directory_indexer)
and I used that as the parent of a class that handled thumbnail creation
(lophty_photo_indexer).
Together, with a stylesheet and a short script where an instance of
the lophty_photo_indexer class is created and invoked, they
comprise the Lophty Photoindexer
Installation, demo
# topInstallation instructions can be found in the README file. If the README is missing, download the latest release of the Photoindexer.
A demo of the Photoindexer, using copyright-free images can be found
here. If
you are viewing this page locally, you will most likely have to upload
all of these files
to a web server and follow the installation instructions in the README
file to see the demo in action.
If there is no demo directory accompanying these docs or any other
files are missing, download the latest release
of the Photoindexer.
Features, options
# top The Photoindexer is highly configurable. If you would like to change
the visual appearance (aspects like colors, fonts, dont size, margins,
padding, etc.)
of the page within which the thumbnails are displayed, then edit the
stylesheet photoindexer.css.
To change the number of columns of thumbnails (the default is 3),
you can use the intNumColumns parameter.
This and other options can be set in the same script in which the
Photoindexer class is instantiated.
They can also be set globally by editing the defaults in the lophty_photo_indexer.php
file, but if you upgrade to a newer version of the Photoindexer later,
you would have to re-edit the new lophty_photo_indexer.php file.
Any changes from defaults for these options must be made after the
class instance is created but before it is used to index the images
(see the index.php file residing in the top level of this package
with the photoindexerfiles directory).
Options
# top- intNumColumns
: Number of columns of thumbnails. Default : 3.
Example 1 : To specify 5 columns instead, you could add the following line to the script in which the Photoindexer is instantiated and invoked :
$classinstLophtyPhotoIndexer->intNumColumns = 5; - intWordsFromStringNames
: Parse file and directory names, replacing characters listed
in
arrWordsFromStringNamesDelimiterswith spaces. Default : 1. Set to 0 to turn this off. - arrWordsFromStringNamesDelimiters
: List of characters used to mark spaces in file or directory
names. By default, the only delimiter in this array is the underscore
character ( _ ).
You can use a different character or add more, but if a file or directory name possesses more than character from this array, it won't be parsed.
Be consistent in your file naming conventions or rename files to include one of the delimiter characters in this array if you want to take advantage of the "file names to words" functionality.Example 2 : Adding another delimiter (the hyphen in this case) :
$classinstLophtyPhotoIndexer->arrWordsFromStringNamesDelimiters[] = '-';Example 3 : Replacing the underscore character (default) with a different delimiter (the hyphen in this case) :
$classinstLophtyPhotoIndexer->arrWordsFromStringNamesDelimiters = array('-'); - intJpegQuality
: Specify an integer from 0-100 to set the JPEG image quality
of any JPEG thumbnail images generated by the Photoindexer.
Set to 0 (the default value) to allow PHP and GD to determine the quality value. - intGenerateThumbImgs
: Controls whether and how thumbnails be generated for the images
being indexed.
Set to 2 by default, which means that the Photoindexer will try to produce thumbnails. Set to 0 if you would rather simply use inlined the original images resized through
the height and width attributes of theirimgelements (not recommended). - arrThumbProps
: array containing the height and width values (in
px) for your thumbnails (the size of the actual thumb images and the height and width attribute values for theirimgelements).Set to 80x80 by default, but it is highly recommended that you use your own values specific to the aspect ratio of your images (ratio of height : width of your images).
Note : these values can only be specified once per page, so the results are most favorable when all of the images being indexed have the same aspect ratio.
Example (from the index.php file residing in the top level of this archive) :$classinstLophtyPhotoIndexer->arrThumbProps = array('intThumbHeight' => '80', 'intThumbWidth' => '120'); - strThumbsSubdirName : The name to use for the thumbnails subdirectory created within the directory of images being indexed. Default "thumbs".
- strGeneratedThumbFilenamePrefix : When thumbs are created, they're given the same name as the original image with this value prepended. Default "thumb-".
"Albums" Options
# top If you would like to group images together and link to such a
group from a Photoindexer page, the simplest way to do this is to
create a subdirectory within the directory being indexed
and upload them into this subdirectory. Give the subdirectory the
same name (sans extension) as one of the images in the main directory
(hint : select an image representative of the files in the subdirectory),
ex. : some_photo.jpg and a subdir some_photo.
When it is preparing the fragment of HTML for displaying a given
thumbnail, the Photoindexer looks for a subdirectory with the same
name.
If it sees one, it descends into that subdirectory and counts the
number of images (files with extensions .jpg, .jpeg, .gif, or .png
by default) within.
If there are any images there, then the thumbnail will link to that
subdirectory instead of linking to the original image.
Empty subdirectories won't be linked. That's how "albums" work.
See the demo for an example.
- intShowAlbums : Controls whether or not "albums" are shown. Set to 1 by default. Set to 0 if you don't want the Photoindexer to link to directories that fit the profile of "albums" (criteria outlined above).
Unimplemented options
# top- blnPngThumbsForGifImgs
: Would control whether or not PNG format thumnails are generated
for GIF format images.
Doesn't do anything as yet. Included because recent versions of GD have had write support for GIF files removed due to the GIF compression algorithm patent controversy.
Haven't implemented yet because I don't have the gif2png utility (used in this example) installed on any of my hosts.
Deleting, Regenerating thumbnails
# top At some point, while experimenting with different thumbnail dimensions
for example, you will need to delete the existing thumbnails.
To do this, simply access the script that invokes the Photoindexer
with ?deletethumbs appended to the url. An HTTP Authenticate
dialog will appear.
Supply the username and password (specified by $strUsername
and $strPasswd in the script.
The Photoindexer will delete all of the thumbnails and the thumbnails
directory. To regenerate the thumbs, simply load the script again
(without the deletethumbs parameter appended to the url
this time).
Unless you've turned off thumbnail generation via the intGenerateThumbImgs
option, the files will be rebuilt.
Troubleshooting
# top-
I upload my images and all of the files associated with the Photoindexer,
but when I load the thumbnails page in my browser, some or all of the thumbnails show as featureless black rectangles.The problem may be with your images. On a few occasions, someone has sent me JPEGs of unknown provenance whose thumbnails, when generated by the Photoindexer,
showed up as plain black rectangles. The same files viewed fine in the browser and other apps.
Opening these files and saving them in Photoshop, then reuploading them, using deletethumbs to flush out the bad thumbs, and generating fresh thumbnails from the opened-and-saved images did the trick. -
I see a very fine, perhaps 1px wide border, on the right and lower sides of (some/all of) the thumbnails.
The problem may be with the thumbnail aspect ratio (can be specified via the arrThumbProps property of the Photoindexer instance) that you're using.
Ideally, you've preprocessed all of the photos so that they're the same size, then arrived at the proper values for thumbnail width and height by choosing one thumbnail dimension
(either height or width) and multiplying it by the ratio of original image height : original image width or vice versa (depending on which thumb dimension you've set as fixed).
I often see the black lines myself when I've rounded the value for the free dimension (the one that you've calculated) upwards to the next nearest pixel.
Getting rid of most of them is as easy as invoking deletethumbs and uploading a new version of the script that calls the Photoindexer with the free thumb dimension's value
reduced by one or more pixels, then refreshing the page. You may find that some remain, regardless of how you jiggle the aspect ratio, but not so many. -
When I access the script, I see the photos, but there are PHP Warning messages at the top of the page.
If the first one or more warnings begin with something similar to "Warning: mkdir([...]) [function.mkdir]: Permission denied in [..]", then you most likely have neglected to set the
proper permissions on the directory containing the images. The Photoindexer cannot create the thumbs directory or the thumb images until you've relaxed the permissions
on the directory within which the thumbs dir and those files will be created.
Credits
# topThanks to Gimp-Savvy.com for the images used in the demo - they're taken from the US Fish & Wildlife Service portion of that site's Copyright-Free image archive.