Allan Spale Electronic Visualization Laboratory, University of Illinois at Chicago November 2004 ImmersaView Launcher is an Access Grid shared application that allows the user to launch an application named ImmersaView that runs on a PC separate from the Access Grid. Please note that this software is not operating system specific. Any operating system that can run ImmersaView, Python, and the Access Grid is acceptable to operate the software for ImmersaView Launcher. There are a number of files contained in the ZIP archive. There are two files contained in this ZIP file: ImmersaViewLauncher.zip and ImmersaViewLauncherControl.zip. Place the file named ImmersaViewLauncher.agpkg on your Access Grid venue client by following the instructions below. Place ImmersaViewLauncherControl.zip in the base directory where ImmersaView is installed. ImmersaView Launcher ==================== I. System Requirements ImmersaView Launcher: Access Grid Toolkit 2.3 and its prerequisite software II. ImmersaView Launcher A. Installation 1. Please make sure that all of the prerequisite software is already installed. 2. Make sure that you are installed as administrator or root. 3. Go to the command line and type the following: a. cd /AGTk2.3/bin b. agpm.py -v -s -z ImmersaViewLauncher.zip 1. Here is an explanation about the flags: -v is for verbose, -s is to install the shared application for all users, and -z indicates that the files are installed in a ZIP file B. Configuration file 1. A configuration file appears in the directory where ImmersaView Launcher was installed named iview-launcher.cfg. Open it with a text editor. 2. If this is the first time that you are editing the file, read this section; otherwise, skip to the next step. It is not necessary to perform this step; however, it will be easier to enter this information now because ImmersaView Launcher will load this information each time it runs. a. Notice the names of the fields that are editable along with the description that appears describing each one. b. Delete the description listed for a field and replace it 3. Delete the description for each field and replace it with the appropriate information whether it is a path or filename. Filenames are less crucial to keep persistent because it is likely that they will change even within a session. C. Operation 1. Make sure that you are connected to an Access Grid virtual venue server. 2. (only necessary if ImmersaView Launcher does not already appear in the venue client) To add ImmersaView Launcher as a shared application to the current venue, right-click on Applications and select "Add ImmersaView Launcher". 3. Right-click on ImmersaView Launcher and select "Open". 4. The GUI for ImmersaView Launcher should appear with the information specified in the configuration file mentioned in part B. Change any of the fields as needed. 5. There are two types of buttons: global and local. Pressing a global button will send an event to all sites connected to the ImmersaView Launcher session. Pressing a local button will only affect your site. Even if a local button type is pressed, it is still possible to receive future global events. Before pressing the "Start Global" button, please make sure that all sites in this shared session have entered the correct configuration information in the GUI. 6. After pressing "Start Local" or "Start Global", ImmersaView Launcher will look for the ZIP file in the specified model directory on the PC running the AG venue client. It is important that these ZIP files are downloaded from the venue before they are used in the session. Also, please do not rename these files or change the contents of these files unless you are specifically told to do so. Since these ZIP files are posted to an Access Grid venue, everyone should be downloading the ZIP files with the same name and the same contents. D. Troubleshooting 1. ImmersaView Launcher has ImmersaView load the wrong model or the file is not available. a. Global buttons will launch an ImmersaView session for everyone tied specifically to the name specified by the site that presses the "Start Global" button. After the site presses this button, the name of the ZIP file used for the session should be transmitted to all participating sites. b. If this information is correctly received, the ZIP file name should replace whatever previous name you had in the model field. If this information is not received, select the ZIP file manually from the appropriate directory and press the "Start Local" button. c. If the ZIP file is already began transferring to the ImmersaView PC, follow these directions. 1. Let ImmersaView finish loading and let it start running. 2. On ImmersaView Launcher, press "Stop local". This will stop your local session of ImmersaView. 3. Make the appropriate changes to the fields in ImmersaView Launcher with the appropriate information for starting ImmersaView with the correct information for this session. 4. On ImmersaView Launcher, press "Start local". This will start ImmersaView locally. ImmersaView should load the correct model. The application will still be able to receive future global events (i.e. stopping the session). 2. ImmersaView Launcher cannot connect to ImmersaView Launcher Control. a. Make sure that a valid text name and port number are given in the "ImmersaView PC" connection information. b. Make sure that ImmersaView Launcher Control is running with the correct port number specified. c. Make sure to specify the correct ImmersaView base path name. Similarly, make sure that the spellings of file names and path names are correct. 3. There are now other error messages that appear for starting ImmersaView that are more descriptive than the single "catch-all" message that was used in the past. ImmersaView Launcher Control ============================ I. System Requirements ImmersaView Launcher Control: Python 2.2 III. ImmersaView Launcher Control A. Installation 1. Transfer the zip file named ImmersaView Launcher Control to the computer that runs ImmersaView. 2. Unzip the file into the base directory of ImmersaView. B. Operation 1. Run the Python script named ImmersaViewLauncherControl and note the port number where the server is listening for messages (default is 8000). 2. Any sort of transaction, whether it was successful or failed, that occurs on the server will be displayed in the command window. 3. WARNING: Because of the absence of security mechanisms implemented with the ImmersaViewLauncherControl Python script, the nature of XML-RPC calls that are permitted on the machine, and the ability for ANYONE to be able to connect to this XML-RPC server and execute commands, it is STRONGLY recommended that the ImmersaView Launcher Control only run for the duration of the presentation in order to minimize possible security problems. The reason for not providing security with the server was because it permitted the proof of concept to be established that would validate the general design of ImmersaView Launcher. a. The security threat is a bit lessened than in the original version because someone who wants to launch a distributed attack will have to put in a bit more effort. The server no longer makes directories, but it still forcibly transfers files and executes a batch file named in a certain manner without any authentication. 4. When the session ends, remember to make sure to stop running ImmersaView Launcher Control. C. Troubleshooting 1. If there was an error closing ImmersaView Launcher Control, the program may have closed, but the port may still be in use. There are two options: wait the specified amount of time for the port to be closed or edit the ImmersaViewLauncherControl.py script to change the port number used for the program. Please note to make this port number change when connecting with ImmersaView Launcher. 2. Other somewhat descriptive messenges will appear if ImmersaView did not start or stop correctly. 3. If ImmersaView is not functioning as expected, ask yourself the following questions... a. Make sure that correct server name is listed in the StereoCameras.iv file in the directory named configFiles? b. (Mac and Linux only) Make sure that the script named make-symbolic-links exists. c. If you are running ImmersaViewserver AND running a firewall, make sure that you collect the IP addresses of the participants and add these addresses to a trusted list in your firewall. d. Make sure that there are no spaces for the pointer name because only the characters up to the space will be printed before the space.