The Virtual Lightbox
Version 1.0 (Beta)
Matthew G. Kirschenbaum,
Jerzy W. Jaromczyk, Amit Kumar, Laura Reynolds and Adam Turner
Supported by the Center for
Computational Sciences at the University of Kentucky and the Research
Experiences for Undergraduates program of the NCSA’s Partnerships for an
Advanced Computational Infrastructure (PACI)
Help
Documentation
The Virtual Lightbox is an image-based, peer-to-peer whiteboard application. It is programmed in Java, using Remote Method Invocation and the Java Shared Data Toolkit. The Lightbox furnishes users with a robust environment for image comparison and the means to share images in realtime with other participants in a Lightbox session. Users can manipulate the images on the surface of the Lightbox, and perform a variety of image processing operations (zoom, adjust contrast, toggle color/greyscale, etc.).
The Lightbox has three principal components: the registry, the server, and the client.
· The registry keeps track of the clients that have joined (or left) a session. It is run only by the person initiating the session.
· The server sends and receives mouse events, image manipulation commands, and image objects. Each participant in a collaborative session must run a server.
· The client provides each participant in a session with a GUI and an image display area (the “surface” of the Lightbox).
To use the Lightbox in stand-alone mode (i.e., offline) only the client is required. To use the Lightbox in its collaborative mode (to share images and image operations with others) the registry, the server, and the client are all required.
The Virtual Lightbox is an open source application, distributed under the terms and conditions of the GNU General Public License <http://www.gnu.org/copyleft/gpl.html>. Source code is available via SourceForge <http://sourceforge.net/projects/lightbox/>.
The Virtual Lightbox is not “supported,” but we are happy to receive comments and bug reports. Please send these to: <mgk3k@jefferson.village.virginia.edu>. Please also visit the Lightbox homepage at <http://www.rch.uky.edu/~mgk/lightbox/> for updates and additional information (such as an explanation of the application’s architecture).
The Lightbox functions on Windows NT/98/2000, Solaris, and Linux. We have not tested functionality for Apple’s Macintosh.
Recommended minimum system requirements are a 500 Mhz Pentium III processor and 128 MB of RAM.
WINDOWS
Client Installation
Unzip the file in the temporary directory and type install at the DOS prompt in the temporary directory. The Lightbox Client is installed in c:\lightbox\client directory.
Backup Administrator Installation
Unzip the file in the temporary directory and type install at the DOS prompt in the temporary directory. The Backup Administrator is installed in c:\lightbox\bakadmin directory.
UNIX
Client Installation
Untar the file in the user’s home directory and type install.sh in the users home directory. During installation the script asks for the location of the Java binaries and it checks the version. The Lightbox requires Java runtime 1.3 and greater for it to work correctly. The Lightbox Client is installed in ~user/lightbox/client directory.
Backup Administrator Installation
Untar the file in the users home directory and type install.sh in the users home directory. During installation the script asks for the location of the Java binary, it checks the version. The Lightbox requires Java runtime 1.3 and greater for it to work correctly.The Lightbox Backup Administrator is installed in ~user/lightbox/bakadmin directory.
The session leader must start the registry, the server, and the client by running these respective batch files in that sequence: first reg.bat, then server.bat, then client.bat. (For UNIX, use the corresponding .sh scripts instead.) The user will be asked to enter a name (which may be anything), and an IP address (which must be the IP of their computer).
Once the leader has initiated a session, then any number of others may join. Other participants in the session must start a server and a client (but not a registry). Therefore they run server.bat and clientl.bat (in that order). When queried for an IP address they enter the IP of the session leader’s computer (not their own computer).
THE BACKUP ADMINISTRATOR
The Backup Administrator is an optional component of the Lightbox. If used, only one person per session should run it (though this need not be the session leader). The Backup Administrator stores copies of all images as they are shared. When a late coming client requests the images, the Backup Administrator sends these images to the client. The Backup Manager requires the IP address of the registry to run. Use bakadmin.bat to run.
INITIATING A STAND-ALONE LIGHTBOX SESSION
A stand-alone session may be initiated when a single user simply wants to work with the Lightbox GUI, using it as an environment for image comparison and manipulation. It is not necessary for the user’s machine to be connected to the network to run a stand-alone session. By definition, image-sharing is impossible during a stand-alone session. The chat feature is also inoperable during a stand-alone session.
Double-click the icon for the client batch file. Select “Work Offline” in the Select Servers dialog box (it is not necessary to provide a host). The GUI will open.
The client has three components: the main surface, or “skin” of the Lightbox
itself; a floating toolbar; and a chat facility. The toolbar icons, however,
merely duplicate those found inline at the top of the Lightbox. Since all
functionality is equivalent, only the inline icons are explicitly described
below.
The first four icons control basic image operations:
· Open Image: opens an image using a standard dialog box from a local directory path. Once opened, the image will appear on the Lightbox surface.
· Save Selected Image: saves a copy of the selected image in its current state, using a standard dialog box.
· Close Image: closes the selected image (removes it from the Lightbox).
· Get Original Image: restores an image to its original state (useful after one or more image processing operations have been performed).
Images may be moved and arranged on the surface of the Lightbox at will. To move an image, simply select it by clicking once with the mouse, and then drag the image to the desired location. Only one image can be selected and moved at a time.
Note when an image is opened, a thumbnail copy of the image also appears along the bottom edge of the client. Clicking the thumbnail toggles that image’s display on and off in the main Lightbox area (useful if one is working with a large number of images and the display area is crowded).
The next six icons control various image processing operations:
· Increase/Decrease Contrast: adjusts the selected image’s contrast. The default is +/- 10%. Note that this can be altered by selecting “Toolbox Functions” under the Configure menu.
· Magnify/De-Magnify: used to increase or decrease the size of the selected image. The default is +/- 10%. Note that this can be altered by selecting “Toolbox Functions” under the Configure menu.
· Convert to Greyscale: converts the selected image to greyscale mode.
· Invert Image: inverts the selected image. Clicking the icon again toggles the image back to its original state.
We plan to add additional image processing operations in future releases of the Lightbox.
Above the icons, there are four menu headings: Session, View, Setup, and Configure.
The menu options under Session---Open, Save, Close, and Get Backup---are used to control the Lightbox session in its entirety. They should not be confused with the Open, Save, and Close options also available for each individual image. A Lightbox session is defined as the collection of images on screen at any given moment. Thus:
· Open may be used to restore a previously saved session (collection of images). It assumes that the images comprising the session retain their original directory paths.
· Save may be used to save the current session. Note that saved Lightbox sessions carry a .VLB extension.
· Close may be used to end the current session (but leave the client open).
· Get Backup may be used to retrieve the backup copy of the current session from the registry (useful when a participant joins an active session late).
· Finally, the Exit option may be used to terminate both the current Lightbox session and the client.
View has only a single menu option, Chat. It is used to open and close the chat facility. (Complete documentation for the chat facility follows below.)
Setup has three menu items: Snap-Grid, Peer List, and Directory Server.
·
Snap-Grid may be used to adjust the grid that
positions objects on the surface of the Lightbox and its accompanying
mouse-action from their default 1-pixel settings.
· Peer List displays the names of the other clients participating in a session.
· Directory Server allows one to edit the host address (and port) for both the local and the global session servers.
Configure likewise has three menu options: Background Color, Frame Color, and ToolBox Functions.
· Background Color presents standard color palettes that may each be used to alter the default background color of the Lightbox.
· Frame Color presents standard color palettes that may each be used to alter the default color of the selection frame.
· Toolbox Functions allows the user to adjust the parameters for image operations such as contrast and magnify. In each case the default is +/- 10%.
USING CHAT
The Lightbox’s built-in Chat facility may be opened under the View menu. Once the Chat client is activated, a participant will see a list of all participants in the current Lightbox session, a text window displaying the contents of the Chat, and an input window that can be used to communicate with the other participants (so long as they have also activated their Chat). The operation of the Chat client is meant to be basic and intuitive, but users should be aware of the following features and options:
Private Chat:
Private Chat allows a participant to send comments to one or many other participants, but not to the entire session. Any comments sent in this fashion will be prefixed with a PRIVATE tag to help distinguish this type of chat from PUBLIC chat.
When private chat is selected, only those participants selected in the chat user list will be sent messages. Users can be selected from the user list by holding <CTRL> while clicking on a users name, or a continuous group can be selected by holding <SHIFT> and clicking on the last user to include in the group.
Input Window:
The input window allows basic HTML to be used. Some tags, such as <a>...</a> do not work in the current version of Lightbox Chat. Any tags that make references to external objects, must reference a server. For example: <img src="http://server.domain.org/img.ext"> will display the specified image if a client has access to it. A local reference such as <img src="file://path/img.ext"> will not work unless that client has this file in the specified path.
Output Window:
The output window will display basic HTML and will automatically color code the messages that are received. These colors can be modified by selecting Edit->StyleSheet.
StyleSheet Editor:
The StyleSheet Editor allows the user to change the basic color coding for received text. When a type of text is selected from the tree in the left frame, its current properties will be displayed in the right frame. These properties can be changed with the drop down list for colors, and the check box for bold and italics. When the desired change has been made, the save button will apply that particular change to the current and future text.
Saving a Session:
The Chat client allows the saving of a session in either HTML or text. If HTML is selected, a StyleSheet complient browser will be able to render the colors for the saved session. When a session is saved, the date and time of the save is recorded for reference.