IBM Visualization Data Explorer (DX)

Interacting with Images

• Java Explorer's Pick mode reflects the design of Data Explorer. Select an Image then choose Pick mode. Place a pick by clicking with the left mouse button on something in the image. The original net must contain a Pick tool with appropriate wiring.
• Rotate mode provides a gnomon for rotating in the x and y planes using the left mouse button. Ctrl+mouse button rotates in the z plane.
• Zoom mode provides a 2d area of interest in response the mouse button. Ctrl+mouse button zooms out.
• Pan mode provides a single pan cursor which moves the screen in response to a mouse button drag.
• The Execution control panel provides a 'Reset Camera' button which works the same way Data Explorer's Reset menu bar option works.

Creating web pages from Visual programs

Starting with a visualization and assuming it's called myprog.net...

• Extend DXMACROS:

  
  $ setenv DXMACROS "${DXMARCROS}:installDir/java/server/dxmacros"
  
  or
  
  $ setenv DXMACROS installDir/java/server/dxmacros
  
  

• Start the new copy of dxui:

  $ dx -ui installDir/java/server/bin_arch/dxui \
      -mdf installDir/java/server/mdf/ui.mdf &
  

• Load myprog.net
• Choose 'Edit/Java/Add Tools' from the VPE menubar.
• Save the visual program.
• Choose 'Edit/Java/Save As Web Page'.
• Edit myprog.make.
• $ make -f myprog.make
• $ make -f myprog.make install

• The actual .net file which runs under control of Java Explorer is the same .net file you use when you run with the Data Explorer user interface. The 'Add Tools' step makes minor modifications to the visualization which don't interfere with using the Image window as you normally do.
• Java Explorer will not work with visual programs containing Display tools. You must manually change your nets so that you use Image tools rather than Display tools for all your images.
• Java Explorer will provide camera interaction modes and possibly pick mode for any image whose Image window in the .net file was assigned a name using the 'Options/Change Image Name' menubar option. If you're converting Display tools to Image tools, then you'll probably want to assign a name to the the original Image tools and leave the Display tools unnamed.
• 'Edit/Java/Remove Tools' reverses the affect of 'Edit/Java/Add Tools'. You can add and remove java tools as often as you like without changing the meaning of the visual program. After you add tools, you'll need to choose 'Edit/Java/Net to Applet' and build and install the resulting java code.
• After you've chosen the 'Add Tools' menubar option in the VPE, the visual program will execute more slowly under control of the Data Explorer user interface.
• The 'Save as Web Page' option will reset dxexec and start an execution in order to produce the first batch of images for your web page. This batch of images allows the web page to be complete at initial browser contact. This differs conceptually from the way Data Explorer works. When you run a visualization under control of Data Explorer you must execute once before you can see any images. If you choose the 'Save as Web Page' option when the Data Explorer user interface is not connected to dxexec, then a complete web page will be written however the images will not be saved to your disk. Of course that's perfectly reasonable if you've already saved these images.

The generated files

• myprog.html
• myprog.make
• myprog.java
• For each Image tool which executes myprog%d_0_0.[gif | wrl] Note that if dxexec is executing in a different directory than the Data Explorer user interface, you might have to go searching for the .gif or .wrl files.

The generated makefile

JARFILE=installDir/java/htmlpages
JDKFILE=/usr/jdk_base/lib/classes.zip
DXSERVER=installDir/java/server

Installing Java Explorer

installDir refers to the location in which you've unpacked the compressed tar file. If you haven't downloaded the distribution yet, click here for a compressed tar file version, or here for a zip file.

1. For cshell users... Add installDir/java/server/bin to your path:

   $ set path = ($path installDir/java/server/bin)
   

2. For pc users... Edit startserver.bat.
3. Have DX Installed
   You need to have a copy of Data Explorer installed somewhere on the system on which you are going to run the http daemon and the DXserver. Set DXROOT to where this version of dx is installed (e.g. /usr/lpp/dx).
4. Install httpd (optional)
   
5. Install JDK. Possible sources are JavaSoft or IBM.
   
6. Install a recent version of Netscape.
   You'll need Navigator 4.04 to view all the web pages however versions as early as 3.01 may allow you to view some of the web pages. If you use Internet Explorer, you'll need 4.0 or later.

Running the Java Explorer server

