Ocean Biogeochemistry Lab
| home | people | research | courses | facilities
| projects | protocols | publications | tools/links

Home > Research > Tools > SeaDAS 7 Command Line Help

SeaDAS 7 Command Line Help

The new SeaDAS is here... No more command line! What now... Below some help to get going again.

SeaDAS 7 is based on BEAM (now SNAP) and can be freely installed. No more expensive IDL licenses! Plus it can analyze much more than just oceancolor satellite data. But it is completely different from Seadas 6, and there are still a lot of bugs and the GUI is not that stable.

On-line SeaDAS 7 help: SeaDAS Help index, the oceancolor forums and more on the SeaDAS website, incl. tutorials. Also the BEAM forum might be helpful. On the oceancolor website there is also a library of IDL routines, esp. the HDF functions might be useful (although some are for the older (hdf) format files, and not nc/hdf5).

Unfortunately there are no real practical HowTo pages on how to actually do stuff from the command line. I will try to provide some guidance below for mostly command line stuff with gpt and other programs like l3mapgen, so you can still use it with your IDL, R, Matlab, Python, shell, etc... scripts. For getting started with the GUI, check out the lab notes of the Remote Sensing course we teach here at Stanford.

What is GPT - GPT = BEAM Graph Processing Tool. From the SeaDAS help: "This tool is used to execute BEAM raster data operators in batch-mode." So we can use it with scripts! Even IDL (or Matlab, R, whatever). The program name on Linux is gpt.sh, on a Mac it is gpt.command. Found in the bin subdirectory of the SeaDAS install. Example usage (in IDL you can use the 'spawn' command to execute this):

gpt.sh -e mosaic_sst.xml -Ssource=A20152132015243.L3m_MO_NSST_sst_4km.nc -t A20152132015243.L3m_MO_NSST_mapped.nc -f netCDF4-CF

where, input file is defined by source (A20152132015243.L3m_MO_NSST_sst_4km.nc), the output file after -t (A20152132015243.L3m_MO_NSST_mapped.nc), output format with -f (netCDF4-CF). The commands on what to do is included in the 'graph' file, in XML format (examples below). GPT has different functions, called 'operators', for example, Mosaic, Reproject, BandMaths. For help on these operators type: gpt.sh -h Mosaic for example.

GPT Mosaic Example - A simple example on how to reproject an image using the Mosaic operator with the following xml-file: mosaic_sst.xml. Usage identical to example above in 'What is GPT' section. Contents of XML file is very similar to the options in the GUI. Code explanation:
- Mosaic is the <operator>
- ${source} in <sources> is the input filename given on the command line
- sst is band to Mosaic
- I put in some conditions to only use the 'Best' and 'Good' pixels
- The GUI is a great help to format the XML file, esp. to code the projection parameters. In the 'Create Mosaic File' window select File -> Display Parameters, gives the XML code that goes in the parameters section of the XML file, incl. variables and conditions.

l3mapgen stereographic - Level 3 binned files (L3b) cannot be reprojected with Mosaic. You will have to use l3mapgen (which is part of the SeaDAS processing components). When using the GUI for l3mapgen, the drop-down list for projections seems very limited, and doesn't include stereographic for example. But, yes, you can still use other projections than listed. SeaDAS/BEAM is using proj.4 for projections. So instead of selecting a pre-defined projection in the GUI, you can just type over it with a proj.4 projection string. For example, if you used the following parameters with the 'old' SeaDAS stored in greenland_map_pfile.par, using the SeaDAS/IDL command line, as:

mapimg, bands=[1], map_pfile="greenland_map_pfile.par"

You can do it in the 'new' SeaDAS from the Unix shell command line as (with the projections parameters stored in l3mapgen_greenland.par):

l3mapgen ifile=A20152132015243.L3b_MO_CHL.nc ofile=A20152132015243.L3m_MO_CHL_mapped.nc par=l3mapgen_greenland.par

Or, using the GUI, you can paste the iproj.4 projection string +proj=stere +lat_0=72.5 +lon_0=-50 in the projection field. What is nice with l3mapgen, compared to mapimg, is that you can set the actual resolution in km. Not nice is that images projected with l3mapgen (still) don't contain geolocation info [a SeaDAS problem], so you are a bit limited with what you can do with it in SeaDAS. Also, stereographic projections over the dateline might give unexpected results [a BEAM problem].

Alternatively, you can still use the new format L3b with the old SeaDAS 6 after you convert them. L3b-files now come in netCDF4 format, while SeaDAS 6 can only deal with HDF4 L3b files. You can use the SeaDAS 7 version of l3bin to output to HDF4 with option oformat=1:

