Home On-line Data Access FAQ Software Download
Documentation EPIC Contacts What's New Site Map
EPIC Programs Database Management EPIC I/O Library Matlab MexEPS
Web Utilities X-Motif Interface PPLUS Graphic Package Java

Java Desktop Applications

Java OceanAtlas

The Java Ocean Atlas (JOA) is an interactive Java application for viewing and manipulating oceanographic profile data, and has been integrated into the PMEL EPIC environment. This documentation is provided for EPIC users who wish to use JOA with EPIC data sets. JOA also provides import, capabilities for a wide variety of profile data formats, it is straight forward to work with your own data.

What is Java OceanAtlas (JOA)?

Java OceanAtlas (or simply JOA) is a software application for viewing and manipulating oceanographic profile data. JOA was designed primarily for oceanographic sections but is also useful for looking at data also in the latitude-longitude domain. Here's a brief list of what JOA can do:

  • Open a wide variety of standard oceanographic profile data files including EPIC netCDF (bottle, CTD, and XBT), WOCE bottle and CTD "EXCHANGE" files, WOCE netCDF bottle and CTD files, spreadsheet or tab-separated value, NODC SD2, and Mac OceanAtlas binary files. JOA can also open EPIC pointer files and zip files containing any of the accepted individual file formats. CTD files can optionally be decimated to a user-defined interval, standard depths, or to custom depths. JOA can perform sophisticated filtering of WOCE data values by quality codes.
  • Property-property plots, profile (waterfall) plots, station value plots, contour plots, residual contour plots, and maps in a variety of projections with coastlines and bathymetry. Property plots and profile plots are automatically colored by a third parameter and T-S plots can have optional isopycnal overlay. Contour plots and residual contour plots can be created using distance offset between stations or offset by latitude or longitude. Maps can optionally color station symbols by value of a parameter interpolated onto an isosurface. For example, you could make a map of salinity interpolated onto pressure surfaces or plot the surface temperature. All plots are resizable and areas of interest can be extracted to new plot windows.
  • Linked browsing between all views. Clicking on a point in any plot will identify the same point in all other views. A central data window shows the values of parameters at the selected point.
  • Wide variety of built-in calculated parameters including (potential temperature, density (built-in and custom reference pressures), heat storage, specific volume anomaly, spiciness, sound velocity, O2 saturation, AOU, NO, PO, Brunt-Vaisala frequency, squared Brunt-Vaisala frequency, potential vorticity (all buoyancy frequency calculations have settable e-folding length), alpha, beta, acoustic travel time, net heat content, potential energy anomaly, and geo-potential anomaly. A custom calculator can be used to create new parameters by arithmetic operations and derivatives on existing parameters.
  • Station Calculations. JOA can calculate the mixed-layer depth using a variety of techniques (slope, surface layer, and difference) with user-settable tolerance. JOA can calculate the integral (or weighted average) of any parameter between surfaces defined by any other parameter. For example, the integral (or weighted average) of salinity can be computed between two user-settable density surfaces.
  • Plots can be filtered by station or observation criteria. Station filters include geographic region, missing parameters, and individual station selection (include or exclude selected stations). Observation filters consists of up to 4 criteria that can be grouped using and/or logic. A criterion can test whether a particular parameter is inside (or outside) a given range or whether it's quality code (if present) matches a certain value. Plots can show or highlight the observations that match the filter criteria.
  • Extensive customization for your data or area of interest. JOA has tools for creating color bars (used for coloring plots as well as contouring), interpolation surfaces (used for contour plots), and color palettes. JOA also can save custom map settings, observation filter settings, and custom CTD decimation schemes. Existing sections can be sorted by latitude, longitude, date, and station number.
  • Plot output can be printed, saved to GIF files or "printed" to Postscript files (Windows and UNIX). MAC OS-X can print graphics to PDF files.

Getting Started With Java OceanAtlas

Downloading and Installing JOA

Note: The current version of JOA requires JDK/JRE 1.1.8 or greater. The "VM" versions of the installers will install a "local" copy of JRE 1.3.1 on your machine. Local means that this JRE is installed along with JOA relative to the JOA installation directory.

The current version of JOA is 3.1.1. If you have an earlier version, you can download the latest installers and reinstall JOA or you can just install the latest version of the JOA files that have changed since the last release. Installing just the updated files insures that any cutomized resources you may have made will be preserved. Note: The base version of JOA at PMEL is 3.1, if you have an earlier version, then you should install a new copy of JOA. Here are instructions for moving any customized resources to a new JOA installation.

Windows Instructions

There are two version of the JOA installers for Windows; one that installs a copy of the Java Virtual Machine (JVM) for use by JOA and one that uses a JVM already installed on your PC.
  1. Download JOA installer for Windows:

    (a) JOA with JVM - JOA_Win_VM.exe
    - OR -
    (b) JOA without JVM - JOA_Win_NoVM.exe

  2. On your PC, double click the JOA_Win_VM.exe to launch the JOA installer
  3. Follow the installer instructions including picking a JVM for the NoVM version of the installer.

UNIX Instructions

There are multiple forms of the JOA installer for UNIX. Currently you can download a combined JOA/Java Virtual Machine (JVM) installers for the Solaris and Linux operating systems, or a generic UNIX installer for machines that already have an installed JVM. The generic UNIX installer should work with Solaris, Linux, AIX, HP-UX, and other Java-enabled UNIX platforms.
  1. Download JOA installer for Unix: (you may need to click the link with right mouse button and select "Save Target As ..." or "Save Link As ...")

    (a) For Solaris: JOA with JVM: JOA_Sol_VM.bin
    - OR -
    (b) For Linux: JOA with JVM: JOA_Linux_VM.bin
    - OR -
    (c) For any generic Unix system: JOA without JVM: JOA_UNIX_NoVM.bin

  2. Move to the directory where you downloaded the installer. Run "chmod a+x installer_name" on the command line to make the file you just downloaded executable.
  3. Start the installer by invoking it's name from a command line. (For example, type 'JOA_Sol.VM.bin' on Solaris.)
  4. Follow the installer instructions.

Mac OS Instructions

Mac OS 9.x or earlier system requires installation of Macintosh Runtime for Java (MRJ). We provide seperate instructions for MAC OS 9.x or earlier and MAC OS X.

I. MAC OS 9.x or earlier

  1. Install Macintosh Runtime for Java (MRJ) from http://developer.apple.com/java/download.html Note: Your Mac may have MRJ already installed. JOA 3.1 requires MRJ 2.2.4 or greater. At the above web site, review which versions of Mac OS are supported by MRJ.
  2. Download JOA installer for Mac OS 9.x: JOA_Mac9_NoVM.bin
  3. Expand JOA_Mac9_NoVM.bin using Stuffit Expander
  4. Double click the expanded installation file
  5. Follow the on-screen instructions
  6. Find the files named 'mac.jar' and 'swingall.jar' in the folder where you installed JOA. Move these files to the 'MRJClasses' folder. The path to this folder is: <your System Volume>:System Folder:Extensions:MRJ Libraries:MRJClasses
  7. You do not need to restart your Mac after moving these files, but you may have to restart Java OceanAtlas if it is running when you move these files.


  1. Download JOA installer for Mac: JOA_MacX_NoVM.sit
  2. Expand Install_JOA_MacOSX.bin using Stuffit Expander
  3. Double click the expanded installation file
  4. Follow the on-screen instructions
Customizing JOA for Your Work

JOA comes from the "factory" setup for basin-scale "blue water" oceanography. JOA can be extended with custom "resource packs" that include custom coastlines and isobaths as well as colorbars, map settings, and interpolation surfaces developed for specific areas of the world. For PMEL, we have created a resource pack useful for research in the Gulf of Alaska and the Bering Sea. This pack contains a high-resolution coastline for the north Pacific as well as 50m, 100m, 200m, and 1000m custom isobaths for the Gulf of Alaska and Bering Sea. To download these resources, click the following link:


To install these resources into JOA:

1) Extract the files from the zip archive such that folder names are preserved (Use Folder Names option in WinZip). This will result in a two folders called Custom_Coastlines and Custom_Isobaths.