The web pages generated using Java Explorer use applets which detect the ip address of the machine from which they were loaded and attempt to contact a DXServer using that ip address.

If you are browsing web pages using a URL beginning with file:/, then the applets will be able to use only a DXServer running on the same machine as your browser.

After you've extended your path, can control the DXServer using the startserver and stopserver scripts.

Scripts for controlling DXServer

•  Format: startserver [ -webpage htmlfile | [ -outdir dir -outurl url ]] \
  		[ -help ] [ -debug ] [ -verbose ] [ -memory Mbytes ] \
  		[ -dxroot dir ] [ -user user ]
      -webpage.......complete path of a Java Explorer web page
      -outdir........directory into which new images should be written
      -outurl........url of the -outdir argument relative to the document base
      -help..........this message
      -debug.........print message traffic
      -verbose.......print cmd line args passed to DXServer
      -version.......the software version number of this script
      -foreground....run in the foreground in order to satisfy init
      -memory........set the amount of memory dxexec uses. 
      -dxroot........use dir as DXROOT
      -user..........run the script under a different user id
      -sessions......max number of simultaneous Data Explorer sessions (default: 1)
      -morehelp......examples
  
  

• stopserver [ host ]
       host..........the host machine of the DXServer (default is localhost)
  

Running the Java Explorer server on a pc

Configuration Files

• dxserver.paths contains directories which are searched for visual program files. DXServer locates the .net file prior to instructing Data Explorer to load the visual program.
• dxserver.hosts contains host names. DXServer will schedule Data Exlporer sessions on the hosts in dxserver.hosts in round-robin fashion. Before using this mechanism you will want to modify the following environment variables which are normally set by the startserver script:
  • $ setenv DXDATA installDir/java/server/userdata
  • $ setenv DXMACROS $DXROOT/samples/macros:installDir/java/server/dxmacros:installDir/java/server/usermacros
  • $ setenv DXINCLUDES $DXMACROS
  The startserver script modifies these for use on localhost. However, settings which work on localhost won't work on a remote machine. You must also modify dxserver.paths so that it contains a pathname beginning with a '/'.

Changes in this release

• Due to an bug in previous versions, you needed to start the Data Explorer user interface and the Data Explorer executive separately. That bug has been fixed. You should load nets saved with an earlier version and save them again.
• DXServer will use a single dxexec to service any number of connected browsers. This should enhance the scalability of Java Explorer. The startserver script understands a -session command line argument which allows you to configure the number of dxexecs which DXServer will start. You'll probably want to user multiple sessions only if you have multiple machines pointed to by your dxserver.hosts.
• Direct interaction uses visual cues which are similar to those in the Data Explorer user interface such as a rotation gnomon.
• The -memory argument now defaults to no explicit limit on the amount dxexec will allocate. This is the norm when using Data Explorer and should provide reasonable behavior given the default number of sessions which is 1.
• Now it should be easy to install web pages in directories of your choosing rather than having to use installDir/java/htmlpages. Several changes to the way dxui generates makefiles and html files and to the startserver script support this change. You may find it most convenient to have dxui generate a new makefile and html file for your existing nets in order to take advantage of these changes. Files generated with an earlier version of Java Explorer will continue to work, so no action is really required on your part.

  The issue to be aware and careful of is applets which share a codebase will be allowed to interoperate. From now on dxui will generate applet tags with a codebase="../". Then individual jar files are located relative to that codebase. The obvious alternative is an applet tag with a relative pathname in the code parameter which isn't legal.

• In addition to gif images and vrml worlds, dx objects can now be transfered into a web page through Java Explorer. This feature uses an ActiveX component in the web page and therefore works in Internet Explorer and not in Netscape. The ActiveX component uses a copy of Data Explorer installed on the machine which runs the browser in order to render its image. This also requires adding tear.exe to your path.

  This technique should be useful for web pages which benefit from frequent camera manipulation.

• A setting in your $HOME/DX file - DX*htmlDir - should be changed so that it does not include the htmlpages directory. For example:

  DX*htmlDir: /usr/http/java
  