l3bin in=A20150012015008.L3b_8D_CHL.nc out=A20150012015008.L3b_8D_CHL.main oformat=1 noext=1

GPT Mosaic + Math Band Example - With gpt you can combine operators. For example, you can first project a band and then do some manipulations with Math Band on it in one go. In the example above after Mosaic'ing the sst file, all missing data were set to 0 instead of NaN, which is kind of silly since 0 can be a valid SST... With BandMaths (the gpt operator for Math Band) you can set it to NaN. This is done after Mosaic'ing, so, even 'valid' 0s will be set to NaN, not sure how to avoid this... Execution is similar as before, using mosaic_bandmath_sst.xml as the 'graph' file:

gpt.sh -e mosaic_bandmath_sst.xml -Ssource=A20152132015243.L3m_MO_NSST_sst_4km.nc -t A20152132015243.L3m_MO_NSST_mapped.nc -f netCDF4-CF

Notes on the code:
- A new node (with id bandMathNode) was added to the original file
- gpt Operator is BandMaths
- The source is not the input file but the result from the "mosaicNode"
- Expression syntax is the same as Math Band GUI (good for testing)

Passing parameters on command line - In the previous examples parameters were hard coded, like for example lat/lon boundaries. Which is fine in a lot of cases, but not when you are trying to output results from pixel value extraction for example. There is a way to pass parameters from the command line with the -P flag. From gpt.sh -h: -P<name>=<value> Defines a processing parameter, <name> is specific for the used operator or graph. In an XML graph, all occurrences of ${<name>} will be replaced with <value>.. So for example the latitude and longitude can be specified on the command line (rather than hardcoded in the XML file pixex.xml) as follows:

gpt.sh -e pixex.xml -Ssource=A20152132015243.L3m_MO_NSST_sst_4km.nc -Plat_in=32. -Plon_in=-120.

Notes on the code:
- Instead of hard-coding 32. in the <latitude> part of the XML file, we are using ${lat_in} instead, and is replace with 32. from the command line, using -Plat_in=32.
- It is easiest to create the code for the parameters section with the Pixel Extraction GUI and modify if necessary (see GPT Mosaic Example above)

Using with IDL Executing shell commands like l3mapgen or gpt.sh can be done with the IDL procedure 'spawn', for example:
IDL> cmd = 'l3bin in=A20150012015008.L3b_8D_CHL.nc out=A20150012015008.L3b_8D_CHL.main oformat=1 noext=1'
IDL> spawn, cmd

With SeaDAS 6 it was also possible to run scripts directly from the command line (seadas -b program.scr). Here is an example to do something similar in IDL, with command line options.
First line of program l3b_proj.pro: pro l3b_proj, year=year, execute from command line as:
[albedo:~ 1043]$ idl -e "l3b_proj, year='2016'"

Reading netCDF4 files with IDL

IDL> nc_file = 'A20152132015243.L3m_MO_CHL_mapped.nc' ; mapped file generated with l3mapgen above
IDL> ncdf_list, nc_file, /var, /dim, /vatt ; will list variable/dimension info
IDL> var = 'chlor_a' ; found with above command
IDL> fileid = ncdf_open(nc_file)
IDL> varid = ncdf_varid(fileid, var)
IDL> ncdf_varget, fileid, varid, chlor_a ; put data in array chlor_a
IDL> ncdf_close,fileid

Level 3 binned files are a bit harder to open. The data is in a 'group' (from the command line check out the contents with: ncdump -h l3b_filename). It is easier to extract data with HDF5 routines. (You can also use 'l3bindump' to retrieve data):

IDL> l3b_file = 'A20152132015243.L3b_MO_CHL.nc'
IDL> file_id = H5F_OPEN(l3b_file)
IDL> ; retrieve fields in BinList and chlor_a
IDL> group='level-3_binned_data'
IDL> grp_id = h5g_open(file_id, group)
IDL> dataset = 'BinList'
IDL> dset_id = h5d_open(grp_id, dataset)
IDL> binlist_grp = h5d_read(dset_id)
IDL> h5d_close, dset_id
IDL> dataset = 'chlor_a'
IDL> dset_id = h5d_open(grp_id, dataset)
IDL> chlor_a_grp = h5d_read(dset_id)
IDL> ; calculate mean chlorophyll by dividing sum with weights 
IDL> chlor_a_weights = binlist_grp.weights
IDL> chlor_a_sum = chlor_a_grp.sum
IDL> chlor_a = chlor_a_sum / chlor_a_weights  ; mean = sum/weights 

More to come...







Page by: Gert van Dijken