Using_VisIt_in_NiCE

The Visit Visualization Tool offers scientists and researchers powerful visualization and data analysis capabilities. These capabilities may be accessed interactively via VisIt's graphical user interface or by VisIt's command line interface (CLI) with its Python API. In order to use the tool from within software developed in Java, VisIt also provides users with a Java API packaged as a JAR file, which is available at the VisIt downloads page. Examples of using this API can be found here.

NiCE uses the VisIt Java API to perform a variety of data analysis and visualization tasks. In order to integrate VisIt into NiCE, an OSGi bundle was created by using the "injection method", which inserts the required OSGi bundle definition information into the JAR's MANIFEST.MF file. Tools within Eclipse for RCP and RAP Developers were used to implement this method. The resulting bundle, gov.ornl.nice.visitjava, contains all of the packages and classes that are available in the current VisIt Java API.

In order to utilize the gov.ornl.nice.visitjava bundle from within NiCE, the gov.ornl.nice.visitanalysistool (or "VisItAnalsysisTools") plugin has been developed. By implementing the interfaces found in the gov.ornl.nice.analysistool package, the VisItAnalsysisTools plugin provides NiCE the following capabilities shown in the list below. When included in within NiCE, the resulting image can then be manipulated and displayed within a NiCE ResourceComponent.

• Launch VisIt as a service running on a background port.

• Open a datafile in the SILO format.

• Extract a list of scalar quantities available for plotting as a Pseudocolor plot.

• Create Pseudocolor plots for a subset of available quantities.

• Set each plot's attributes to custom or default values.

• Store the Pseudocolor plot on disk as a PNG image.

Using the VisIt OSGi Bundle from an OSGi Plugin

This section details how to create an OSGi plugin which uses the VisIt OSGi bundle with tools in Eclipse for RCP and RAP Developers. It assumes that all of the steps listed in the Getting NiCE Wiki Article have been completed successfully. These steps include downloading all of the NiCE source from the NiCE Repository.

Before using the VisIt bundle, an OSGi plugin must be created. From Eclipse, select File > New > Plugin Project. Then enter the Project Name in the field provided and select "an OSGi framework" under the Target Platform section. Click "Next" to continue. On the next screen, be sure that the "Generate an activator.." checkbox is checked and then click "Finish" to create a new plugin project. Next we must add the VisIt bundle as a required dependency in the MANIFEST.MF in the META-INF directory of the new plugin. To do so, right-click on the MANIFEST.MF file and select Open With > Plugin Manifest Editor. Under the Dependencies tab, click "Add" in the Required Plug-ins section. Under Select a Plug-in, enter "gov.ornl.nice.visitjava" and click OK. Next create a new Java class under the package displayed in the plugin's src directory. To do this simply right-click on the package and select New > Class. Enter a name for the class in the Name field and click "Finish". You should now be able to recognize imports from the "llnl.visit" package and the "llnl.visit.operators" and "llnl.visit.plots" subpackages.

In order to launch this plugin as an OSGI service, we need to modify the Activator class in the plugin's source package. Open Activator.java and insert code into the start method that will instantiate and call any desired methods from your new Java class. The last step is to run the plugin as an OSGi service. To do this, right-click on the plugin package and select Run As > Run Configurations. Then right-click on OSGi Framework in the menu on the left and select "New". Under the Bundles tab click "Deselect All". Now we must choose the bundles we wish to include in this new OSGi Framework. In the Bundles table, select your plugin, gov.ornl.nice.visitjava and org.eclipse.osgi.services. Then click "Apply" followed by "Run". This will launch the new OSGi service using Visit's Java API.

<gallery> File:Create_osgi_plugin.png|Creating a new OSGi Plug-in Project File:Create_osgi_class.png|Creating a new Java class in the Plug-in Project File:Import_visit_java_api.png|Importing the VisIt Java API packages into the new Java class File:Activator_start_code.png|The addition of code to Activator.java to instantiate the new Java class </gallery>

Using the VisItAnalysisTools Plugin

The VisItAnalysisTools plugin consists of three classes and one enumeration: VisItAnalysisTool, VisItAnalysisDocument, VisItAnalysisAsset and VisItAnalysisPictureProperty. As seen in the class diagram below, these classes implement the interfaces described in the gov.ornl.nice.analysistool plugin.

[-img src=Visitanalysistool class diagram.png: missing =-]

Let's examine the rolls of each of these classes. The VisItAnalysisTool class acts as a wrapper class for a running VisIt process. Upon instantiation, this class configures and launches VisIt via classes in the gov.ornl.nice.javavisit bundle. Notice that the VisItAnalysisTool class has two constructors. The parameterized constructor requires two arguments: the path to the VisIt installation's "bin" directory and the port number used for launching VisIt as a service running in the background. If the nullary constructor is used, the System Properties listed in the table below must be set. Go here to view descriptions of other System Properties possibly required by NiCE.

