The WWWthumb Utility
Abstract:
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.
Contents
- Introduction
- Installation
- Getting Started
- Parameters
- Options
- View a list of Thumbnails
Introduction
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:
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.
Installation
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.
For example, C:\OS2\APPS
- 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!
Installation Notes
- EA2GIF.EXE and GIFWRITE.DLL are courtesy of Peter Nielsen (pnielsen@abo.fi)
- 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
(rvanney@ibm.net).
- When run as an SRE-http addon, several REXXLIB procedures are used. However,
when run as a CGI-BIN script, REXXLIB is not required.
Getting Started
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:
http://foo.bar.net/houses/describe.html
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.
For example:
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.
Some Cautions
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).
WWWthumb.cmd Parameters
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
- THUMBNAIL_DIR
- 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\THUMCASH'
Note to SRE-http users: It is not strictly required
that the thumbnail_dir be "web accessible". However, if it is not:
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.
- THUMBNAIL_SIZE
- 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 '
- TEXT_COLOR
- r,g,b color to use when writing size, using rrggbb; with
rr (and gg and bb) a hex number between 00 and ff
Example: text_color='22aaFF'
- TEXT_BCOLOR
- The background for the message text.
Either the 6 character r,g,b colors, or
the color table # (0 to 255)
Example: text_bcolor='22bb44'
Example: text_bcolor='0'
The last example means use color table entry 0 as the background color
- TEXT_HEIGHT
- The height of the message text, in pixels
Example: text_height=10
- TEXT_WIDTH
- The width of the message text, in pixels
Example: text_width=5.2
Other parameters
- DEFAULTS.
- 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
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:
- ON_THE_FLY
-
- 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
- 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
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 &
- SEL=file_or_directory
- 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.
Notes:
Example:
<img src="/WWWthumb?sel=/house/kitchen.jpg">
- INDEX=thumbnail_index
- 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
- 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:
<img src="/WWWthumb?sel=/animals/&create=1">
- DESC
- An optional description. This is included in the .IND file. In addition,
it can be used as the header (see the description of BIGHEADER).
- DOSUB
- Used with CREATE. When DOSUB=1, then also create thumbnails for
files specified in the subdirectories of SEL.
Example: <img src="/WWWthumb?sel=/animals/&create=1&dosub=1">
- AUTOGIF
- 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: <img src="/WWWthumb?sel=/animals/&create=1&autogif=1">
- INCLUSION
- 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_GIF_SIZE
- 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: <img src="/WWWthumb?sel=/animals/&create=1&sel=/animals&write_gif_size=1">
- WRITE_TRANSPARENT
- 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:
<img src="/WWWthumb?sel=/animals/&create=1&sel=/animals&write_gif_size=1&write_transparent=1">
- 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:
<img src="/WWWthumb?sel=/animals/&create=1&write_gif_size=2&text_color=11199ee">
- VIEW=n
- 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.
VIEW options
- VIEW=n
- 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:
- NO_DESCRIBE
- Used with VIEW. If NO_DESCRIBE=1, then suppress writing the "description"
Example:
<img src="/WWWthumb?index=houses&view=3"&no_describe=1>
- BIGPICTURE
- 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:
- 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:
Document created on 09 March 2001 by Daniel Hellerstein