PhotoArch mini-HOWTO Ilia Baldine ibaldin@anr.mcnc.org v 0.2, 1 February 2002 This document describes how to setup and use PhotoArch - a PHP photo archival system ______________________________________________________________________ Table of Contents 1. Copyright 2. License 3. Disclaimer 4. What is PhotoArch? 5. Prerequisites 6. Installation and configuration 6.1 Installing PhotoArch 6.2 Configuring PHP 6.3 Configuring MySQL 6.4 Configuring PhotoArch 6.4.1 Database 6.4.2 EXIF 6.4.3 Appearance 6.4.4 FileSystem 6.4.5 Miscellaneous 6.5 Security 6.6 Upgrading from the previous version 7. How it all works 7.1 Overview 7.2 Adding a new volume to the database 7.3 Volume structure 7.4 Correlating film media to digital images 7.5 Batch processing 7.6 Viewing images 7.7 Albums and Users 7.8 Searching and Browsing 7.9 Database manipulation 8. Further Extensions 9. Acknowledgements 10. Resources ______________________________________________________________________ 11.. CCooppyyrriigghhtt Copyright 2001(c) by Ilia Baldine. This document may be distributed only subject to the terms and conditions set forth in the GPL License at, except that this document must not be distributed in modified form without the author's consent. 22.. LLiicceennssee PhotoArch is provided under the GPL open-source license: Copyright (C) 2001 Ilia Baldine This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 33.. DDiissccllaaiimmeerr +o This program is provided as-is with no implied or explicit warranty. In all likelihood, running this program on a computer will very likely cause earthquakes, severe floods, droughts or any number of other major natural or man-made disasters in combination or one at a time. Irretrievable loss of invaluable data is par for the course. +o Not a single Microsoft product was harmed in the process of design and implementation of this program 44.. WWhhaatt iiss PPhhoottooAArrcchh?? PhotoArch is a photographic storage and retrieval system. It is written mostly in PHP (PHP3 or PHP4 compatible) with a bit of JavaScript thrown in for good measure.You might say - "'...photographic storage and retrieval system': that's just a fancy name for a web photoalbum" and we all know there's plenty of those around. So how is PhotoArch different? In a number of ways actually: PPhhoottooAArrcchh ccaann iinnddeexx mmoouunnttaabbllee vvoolluummeess ccoonnttaaiinniinngg ddiiggiittiizzeedd ppiicc-- ttuurreess:: if you want to store high-quality digitized pictures on a bunch of CD-s and need a way to track them - PhotoArch is for you PPhhoottooAArrcchh ccaann hheellpp yyoouu kkeeeepp ttrraacckk ooff tthhee oorriiggiinnaall ffiillmm mmeeddiiaa:: if you are old-fashioned, like myself, and have a lot of older pictures on slides or prints, with stored negatives, PhotoArch is for you PPhhoottooAArrcchh pprroovviiddeess yyoouu wwiitthh aa ggrraapphhiiccaall ffrroonntt--eenndd ttoo tthhee ddaattaabbaassee:: you can modify any part of your database at any time by simply using your web browser. PhotoArch can also serve as a web photoalbum. To that end it provides the following capabilities: KKeeyywwoorrdd sseeaarrcchhiinngg ffoorr pphhoottooggrraapphhss:: each photograph has meta data associated with it: location, people, comments, date etc. The database can be searched by any combination of these parameters AAllbbuumm bbrroowwssiinngg:: instead of searching you can choose to browse individual albums AAllbbuumm ppeerrmmiissssiioonnss:: each album can be either open to the public, a limited set of users who must be authenticated prior to viewing them or, finally, only to the database administrator Other miscellaneous features include: SSuuppppoorrtt ffoorr EEXXIIFF iinn iimmaaggeess:: EXIF data of your choosing is stored along with images (yes, you can customize the set of EXIF tags that is gathered) DDyynnaammiicc rreessiizziinngg ooff iimmaaggeess oonn--ddeemmaanndd:: for your low-bandwidth friends, PhotoArch offers the ability to dynamically resize (shrink) the original high-res images before sending them on the wire BBaattcchh pprroocceessssiinngg ooff nneeww iimmaaggeess:: in addition to being able to add each volume of images interactively, PhotoArch allows you to add each volume as a single batch operation, giving you an option to put all images in a given volume into a specific album. New in version 1.0: FFrreeee--ssttrruuccttuurreedd vvoolluummeess:: gone are the days when you were forced to structure each volume by film directories. Now a volume can have any directory structure of arbitrary depth and complexity: from the simple single directory to a complex arrangement of directories only you can figure out. Arrangement of image files by film, as present in the previous versions of PhotoArch is still possible, but is no longer a requirement. BBaattcchh pprroocceessssiinngg:: interactive addition of volume content (images) to the database is no longer the only choice - you can also add the entire volume in batch mode. You can specify the default album the volume contents will belong to, sit back and relax. The following sections will describe how to install and use PhotoArch. 55.. PPrreerreeqquuiissiitteess Prerequisites to running PhotoArch include: +o Having shell access to a *NIX box running Apache +o Having access to a MySQL database server (can be Co-located with Apache, but does not have to) +o The box with Apache must have a reasonably recent version of ImageMagick installed +o Perl with Image::Info module is needed if you wish to get EXIF capability This code was developed under the following configuration: +o Linux 2.4.4 +o Apache 1.3.19 with PHP4 +o MySQL server 3.23.37 +o ImageMagick 5.3.1 +o Perl 5.6 with Image::Info module Useful URLs are: +o http://www.apache.org +o http://www.mysql.com +o http://www.imagemagick.org +o http://www.cpan.org 66.. IInnssttaallllaattiioonn aanndd ccoonnffiigguurraattiioonn 66..11.. IInnssttaalllliinngg PPhhoottooAArrcchh Presumably, first you acquire the code to PhotoArch from http://photoarch.sourcefource.org . You must now pick a location in your filesystem, where you want PhotoArch to reside. The installation process simply consists of uncompressing the archive in the right place and telling Apache (if you want to have a http://www.domain.com/photoarch type URL) where to find it. Alternatively, you can just put it wherever Apache can get to it (your /public_html directory, for instance) and run it from there. For the former case you must insert the following directive in your httpd.conf file: +o Alias /photoarch/ "/wherever/you/happen/to/uncompress/PhotoArch/archive/into" Remember, that if you are putting PhotoArch in a location that is not described in one of Apache's add such a tag. Also, for convenience, you may link photoarch.php3 file in the distribution to an index.php3 (make sure your Apache configuration includes using index.php3 along with index.html for default directory index) 66..22.. CCoonnffiigguurriinngg PPHHPP Depending on the distribution and the flavor of your *NIX box, you may need to finesse your PHP configuration prior to using PhotoArch. This configuration is contained in php.ini (/etc/php.ini or /usr/local/etc/php.ini or some other conspicuous place) file. The thing to check in it is the _s_a_f_e___m_o_d_e directive. If it is turned _O_n, you have two choices: 1. Turn it to _O_f_f and wallow in the sense of insecurity this gives you. (PhotoArch, however, will work just fine) 2. Leave in on and adjust the _s_a_f_e___m_o_d_e___e_x_e_c___d_i_r directive so that it matches the location of ImageMagick executables ('convert' and 'identify'). It is usually either /usr/bin or /usr/X11R6/bin. 3. If you plan to use EXIF features and _s_a_f_e___m_o_d_e is left _O_n, copy the 'exifextr' script from the distribution's scripts/ directory to the same directory where 'convert' and 'identify' are. If, however, the _s_a_f_e___m_o_d_e directive is _O_f_f you can probably leave it as is, or else do as the above paragraph describes. After all modifications to httpd.conf and php.ini are completed, you can restart your webserver and test the installation. _N_o_t_e_: if you do not have the authority or the skill to modify the installation configuration, do not dispair: in all likelihood everything will work just fine. You may need to ask your system administrator what _s_a_f_e___m_o_d_e for PHP is set to and modify the _s_a_f_e___m_o_d_e___e_x_e_c___d_i_r. Placing PhotoArch source into your user home directory under html/ or public_html/ will make it perfectly usable, albeit the URL to get to it will look a bit ugly (something like http://www.domain.com/ /photoarch/). One more fact to keep in mind: you _m_u_s_t change the ownership of the PhotoArch php scripts to be the same as the webserver (user www or wwwrun or httpd) when using PHP _s_a_f_e___m_o_d_e. 66..33.. CCoonnffiigguurriinngg MMyySSQQLL PhotoArch uses MySQL as its back-end database. The scripts to create users and tables in your MySQL database are provided: 1. createusers.sql to create database users. 2. createtables.sql to create the database and the tables it it. You may wish to modify the createusers.sql file to change the default access password to the photoarch database. This script creates two users: 1. photoarch - the user that has only read permissions to the database 2. photoarchadmin - the user that has modify permissions to the database You may need to run one or both of these scripts depending on your situation: +o If you are running your own MySQL server, you will have to run first createusers.sql, then createtables.sql +o If you are using someone else's server, you will have to ask them to create the users and the database for you. You can simply send them the createusers.sql script and they will be able to run it for you. Prior to running this script however, you must edit it and replace all occurences of "mypassword" with the password of your choosing - this will be the password you use to modify your database. Once ready, you can run it as follows: $ > mysql -u root -p < createusers.sql Note that you must use the database root password when prompted. If no errors are reported, you may run the second script as follows: $ > mysql -u photoarchadmin -p < createtables.sql Note that you must use the password that you chose for your database when prompted. 66..44.. CCoonnffiigguurriinngg PPhhoottooAArrcchh The behavior of PhotoArch and the look and feel of it are defined by the _c_o_n_f_i_g_._p_h_p_3 file found with the distributions. Future versions will utilize CSS (Cascading Style Sheets) for ease of customization of the look. Open the configuration file config.php3 with one of your favorite editors and lets look at it closer. Skip down to the line that says: if (!defined("CONFIG_INC")) { define (CONFIG_INC, true); 66..44..11.. DDaattaabbaassee The first block of definitions has to do with the database configuration - which host it resides on. They are pretty self- explanatory. If you database server and the webserver are co-located, you can put DEFAULT_MYSQHOST as "localhost". Unless you modified the default database and usernames in the createusers.sql script, the other three options should remain the same. 66..44..22.. EEXXIIFF Next block of definitions has to do with EXIF functionality. If you don't know what it is, or don't need it - simply set USE_EXIF to "no". It is only useful to you if you have a digital camera that is capable of producing JPEG images of EXIF variety (with embedded meta-data like date, time, focus mode etc.). If you decide you do want to utilize EXIF, make sure that perl is installed on the host and Image::Info module is available to it. Easy way to test it is to run the _e_x_i_f_d_u_m_p script in the php/scripts directory and give it a name of one of the JPEG images from your camera as a command-line parameter. If you see a bunch of data being extracted - you are in good shape. Installation of PERL and its modules is outside of the scope of this document. See the installation chapter for useful URLs to visit for help. Remember, if you are running PHP in safe mode, move _e_x_i_f_e_x_t_r script to the same directory where _c_o_n_v_e_r_t and _i_d_e_n_t_i_f_y reside and change the EXIF_SCRIPT variable in config.php3 appropriately. PhotoArch provides you with opportunity to pick and choose which EXIF options you want to extract and store. As mentioned above, you should run _e_x_i_f_d_u_m_p on one of your images and see what types of EXIF data are available. Next step is to pick the ones that are of interest to you and add them to the _s_p_a_c_e separated array called _E_x_i_f_O_p_t_s. They must be spelled exactly the way they appear in the exifdump output. 66..44..33.. AAppppeeaarraannccee The next several options govern the appearance of PhotoArch: BBGGCCOOLLOORR - background color of every page TTEEXXTT - text color LLIINNKK - hyperlink color VVLLIINNKK - visited link color AALLIINNKK - depressed link color TTHHUUMMBBSSIIZZEE - size of generated thumbnail images in pixels (thumbnail fits into SIZExSIZE square) SSAAMMPPLLEESSIIZZEE - size of generated loq-quality sample images (stored in the database) TTHHUUMMBBQQUUAALL - JPEG quality parameter for thumbnails. The higher the quality, the larger the image SSAAMMPPLLEEQQUUAALL - JPEG quality parameter for sample images. Sample images are the ones that you see by clicking on a thumbnail (search or browse mode). They are also the only large images that unauthenticated users are allowed to see. I would not advise to put it above 50 unless you have oodles of free disk space and bandwidth. TTHHUUMMBBSSPPEERRPPAAGGEE - number of images displayed per page in "Add Volume" and "Search" modes. TTHHUUMMBBRROOWWSS - number of rows of thumbnails displayed in "Browse" mode. TTHHUUMMBBCCOOLLSS - number of columns of thumbnails displayed in "Browse" mode. SSLLIIDDEEFFAACCTTOORR - in "Search" and "Browse" modes the thumbnails are displayed inside a dark frame, so they appear like mounted positives (purely for aesthetic purposes). This determines the ratio of the frame size to the thumbnail size. 66..44..44.. FFiilleeSSyysstteemm CCOONNVVEERRTT__EEXXEECC - location of ImageMagick "convert" executable (if PHP is in safe mode, make sure the directory where it is located is on the safe list) IIDDEENNTTIIFFYY__EEXXEECC - location of ImageMagick "identify" executable (if PHP is in safe mode, make sure the directory where it is located is on the safe list) TTMMPPDDIIRR - location for temporary file storage CCDDMMOOUUNNTT - mount point of the CDROM drive JJAAZZZZMMOOUUNNTT - mount point of a JAZZ drive ZZIIPPMMOOUUNNTT - mount point of a ZIP drive OOTTHHEERRMMOOUUNNTT - mount point for some other mountable device 66..44..55.. MMiisscceellllaanneeoouuss The final adjustable parameters must be changed with caution: their modification must be accompanied by a matching modification of the _c_r_e_a_t_e_t_a_b_l_e_s_._s_q_l file, because they have to do with the database structure. FFiillmmTTyyppeess - supported film media types VVoolluummeeTTyyppeess - supported volume types FFiilleeFFoorrmmaattss - supported graphic file formats/MIME types No other parameters should be modified in config.php3. 66..55.. SSeeccuurriittyy PhotoArch uses MD5 hashes for passwords, this way they are not stored in cleartext for everyone to see. For improved security you may want to choose to run PhotoArch over SSL, if your capabilities allow. This will prevent anyone from sniffing out your administrative password, which is the main thing you need to protect. To that end it is advisable to create a file named _._h_t_a_c_c_e_s_s in the sql/ directory with the following contents: Order allow,deny Deny from all This will prevent enterprising miscreants from directly looking up the password from the SQL scripts. 66..66.. UUppggrraaddiinngg ffrroomm tthhee pprreevviioouuss vveerrssiioonn Mainly you should go over the new config.php3 and restore your settings. Its is a good idea to save your old config.php3 and the compare the two. Starting with ver 1.0 more features have been introduced, so most likely you will not be able to reuse your old config.php3, but they are similar enough so you will have a pretty good idea of what to set things to. If you used a pre-ver 1.0 PhotoArch (and thank you, by the way), you will need to update tables in your MySQL database. Your existing data will not be disturbed, nor will it affect how your old pics are displayed. It will simply offer you more options with your new pics. Use upgradetables.sql script in sql/ directory: $ > mysql -u photoarchadmin -p < upgradetables.sql 77.. HHooww iitt aallll wwoorrkkss 77..11.. OOvveerrvviieeww PhotoArch is built on a slightly different premise than most web photoalbums out there. Its main goal is in assisting the user in keeping track of his/her photography database stored on mountable volumes (CDROMs or other). Logically the data is represented as follows: images belong to FFiillmmss - each image comes from a negative of some film, which can be referenced. This association is optional. If you don't want to track your pictures by film, you don't have to. VVoolluummeess - images are stored on digital volumes, which can be directories on your filesystem or mountable digital volumes (CD-ROMs, JAZZ or ZIP disks, etc) AAllbbuummss - images belong to albums which are logical arrangements of images. What is actually stored in the database, is information about each image, film, volume and album. It is then cross-referenced to make searches possible. 77..22.. AAddddiinngg aa nneeww vvoolluummee ttoo tthhee ddaattaabbaassee +o Place image files which will constitute a new volume in a directory readable by the host on which the webserver is running. This is a very important point: if you are administering PhotoArch from one host and the webserver is located on another, the files must be present in the filesystem of the host, on which the webserver is running. PhotoArch currently has no way to retrieve images from your local filesystem through your browser and deliver them remotely to the host where the server is running. +o Once the images are placed on the server host, you use "Modify/Add volume" operation to add a new volume. Specify the volume directory, which is the top-level directory that contains the images. If used in interactive mode, you are given the opportunity to fill in information associated with each image (it can also be filled in later). In batch mode the entire volume will be processed silently. +o For each image the database remembers which volume and, optionally, the film number the image came from, so if you need the high- resolution version of it, it will either ask you to mount a particular volume, or will tell you the number of the film it came from, depending on whether you need the digitized version of the image or the original. +o Finally you can assign each image to an album, which must be created first. Images that are unassigned belong to an "Unfiled" album, which is always present in the database (other albums can be deleted). This album is also only viewable by the database owner. When adding a new volume, you can specify the default album name you want all the images in this volume to belong to. 77..33.. VVoolluummee ssttrruuccttuurree Unless you are planning to track images by film (in which case you need to read the section entitled 'Correlating film media to digital images'), a volume can have any directory structure you want - it can be completely flat, with all images placed immediately under the volume top directory, or it can have a complex directory structure and depth of your choosing. PhotoArch will index all image files and skip non-image files in the volume. 77..44.. CCoorrrreellaattiinngg ffiillmm mmeeddiiaa ttoo ddiiggiittaall iimmaaggeess For those of us who are not blessed with a digital camera, or for some other reason stubbornly insist on using film, PhotoArch offers a unique ability of keeping track of which digital image belongs to which film, allowing you to quickly locate the negatives based on your search in the digital library of PhotoArch. This requires a special arrangement of files on your digital volumes, to help PhotoArch figure out which images belong to which films. If you plan not to use this feature, you can go ahead and skip this section. You will still be able to correllate images and the digital volumes they came from. When adding a volume of scanned images which you want to track together with the films they came from, some additional steps are required, as compared to adding a volume of digital pictures which require no correlation to the negatives they came from. In this case, when adding new images to the database the volume must be structured as follows: +o You enter information about individual films that you want to add to the database (Modify/Add film). The database issues unique numeric identifiers to each film, so you can later locate them. +o You scan images from these films and put them on a digital volume (can be directory or a burned CD-ROM). The structure of such volume must be as follows: volume_top/ volume_top/film#/ volume_top/film##/ volume_top/film###/ where #, ## and ### are the film numbers that the database issued to you through the "Add film" operation and volume_top is most likely /mnt/cdrom or /cdrom. The image files for each film are stored in the corresponding film# directory. The rest of actions are identical with adding an unstructured volume. One note is that on the same volume you can have directories which are named film## and others that are not. Images in directories named film## will be correllated with film## for future reference. Images in directories named something else will have a film number 0 assigned to them. This film number is reserved, it cannot be deleted, unlike all others. 77..55.. BBaattcchh pprroocceessssiinngg New feature in ver 1.0 is the ability to add images in a volume in batches, by skipping the interactive add, in which you tediously enter information for each image. In batch mode you can simply point PhotoArch to a volume directory and click 'SUBMIT' and it will add images under that volume. A convenient feature for batch processing is the 'Default Album' option in 'Modify/Add digital volume'. Selecting a particular album will put all images in the new volume into this album. This feature also works with interactive mode. 77..66.. VViieewwiinngg iimmaaggeess After you entered images into the database in this manner, they are available for searching and browsing. When a particular image is found, you can readily view the +o Thumbnail +o Sample low-quality image (by clicking on the thumbnail) +o Meta data (location, people, comments, date, EXIF etc) +o Which volume and film the image belongs to Additionally, if you wish to view the high-quality version of the image, PhotoArch will attempt to display it off the filesystem. If the image was on a mountable volume, it will request that you mount the volume first. As explained below, only the administrator and authenticated users are allowed to see the high-resolution images. Unauthenticated users will have to contend with low-quality jpegs stored in the database. 77..77.. AAllbbuummss aanndd UUsseerrss The easiest way to search and browse a photo database is by albums. PhotoArch presents extensive features to allow you to do that. Additionally it gives you as the database administrator the ability to select who can view a particular album. This latter feature is achieved through the following: Each album can have the following permissions: PPuubblliicc - album is viewable by anyone PPrriivvaattee wwiitthh aauutthhoorriizzeess uusseerrss - album is only viewable by certain users, whom you create accounts for with password protection TToottaallllyy pprriivvaattee - album is only viewable by the database owner Each private album can have up to 3 different users who are authorized to view it (not counting the administrator). When using PhotoArch each user possesses a status, which can be: AAddmmiinniissttrraattoorr - can modify anything in the database. Can view the complete contents of the database. AAuutthheennttiiccaatteedd uusseerr - user which supplied a correct password to his/her username. Can view albums that were administratively allowed to him by the administrator and all public albums. UUnnaauutthheennttiiccaatteedd uusseerr - can only view public albums and only the low-quality sample images. How low a quality is adjusted through the configuration file. In addition, authenticated users are allowed to view the high- resolution versions of each picture, while unauthenticated users can only view the low-quality samples stored in the database. This is done to save bandwith and compute resources on the server. Additionally, PhotoArch offers dynamic resizing capabilities for high-res images, which can be draining on the server if a large number of users attempt to view the collection. 77..88.. SSeeaarrcchhiinngg aanndd BBrroowwssiinngg PhotoArch gives you the ability to do targeted searches as well as simply browse the database. Searches can be done by any combination of metadata associated with each image: keywords, dates, association with a specific album, film or volume. All search criteria are logically 'AND'ed to produce the final search query. Browsing on the other hand simply allows you to look through an album sequentially. Access permissions are always in effect while searching or browsing. Depending on your status, you are allowed to search through or browse only the albums that the administrator wants you to browse. 77..99.. DDaattaabbaassee mmaanniippuullaattiioonn All database functions have a front end in PhotoArch. Users can be assigned to albums at any time and user permissions can be removed from an album at any time by the database owner. You, as the owner, can create and delete users at will. You can add and delete films, volumes and albums. Keep in mind however, that _d_e_l_e_t_i_n_g _a _v_o_l_u_m_e _o_r _a _f_i_l_m _a_l_s_o _d_e_l_e_t_e_s _a_l_l _i_m_a_g_e_s _a_s_s_o_c_i_a_t_e_d _w_i_t_h _t_h_e_m. Deleting an album puts all images from that album into the Unfiled album. (Unfiled is a special private album which cannot be deleted or modified) 88.. FFuurrtthheerr EExxtteennssiioonnss Things I would like to see done: +o CSS support for look-and-feel customization 99.. AAcckknnoowwlleeddggeemmeennttss This software contains code written by others: +o CDir class written by Hannes Dorn hannes.dorn@ibit.at +o Adding new film speeds implemented by Sunil William Savkar savkar@inthespace.com 1100.. RReessoouurrcceess Most of the resources for PhotoArch can be located through SourceForge: http://www.sourceforge.net or directly at http://photoarch.sourceforge.net Enjoy!