About AreaJ

AreaJ is an open-source digital-image web engine written with MySQL, Apache, and mod_perl, and perl. It is intended to provide advanced image search, management and editing features.


AreaJ requires Apache, mod_perl, perl 5.6, mysql, and many open-source perl packages obtainable from www.cpan.org. No attempt has been made to run this under windows, although theoretically it should be possible.

User guide


Use-Case Guide

Browsing pictures

Use case 1: You just surfed in from the from the web and you want to see as many pictures as possible, without any text whatsoever.
Procedure: Go to the search page, set the Search user to "any", make sure that the "Before Date" and "After Date" fields are clear, and that the "Captions" field is clear, and that "Deleted Images" is set to "Non-Deleted Images". Turn off all editing if you've logged in and have those options - Set the navigation style to manual, image size to thumbnail, "allow size change" to "Don't Show Links", basic info to "No" "Show EXIF" to "No", "Captions" to "None", "Table Width" to 5 or so, "Table Height" to something large - if you don't mind scrolling down, you can set it to 100000 and you'll see everything on one page assuming you don't mind waiting for it all to load. If you want to see some text but not all of it, turn on just "Basic Info" and "Allow Size Change" - these options usually use up only about as much space as a single image.

Use case 2: You'd like to look at images one by one at a reasonable (non-thumbnail) size but still don't want to see any of the textual clutter.
Procedure: Do as in use case 1, but set Image Size to "Small" or "Large" and the "Table Width" and "Table Height" to 1. You can set the "Table Height" to 10 or so if you like scrolling down a column of images. The more images you allow to appear on a page, however, the longer it will take to load them. Also, non-thumbnails may not be cached on the server (unless someone else has already looked at them at this image size) so you may have to wait awhile for each one. If you don't like waiting for each image to load, set the Navigation Style to "Auto SlideShow" and the Auto Interval to something small - 5 or so. This will cause the images to be uncached for display on a timer - you don't have to look at them right away, just set it up and let it do it's thing in the background - then after awhile when it's done you can go through them one (change to Manual mode) since the generated images will now be cached.

Uploading your own pictures

Use Case 1: You've got a set of pictures on your digital camera. You'd like to upload them, weed out the ones that are bad, rotate the pictures whose orientation is wrong, crank the brightness on a few underexposed shots, sharpen probably almost everything, create a referring URL to send to the parents in Kamloops, and still have time to get to work before noon. Procedure: This is basically what AreaJ was written for. Do:

Setting up slideshows

Use Case 1: You'd like to set up an automatic slideshow of your recent trip to Bora-Bora.

Procedure: After setting up your images to your satisfaction, go to the Search page. In the Search page, select the image size you'd like - generally speaking, you shouldn't go any larger than "Large" (800x600) unless you're confident that the resolution of your monitor is greater than that of the images your camera generates (or unless you like looking at only small parts of your images). Select the navigation style to "Auto Slideshow". Set the desired interval time in seconds. The interval time only dictates how long the browser will wait between displaying images - if the images haven't been viewed before at the desired size, it may take some time for each of them to be generated at that size, meaning your total time spent may be greater than you think. If you know you're going to look at all of your pictures at a certain size, you may want to set up an auto slideshow with a low interval, at the size you want, start it off and then take a break for awhile while it generates all of the images. After the images have been generated in this fashion, they are cached, so that the next time access should be virtually instantaneous. If you want the pictures to be in random order, choose "(Pseudo)Random" from the "Order By" drop-down.

Functional Guide


In the logged-out state, you'll see only four buttons on the bottom navigation bar. The third button should read "Login". Press that. The content frame should now contain Login and Password fields, along with a pulldown indicating whether the user wishes to request administrator priveledges.

A user should only request administrator priveledges if they are a designated administrator and they intend to do administration when logged in. To avoid possible misuse of the administrator priveledges, it is a good idea to not request administrator priveledges even if you are an administrator. In this way, malicious users should be unable to abuse the administrator priveledges of an administrator who has left him/herself logged in.

Once a user has logged in, the button should read "Logout <username>". Pressing the button will immediately log out the user.

New User

The "New User" feature may be available if this AreaJ site has been set up to allow it. This screen lets you create your own account. Various conditions may apply to this account, at the option of the administrators - this feature principally exists to allow the user-only features of AreaJ to be demoable to any user who can find the website.

