Documentation for AniS - the AnimationS applet

October 13, 1999
updated: November 3rd, 2003

To run the applet, you need an applet tag. The skeleton for this is:

<HTML> <HEAD> <TITLE> Example of the AniS applet </TITLE> </HEAD> <BODY> <P> <APPLET code="AniS.class" width=640 height=540> <PARAM name="parametername" value="value(s) for parameter"> </APPLET> </BODY> </HTML> The rest of this document describes the PARAMeter names and values needed to drive the AniS applet. We begin with the controls and then describe the specification of the filenames of the images.

One word about blanks (spaces). Within each PARAMeter clause, leading and training blanks are ignored for each parameter. You should use spaces to provide for easier readability.

Parameters for controls (if the control is named, it will appear; otherwise, its default value will be used):

<PARAM name="controls" value="startstop, looprock, step, speed, enhance, firstlast, refresh, toggle, rotator, zoom, fader, overlay, framelabel, audio">

This controls parameter will position the controls above the image window. If you would like some (or all) of the controls below the image window, use the bottom_controls tag, as in:

<PARAM name="bottom_controls" value="startstop, looprock, step, speed, enhance, firstlast, refresh, toggle, rotator, zoom, fader, overlay, framelabel, audio">

Note: You must not specify the same control in both the controls and the bottom_controls parameters!

Here are the details about each control:

Other parameters that may be used: <PARAM name="use_archive" value="x"> specifies that all the data files are contained in an archive file that is specified in the <applet> tag. You must include all extra files (enh.tab, file-of-filenames) as well. The form of the <applet> tag is like:
   <applet archive="aniscode.jar,data.zip" class="AniS.class" height=....>
where the data files are stored in "data.zip".
<PARAM name="active_zoom" value="x"> specifies that the zoom ability will always be active; this cannot be used in conjunction with the "zoom control". If you specify this parameter, user left-clicks on the image will zoom at that point, right-clicks will zoom out. While zoomed, the image may be roams by dragging the mouse around.

This option should not be used when portals are also used.

<PARAM name="image_window_size" value="400,200"> specifies that the images will be displayed in a window with a width=400 and a height=200. Without this parameter, the size of the window is the size of the first frame (image). When this parameter is used, the images will be rescaled to this size. If zooming is active, when the user zooms, the image will be zoomed as usual, possibly showing more detail.

This option should not be used when portals are also used.

