Package noaa.coastwatch.tools

Class cwanimate

java.lang.Object
noaa.coastwatch.tools.cwanimate
public final class cwanimate extends Object

The animate tool creates animations of earth data.

Name

cwanimate - creates earth data animations.

Synopsis

cwanimate [OPTIONS] input [input2 ...] [output]

Options:

-a, --axis NAME/INDEX | NAME/START/END[/STEP]
-c, --colormap PALETTE/MIN/MAX[/FUNCTION]
-C, --credit TEXT
-h, --help
-H, --height PIXELS
-l, --list-vars
-L, --logo NAME | FILE
-q, --query-var VARIABLE
-r, --rate FPS
-t, --title TEXT
-u, --units UNITS
-V, --variable VARIABLE
-v, --verbose
--version
-W, --width PIXELS
-z, --zoom LATITUDE/LONGITUDE[/SCALE]

Description

The animate tool creates a movie out of multiple frames of earth data. You can specify either a single file or URL to a THREDDS / DODS / ERDDAP server or multiple files on the local file system as input. The data is scaled using a color map and output with standard annotations to an output MP4 file. The defaut is to search for a time axis in the input for animation, but other axes can also be used. Before animating, you can query the input for variables and axes: 

   $ cwanimate --list-vars input.nc4
   $ cwanimate --query-var sst input.nc4

The output MP4 file contains metadata including the software version used and the command line parameters, so that you can create new animations based on existing ones. Use the exiftool on Linux or Mac to query the output file metadata.

Parameters

Main parameters:

input [input2 ...]
Either (i) a single input dataset specified as a local file name or URL containing a set of 2D data grids with additional time, level, or some other axis, or (ii) a list of input datasets each containing a single timestep of 2D data grids.
[output]
The output movie file name.

Options:

-a, --axis NAME/INDEX | NAME/START/END[/STEP]
The axis name and index/range for animation. Only one axis can be specified with a range and optional step value to animate, and all other axes with a single index value. If an axis name is not specfied, the zero index is assumed for that axis.
-c, --colormap PALETTE/MIN/MAX[/FUNCTION]
The color map assignment for the data, consisting of the palette name (see cwrender), minimum data value, maximum data value, and optionally a function type: 'linear' (default), 'log', 'stepN', or 'gamma'.
-C, --credit TEXT
The data credit text, default is the origin/institution metadata value.
-h, --help
Prints a brief help message.
-H, --height PIXELS
The height of the output in pixels, default is 720.
-l, --list-vars
Lists the variables in the input data that are available to animate.
-L, --logo NAME | FILE
The logo on the plot, default is the NOAA logo. The logo can either be a name like in cwrender, or a custom PNG, GIF, or JPEG file.
-q, --query-var VARIABLE
Performs a query of the specified variable in the input data and prints out the axis information.
-r, --rate FPS
The frame rate of the output in frames per second, default is 15.
-t, --title TEXT
The title text, default is the variable long name metadata value.
-u, --units UNITS
The units for the color map, default is to read from the input file.
-V, --variable VARIABLE
The variable data to animate.
-v, --verbose
Turns verbose mode on. The current status of creating the data animation is printed periodically. The default is to run quietly.
--version
Prints the software version.
-W, --width PIXELS
The width of the output in pixels, default is 1280.
-z, --zoom LATITUDE/LONGITUDE[/SCALE]
Zooms and recenters the view on a new latitude and longitude point. The optional zoom scale is either a screen:data pixel factor (eg: 0.5, 1, 2), a screen pixel size in kilometres (eg: '5km'), or a GIS map zoom level (eg: 'L5'). The default zoom scale is 1:1 screen:data pixels.

Exit status

0 on success, > 0 on failure. Possible causes of errors:

  • Invalid command line option
  • Invalid input or output file names
  • Unsupported input file format
  • Input file earth transforms do not match
  • Variable name not found
  • No variable specified to animate
  • Axis name not found

Examples

  • Create a chlorophyll-a animation centered on the Gulf of Mexico from a time series of NetCDF files: 
     
     $ cwanimate -v --zoom 24.7/-87.7/L5 --variable chlor_a 
     --colormap NCCOS-chla/0.01/64/log dineof/*.nc output_dineof_chlor_a_gom.mp4
  • Similar to above, but for monthly Hawaii data over a three year period and from a THREDDS server: 
         $ cwanimate -v --zoom 20.6/-156.9/L7 --axis time/0/36 --variable chlor_a 
     --colormap Turbo/0.01/1/log 
     https://oceanwatch.pifsc.noaa.gov/thredds/dodsC/noaa_snpp_chla/monthly 
     output_chlor_a_hawaii.mp4
  • Create a sea surface temperature animation centered on the Gulf of Mexico from a NetCDF 4 file containing multiple time steps downloaded from a THREDDS server using the NetCDF Subset Service: 
         $ cwanimate -v --title "SST Analysis Gulf of Mexico" --zoom 24.7/-87.7/L6 
     --variable sst_analysis_night_only --colormap Turbo/8/35 
     CW_BLENDED_NIGHT_SST_cwblendednightsst.nc4 output_sst_gom.mp4
Since:
4.0.1
Author:
Peter Hollemans

  • Method Details

    • main

      public static void main(String[] argv)
      Performs the main function.
      Parameters:
      argv - the list of command line parameters.