Setting up the environment to test pTolemy3D as desktop application

If you have read and followed the steps described at Developer Guide section, you have the pTolemy3D source code in your local machine and can build the binary JAR files without problems.

Although pTolemy3D is mainly intended to be used as an applet, when you are developing the pTolemy3D viewer (adding new features to the core or implementing new plugins) you would like to test it without the need to build and test in a HTML page.

JOGL library dependencies

In addition to some JAR files, handled by Maven, JOGL requires a set of wrapper and binary libraries (*.dll or *.so depending on your OS) to run properly.

• Download JOGL release from the project's site.
• Uncompress it at some place. We will call the JOGL uncompressed directory $JOGL_HOME. Normally a lib folder must exists with all required/needed libraries.

Now, when running pTolemy3D we need to set the system property java.library.path pointing to $JOGL_HOME/lib.

The test frame

If you look at the org.ptolemy3d.viewer source code package you will find two important classes: Ptolemy3DFrame and Ptolemy3DApplet. The first is a JFrame subclass, with a main() method, which allows us to execute the pTolemy3D viewer as a normal desktop application.

In the same way we need to specify some parameters when pTolemy3D is used as an applet, like: the server where the images resides, the initial camera position, etc, we can specify a XML configuration file when executing it as a desktop application. What you need to specify at the command line is:

-xmlfile [xml file] -w [screen width] -h [screen height]

where w and h params are optionals.

pTolemy3D configuration file

The syntax of the XML configuration file is very similar to the syntax using the applet's param tag. Next is an example configuration file, supposing you have a local web server with JP2 images located at http://127.0.0.1:8080/Ptolemy_test/jp2base and an icon image at http://127.0.0.1:8080/Ptolemy_test/icon.png:

<root>
    <Orientation>-100000000,40000000,4500000,0,0</Orientation>

    <CenterX>0</CenterX>
    <CenterY>0</CenterY>
    <DisplayRatio>1</DisplayRatio>

    <Server>127.0.0.1:8080</Server>

    <nMapDataSvr>1</nMapDataSvr>
    <MapDataSvr1>127.0.0.1:8080</MapDataSvr1>
    <MServerKey1></MServerKey1>
    <MapJp2Store1>/Ptolemy_test/jp2base/</MapJp2Store1>
    <MapDemStore1>/Ptolemy_test/jp2base/</MapDemStore1>

    <TILECOLOR>47,47,86</TILECOLOR>
    <Area>00</Area>
    <HORIZON>10000</HORIZON>
    <FlightFrameDelay>200</FlightFrameDelay>
    <TIN>1</TIN>
    <FOLLOWDEM>0</FOLLOWDEM>
    <Units>DD</Units>
    <BGCOLOR>0,0,0</BGCOLOR>
    <SubTextures>1</SubTextures>

    <NumLayers>2</NumLayers>

    <LayerWidth_1>52428800</LayerWidth_1>
    <LayerDEM_1>9</LayerDEM_1>
    <LayerMIN_1>50000</LayerMIN_1>
    <LayerMAX_1>10000000</LayerMAX_1>
    <LayerDIVIDER_1>0</LayerDIVIDER_1>

    <LayerWidth_2>6553600</LayerWidth_2>
    <LayerDEM_2>9</LayerDEM_2>
    <LayerMIN_2>10000</LayerMIN_2>
    <LayerMAX_2>5000000</LayerMAX_2>
    <LayerDIVIDER_2>0</LayerDIVIDER_2>

    <NumPlugins>2</NumPlugins>

    <PluginType_1>org.ptolemy3d.plugin.AxisPlugin</PluginType_1>
    <PluginParam_1>1</PluginParam_1>
    
    <PluginType_2>org.ptolemy3d.plugin.IconPlugin</PluginType_2>
    <PluginParam_2>/Ptolemy_test/stock_channel.png,40,0</PluginParam_2>

</root>

Executing pTolemy3D at desktop

Supposing you have work with pTolemy3D code and built its binay file without problems, you must go to the target directory and execute the next line, referencing the XML configuration file and setting the system property which points to the JOGL libraries:

java -Djava.library.path=path/to/$JOGL_HOME/lib -jar ptolemy3d-1.0-SNAPSHOT.jar -xmlfile path_to_config.xml

Now you are ready to hack the pTolemy3D code improving and adding new features and testing it easily in your desktop.

Executing pTolemy3D-Plugins at desktop

If what you want is to work on the pTolemy3D-Plugins project improving or adding new plugins, the steps are similar to the above.

• Ensure you have a JOGL release downloaded and uncompressed on your system.
• Write a desired XML configuration file.
• And the most important step, ensure you have the right version of pTolemy3D JAR file installed on your local Maven repository. If you have modified the pTolemy3D project code, install the JAR file using mvn install after every important modification. If not you will compile pTolemy3D-Plugins project using an old version of pTolemy3D.

Having all this, when you want to test the plugins changes, package the pTolemy3D-Plugins project using mvn clean package, change to the target folder and execute:

java -Djava.library.path=path/to/$JOGL_HOME/lib -jar ptolemy3dplugin-1.0-SNAPSHOT.jar -xmlfile path_to_config.xml

Working with Eclipse

As you may suppose, work with an IDE simplifies a lot all this steps. Once you have the source code of the project and imported it into Eclipse workspace, you can configure the execution:

• Right click on the project's node.
• Select: Run As > Run configurations....
• Now right click on Java Aplication and create a new configuration.
• Select the main class:

• Set the command line argument pointing to the configuration file and system properties:

• Apply and run.