Jazz

Introduction

     Jazz is a Java-based data display designed for scientific use. The display can be used to explore datasets in various data formats (MDV, SPDB, NetCDF, etc) as well as Open Geospatial protocols (WMS, WFS, and WCS). It supports thematic basemaps from Shapefile, WMS, and CIDD Map, as well as multiple feature overlays from WFS and ADDS Dataserver. It slices data in five dimensions: horizontal slices at selectable altitudes over time for selectable model runs and lead times. It is highly customizable through a simple XML configuration file that can be shared with colleagues. It also contains a suite of optional tools for more advanced data analysis and depiction.

     The Jazz display is built on top of the RAL-developped JADE toolkit. That toolkit has been used for the ADDS Flight Path Tool and HEMS Tool, ATEC JViz, MDSS display, and several other research displays. The toolkit is still under active development. We welcome your feedback about any of its applications.

     Jazz is free to use under the terms of this BSD license.

Running Jazz

Due to Oracle's new licensing requirements for Java, RAL has moved to using the Open-Source OpenJDK for Jazz development and releases. This should not affect any of the application's functionality, but changes slightly how you launch Jazz.

If you are using OpenJDK (recommended) or a newer, licensed, version of the Oracle JDK that does not have Java WebStart

Make sure you have Java (JRE or JDK) 11+ installed on your system and verify that it is in your search path by running the command:
java -version
You should see a confirmation, such as: "openjdk 11.0.1 2018-10-16"

Download this zip file (sha256) and unpack it with the command:
unzip jazz.zip

Go into the newly created directory and launch Jazz with this command:
java -jar jazz.jar .
Additional options are documented in the README.run file.

The latest release of Jazz, which requires JRE 11+, is v2.8.14, released on 11/12/2023 (Release Notes)

You should automatically be updated to this version (and future versions) when you restart Jazz.

NOTE: In the unlikely event that you are still on Linux Debian Jesse OS, this release may NOT work for you, as the default JDK for that OS is the old JDK 8 in /usr/local/jdk. In that case, you have two options:

You can point to a JRE/JDK 11+ explicitly by setting your $JAVA_HOME environment variable to point a JRE/JDK 11+ installation, like this:
- for bash in ~/.profile: export JAVA_HOME=/usr/local/jdk11
- for csh in ~/.cshrc: setenv JAVA_HOME /usr/local/jdk11
then source your updated environment and confirm that your path is picking up the correct Java as described in step #1 above.
or you can use an older version of Jazz that is supported by JRE/JDK 8. That previous version is v2.5.2, released on 12/17/2019 (Release Notes)
To run this earlier release, you will need to paste this getdown.txt configuration file in place of the 'getdown.txt' file that already exists in your Jazz installation directory and then restart Jazz. If that does not work (Jazz doesn't start or it still comes up with the latest numbered version), you may need to do a fresh installation of this static version by:
1. Deleting your entire Jazz installation directory (beware of not deleting any of your XML configurations) and
2. Downloading this zip file (sha256) and unpacking it with the command:
  unzip jazz.zip

Configuring Jazz

     To view all of the documentation for Jazz XML configuration files, select "Config Help..." from the "Help" menu or run Jazz from the command with a "-help" argument, like this:
          java -jar jazz.jar . -help
     The help text will be displayed in the jazz.log file, located in the unzipped directory where you are running Jazz.

     To see a working configuration, download this sampleConfig.xml. NOTE: this link WILL NOT render in a browser because it's raw XML. You must right-click and choose to save the link locally instead. Then load the file from the configuration chooser dialog when Jazz first starts.

     To automatically configure Jazz from an existing MDV and/or SPDB server, run Dan Adriaansen's very useful jazzparamgen tool. It generates a Jazz config file for you, containing every field on the server(s). You can download it from https://github.com/NCAR/jazzparamgen.

Upgrading to Jazz from CIDD

If you are currently a CIDD user, you can use the CiddParams2JazzXml application to convert your CIDD parameter files to Jazz configuration files. This application is included in the RAL nightly builds so can be found in /rap/dev/bin and /rap/bin on RAL internal hosts. If you are an external user, you will have to get a copy of the application from your RAL contact. Note that Jazz does not currently support all of the options available in the CIDD parameter file so only those options that are supported are included in the Jazz XML file. Some CIDD parameters cannot be converted exactly into the Jazz XML.

Parameters that might need some tweaking when converting CIDD parameter files into Jazz XML configuration files:

In Jazz, all CIDD-style colorscale files must use the ".colors" extension. CiddParams2JazzXml will copy the colorscale filenames as they appear in the CIDD parameter file, so the user will need to rename these files and update the Jazz XML file with the new names.
Jazz has an MDVWIND layer, but it is not implemented in the same way as the CIDD WINDS layer. CiddParams2JazzXml goes ahead and converts the CIDD WINDS layers to Jazz MDVWIND layers, but these will probably have to be updated once we implement CIDD-style wind layers in Jazz.
In the GUI_CONFIG section. CIDD allows you to include the same field in multiple field lists. Jazz allows fields to only appear in a single menu. So, if a field in the CIDD parameter file is found in multiple field lists, it will only appear in a single menu in the Jazz XML file.

Direct questions or comments to Arnaud Dumont (dumont@ucar.edu).