If you are migrating from a previous version of DLXS that used imageprep rather than mediaprep, please read this entire document, especially "Migration," before running mediaprep.
Image Class supports JPEG2000, MrSID, JPEG, GIF, PNG, Flash, MP3, and WAV, and PDF media formats by default. Support for other formats can be added.
Place media files (filenames must be unique within the collection) on production web server following the convention below. The "incoming" directory is optional. If you use the incoming directory, files will automatically be moved out and into a directory named by year and month (YYYYMM). The "incoming" directory is required if adding files incrementally without reprocessing all media files (see next section).
JPEG2000 with thumbnail:
$DLXSDATAROOT/img/c/coll/[incoming]/.../jp2/filename.jp2
$DLXSDATAROOT/img/c/coll/[incoming]/.../thumbjp2/filename.jpg
MrSID with thumbnail:
$DLXSDATAROOT/img/c/coll/[incoming]/.../sid/filename.sid
$DLXSDATAROOT/img/c/coll/[incoming]/.../thumb/filename.jpg
JPEG with thumbnail:
$DLXSDATAROOT/img/c/coll/[incoming]/.../filename.jpg
$DLXSDATAROOT/img/c/coll/[incoming]/.../thumb/filename.jpg
PDF:
$DLXSDATAROOT/img/c/coll/[incoming]/.../filename.pdf
MOV:
$DLXSDATAROOT/img/c/coll/[incoming]/.../filename.mov
RM:
$DLXSDATAROOT/img/c/coll/[incoming]/.../filename.rm
MP3:
$DLXSDATAROOT/img/c/coll/[incoming]/.../filename.mp3
WAV:
$DLXSDATAROOT/img/c/coll/[incoming]/.../filename.wav
Flash:
$DLXSDATAROOT/img/c/coll/[incoming]/.../filename.swf
JPEG, GIF, and PNG formats are supported equally. Anywhere you see ".jpg" above, you can substitute ".gif" or ".png", and in any combination.
Please refer to the Image Class Image File Naming document for the more information about filenaming.
With your media files in place run the mediaprep script like this...
$DLXSROOT/bin/i/image/mediaprep c=[collid]
mediaprep analyzes all media files and registers findings in a DLXS database table called ImageClassMediaFiles. It also creates a directory of symlinks called "index". Together, the table ImageClassMediaFiles and the "index" directory are used in the processes of loading metadata records and providing web access to the images.
mediaprep should be run before the loading of metadata records.
Migration from a previous version of DLXS that did not use mediaprep requires an understanding of the changes that have occurred. Note: DLXS 12a was the last version to use imageprep.
mediaprep differs from the its predecessor imageprep in the following ways:
mediaprep resembles its predecessor imageprep in the following ways:
Fast delivery of thumbnails to the browser requires the thumbnail image files to be under the web server's document root directory. To achieve this, add a symlink named "thumb" in the collection's web directory, and have it point to the "index" directory.
You may have to create a web directory for the collection if one does not already exist.
cd $DLXSROOT/web/c/coll
ln -s $DLXSDATAROOT/img/c/coll/index thumb
Remember, "c/coll" should be replaced with the actual collid and inital letter.
To incrementally add media files without reprocessing the entire set, create an "incoming" directory and place new files in it, then run mediaprep with the "incoming" command line parameter set.
mkdir $DLXSDATAROOT/img/c/coll/incoming.
Place files in incoming (as shown above in Quick Start).
$DLXSROOT/bin/i/image/mediaprep c=collid incoming=1
When mediaprep runs, it creates a directory called "indexprep" and places within it relative symlinks to the thumbnail images. When done creating symlinks, the "indexprep" directory is renamed to "index", automatically. If necessary, an existing "index" directory is first renamed "index-old" and then deleted after everything else is done.
Optionally, mediaprep can create an "indexprep" directory, but refrain from renaming it as "index". Rarely useful, but a handy trick if transitioning from DLXS 12 or 12a to 13 because 13 can use an index directory created by 12a.
e.g.,
$DLXSROOT/bin/i/image/mediaprep c=collid hold=1
mediaprep by default moves old duplicate files to the outgoing directory, creating the directory if necessary. Keeping old files can be useful when migrating to DLXS 13, because it allows for minor differences in the way duplicate files are handled. If mediaprep were allowed to shift duplicates to the outgoing directory, it might cause the index directory created by the older imageprep program to become disconnected with some of the media files.
e.g.,
$DLXSROOT/bin/i/image/mediaprep c=collid keepold=1
mediaprep by default uses the existing rows in the ImageClassMediaFiles table, making relative modifications as necessary. Sometimes it is valuable to purge the existing rows for a collection from the table first. The purge=1 command line option does just that before proceeding with trest of the operation.
The primary advantage of purge is that it gives you a clean slate which is essential when using the sidjp2 equivalency option.
The only real disadvantage to using purge is that none of the images of the collection will not be accessible to users during the run of mediaprep. If the collection is small, this hardly matters. If the collection is large, and it takes a couple of hours for mediaprep to run, then it may be worth considering.
e.g.,
$DLXSROOT/bin/i/image/mediaprep c=collid purge=1
MrSID and JPEG2000 files are fairly interchangeable in Image Class. JPEG2000 has become preferred in recent years, and you may be wanting to replace MrSID files with JPEG2000 (we recommend it, in fact.) If the files are named the same with the exception of the filename extension, mediaprep can replace MrSID files with JPEG2000. The opposite is also true. MrSID files can replace JPEG2000 files. The determining factor is the timestamp of the file. The newest file is always used. The sidjp2=1 command line option requires the purge option be used as well.
e.g.,
$DLXSROOT/bin/i/image/mediaprep c=collid purge=1 sidjp2=1
A collection needs an index directory on every server running the Image Class middleware. Chances are this includes your production server, and your development server (if you have one). The actual media files only need to be on one server, since the Collmgr "mediahost" and "devmediahost" fields can be used to tell Image Class which server to hit for image delivery. Once mediaprep has been run against the media files, generating an index directory on other servers is easy (as long as DLXS is installed).
$DLXSROOT/bin/i/image/mediaprep c=collid indexonly=1 [hold=1]
The index directory is generated by reading rows from the ImageClassMediaFiles table and creating symlinks from the table row information.
It is no longer necessary to manually tar and transfer the index directory to other servers. And it is no longer necessary to have an index directory in machines used only for dataprep as long as the machine is not as an Image Class web server.
Optionally, mediaprep will check the permissions of media files and attempt to set permissions properly for Image Class if necessary. Permissions are not checked by default. Use the checkperms command line parameter to turn this option on.
The following command does the normal mediaprep operation, plus checks file permissions.
$DLXSROOT/bin/i/image/mediaprep c=collid checkperms=1
Image files need to be readable by the web server, which often runs as user "nobody".
Image directories should be 775 and image files should be 664. The "mediaprep" program will attempt to properly set all permissions for all image directories and files. However, if the user excecuting "imageprep" does not have the necessary permissions to change the mode of the directories and files, the "imageprep" program will not be successful in its attempt, and will generate a message reporting this is the case.
Alternatively, the chmod command can be used to set permissions. There are ways to modify files in batch with UNIX commands, but this topic is beyond the scope of this document.
chmod 775 $DLXSDATAROOT/img/m/musart/sid
chmod 664 abc.sid
Please refer to the Image Class Image File Naming document for the details.
It is best/easiest if filenames are unique within a collection. If they are not, the subdirectory path can be used to force uniqueness. To enable this function, edit the file at $DLXSROOT/bin/i/image/localimageprep.cfg to add the following code to the "COLL SPECIFIC OVERRIDES/ADDITIONS" section
if ($coll eq 'collid')
{
$gLoadedName = 'loaded';
}
Be sure to replace "collid" with the collection's ID!
Use of "loaded" requires that filenames in the data records also be a concatenation of the filename with the parent directory path. After running mediaprep look within the $DLXSDATAROOT/img/c/coll/index directory at the names of the .inf files. The media filename should be the same as the .inf file, except with the .inf exetension changed to the appropriate media file extension.
Media files must be stored using the following collection level directory convention:
For example, the unique collid for the collection "French Architecture" is "sampleic", in which case the image file directory is...
$DLXSDATAROOT/img/s/sampleic
The software assumes that every image has a thumbnail image and a larger display image. It is not a requirement, and a thumbnail is not expected for media types other than still images.
Within the collection directory, images should be stored in the following locations.
To clarify with an example, the Image Class middleware assumes that all JPEG files in directories named "thumbjp2" and within the $DLXSDATAROOT/img/c/collid structure are thumbnails to be displayed in association with JPEG2000 images (stored in "jp2" directories. All JPEG images not in thumb directories are assumed to be single resolution images for large display.
Example:
The "sampleic" collection can again be used as a simple example. $DLXSDATAROOT/img/s/sampleic has the following directories...
drwxrwxr-x 4 jweise dlps 512 Feb 15 14:37 index
drwxrwxr-x 2 jweise dlps 2048 Feb 15 13:30 sid
drwxrwxr-x 2 jweise dlps 2048 Jun 8 1998 thumb
$DLXSDATAROOT/img/s/sampleic/sid contains all of the SID format, multiple resolution, files for the collection.
$DLXSDATAROOT/img/s/sampleic/thumb contains all of the JPEG format, thumbnail size, files for the collection.
The sampleic collection does not have any large JPEG files since it relies on SID files for large display.
The flexibility of structure within the collection specific image directory is intentional and supports the variety of directory structures that are typically encountered.
For example, at Michigan, we find it useful to load the image files on the production server in a structure that reflects the CD that the master image files are stored on. A single collection can easily have dozens of CDs worth of master image data (typically TIFF format files). In the process of generating SID and JPEG files, we maintain at least the name of the CD in the name of the directory that the SID and JPEG images are kept in.
...
CD0005
Image directories (that are loaded to the production server in the $DLXSDATAROOT/img/c/collid directory)
thumb
...
CD0005
thumb
It is fine for the images to be loaded in this type of hierarchical structure. When the "mediaprep" program creates the index directory, it recursively parses directories to find all media files.
You may find that media files loaded to Image Class for various reasons get loaded more than once over time. For example, maybe the JPEG2000 files need to be regenerated at a higher quality and reloaded. Whatever the reason, mediaprep helps to manage the reload process by moving the files being replaced to a directory called "outgoing" located at...
$DLXSDATAROOT/img/c/collid/outgoing
mediaprep checks filenames for duplicates and in the case of duplicates keeps the newest file and moves older copies to outgoing. Optionally, you can tell it not to move files to outgoing with the keepold=1 command line option, in which case the newest file will still be used, but the others will be left alone.
When moving files to outgoing, mediaprep also tries to move corresponding thumbnail images and text files. It is generally successful at this.
Another option, sidjp2=1 causes JPEG2000 and MrSID files to be treated equally in terms of replacement. That is, a JPEG2000 can cause a MrSID file to be pushed to the "outgoing" directory, and vice versa! The file with the newest timestamp wins, as always. This is a useful feature if replacing all MrSID files with JPEG2000 files as we are at Michgian, but it could also be used if going the other direction (replacing all JPEG2000s with MrSIDs). It is important to realize that the sidjp2 option must be used in conjunction with the purge option otherwise comparison of MrSIDs to JPEG2000s could not be done accurately because there might be multiple rows already in the database table.
Files inadvertantly moved to outgoing by mediaprep may be moved back to their original location, though think carefully about what the implications might be before doing so. The process involves tarring up the relevant directories in outgoing and untarring them at the root of the old location. Proceed with caution.
Image Class can be configured to support a wide variety of directory and filenaming conventions. This configuration is done in the $DLXSROOT/bin/i/image/localimageprep.cfg file. Copy the %gTypeHash, and @gTypeComarisonOrder definitions from imageprep.cfg to localimageprep.cfg and modify it to support local conventions
It is even possible to add support for multiple image sizes for a single image in a non-MrSID format such as JPEG. That is, you could have small, medium, and large JPEG images for a single item and have them all be available to the user in the interface. Michigan has done this for the APIS (Papyrus) collection where there is a mix of MrSID and JPEGs at multiple sizes (Though the examples are few and far between. In fact I can't find one at the moment.) Zooming is not possible without MrSID, but the user may select from the multiple sizes.
Below is the %gTypeHash Michigan added to localimageprep.cfg to handle the APIS collection. The hash holds for each type of image an array of regular expressions used to match image files. For APIS, thumbnail images must either be JPEG files in a "thumb" directory or GIF files with "-tn" preceding the extension. SID images are also allowed and can reside anywhere. JPEGs that aren't thumbnails are assumed to be large image files and are given the label "1200", which is a somewhat arbitrary estimation of the maximum pixel dimension of the file. JPEGs with "-50" preceding the extension are labelled as large JPEGs with maximum pixel dimensions of 600. It does not matter too much what the labels are as long as they cause the images to sort properly by size in the user interface.
The @gTypeComparison order array is important because it specifies an order of precedence for identifying images. In this case "thumb" is checked first, and if the filename matches one of the "thumb" regular expressions, it is not tested against the other types (i.e,. sid, 600, 1200).
if ($coll eq 'apis')
{
%gTypeHash =
(
'image:::dynamic:-:thumb' => [
'/thumb/([^/]+)\\.(jpg)',
'/thumb/([^/]+)\\.(JPG)',
],
'image:::fixed:-:thumb' => [
'/([^/]+)-tn\\.(gif)',
'/([^/]+)-tn\\.(GIF)',
],
'image:::dynamic:-:sid' => ['/([^/]+)\\.(sid)', '/([^/]+)\\.(SID)'],
'image:::fixed:-:600' => ['/([^/]+)-50\\.(jpg)', '/([^/]+)-50\\.(JPG)'],
'image:::fixed:-:1200' => ['/([^/]+)\\.(jpg)', '/([^/]+)\\.(JPG)'],
);
@gTypeComparisonOrder = ('image:::dynamic:-:thumb','image:::fixed:-:thumb', '
image:::fixed:-:600','image:::fixed:-:1200','image:::dynamic:-:sid');
}