2) Open your JOA folder. This is where you originally installed JOA. You should have a folder called JOA_Support.

3) Copy the files from the Custom_Coastlines and Custom_Isobaths folders from the zip archive to the folders of the same name in your JOA_Support folder

To best use the contour plots and plot value coloring features of JOA, it is important that you create JOA colorbar and surface resources (and perhaps color palettes) for the type and ranges of the data that you will work with.


A colobar is the JOA term for how values of parameter (e.g., salinity) are associated with color (e.g., warm colors for high salinity and cool colors for low salinity). Colorbars are used to color observation symbols in property and profile plots and for defining how a parameter is contoured. The JOA Contour Editor allows you to select a range of values for a parameter, how many color steps in this range and whether initial colors are selected from a palette of colors or algorithmically by choosing start, end and middle colors. The mapping of values to color can be anything you chose, linear, logistic, exponential or any shape you can define. JOA can create initial colorbars with linear, logistic, or exponential shapes. Contour plots can use pre-built colorbars or create autoscaled colorbars for an individual plot. A colorbar can have a maximum of 128 levels. Click the tutorial link below to learn about creating custom color bars in JOA

Tutorial on Creating a Custom Colorbar

Interpolation Surfaces

JOA contours data by interpolating the values onto a regular grid. This grid of values is called an interpolation surface in JOA. The most common interpolation parameter is pressure but JOA allows interpolation of any parameter onto any defined surface. Interpolation surfaces need not be linear - you may want higher resolution in shallow water and lower resolution in deeper waters. The final choice for your interpolation surfaces will depend upon the nature of the data you are working with. If you are using bottle profiles you will want a surface that will generally match the spacing of the bottles. JOA has a limitation of 128 levels per interpolation surface. Click the tutorial link below to learn how to create a custom interpolation surface.