Creating a user account with this feature is pretty straightforward; enter a name, an optional email address, and a password (twice) and a new user will be creted if the username is unique and the passwords match. New users by default are given a set of private images for demonstration purposes. The images are private by default so that zillions of duplicate images don't appear in general searches or the title page.


The Search page is the meat of the entire application suite. There are four sections to the search page:


The "User" pulldown may be changed to specify the owner of the images you're looking for. Choose "any" to specify that images from all users should be retrieved. After a login, the logged-in user should be automatically selected from this list, though of course you can change it.

Before Date/After Date
The "After Date" and "Before Date" fields may be specified to indicate a date range to search on. These dates need to be specified in YYYY-MM-DD format - for instance, specifying an "After Date" of "2000-2-1" and a "Before Date" of 2002-2-1" will return images taken between February 1 at 0:00 and January 31, 2002, midnight. Leaving no specification in either field effectively unbinds the top or bottom of the range. The time may also be specified in these fields - the full format is YYYY-MM-DD HH:MM:SS (24 hour format) - (for instance, 2001-01-08 13:14:15).

The "Captions" field may be used to specify captions that you are searching for. The caption values are "or'd" together - for instance, if you've captioned a number of images with 'France' and a number with 'Spain', but you can't remember whether a particular picture was taken in France or Spain, you might specify 'France Spain' in the Captions field. The resulting images will be all of those captioned 'France' and all of those captioned 'Spain' (that is, each image will be captioned 'France' or 'Spain', or both, hence 'OR').

Caption values, in addition, may be loosely compared - for instance, if you search for the caption 'steph%%', you'll get everything captioned 'stephanie', 'stephanopolos' or just plain 'steph'. Likewise if you remember that you captioned something with a quoted sequence that contained the word 'red', you could search for '%%red%%'. (The initial caption would have to have been applied surrounded with double-quotes in order for the multi-word combination to be considered a single caption). Captions found with this feature will include all captions, indexed and otherwise (see Result/Captions for an explanation of the difference between indexed and unindexed captions.

Deleted Images
You may specify deleted images only if you want to look at images you've marked for deletion; or non-deleted images only if you want to look at only those that haven't been marked for deletion (this is most typical); or, you may specify that you want to see both (possible in those situations where you've got several shots of the same thing and you've chosen to mark most of them for deletion, but want to re-examine that decision).

Private Images
You may use the "Private Images" pulldown to specify that you want to see public images only, private images only, or both. Regardless of what you choose, the result set will not contain images owned by other users that are marked private. (However, if you have "any" user selected, and "both" private and public images selected, you will see public images from other users, as well as both public and private images of your own).

Display Results

AreaJ gives you a lot of choices with respect to output. Here's a brief summary of what each option does:

Navigation Style
This may be set to "Manual Slideshow" or "Auto Slideshow". Manual Slideshow indicates that the result set pages should be navigated by means of 'Start', 'Prev', 'Next' and 'End' buttons. Auto Slideshow indicates that the pages should cycle on a time interval set by the "Auto Interval" field. This field is ignored if "Auto Slideshow" is not set as the Navigation Style. Note Just because you set an interval of 10 seconds doesn't mean the image will cycle every 10 seconds. If the image hasn't been viewed at this resolution before, it must first be generated and written to disk; this can take awhile depending on the power of your web server and how much it is being used. Once all the images have been created, the cycle time should be more reliable. More on this in the Navigation section of the Results page.

Image Size
AreaJ supports 4 images sizes for no particular reason: Thumbnail, Small, Large, and Full. You should choose this option carefully; probably only thumbnail is appropriate if you've chosen a large table width size. If you choose a larger size, probably the table width should be adjusted downward accordingly. All sizes will work, because scrollbars will automatically appear in the content frame; however that doesn't tend to be a convenient way to navigate your user interface.

The original image that you uploaded is where the real size resides. When you request images of thumbnail, small, or large size, the original image is dynamically scaled and the result is presented to you. However, the actual size of the original is unchanged - in fact, we never, ever modify the original file.

Font Size
The font size of the pages generated for the search results will be adjusted up or down by this number.

Allow Size Change
When turned on, a set of links appears under the image - "Thumbnail, Small, Medium, Full, Original". Leave this turned on if you want to switch between the different sizes. Turn it off if you want to save a line of space in the output. See Size Change Links for more information on how these work.

