Vectorize: a THREDDS plugin

About

This plugin allows THREDDS projects to read vector data stored as u and v components as magnitude and direction components (useful for showing vectors with WMS).

It leverages netCDF-Java's service provider mechanism for Enhancements to make two new Attributes readable to NetCDF-Java and virtually modify a dataset. It can be used from the THREDDS Data Server or directly from the netCDF-Java library.

Deploying

Step 1: jar the plugin with mvn package
Step 2: put the jar on your netCDF-Java classpath (see Runtime Loading).
Step 3: That's it, it should just work.

Requirements

• netCDF-Java 5.6.1+ (or SHAPSHOT releases after 10/25/2024)
  • netCDF-Java 5.6.1+ is packaged with TDS 5.6+ (or SNAPSHOTS from after the same date)
  • TDS 5.6+ requires Java 17 and Tomcat 10

How to use it

To use Vectorize, you will need to do the following: 1) make two new variables in your dataset in the same Group as your u and v: one for vector magnitude and one for vector direction 2) give these variables the same Dimensions as your u and v variables (u and v must share the same Dimension set) 3) add an Attribute to your magnitude variable with name="vectorize_mag" and value="{U var name}/{V var name}" 4) add anAttributeto your direction variable withname="vectorize_dir"andvalue="{U var name}/{V var name}"`.

These new variables will be read by NetCDF-Java (and the TDS) as the magnitude and directions of the provided u and v variables.

netCDF-Java API

If you're using netCDF-Java directly in your project, you can add the new Variables as follows:

  NetcdfFormatWriter.Builder builder = NetcdfFormatWriter.openExisting("pathToMyFile");

  // add new variables with attributes
  builder.addVariable(magVar, DataType.FLOAT, "myDim")
          .addAttribute(new Attribute(VectorMagnitude.ATTRIBUTE_NAME, "myUVarName/myVVarName"));
  builder.addVariable(dirVar, DataType.FLOAT, "myDim")
          .addAttribute(new Attribute(VectorDirection.ATTRIBUTE_NAME, "myUVarName/myVVarName"));

  // write data to new vars
  NetcdfFormatWriter writer = builder.build()
  Array indices = Array.makeArray(DataType.FLOAT, dataLen, 0, 1);
  writer.write(writer.findVariable(magVar), indices);
  writer.write(writer.findVariable(dirVar), indices);

See here for more about writing to NetcdfDataset objects.

NcML

If you're using the plugin in the TDS, you can add virtual variables to your dataset with NcML:

<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2" location="{myDatasetLocation}">
  ...
  <variable name="magtitude" shape="{ same dims as U and V }" type="float">
    <attribute name="vectorize_mag" value="myUVarName/myVVarName" />
    <values start="0" incr="1" />
  </variable>
  <variable name="direction" shape="{ same dims as U and V}" type="float">
    <attribute name="vectorize_dir" value="myUVarName/myVVarName" />
    <values start="0" incr="1" />
  </variable>
  ...
</netcdf>

See here for more on using NcML.

Developing and testing

This project uses basic maven to build, test, and package.

• To test: mvn test
• To build:mvn compile
• To create a jar file: mvn package