Tutorial on Creating a Custom Interpolation Surface

Custom Maps

JOA allows you to create maps of anywhere on the globe in a variety of projections. Maps can have optional graticules, coastlines, or bathymetry (isolines or etopo). After you have created a map of your study area, you can optionally save it to a settings file for use in future JOA sessions. You can also save the map settings as the default map settings for JOA.

Color Palettes

JOA comes with built in color palettes that have been created especially for oceanographic data. However, you are free to create your own color palettes for use in your own custom colorbars. Click the tutorial link below to learn how to create custom color palette

Tutorial on Creating a Custom Color Palette

Using the Smith and Sandwell 2-Minute Bathymetry Data with JOA

Smith and Sandwell is a high-resolution bathymetry resource that is compatible with Java OceanAtlas 3.1. Due to the size of this data set (around 270MB), we advise you to only use small subsets.

To use the Smith and Sandwell 2 minute bathymetry data with JOA follow these steps:

1. Go to the National Virtual Ocean Data web site at: http://www.ferret.noaa.gov/nopp/main.pl

2. In the Data Sets list, click on the link for "Smith and Sandwell 2 min topo"

3. Click the Surface relief link displayed below the "Smith and Sandwell 2 min topo" link.

4. Using either the map, the region popup, or the latitude/longitude text fields, define a subarea of the map. Bathymetry data will be returned for this area.

5. Set these options: Select View: x/y (lat/lon) slice, Select Product: netCDF

6. Click the red Get Data button. You will be prompted to save the data file on your local disk drive.

7. Change the name to be compatible with JOA. The name you choose must contain the text "ETOPO2" and end with an .nc extension. Example: ETOPO2_Kodiak.nc, etopo2_Bering_Sea.nc

8. Downloaded files and rename them. The files should be installed in the JOA_Support folder found in your JOA installation folder.

9. You will see the files you downloaded in the Bathymetry panel of the map dialog. You can use any of the ROSE colorbars to color the bathymetry.

Getting More Information

More information about Java OceanAtlas can be found using the following links:

  • Java OceanAtlas 3.0 Guided Tour: This page takes a user completely through a typical JOA session exploring water masses in the South Atlantic Ocean. The tour is based upon the 3.0 release of JOA but still includes most of the functionality of JOA 3.1. See Whats New in JOA 3.1 for a list of new features since version 3.0.

If you have any questions about JOA, please send mail to oz or epic@noaa.gov.