Show Basic Info
"Basic Info" includes the original size of the file, the owner of the file, the date that the file was written, and whether the file is marked for delete or is marked private. Turn it off if you want to recover some space in your output - often your search is user and time, deletion and privacy -state restricted already, so this information may not be of use to you. If, however, you want to change the privacy/deletion state of the images on an individual basis when looking at the result set, you'll need to leave this turned on. See the section on Basic Info in the Results Pages segment.

Every digital camera these days puts an EXIF header into their files. EXIF stands for "Exchangeable Image File", and is a Japanese Electronic Industry Development Association (JEIDA) standard for encoding certain information in image files. Particularly digital photography information. Accordingly, this option will display the Make and Model of camera that took the photograph; the effective ISO sensitivity used; whether or not a flash was used; speed and exposure time; exposure bias, focal length, F Number, Light Source, Aperture used and Maximum Aperture of lense used, the Metering Mode set in the camera, and the Exposure Program. At least, these are the fields I have chosen to include; primarily because they are the most useful ones, and because they are a good superset of fields that are (mostly) filled in by the two digital cameras that I've used most (Canon D30 and Nikon 990).

This option will gain you the most real estate if you turn it off.

There's a little bit about this in the Results Page/EXIF Information section as well.

Show Captions
A caption is a small snippet of text (usually 100 words or less) that may be associated with one or more images. Every caption is dated and has an owner, and may be associated with any number of images. The "Show Captions" choice lets you pick what captions you want shown for each image in the result set. You can choose "All Users Captions" which will show, for each image, all captions regardless of owner. Choosing "Owner's Captions Only" will show only the captions applied to the image by the image's owner. "Story Captions Only" will show you only non-indexable captions - this is useful when you want to retrieve a set of pictures with a set of captions that bind the pictures together in a story of some sort. Choosing "Viewer's Captions Only" will show only the captions of the user who is currently logged in (the option isn't available if nobody is logged in). Finally, you can choose not to see any captions at all.

You would probably choose "Viewer's Captions Only" if you've gotten in the habit of applying your own captions to other users' images. You might choose "Owner's Captions Only" if you're only interested in the captions that the owner applied to the image.

Text Location
You can choose to have the text located below or to the right of the image. Typically 'Below Image' works best when you're viewing many thumbnail images, and 'To The Right of Image' works best with larger images, with fewer per page.

Choosing 'Yes' here will mean that the resulting pages won't be displayed until all of the requested images have been generated. This has the drawback of taking awhile, but can sometimes be helpful when each result page contains so many images that the httpd server you're using runs out of processes and returns dead links for many of them. This should never be necessary when you're looking at thumbnail images, as all uploaded thumbnails are generated during the upload procedure. However, if you're attempting to look at a lot of 'small' images stacked in a result set - say a table of 1x20 or so - and you're seeing dead links, try using this option to get more reliable results.

Table Width, Table Height
This specifies the layout of result images per result page. A simple table is constructed with the specified width and height, and an image will occupy each cell. The full result set may still be accessed through the use of 'Start', 'Prev', 'Next' and 'End' links.

Result Order

You may choose to order your results by Date, User and Date, or Randomly. Ordering by date simply returns the images in the order of the taken date. Ordering by User and Date will order first by user, and then by date - so if you're searching for "any" user and get back images from more than one user, the images will be grouped by user and sorted alphabetically; then within each group, the images will be ordered by taken date. Choosing either of these options also guarantees that images with dates that are identical ('0000-00-00 00:00:00' is common, due to a failure to set a camera's date, for instance) will be sorted by the final component of their filename. For most camera numbering systems, this should ensure that these pictures appear in chronological order, even though the dates may be marked the same.

Ordering Randomly is mainly useful for slideshow presentations - a random permutation is applied to the result set such that the order will be unpredictable and hopefully interesting. The search criterion still apply; if you define your search criterion too narrowly you may still have too small a result set to be interesting.

The "Fectch Limit" may be used to specify that no more than n images be returned - probably only useful when you're doing large ad-hoc searches.


You only get to see the editing controls if you are a logged-in user. The edit controls on the search page determine what edit controls will appear on the result pages, and in some cases the behaviour of the controls on the result pages.

Deletion Marking
When on, the "Yes" or "No" indicator after "Marked For Delete:" in the result pages will be a link that will toggle the state. The image will remain in the result set even if the new state is inconsistent with the search parameters, until you make a new search.

Private Marking
When on, the "Yes" or "No" indicator after "Marked Private:" in the result pages will be a link that will toggle the state. The image will remain in the result set even if the new state is inconsistent with the search parameters.