<PARAM name="auto_refresh" value="16"> specifies that the base images will be automatically reloaded from the source every 16 minutes. An attempt is made to by-pass any use of caching, and this process has been found to work quiet well in both Netscape and IE. Note: do not use overlays or portals when using the auto_refresh option -- they do not always work as expected. <PARAM name="start_looping" value="false"> specifies the initial state of the animation. A value of "false" means the animation is not started automatically. The default value is "true", meaning the animation begins automatically as soon as all frames are loaded. Note: if you do not put in a startstop control and set start_looping to "true" then the animation will run "forever". <PARAM name="start_frame" value="18"> specifies the frame number (starting at zero) of the frame to display after all loading is done. This option implies "start_looping" is "false". <PARAM name="rate" value="120"> specifies the initial loop rate as a number corresponding to frames per second times 10 (thus, 120 means 12 frames per second). <PARAM name="rocking" value="true"> make "rocking" the startup mode for displaying the sequence; otherwise, "movie loop" is the startup mode. <PARAM name="pause" value="2000"> pause on the last frame of a loop the additional number of milliseconds given (2 seconds in this example). The default is zero. <PARAM name="pause_percent" value="250"> pause on the last frame of a loop the additional percentage of the current dwell time specified (250% in this example). In addition, if the current dwell is > 1 second, a fixed value of 100% will be used whenever this pause_percent option is specified. The default value is zero. <PARAM name="transparency" value="#FFFFFF"> use the color "white" as the transparency value. This is only needed for overlays, and is optional for fading. The value is a hex value of red/green/blue (template: #rrggbb). "black" (#000000) is also commonly used. <PARAM name="fade" value="true"> instead of just showing the images, generate 'faded' images between them and use the result as the sequence. <PARAM name="fader_label" value="Vis IR"> instead of the "Set Fader Level" label on the fader control, use the specified label. Note the label is centered so you must provide ample spaces to ensure the fader control is made large enough. In this case, the user wanted "Vis" on the left and "IR" on the right, so many spaces were put between the words. <PARAM name="backcolor" value="xff00ff"> set the applet background color (used for backgrounds of all the controls as well...) to the RGB value (in hex) given (in this case, red=255, green=0 and blue=255) <PARAM name="forecolor" value="xffffff"> set the color of the foreground (used for names on buttons, etc.) to the RGB value (in hex) given (in this case, white). Note that you should keep a good contrast between the background and foreground colors. <PARAM name="frame_label" value="label for 1, label for 2, ..."> when the framelabel control is specified, the values in this comma-separated list will be used to label each frame. If you enclose a standard format date-time between a pair of "$$" characters, it will be replaced by a string for the computer's local time zone. For example: "Picture from $$5/10/00 15:00 GMT$$ in the morning" will be displayed as: Picture from May 10 10:00:00 CDT 2000 in the morning The formatting is fixed by the Java library... <PARAM name="frame_label_width" value="30"> this specifies the width of the text box (in characters) to be used for the frame_label strings. The default is 20 <PARAM name="audio_filename" value="audioclip.au"> this specifies the name of the audio clip to be played when the audio control is specified. This must be a .AU file. <PARAM name="image_base" value="http://www.my.host/mydir/"> this directs that the base URL of the image files (and the file_of_filenames, if used) should be the value given. The default URL is the directory containing the HTML. Note that the hostname in the specified URL must be the same as the hostname where the applet is read from. <PARAM name="toggle_size" value="5,10,3"> this sets the toggle control's little boxes width to 5, the height to 10, and the spacing between them to 3. This can be very helpful if you have a large number of frames and don't want to make your applet width too large just to accomodate these boxes. <PARAM name="rotator_labels" value="N, E, S, W"> this defines the labels to be used with the rotator widget. You may specify up to 8 labels (more just won't fit...) that will be evenly distributed around the circle. The first label will be placed at the top ("North"), and sucessive labels will be positioned clockwise around the circle. Depending on the letters, you may be able to get up to 4 letters per label (certainly more than that for the top and bottom (0 and 180 degrees). If you use 'fading', then the number of frames will be recomputed when you activate/de-activate it, but the rotator labels will not change. <PARAM name="rotator_color" value="x00ff00"> this defines the color to use for the rotator "arm". It is in for format: xRRGGBB, so the value shown will make a green colored arm. The labels and circle will be drawn with the foreground color specified. The default is yellow (xffff00). <PARAM name="enable_png" value="true"> this enables the use of PNG files for all JVMs/browser versions by using the sixlegs PNG decoder. If you want to use PNG and do not have control over browser or JVM versions, you may want to consider this. If you use this option, then your image file names MUST end with png (See note, below, under "Image file names" regarding the use of the wildcard format.) <PARAM name="blank_screen" value="true"> this will cause the background of each frame to be blanked out priod to showing each image. This should be used if some of your images have 'transparency' set (for example, GIF and PNG images allow you to set a level, like the 'background' to transparent). Enabling this option will prevent the images from appearing to be overlaid, but may slow down the animation speed. <PARAM name="no_enh" value="true"> this supresses the attempt to read the "enh.tab" file. This takes care of a problem when using a firewall with password protection, when no enhancement is used.


Image file names
All the image files can be in GIF or JPEG formats. The files identified using the parameter names described in this section should fill the desired window. If used, overlays and portals should be the same size and have the same geometry as these "background" images.

For the background images, the GIF/JPEG files may be specified in one of three, mutually exclusive, ways.

  1. Using a "root" name, to which successive numbers are appended to create the actual filenames:
    <PARAM name="basename" value="file"> <PARAM name="num_frames" value="4"> <PARAM name="base_starting_number" value="0"> In this case, the root name is file and since there are 4 images specified with the numbering starting at 0, the actual filenames must be: file0, file1, file2, and file3. Please note that the default base_starting_number is zero, and so it would not have to specified in this case...

  2. Using the filenames themselvels:
    <PARAM name="filenames" value="file0, file1, file2, file3">
  3. Using a file which contains a list of the image filenames (one per record)
    <PARAM name="file_of_filenames" value="file-containing-filenames"> where the file "file-containing-filenames" contains lines of text that are in the form:
    file0 file1 file2 file3 lines beginning with # are ignored, so you may put comments into your file_of_filenames.

    NOTE: If you want to specify an optional frame label (see the controls section above), you may put the value with quote marks after the filenames. (The label may, optionally, contain a date-time to be reformatted for the user's timezone -- see "frame_label", above.) For example: file0 "label one" file1 "label two"
NOTE: For the first form (specifying a "basename"), you may also use a wildcard format. There are two forms of this, one using a single * (to substitute numbers 0,1,2...,10,11,.. at that point) and the second using one or more ? (to substitute the numbers with leading zeroes for all the ? marks). For example, if you say: <PARAM name="basename" value="file*.gif"> the actual filenames must be: file0.gif, file1.gif, file2.gif, and file3.gif

You may also use the form:

<PARAM name="basename" value="file????.gif"> the actual filenames in this case must be: file0000.gif, file0001.gif, file0002.gif, and file0003.gif


Portals
Portals are viewports into other images, which are shown in windows superimposed onto the background image. The user "roams" around in a portal by dragging the mouse pointer around on the background image. For each portal, you must specify its location and size, and then the filename(s). If you are animating the background images, you'll need to specify a corresponding number of portal filenames for each frame of the animation.

First, however, the parameter for specifying the location:

<PARAM name="portal_locations" value="x & y & width & height, x2 & y2 & width2 & height2, ..."> Each list item separated by a comma defines the location (x,y) of the upper left corner of the portal and the portal's width and height values. All values are given in pixels; the upper left corner is (0,0).

You may have any number of portal windows that you like, but they should all fit inside the dimensions of the background image and should not overlap.

To specify the portal image filenames, you may use one of the following forms (note in each example, 3 portals are being defined with the names associated with each separated by a comma; in the second method, the files for each of 4 frames are explicitly named separated by &).

  1. In the first case, you are specifying a "basename" for each portal (see file name conventions, above). Each name you specify is for an individual portal, and the software will load as many images for each portal as there are background image frames. <PARAM name="portal_basenames" value="pfileA, pfileB, pfileC"> (You may also use the wildcard format mentioned above.)
  2. In the second case, you are naming each file explicitly. The grouping of names is the same as above -- commas separate portals. Ampersands separate filenames for each frame of a loop. <PARAM name="portal_filenames" value="pfileA0 & pfileA1 & pfileA2 & pfileA3, pfileB0 & pfileB1 & pfileC2 & pfileD3, pfileC0 & pfileC1 & pfileC2 & pfileC3">
  3. Finally, you may also use a text file (the "file-containing-filenames" form) to specify all the filenames. To use portals with this form, the filenames for all the portals for one frame appear on one line. file0 portal=pfileA0, pfileB0, pfileC0 file1 portal=pfileA1, pfileB1, pfileC1 file2 portal=pfileA2, pfileB2, pfileC2 file3 portal=pfileA3,pfileB3, pfileC3 NOTE: You MUST supply all portals names for each frame, even if the filename is repeated!!
    NOTE: If you want to specify an optional frame label (see the controls section above), you may put the value with quote marks between the filenames and the keyword that follows. For example: file0 "label one" portal=pfileA0, pfileB0,... file1 "label two" portal=pfileA1, pfileB1,...


Overlays
You may also use overlays -- one or more images that are (optionally) displayed on top of the base image, usually in such a way that part of the base image shows through. For example, a map or plotted data may be an overlay. In order to let some of the base (background) image show through, you must designate one color level in the overlay images as "transparent" and then specify that value using the transparency parameter (above).

In addition, you need to specify the overlay control, and provide a few more parameters:

<PARAM name="overlay_labels" value="label1, label2, label3..."> This specifies the labels that will be used on the controls for each overlay. The ordering of the values should be the same as the filenames (below). You'll want to keep these labels brief!

By default, all overlays are initially "off". If you want to force one to be on, append /on to the label. From the previous example:

<PARAM name="overlay_labels" value="label1, label2/on, label3..."> would force the second overlay to be initially turned on.

If you want to treat some or all of the overlays as 'radio buttons' (that is, only one of them may be showing at once), you may use the overlay_radio parameter. For example:

<PARAM name="overlay_radio" value="true,false,true,true,..."> This would specify that overlays 1, 3, and 4 would be 'radio buttons' and only one could appear at once. Overlay #2, however, may be toggled on and off indepdently. If you want to use radio buttons for all of your overlays, you may simply say <param name="overlay_radio" value="true">

You may also change the position of an overlay on the screen. Normally, overlay images are located with the upper left corner in the upper-left of the display (x=0, y=0). You may use the overlay_locations parameter to move the overlay. For exampleL

<PARAM name="overlay_locations" value="10&20, 100&200, 0&0,..."> This would specify the overlay #1 would be positioned with it's upper left corner at location (x=10, y=20), overlay #2 would be at (x=100,y=200), and overlay #3 at (x=0, y=0...the default). If you use this parameter, you must specify a location for each overlay for which you provide a label.

To specify the names of the files for the overlays, you may use one of these forms (note in each example, 3 overlays (A,B,c) are being defined with the names associated with each separated by a comma; in the second method, the files for each of 4 frames are explicitly named separated by &).

  1. In the first case, you are specifying a "basename" for each overlay (see file name conventions, above). Each name you specify is for an individual overlay, and the software will load as many images for each overlay as there are background image frames. <PARAM name="overlay_basenames" value="ofileA, ofileB, ofileC"> (Again, you may use the wildcard format -- see above.)
  2. In the second case, you are naming each file explicitly. The grouping of names is the same as above -- commas separate portals. Ampersands separate filenames for each frame of a loop. <PARAM name="overlay_filenames" value="ofileA0 & ofileA1 & ofileA2 & ofileA3, ofileB0 & ofileB1 & ofileB2 & ofileB3, ofileC0 & ofileC1 & ofileC2 & ofileC3">
  3. Finally, you may also use a text file (the "file-containing-filenames" form) to specify all the filenames. To use overlays with this form, the filenames for all the overlays for one frame appear on one line. file0 overlay=ofileA0, ofileB0, ofileC0 file1 overlay=ofileA1, ofileB1, ofileC1 file2 overlay=ofileA2, ofileB2, ofileC2 file3 overlay=ofileA3,ofileB3, ofileC3 NOTE: You MUST supply all overlay file names for each frame, even if the filename is repeated!!
    NOTE: If you want to specify an optional frame label (see the controls section above), you may put the value with quote marks between the filenames and the keyword that follows. For example: file0 "label one" overlay=ofileA0, ofileB0, ofileC0 file1 "label two" overlay=ofileA1, ofileB1, ofileC1


Explicit paths in your HTML for dynamic web pages (or how to avoid having multiple copies of the AniS class files on your server)

If you are generating dynamic web pages (using, for example, a Python script) or have several different animations on your server and want to avoid having multiple copies of the AniS class (or JAR) files, we suggest you use the "codebase" attribute that is available in the <applet> tag to point to the location on your server of the class or JAR files. For example:

<applet codebase="../../code" code="AniS.class" height=...> or, if you are using the aniscode.jar file, then: <applet codebase="../../code" archive="aniscode.jar" code="AniS.class" height=...> You may also give a full URL for the codebase, but it must be on the same machine: <applet codebase="http://my/machine/applets/code" code="AniS.class" height=...> Finally, the image files are read _relative to the directory containing the HTML_. If you need to change that you can include the directory information in the filename (the same is true when using the 'file-of-filenames' method). For example: <param name="filenames" value="../../images/goes1.gif,../../images/goes2.gif">