• Two new settings in $HOME/DX are now used. They are DX*userHtmlDir and DX*userJarFile. The default settings are user and user.jar respectively. Consequently, dxui will generate makefiles which compile applets into user.jar and install user.jar into htmlDir/userHtmlDir. By default, all web pages generated by dxui will not be installed into installDir/java/htmlpages. Instead they'll be installed into a directory beside htmlpages.
• The net files you save for use with DXServer, have always used a special version of the Image macro. Now, the macro uses an internal cache setting of CACHE_LAST which should save memory.
• This 2.0.0 release begins adding the ability to use a gui builder such as VisualAge to combine Java Explorer's machine generated java code with customized gui interfaces for your web pages. Future releases will include examples of such applets. Combining the capabilites of Java Explorer with VisualAge involves importing Java Explorer's jar file, making an applet which subclasses dx.net.DXLinkApplication, and setting some of Java Explorer's properties. The documentation you would need for this is missing, so it's virtually impossible to do.

Java Interfaces

package dx.net;

public interface DXLinkHandler {
    public void outputHandler(String key, String msg, Object data);
    public boolean hasHandler(String key);
};

outputHandler() will be called once each time a value is received from Data Explorer for the corresponding DXLOutput tool. The name of the tool will be in key.

hasHandler() will be called by Java Explorer to determine if the applet intends to handle messages produced the the DXLOutput tool named in key.

References

Richard Brealy and Stewart Myers 1981. Principles of Corporate Finance. McGraw-Hill Book Company

Bugs/Issues

Issues

• Data driven selector interactors don't work in the following circumstances:
  1. The selector interactor style was set to 'Option Menu' in the Data Explorer control panel, AND
  2. The browser is Netscape 4.05 or earlier.
  This is very unfortunate since 'Option Menu' style selector interactors account for a large fraction of all data driven interactors. Some factors which make the problem a little less serious:
  1. The latest version of the Data Explorer user interface offers a new style - 'Scrolled List' - of selector interactor.
  2. The interactors do work using Internet Explorer 4.0 or later.
  The symptom you will see if you use a data driven selector in a Netscape browser is that the menu gets larger and larger with each execution of the visual program. The root cause of the problem is that Netscape's version of Java supports only the Java 1.0 api for handling the Java Choice gui object. It was only with Java 1.1 that the possibility of implementing such a beast was provided.
• All browsers used in testing this software exhibit certain cranky behavior when redrawing screen contents during a scrolling operations. The symptom is incorrectly drawn images or applets. Sometimes an applet is left completely blank. The workaround with Netscape 4.04, 4.05 and Internet Explorer 4.0 seems to be to select 'Reload' or 'Refresh'.

Bugs

• There are inputs of some interactors whose data driven-ness is not handled. This is simply a matter of the software being incomplete. Those that are handled:
  • Reset
  • Scalar, Integer, Vector
    • min, max, delta, value, decimals
  • Selector, SelectorList
    • stringdata, valuelist, index
  • Toggle
    • setvalue, unsetvalue
• Data Explorer generates incorrect java code if an interactor in your visual program has multiple interactors in control panels.
• Pan mode does not work if the image tool is using a perspective camera.
• Scalar and Integer interactor nodes may have associated with them only stepper interactors in control panels. Any other interactor types will cause runtime errors.
• Data Explorer's ui provides no way for the visual program author or the web page author to enter certain values:
  • Locations of class files in the generated makefile needed for compiling.
  • Destination directory in the generated makefile needed for installing.
  • Ordering of control panels within the generated applet.
  • The contents of the 'Select an Image Tool' menu in the 'Execution' panel of the generated applet are based only on which Images were named in the original .net file. (See 'Edit/Change Image Name' on the menubar of a DX Image window.)
• Differences in width and height requirements between the java and OSF/Motif versions of interactors can lead to overlapping interactors. As a workaround make the OSF/Motif interactors in the original visual program about a 1/4 of an inch larger than they need to be.
• Although your visual program may contain many Image tools, execution of the program in web page mode will update only those images which actually change as a result of an execution. (That's a good thing.) However if an image tool's defaultCamera input param in wired in then a new image will be transmitted to the browser with each execution. This is currently a problem even if resetCamera remains 0.
• The distributed execution mechanism works badly on AIX4.1. Because of an apparent limitation on the use of popen to run remote programs via rsh, DXServer can not run multiple simultaneous sessions. In other words if you point more than browsers at pages served by a DXServer spawning remote dx sessions, the DXServer will hang. You'll have to use $ kill -9 <pid> to clean up after it. This mechanism does work on AIX4.2.