The WWWthumb Utility
WWWthumb is a utility designed to create descriptive thumbnails (small GIF files that represent the contents of a file). More importantly, WWWthumb will deliver these thumbnails over the WWW. WWWthumb can be run as a CGI-BIN script, as an addon for the SRE-http web server, or directly from an OS/2 command prompt.
When offering a list of files for downloading over the WWW, it's often convenient to graphically illustrate the contents of the file by displaying a thumbnail (a small GIF image) adjacent to the file name. For example, thumbnails are often minatures of larger graphics files; or, they can also be the desktop icon associated with a non-graphics file.
WWWthumb is designed to create, and deliver, these thumbnails. It's main advantage is ease of use; it's trivial to request a thumbnail image by inclusion of simple IMG elements in one's HTML documents.
WWWthumb can be run in several manners:
- As an addon for the SRE-http web server. WWWthumb is optimized for SRE-http - you'll get the fastest and most convenient performance when you run WWWthumb as an SRE-http addon. Of course, this does require that you use SRE-http as your web-server,
- As a CGI-BIN script on an CGI-BIN compliant OS/2 Web Server. This need not be (though it can be) SRE-http - any OS/2 web server that understands CGI-BIN should be able to host WWWthumb. Unfortunately, the inherent limitiations of CGI-BIN limit the functionality of WWWthumb. In particular, you can not create thumbnails via a CGI-BIN script.
- In standalone mode from an OS/2 prompt. This requires no server, you don't even have to be connected to the Internet. Standalone mode is best used to create thumbnails, for later distribution by an instance of WWWthumb being run as a CGI-BIN script (or an SRE-http addon).
WWWthumb is designed to work with the PMVIEW make a thumbnail option. PMVIEW, a powerful OS/2 graphics utility, will automatically create thumbnails for a wide variety of graphics files (and store them in the files' extended attributes). WWWthumb knows how to use these thumbnails (it extracts them from extended attributes). In fact, any ICON stored in the extended attributes can be used by WWWthumb as a thumbnail.
In addition to this use of PMVIEW thumbnails, WWWthumb can also create thumbnails from .GIF files.
Lastly, WWWthumb has a few special features, such as the ability to write the file dimensions on the bottom of the thumbnail (for .GIF and several other types of graphics files).
If you are using the SRE-http web server, then you may want to consider ThumbIndex Provides a streamlined and easy to use means of creating web accessible indices to directories of image files. It has some useful features not found in WWWThumb.
The installation of WWWthumb depends on whether you are running WWWthumb as a CGI-BIN script, or as an addon for SRE-http.
I) Installing WWWthumb as a SRE-http addon
- Unzip WWWthumb.ZIP to an empty temporary directory.
- Run INSTALL from an OS/2 command prompt (in this temporary directory)
- Note: to remotely create thumbnails (using ThumbSRE.HTM), the client must have either a SUPERUSER or a THUMBNAIL privilege.
As an alternative, those who like to do things by hand can follow (with suitable modifications) the instructions in part II below.
II) Installing WWWthumb as a CGI-BIN script
- Unzip WWWthumb.ZIP to an empty temporary directory.
- Copy GIFWRITE.DLL and RXGDUTIL.DLL to a directory in your LIBPATH.
For example, C:\OS2\DLL (assuming OS/2 is installed on C:).
- Copy EA2GIF.EXE to a directory in your PATH.
- Create a thumbnails "cache" directory in a web accessible place (let's call this your thumbnail_dir directory.)
For example, if D:\WWW is the root of your web tree, you could create D:\WWW\THUMCASH; the contents of which would be WWW accessible through the use of "selectors" that start with /THUMCASH/
SRE-http users: On SRE-http servers, you can place this thumbnail_dir cache directory under the GoServe data directory, or in an SRE-http virtual directory.
- Copy ThumbCGI.HTM (the CGI-BIN version) or ThumbSRE.HTM (the SRE-http version) to one of your web directories. You might also want to copy WWWthumb.HTM (the WWWthumb manual) to this directory.
ThumbCGI.HTM (and ThumbSRE.HTM) provide a handy front-end to the WWWthumb utility; you may find them useful templates, and modify them to suit your own needs.
Caution: We advise not copying either of these files to the thumbnail_dir directory you created in step 4 (the thumbnail_dir directory is meant to hold semi-permanent thumbnail files, and you may from time-to-time delete it's contents).
- Copy WWWthumb.CMD to your CGI-BIN scripts directory.
- Copy the six .GIF files to a "web accessible" directory, preferably one that contains various image files (let's call this the IMG_DIR directory.)
SRE-http users: Since these files should already be in the IMGS directory created when you installed SRE-http, you can probably skip this step.
- Edit WWWthumb.CMD and set a few parameters.
In particular, you must specify the THUMBNAIL_DIR parameter, and you should specify the IMG_DIR parameter.For a description of these parameters, see the Parameters section below.
You are now ready create some thumbnails!
- EA2GIF.EXE and GIFWRITE.DLL are courtesy of Peter Nielsen (firstname.lastname@example.org)
- RXGDUTIL.DLL is courtesy of Andy Wysocki (http://www.bearsoft.com/abs/rexxgd.html)
- Several "dimension" lookup procedures are courtesy of the GRFXREXX package (available at http://hobbes.nmsu.edu ); they were written by Rapha‰l Vanney (email@example.com).
- When run as an SRE-http addon, several REXXLIB procedures are used. However, when run as a CGI-BIN script, REXXLIB is not required.
Let's assume you've successfully installed WWWthumb (hmmm, perhaps it's impossible to know if you've been successful until after you've "gotten started"). Now you are ready to create a few thumbnails, and make them available to the public.
In order to attain this laudable goal, you'll need to follow (more or less) the following steps. But before commencing with these instructions, let's define an oft-used term: selector..
A selector is a pointer to a resource on a web server. Typically, the selector is the portion of a URL that follows the server's address. For example, in the URL:
the selector is /houses/describe.html. In the context of WWWthumb, the selector refers to the file (or directory) that WWWthumb should operate on. This file will be in the server's web space; a space which maps (usually in a fairly simple way) to OS/2's disks & drives. For example, in the HTML element:
<img src="/cgi-bin/WWWthumb?sel=/houses/describe.html">/houses/describe.html is the selector. Using the above example, if the root of the web space is E:\WWW\HTML, then /houses/describe.html might point to a file named E:\WWW\HTML\HOUSES\DESRIBE.HTML. Similarly, /houses/interior/ might refer to a subdirectory named E:\WWW\HTML\HOUSES\INTERIOR.
Noting that SRE-http users have additional options not available to those using WWWthumb as a CGI-BIN script, the following should get you started.
- Generate the thumbnails. Use PMVIEW, or some similar utility, to generate thumbnails stored in extended attributes. PMVIEW is quite good at this -- it recognizes zillions of graphic formats, and can be instructed to automatically create thumbnails for all files in a directory (and it's fairly fast). If you are interested in creating thumbnails only for .GIF files, you can skip this step (and let WWWthumb generate the thumbnails for you)!
- Create a thumbnails cache. From an OS/2 prompt, run WWWthumb.CMD. You will be presented with a fairly primitive (i.e.; non-GUI) series of prompts. You'll need to select the target directory and a few other options. The first few times you should probably select the "defaults" for the advanced options; you can play with them (i.e.; use them to add image height and width information to the thumbnail) after you are more comfortable with the basic process. Hint: When experimenting, use fairly small sets of files (say, less then 50) --- it takes about a second or so to generate each thumbnail.SRE-http users: If you are running WWWthumb as an SRE-http addon, you can use ThumbSRE.HTM to create these thumbnails. We find this to be slightly easier to use, but it does take a bit longer (and it does require SRE-http!)
- Record the name of the thumbnail cache index file. When step 2 completes, you will be told the name of the thumbnail cache index file (aka the thumbnail cache ). You should jot this name down, since you'll need it when you want to request the thumbnail associated with a selector. For purposes of illustration, let's assume the name is THUM1 (by coincidence, this just happens to be the very same name that WWWthumb will automatically generate).
- View the thumbnails. If you want to view the thumbnails you just ordered up, you can use either of the view thumbnails options in ThumbSRE.HTM (or ThumbCGI.HTM). The second of these options is quite friendly; it will let you choose from a list of available thumbnail indices, and then show you all the thumbnails pointed to by the index you then select.
- Create a document that contains a get a thumbnail request. Specifically, this will consist of an HTML IMG element that invokes WWWthumb with the name of a selector and the thumbnail index.
The thumbnail for /HOUSES/SUMMER1.JPG is: <img src="/cgi-bin/WWWthumb?sel=houses/summer1.jpg&index=thum1"> (if you are an SRE-http user, drop the /cgi-bin). SRE-http users: the GETAFILE directory lister SRE-http addon) now contains a "show me the thumbnail" option (along with date, size, etc). It's quite easy to specify (as long as your THUMBNAIL_DIR is "web accessible").
Once you've generated a few sets of thumbnails, you should be ready to check out the more advanced features specified; such as writing height and width information on the thumbnail, and modifying the thumbnail size. These are described in the WWWthumb.CMD parameters, and in the WWWthumb options.
In order to create thumbnails from .GIF files, WWWcount makes use of the RXGDUTIL library. Although a fairly nice resource (especially given it's no-cost), it has a few limitations. In particular, it can not handle animated GIFs. Therefore, WWWcount has to jump through a few hoops (i.e.; make a temporary file) when an animated GIF is encountered -- a process which may slow things down a bit.
Therefore, it is best to use PMVIEW (or an equivalent program) to create "thumbnails in the extended attributes", and then use WWWcount to extract and otherwise manipulate these thumbnails. This PMVIEW'ized approach also has the advantage of generating thumbnails for non-GIF graphics files. Of course, this does mean running PMVIEW, which can be a bit time consuming (especially if you have many files spread over a slew of subdirectories).
Parameters stored in WWWthumb.CMD have several purposes, including specification of storage directories, size and color selection, and selection of default thumbnail images.
When you first install WWWthumb.CMD:
- you must set the THUMBNAIL_DIR parameter.
- You should set the IMG_DIR parameter.
SRE-http users: you should set the THUMBNAIL_DIR_SEL parameter.
- You might want to modify several of the size and color parameters
- You might want to change some of the DEFAULTS.
Note that several of the size and color parameters can be over-ridden by request-line options (options included when WWWthumb.cmd is invoked as a CGI-BIN script or as a SRE-http addon).
Directory and Selector parameters
- The thumbnail_dir parameter is the fully qualifed directory in which thumbnail files should be stored.
Example: thumbnail_dir='d:\www\thumcash' While not strictly necessary, we highly recommend' that this be a web-accessible directory. That is, contents of the thumbnail_dir directory should be accessible by your intended WWW audience using their favorite browsers.Example: WWWthumb_DIR='D:\WWW\THUMCASHNote to SRE-http users: It is not strictly required that the thumbnail_dir be "web accessible". However, if it is not:
- You will not be able to use "redirection" to deliver thumbnails
- You will not be able to use thumbnails in conjuntion with the GETAFILE addon
- The "list all thumbnails" option (in ThumbSRE.HTM) will not work well
- THUMBNAIL_DIR_SEL is not used when WWWthumb.CMD is run as a CGI-BIN script The THUMBNAIL_DIR_SEL is the "selector" corresponding to thumbnail_dir. It is used in several cases where "redirection" is used to deliver thumbnails to a client.Basically, when WWWthumb is invoked, it can either retrieve the thumbnail image and return it directly, or it can redirect the client's browser to the image. This latter method (which will only be available if you've correctly specified thumbnail_dir_sel) allows you to interpose SEL-specific access controls (that is, you can limit access to your thumbnail directory in the usual SRE-http fashion).Example: WWWthumb_DIR_SEL='/THUMCASH'
Note that trailing and leading / are optional (they will automatically be added as needed).
- Fully qualified directory containing the "default thumbnails" (as installed in step 7 above). Example: IMG_DIR='D:\www\imgs'
Size and Message Text Parameters
The message text is used to label a thumbnail. The message is written on top of, or underneath the thumbnail (as specified by the WRITE_GIF_SIZE option described below).
Currently, one type of message is available: the width and height (in pixels) of the original file.
- The Width and Height dimensions of the thumbnails (not of the original files!).
If this is left blank, the default sizes are used. There are two kinds of defaults:
- Pre-existing thumbnails (ICON attributes found in a file's extended attributes), are used as is. Note that if THUMBNAIL_SIZE is specified, the thumbnail will be shrunk (or expanded) accordingly.
- For auto-generated thumbnails (from .GIF files) a size of 32x32 is used
Example: thumbnail_size='32 32 '
- r,g,b color to use when writing size, using rrggbb; with rr (and gg and bb) a hex number between 00 and ff
- The background for the message text. Either the 6 character r,g,b colors, or the color table # (0 to 255)
The last example means use color table entry 0 as the background color
- The height of the message text, in pixels
- The width of the message text, in pixels
- DEFAULTS is a set of stem variables containing a list of "default" thumbails. Each DEFAULTS. variable should have at least two substrings (seperated by spaces):
defaults.n=pattern [pattern2...] tfile
- pattern: The (wildcardable) pattern (and the optional pattern2, etc. ] are compared against the selector. Typically, the pattern(s) are wildcarded to match an extension (but they can be a specific selector, such as DIR1/INDEX.HTM)
- tfile: The tfile should be the name of a default thumbnail image file. It tfile is a relative filename, it is assumed to be relative to the img_dir directory. Examples:
defaults.1='*.TXT *.TEXT *.DOC *.FAQ text.gif' defaults.2='*.GIF *.JPG *.JPEG *.TIF* *.BMP *.PNG image.gif ' defaults.3='PRESIDENT/HOUSE WHOUSE.gif ' defaults.0=3 Notes:
- You may include several patterns for a single tfile.
- The first matching DEFAULTS. variable is used.
- You must set DEFAULTS.0 to be the number of DEFAULTS. variables; and DEFAULTS.n must be numbered from 1 to DEFAULTS.0.
- ON_THE_FLY is not used when WWWthumb.CMD is run as a CGI-BIN script In general, we recommend using WWWthumb in conjunction with cached thumbnails. However, SRE-http users can run WWWthumb in an "on-the-fly" mode; which means that WWWthumb will create, return (and not save) a thumbnail for a specified selector.You can suppress this capability by setting the ON_THE_FLY parameter:
- NOT_ON_THE_FLY=1 : Suppress "on the fly" creation of thumbnails,
- NOT_ON_THE_FLY=2 : To also suppress use of default images. If NOT_ON_THE_FLY=2, WWWthumb will only use thumbnail images stored in a pre-created cache. Notes:
- By default, NOT_ON_THE_FLY is off (that is, on-the-fly creation is permitted).
- For clients with SUPERUSER or THUMBNAIL privileges, not_on_the_fly is ignored.
- When called as a cgi-bin, not_on_the_fly is always set to 2
- PAD_WITH is used to allocate extra space at the end of each record (in the cache index file). Examples: PAD_WITH=' _____ | ' PAD_WITH='' Note that when PAD_WITH='', entries in the cache will not have extra "padding".
WWWthumb options are specified when WWWthumb is invoked as a CGI-BIN script, or as an SRE-http addon (many of them can also be specified when you run WWWthumb in stand-alone mode). Often these requests are generated by an HTML FORM (such as found in THUMBsre.HTM), but you can easily hard-code a "call" to WWWthumb by including an HTML IMG element, with options appearing (in the usual HTTP fashion) after a ?, with each option seperated by a &
- The SEL (short for selector) typically points to a file (in the server's "web tree") for which you'ld like to retrieve (or create) a thumbnail image.
- SRE-http users: If you are creating thumbnails using the CREATE mode (described below), the selector should point to a directory.
- SRE-http users: The selector is mapped to a file using either the GoServe data directory, or an SRE-http virtual directory.
- CGI-BIN users: The selector is mapped to a file using the Selector that points to xxx value you specified when you created the thumbnail index (by running WWWthumb.cmd in stand-alone mode). Example: <img src="/WWWthumb?sel=/house/kitchen.jpg">
- INDEX specifies the thumbnail cache index file (or files) that contain the thumbnail for the desired selector. Since there may be cases where you've created multiple indices (say, one for each of several directories), and you may not be able to predict which index will contain an entry for the desired selector, you can specify multiple indices. To do this, just enter each name in a space delimited list (if you are hand-coding a URL, remember to use + instead of a space). Or, if you have many sets of indices, you can use * wildcarded names. Examples:
<img src="/WWWthumb?sel=/house/kitchen.jpg&index=floor1.ind"> <img src="/WWWthumb?sel=/house/attic.jpg&index=thum1+thum2"> <img src="/WWWthumb?sel=/animals/kitten.gif&index=thum*">Notes
- Indices will be searched in order of appearance
- The first match will be used; possible matches in subsequent indices are not investigated.
- If no match is found, then a blank document is returned.
SRE-http users: Before returing a blank document, WWWthumb will see if any of the DEFAULTS. match.
- In no case will WWWthumb attempt to generate a thumbnail on-the-fly. That is, if SRE-http users want to generate a thumbnail on-the-fly, you must not specify an INDEX.
- If no extension is given, a .IND will be added
- CREATE is avaiable only to SRE-http users. When CREATE=1, then a set of thumbnails will be created for the directory specified in the SEL option. Example:
- An optional description. This is included in the .IND file. In addition, it can be used as the header (see the description of BIGHEADER).
- Used with CREATE. When DOSUB=1, then also create thumbnails for files specified in the subdirectories of SEL. Example:
- Used with CREATE. If AUTOGIF=1, and a .GIF file does not have a thumbnail in the extended attributes, then WWWthumb will create one. Example:
- Used with CREATE. INCLUSION is used to specify files to "include" -- thumbnails will not be created for non-included files.
INCLUSION should consist of a space seperated list of file names, with * wildcards permitted. Note that each pattern will be compared against a file name relative to the SELected directory. Example:
<img src="/WWWthumb?sel=/boats/&create=1&inclusion=SAIL.*">Hence, if /BOATS maps to D:\WWW\BOATS, which contains D:\WWW\BOATS\SAIL.JPG and D:\WWW\BOATS\BIGSAIL.GIF, then SAIL.JPG would be included, but BIGSAIL.JPG would be excluded.
- Write the width and height of the image on the the thumbnail. There are 3 values:
- WRITE_GIF_SIZE=0 : do not write width and height
- WRITE_GIF_SIZE=1 : overlay width and height on the bottom of the thumbnail.
- WRITE_GIF_SIZE=2 : squoosh the thumbnail up, and write the height and width underneath this now shorter thumbnail. Note that the total height of the thumbnail image, including this height and width, will not be effected. Examples:
- When WRITE_GIF_SIZE is 1 or 2, WRITE_TRANSPARENT=1 signals "use transparent background". If you do not use a transparent background, and WRITE_GIF_SIZE=1, then a monocolor filled-box will first be written to the thumbnail, and then the height and width wil be written in this box. Example:
- THUMBNAIL_SIZE, TEXT_COLOR, TEXT_BCOLOR, TEXT_HEIGHT, TEXT_WIDTH
- Set the thumbnail size, and the color, background color, height and width of the "height and width message text" (see the parameter section for further description of these options). Note that values specified in the options will overwrite the "default" values specified in WWWthumb.CMD parameters. Example:
- When n is greater then 0,then WWWthumb will display all the thumbnails listed in the given index. See the View A List of Thumbnails section for details on additional options that are only used when VIEW is selected.
View A List of Thumbnails
The View a list of Thumbnails tool is a convenient way of examining what thumbnails were produced. It can also be used to produce an HTML document that uses thumbnails to link back to the original files -- a document that you can use (with suitable site-specific customizations) as a web-accessible "choose a file to download" directory list.
This View mode understands it's own set of options. which are described below. Please note that the most important options are VIEW and BIGPICTURE. You can find an illustration of their uses in ThumbCGI.HTM and ThumSRE.HTM.
- When n is greater then 0,then WWWthumb will display thumbnails listed in the given index, with links back to the original files. An n column table is used. Example: <img src="/WWWthumb?index=houses&view=3"> Notes:
- All thumbnails in the HOUSES.IND thumbnail index will be displayed
- A 3 column table will be used.
- Each thumbnail will be linked to the file from which it was derived.
- Each cell of the table will contain the thumbnail image, the selector of the original file, and a description (typically, the description is the original files's height and width in pixels).
- If n=1, an ordered list (
- ) is used (since a 1 column table is not real useful)
- Used with VIEW. If NO_DESCRIBE=1, then suppress writing the "description" Example: <img src="/WWWthumb?index=houses&view=3"&no_describe=1>
- If BIGPICTURE=1, then a "big picture" is constructed from all the thumbnails. More precisely, a grid is generated, with each thumbnail written to one of the cells of this grid. Each of these cells will contain the thumbnail, and a short message written below the thumbnail. The advantage of BIGPICTURE is speed -- it is substantially faster then returning each thumbnail as a seperate IMG, since only one (more or less) image needs to be returned. The disadvantage is that less information can be included, and downloading requires that the client's browser supports client-side imagemaps (i.e.; NetScape 2.0 and above).Example: <img src="/WWWthumb?index=houses&view=3"&bigpicture=1>Notes:
- When BIGPICTURE=1, the exact value of VIEW is ignored (though VIEW must be greater then 0).
- If there are many (say, over 100) images referred to by the thumbnail index, several images will be generated.
- The "big picture" images will be stored in the THUMBNAIL_DIR directory, using randomly generated names of the form BIGnnnnn.GIF.
- When BIGPICTURE is used, NO_DESCRIBE is ignored.
- BIG_COL and BIG_ROW (used with BIGPICTURE)
- Set the number of columns and rows in the big picture (with one thumbnail per cell. The default value of BIG_COL and BIG_ROW is 10. However, this default will be adjusted to prevent overly large images (this adjusment will not occur if you explicitly set BIG_COL or BIG_ROW. Example: <img src="/WWWthumb?index=houses&view=3"&bigpicture=1&BIG_COL=15>
- BIGHEADER (used with BIGPICTURE)
- BIGHEADER is used to specify a header to write at the top of the page. If you do not specify BIGHEADER, some descriptive info will be written.
Special feature: setting BIGHEADER=$DESC means "use the description as a header" (the description is set by the DESC option).
- BIG_MESS (used with BIGPICTURE)
- BIG_MESS selects what sort of "message" to write below the thumbnail. It can take one of the following values:
- BIG_MESS='NAME' -- the default. Write the file name.
- BIG_MESS='THUMB' -- write the thumbnail-specific message stored in the thumbnail index. Typically, this is the width and height of the original image file.
- BIG_MESS='DATE' -- Datestamp of the original file.
- BIG_MESS='NONE' -- do not write a message. There's not much space beneath each thumbnail (a 10 pixel high rectangle that's the width of the thumbnail. Hence, on a 50x50 thumbnail, only the first 8 or so characters of the message will be written. Example: <img src="/WWWthumb?index=houses&view=3"&bigpicture=1&BIG_MESS='THUMB'>
- CLIENTMAP (used with BIGPICTURE)
- If CLIENTMAP=1, then a client-side image map will be generated along with the big picture. The client-side image map will point back to the original files. That is (assuming one's browser supports client side image maps), clicking on the thumbnail will issue a request for the original file. Example: <img src="/WWWthumb?index=houses&view=3"&bigpicture=1&clientmap=1>
- MAPALT=YES or NO (used with BIGPICTURE)
- When MAPALT=YES (and BIGPICTURE is enabled), then a link to a list of files (with their thumbnails) is provided - basically, this is the standard (non clientside imagemap) WWWTHUMB-stylelist of links.
- VIEW_WIN=YES or NO
- When VIEW_WIN=YES, then selected images will be displayed in a seperate viewer window. In other words, the list of images (with their thumbnails) will be in one window, and a seperate (viewer) window is used to display selected images. If VIEW_WIN=NO, then images are displayed in the same window (they will overwrite the list of images).