When on, controls that allow you to add or delete captions to each image will be included in the result pages. The ability to delete is provided by a small link ("d") after each caption that will delete the association of that caption to the listed image, and will in fact delete the caption itself if there are no other images remaining to which that caption is associated. The ability to add a caption on an image-by-image basis is provided by means of a text field under the last listed caption, with an "Add" link beside it. Entering a caption and then hitting the "Add" link will result in the caption being created if it is unique, and then associated with the image. Neither the add nor delete controls will appear if Show Captions has been set to "Don't Show Captions" in the Display Results segment of the search page.

Along with showing EXIF information, showing edit links uses up the most space. Edit links consist of five controls and an optional button, arranged in a column. In order, they are rotate, hue, saturation, brightness, and sharpness. The key to understanding how images are edited in AreaJ is to understand that the editing is always done in that order - rotation is done first, then hue saturation and brightness (in reality these are a single operation) and then sharpness adjustment. In fact, a silent resize is done before any of these operations in order to get the image to the size that has been requested (thumbnail, small, large, full, see the section on Image Size for more details). For further details on how this works, see the section on Result Pages.

Editing Style
If Image editing is turned on, this control will determine the behaviour of the rotate, hue, saturation, brightness controls. When set to "Control Per Image", then a button will appear below the editing controls that you can press after making the desired edit modifications. When set to "Immediate Reaction", no button will appear, and the image will be modified every time you change a control. If Image Editing is not turned on, this control has no effect.

Which setting you should choose depends on your values of the moment. If you're doing inital processing of raw images to get their rotation right, adjust their brightness a bit, and then sharpen it (for instance), then "Control Per Image" might make more sense since you know what you need to do for each image (even though it isn't the same for every image) and you don't want to waste time for interim changes to take effect. If, on the other hand, you're experimenting with effects, or just getting used to the behaviour of the controls, you might want to use "Immediate Reaction" to see what the effect of a given editing change is without having to always be clicking on the "Perform" button.