System Property Description Example Value

visit.binpath
The absolute path to the local installation of VisIt used by the VisItAnalysisTools bundle.
/usr/local/visit/bin

visit.port
the port number used for launching VisIt as a service running in the background.
5600

The VisItAnalysisDocument class represents a particular set of data which allows access to quantities available for plotting by VisIt. An object of this type holds a collection of VisItAnalysisAssets. A VisItAnalysisAsset corresponds to a particular quantity that will be plotted and saved as a PNG image. Users can robustly modify the plot's appearance by setting property values for a VisItAnalysisAsset object via the setProperty() operation. The names of these properties correspond to the enumeration literals contained in the VisItAnalysisPictureProperty enum. The string used as property name in the setProperty() operation can be accessed by calling the enumeration literal's toString() operation. The table seen below lists the property name, description and available values as well as the corresponding VisItAnalysisPictureProperty enumeration literal.

Property Name VisItAnalysisPictureProperty Literal Property Description Available Values

Colortable
COLORTABLE
The image's colortable by name
The available color table names are retrieved by calling the getColorTables() operation in VisItAnalysisAsset.

Database Label Type
DATABASE_LABEL_TYPE
The type of database label
Available types are "File", "Directory" and "Full".

Image Width (pixels)
IMAGE_WIDTH
The image's width in pixels
Integer

Image Height (pixels)
IMAGE_HEIGHT
The image's height in pixels
Integer

Invert Colortable
INVERT_COLORTABLE
Whether or not to invert the selected color table
"true" or "false"

Mesh Name
MESH_NAME
The name of the mesh to be displayed. A value of "true" must be set for the "Show Mesh" property for the selected mesh to be displayed.
All available mesh names can be accessed by calling the getAvailableMeshes() VisItAnalysisAsset operation.

Pan X
PAN_X
The image's pan x value
Double

Pan Y
PAN_Y
The image's pan y value
Double

Scale Minimum
SCALE_MIN
The scale's minimum value. VisIt's default value will be used if an empty string is passed as the value of this property.
Double

Scale Maximum
SCALE_MAX
The scale's maximum value. VisIt's default value will be used if an empty string is passed as the value of this property.
Double

Scale Skew Factor
SCALE_SKEW_FACTOR
The scale's skew factor. A value of "Skew" must be set for "Scale Type" for this property to take effect.
Double

Scale Type
SCALE_TYPE
The scale's type. If "Skew" is selected, then a value for "Scale Skew Factor" should be set.
Available types are "Lin", "Log" and "Skew".

Show Axes
SHOW_AXES
Whether to display the x, y, and z axes
"true" or "false"

Show Bounding Box
SHOW_BOUNDING_BOX
Whether to display a bounding box
"true" or "false"

Show Database Label
SHOW_DATABASE_LABEL
Whether to display the database label
"true" or "false"

Show Date and User
SHOW_DATE_AND_USER
Whether to display the image's creation date and user. Note that in the current version of VisIt these properties can not be decoupled.
"true" or "false"

Show Legend
SHOW_LEGEND
Whether to display the legend
"true" or "false"

Show Mesh
SHOW_MESH
Whether to display the mesh. A value for "Mesh Name" must also be set for this to be applied to the plot.
"true" or "false"

Show Triad
SHOW_TRIAD
Whether to display the triad
"true" or "false"

Angle of View (degrees)
VIEW_ANGLE
The angle of view in degrees
Double

View Normal X
VIEW_NORMAL_X
The X component of the unit vector normal to the view
A double between 0 and 1

View Normal Y
VIEW_NORMAL_Y
The Y component of the unit vector normal to the view
A double between 0 and 1

View Normal Z
VIEW_NORMAL_Z
The Z component of the unit vector normal to the view
A double between 0 and 1

View Up X
VIEW_UP_X
The X component of the unit vector pointing up
A double between 0 and 1

View Up Y
VIEW_UP_Y
The Y component of the unit vector pointing up
A double between 0 and 1

View Up Z
VIEW_UP_Z
The Z component of the unit vector pointing up
A double between 0 and 1

X Axis Label
X_AXIS_LABEL
The X axis label
String

Y Axis Label
Y_AXIS_LABEL
The Y axis label
String

Z Axis Label
Z_AXIS_LABEL
The Z axis label
String

X Axis Units
X_AXIS_UNITS
The X axis units.
String

Y Axis Units
Y_AXIS_UNITS
The Y axis units.
String

Z Axis Units
Z_AXIS_UNITS
The Z axis units.
String

Zoom Level
ZOOM_LEVEL
The zoom level in percent.
Double