Post-edit Refresh
This setting also only has effect if Image Editing is turned on. When set to "Image", AreaJ will attempt to modify only the image that is displayed, rather than reloading the whole page. This is desireable because reloading the whole page takes longer, and introduces an annoying flicker. Due to browser restrictions, rotates will always induce a page refresh (this is because the layout of the page must change because the image's effective width and height have changed; so the whole page needs to be layed out again). Some browsers (Netscape) have flaky behaviour with the "Image" setting here.

Turning this option on will enable a set of controls at the bottom of the page that are similar to the editing controls described above, but which apply to a selection of images in the result set, rather than just a single image. When turned on, there will appear immediately under each image a "Select" checkbox, and a set of controls will appear at the bottom of each result page. For more information on selection, see Results/Selection.

Edit Dates
Enabling this option will cause the dates of the images to appear as editable fields, and will enable a date field in the Selection area. This is useful for those circumstances where you forgot to set the date on your camera, so a whole bunch of pictures of Paris came out dated "0000-00-00 00:00:00". You can identify these pictures easily because they show up at the beginning of your date-sorted searches. See Results/Basic Info and Results/Selection (Set Date).

Get Images
Press the "Get Images" button to trigger the search and see the results pages.

Result Pages

The format of the result pages can vary widely based on the selections you made in the Search page. What is described here are all the controls and their behaviour if you left all the controls turned on (as they are by default), along with some explanation of the variations you might see based on different settings in the search page.

The results page is divided into two or three segments stacked on top of eachother. The top segment is a table of images whose properties conform to the results you requested in the Search segment of the Search page. The optional middle segment consists of selection controls. The middle segment will only appear if Selection is turned on in the Editing section of the Search page. The bottom segment consists of navigation links to take you forward or back in the pages of the result set, and to turn the mode from auto to manual and back again.

Image Table

Before the image table, a single line should appear specifying the total number of images in the search, and the set of images being shown. The images and their associated information should be layed out from left to right, top to bottom in the order specified in Result Order. The table of images should conform to the dimensions specified in the Table Width/Height setting. If there are more images in the result set than can fit in the table dimensions, navigation buttons should be enabled at the bottom of the page (see Navigation).

Within each cell of the table will be the image itself, in the size originally requested in the Image Size control on the search page. Then, below or to the right of the image (depending on the setting in Text Location) will appear a column of the text information requested in the Display section of the Search page.

The column of text may contain the following information and controls:

Select Checkbox
When turned on, the imge is considered selected. See Selection for more details.

Size Change Links
These are links that allow you go change the viewing size of the image from thumbnail (160x120) to small (640x480) to large (800x600) to the full size of the image - whatever it's original resolution was. These links only appear if you turned on the Allow Size Change option in the Search page. Using any of these links other than the "Thumb" link will automatically go to a 1x1 viewing area if your image size setting is different from the destination setting. For instance, if you start out viewing thumbnails in a 5x1 grid, and you click on a "small" link, the page generated will be a 1x1 image grid - then if you press "Thumb" again, you'll go back to the 5x1 grid. You can, however, use the navigation buttons in either view to proceed through the image result set. The same settings that were applied to the page you are viewing will be applied to the new page. The "Original" link is different from the others; it opens a browser window containing the original image, without any edits applied. This is often useful if you want to recover a single image for processing for a print-job or anything more sophisticated than the very limited editing capabilities that areaj provides.

Basic Info
This information consists of the original image size, the owning user, the date the image was written, and flags to indicate whether the image is marked for delete or is private. This information will only appear if Show Basic Info is turned on in the Search page. The date will appear as editable if the Edit Dates feature in the search pages has been turned on. This is useful in situations where you want to apply dates to your pictures after the fact, because you accidentally forgot to set the date on your camera, for instance.

If the owner of the image provided an e-mail address in his/her user data, then the owner will be listed as a mailto: link, which users will be able to use to send mail to the owner, presumeably about the images in areaj, and not about the latest stock or penis-enlargement scam. If the owning user does not provide an e-mail address, the user name will not be a link.

If Deletion Marking was turned on in the Search page, then the Yes/No indicator after the "Marked For Delete:" statement is a link that will toggle the "marked for deletion" state of the image. Even if the Deleted Images setting on the Search part of the Search page doesn't agree with the new state of the image, it will remain in the result set until a new search is performed.

If Private Marking was turned on in the Search page, then the Yes/No indicator after the "Marked Private:" statement is a link that will toggle the "private" state of the image. Even if the Private Images setting on the Search part of the Search page doesn't agree with the new state of the image, it will remain in the result set until a new search is performed.

EXIF Information
If Show EXIF was turned on, you'll get a column of photographic information here. Most of this is pretty straightforward, and there are no controls you can operate. The content here varies from camera to camera, and for images that have been post-processed, you probably won't find any information at all (likewise the picture date will probably be missing).

You'll see this section if Show Captions was turned on on the Search page. The captions will be listed in order of date. Each caption is displayed like so: [owner]Date:caption text. In addition, if Edit Captions is turned on, then a link ("d") may appear after each caption that you own that will allow you to delete it if you want. Likewise, if Edit Captions is set, after all the captions are listed, you can fill in a new caption in a field and press the "Add" link, which will create the caption if it is unique and then associate it with the image. If the caption already exists, then the existing one is associated with the image - or to put it another way, the image is added to the set of images associated with that caption. If the checkbox to the left of the caption to add is checked (the default) then the caption will be considered 'indexable', meaning that the User/Caption Tree feature will be aware of it. If it is deselected, it won't appear in the caption lists of the User/Caption Tree. You can either leave this on all the time (which clutters the User/Caption Tree feature) or turn it off for captions that aren't grouping-related - 'Canada', 'Bill Clinton', and 'Burds' are examples of captions that you might want to leave as indexable (since they are likely to apply to multiple images), while 'Opus getting Naked in the Meadow' or 'Look at this thing I ran over on the I5' are probably better off as non-indexable, 'story' captions.

Editing Controls
You'll see this section if Edit Images was turned on. This section consists of five choice boxes - rotate, hue, saturation, brightness, and sharpen. In addition, if Editing Style is set to "Control Per Image", then a "Perform" button will appear underneath the editing buttons.

These controls provide rudimentary editing capabilities - just enough to allow you to tweak digital images on the fly so that they look a little better online. Typically, this involves rotating images that need it, adjusting the brightness of images that might have been underexposed, and then almost always concluding with a sharpen. The editing operations are always done in the order listed, except of course that a resize is done first. This actually doesn't produce the best-quality images - ideally, we should resize as the final step before sharpening. But since most images out of digital cameras these days are really huge, doing things in this manner would burden the server unnecessarily, so currently the resize is done first.

The behaviour of the choice boxes themselves is variable. If Editing Style is set to "Control Per Image" then your changes will only take effect once you press the "Perform" button. If the setting is "Immediate Reaction", then the effect will occur as soon as you release the mouse. The former is probably best for initial uploading and rough-tuning of images, the latter is probably best for experimental tweaking later. In addition, the setting of the Post Edit Refresh choice box will determine wither only the Image is reloaded after edits, or whether the entire page must refresh. The former is more esthetically pleasing, but has some problems on certain browsers; the latter is more sure but requires an ugly refresh after every editing operation. Rotations always cause a refresh, because of the layout change.


The Selection segment is visible if you set Edit Selection on. This area appears as a bordered, divided area directly under your images and their associated text. The selection area provides controls that take effect on all selected images. Important: "All selected images" are not just the images on the Results page you're looking at, but all of the images that you've selected while looking at result pages for this search. That is, if you selected an image on the first page, click the "Next" link, and select something on the second page, the selection contains two images - the one you selected on the first page, and the one you've selected on the second page. The selection isn't wiped out until you start a new search. The selection can be modified by hand by toggling the Select checkbox for any image on the page. Under the "Selection" heading should be a single line informing of the number of images that are selected but not shown on the visible page.

Select All/Select None
These links allow you to change the selection to select all images in the result set, or clear the selection. Selecting all is probably most useful after you've made some complex search and want to caption the results. Selecting none is useful if you're unsure whether you left an image selected on an earlier or later page, and you want to make sure you're not unintentionally editing something.

Mark/Unmark Selected for delete
These links allow you to, in one stroke mark all the selected images for delete, or unmark them. Marking images for deletion doesn't actually delete them. To totally delete images, mark what you want to delete, and then choose the Delete button on the navigation bar. Even then the image can still be recovered from your uploaded archive files if necessary.

Mark/Unmark Selected private
These links allow you to, in one stroke mark all the selected images private, or unmark them. Marking images private merely insures that only you will be able to see them. You probably won't be able to do this to images owned by other people, even it if seems like the interface will let you.

Add Caption To Selected/Delete Caption From Selected
Put a caption in the field, and click "Add Caption To Selected"... the caption entered will be created if necessary, and then associated with the selected images. If the caption already exists, the images will be associated with that caption. Deleting a caption works the same way - if the caption exists and is associated with any of the selected images, it will be dissasociated. If as a result the caption has no images associated with it, it will be deleted.

Set Date
A "Set Date" field will appear after in the selection box under the caption field if "Edit Dates" was enabled in the search page. This field allows you to change the date on all the selected images, using the 'YYYY-MM-DD[ HH:MM:SS]' format. The date set changes only the data in the database, not the EXIF data in the image files on the disk (but the EXIF date is only used initially to set the database date anyway). See Search/EditDates for more information.

The same editing controls that appear for each image are reproduced here, with some differences. First, everything is initially set to "ignore" - this means, that if everything but "sharpen" is set to ignore, and "sharpen" is set to 1, the sharpness of all the selected images will be bumped by one, while leaving their respective other attributes alone. So sharpening the images with this control won't, for example blow away all their rotations, because the operation has been instructed to ignore the rotate property. Similarly, you might use this set of controls by selecting all of the images in a new set that need to be rotated, then select Rotate->90 degrees in the Selection box, click Perform, and in one operation adjust the rotation of all the images that needed it. This option always does a page refresh, because an image refresh would leave the image-editing choices under each image in an innacurate state.

Page-to-page Navigation

When Navigation Style is set to "Manual Slideshow", the navigation bar will consist of six links - Start, Prev, Next, End, Auto, and Generate Bookmark. Start, Prev, Next and End may be disabled if the currently displayed page is at the end or beggining of the result set images. Start and End move you to the beginning and end of the pages in the current result set. Prev and Next move you to the prevous or Next pages.

Clicking on the "Auto" link will change the mode to "auto slideshow", in which the next segment of the result set will be displayed after a preditermined fixed interval without any human intervention. The interval used is set on the search page Auto Interval field, and regardless of that value no value smaller than 5 seconds will be attempted. Once navigation has been set to auto (either initially through the Navigation Style setting, or by hand by pressing the "Auto" link) it will proceed on automatic until the "Manual" link has been executed, which will bring you back to "Manual" mode.

While in "Auto Slideshow" mode, all editing and selection controls will be turned off to keep random disasters from occurring. Note that initial display of individual images during auto mode may take arbitrarily long due to the fact that the image may need to be generated and cached.

The final "Generate Bookmark" link serves a particular need. One of the downsides of frame-based websites like areaj are that frames remove the ability to bookmark content frames - that is, you can bookmark http://areaj.org/areaj, but you can't bookmark a particular search inside of areaj. Well, actually, you can, but you have to generate a special URL using the "Generate Bookmark" button. You may generate a bookmark for any page of any search by using this button. The generated bookmark will appear in a separate browser window for you to cut and paste elsewhere. Note that although you can generate a bookmark for any page of a result set, it may not be wise to do so except for the first page, if the result set is likely to change in the future. For instance, bookmarking the 3rd page of a set that is a result of a search on some 'vacationpics' caption will potentially generate different results if you caption new pictures with 'vacationpics' - or if you change the name of the caption, or delete it. Bookmarks are probably best only when you know you're no longer going to change the set of pictures much - or if you are, best to bookmark the first page only. How to bookmark a single picture? Currently you'd have to uniquely caption that picture, and do a search for it.


The Diary feature provides a simple way of browsing pictures by date. A selectable user list appears at the top, allowing the user to browse all users, or any particular user. Links to move the year of visible calendars forward or back by 3 months are available at the top as well.

The calendars that initially appear depend on a number of things. If you entered a date in the "After Date" field of the search form, the calendars will be centered around that. If you haven't done that, then calendars centered around the current date should appear.

Dates for which pictures exist for the user selected should show up in a highlight color. Clicking on those dates will search for those images. Returning to the search page from those images, you'll find that the search page is set for your convenience to return you to those images. When searching for images from the Diary page, others' private images will not be shown, but if you are logged in, any images that are owned by you and are private will be shown.

User/Caption Tree

The User/Caption Tree feature provides a way of identifying all the captions in the system, by user. The first level of the tree identifies users owning captions, and the second level includes the captions that are owned by the user. The number in parenthesis is the number of images that are captioned with the specified caption. Clicking on the link takes you to search results for that caption. If the number of images in the search results doesn't match the number in the parenthesis, it is probably because some of the captioned images are marked as private, and are owned by another user. Only captions considered 'indexable' are counted by this feature. Non-indexable, so-called 'story' captions don't show up here. See Result/Captions for an explanation of what it means for a caption to be indexed.

Change Password

Any logged-in user may change their password at any time by pressing the "Change Password" button in the navigation bar. If the user is logged in as an administrator, he or she will be able to choose from a list of users which user it is that they wish to change the password for. If the user is an ordinary user, they can only change their own password. To eliminate possible errors, the same password must be entered twice in order to change the password.

Delete Files

Any logged-in user may use this feature to delete the files that they've marked for deletion (see editing). Deletion of marked files, however, means that the files themselves will be removed from disk; all database entries relating to the files (including any caption information solely attached to the marked files) will be removed; and all cached images will be removed. This is a radical, irreversable procedure that should be approached with caution. If disk space is plentiful, you're probably better off just marking your images for delete and making your searches only include images not marked for delete (see searching). That way these images can always be recovered.

Upload Files

Any logged in user may use the upload feature. Uploaded files must either be .tar, .tar.gz, or .zip files. The directory structure of the contents may be totally arbitrary; but currently only .jpg files will be added to the system on upload. The upload form includes four elements - a caption that will be bound to all the uploaded files when they are added to the system, a boolean flag indicating whether all uploaded files should start out marked as private, and the file itself to upload (which may be set by hand or through your web browser's file chooser).

It's a good idea to uniquely caption all uploads so that you can find them afterward. Depending on the date of pictures to find them is not a good idea, as your camera may not have it's internal date set properly, or it may have lost its date due to battery failure. Marking images private is another way to identify them after upload, if you only ever mark them private when you upload, then modify them to your satisfaction, then remove the private markings. This methodology, however, will tend to get confusing if you start keeping images private because you don't want anyone to ever see them (rather than just because you don't want others to see them until they're edited to your satisfaction). My reccomendation: use a caption, you can always remove it later.

Uploaded files are found in the uploads subdirectory of the users' areaj directory (which defaults to AreaJ::Features::areajRoot()/users/). This is worth knowing if you are also an OS user of the system that AreaJ is running on, if you ever want to use the images for other purposes than AreaJ.

After upload, the uploaded archive files are decompressed (the uploaded files can be found in a path something like AreaJ::Features::areajRoot()/<user>/uploads/<timestamp>/<uploadfilename.tar.gz>) into a files subdirectory of the users' areaj directory - something like: AreaJ::Features::areajRoot()/users/<user>/files/<archivename>;/DCIM/100Canon/<DSCN0596.JPG>. Those files are then added to the database, along with the captioning information.

The archive files that you've uploaded are listed by date and time uploaded at the bottom of the window; you can click on the links to download them again if you want - you can also click "Show" to go to a search results page showing just the images in that archive; in addition, you can permanently delete the archive and all the files contained within it, along with all the captions and other information associated with the archive from here.

If you attempt to upload an archive that will cause your total amount of space used to exceed your quota, behaviour will differ depending on the policy of the areaj site. AreaJ sites that enforce strict quotas will reject any upload that exceeds the user's quota amount, while non-strict sites will allow you to exceed your quota on your final upload. Non-strict is nicer to users because it won't waste their time; in order to reject an upload, a strict site actually has to wait until all the data is transferred, which for a large file can take some time.

Manage Users

Without an account, the only features available are those of public search. User accounts need not correspond to actual accounts on the server. Each user account consists of the following information:

Only an administrator can add a user to the system, or change any of the properties of the user (except the password; each user is allowed to change his or her own password).

When adding or enabling a user, the user's username will be randomly generated, and printed out for the administrator to see. You should copy this password somewhere to send to the user as it is the only plaintext record of the password, or you can immediately change the user's password, or eliminate it alltogether by disabling the user when you add them. The user will then not be able to login until their password is changed using the "Change Password" screen - which the administrator will have to do since the user can't login yet. If you're running areaj under https only, this should be relatively secure, though there is always the possibility of someone reading the users initial password over the shoulder of the creator/enabler. As a policy, it's a good idea to have users change their password as soon as possible. If you're not running over https, this potential security hole is probably the least of your worries.

An administrator cannot disable him/herself, or remove his/her own administrator priveledges. This is to ensure that there will always be a valid administrator in the system.

Deleting a user is probably not a great idea - it destroys the user, and deletes all of the users' files, database entries, and uploaded archives. It is almost always a better idea to merely disable the user; that way all of their images and captions remain in the system in case you ever need to recover anything.

The email address associated with a user becomes effectively public - so if you don't want your e-mail address public, leave it blank or use your favorite spam-filtering email address.

Disk quotas can be set here; Use 'NONE' if you want the user to have an unlimited quota.

Miscellaneous Topics

Cache Management
Cached images are kept in AreaJ::Features::areajRoot()/cache. Nothing in this directory is required; at any time you can blow it all away. However. Doing so would make image display very slow, as thumbnails would have to be generated on demand. The ideal caching policy would be to never touch this directory. But, if you have a space crunch, and want to intelligently remove files to get space back without crippling AreaJ, you could consider removing only the files older than a certain number of days. A cron job to do such a thing is trivial to write. You could also consider removing anything that isn't a thumbnail image. This would make it slower to look at small, large, or full-sized edited images. The file names in this cache look like this: 23-t-r90h1f2b3s0.gif or 23-t-.gif, or others. The reliable part of the file is that there will be a number followed by a dash, followed by a character followed by a dash, and that it will end in .gif. The character may be one of t, s, l, f - for thumbnail, small, large, and full. To remove all non-thumbnail cached files, you'd need to remove anything that didn't have 't' as the character following the dash following the number, ending in .gif.


No backup support has been provided yet. What needs to be backed up is the entire areaj database in mysql, and the contents of AreaJ::Features::areajRoot() (excluding AreaJ::Features::areajRoot()/cache). If non-default locations have been used for some users' areaj directories, those would need to be backed up as well.


I tried to take security very seriously when writing this. Here are the high points: Here are the areas you should check before going live:


AreaJ is distributed under the GPL.


AreaJ is written by Thomas K. Burkholder, that's me. You can reach me at burkhold@dogrobber.com. I'd appreciate hearing from you if you use AreaJ, and I welcome any suggestions.


I'd like to thank Markus Gutschke for being tireless and patient in mentoring me with debian technology. Without Markus getting me out of various scrapes, I'd still be trying to get lilo to boot. I'd also like to thank Karl M. Hegbloom for providing me with a patched version of mod_ssl which enabled me to not drive my forehead through my computer screen. Thanks to my friend Mike Gobbi who reviewed it and gave tons of great feedback. And thanks to Richard Williamson for letting me rip off his excellent finishing-touches mat and dropshadow graphics, as well as for hosting the areaj.org server in his basement. And of course, to the thousands of crazed open source coders out there who wrote the vast majority of the software that makes AreaJ work, thanks. All of us are richer for your efforts.