This software package has been created for generating grids for WAVEWATCH III using MATLAB. This
package has been developed and tested on MATLAB v7 or higher.

Documentation : Documentation is available at three levels. First, is the grid generation 
                manual -- grid_generation.pdf -- that is included with the release of the 
                software (download the images from ftp to compile tex: 
                wget ftp://polar.ncep.noaa.gov/tempor/ww3ftp/gridgen.images.tar.gz).
                The second, are the comments in the master scripts that explain
                what the individual parts of the code are doing. And finally, there are 
                brief explainations in each subroutine that can be read from the MATLAB
                workspace by typing help <name>, where <name> is the subroutine. (NOTE: The
                path to the subroutines should be set when trying this option).

Installation  : To install the gridgen to your local system, including all the required binary 
                files, run on your Matlab console:
                `cd gridgen`
                `setup_gridgen`
                
                It will take some time, depending on your internet connection, but the gridgen will
                be added to your local path and the binary files will be downloaded automatically.

GIT users     : If for any reason you want to avoid the "Installation" steps above, follow the 
                instructions below. If you are a developer and/or acquired this package through NCEP's 
                git repository, you will need to download the binary files package gridgen.tgz. 
                Large binary files are not available in the GIT repository, and need to be added to 
                your griden local copy reference_data directory. After you cd to reference_data, get 
                the binaries using:

                wget ftp://polar.ncep.noaa.gov/tempor/ww3ftp/gridgen_addit.tgz

                This will unpack the netcdf batymetry files:
                  - etopo1.nc 
                  - etopo2.nc 
                and matlab binary files:
                  - coastal_bound_coarse.mat
                  - coastal_bound_high.mat   
                  - coastal_bound_low.mat
                  - coastal_bound_full.mat    
                  - coastal_bound_inter.mat  
                  - optional_coastal_polygons.mat
.

Dependency    : Matlab and netcdf routines for matlab. 
                Netcdf toolbox for Matlab can be obtained from (http://mexcdf.sourceforge.net/)
                (NOTE: Netcdf toolbox is only used for reading the global bathymetry data files
                 If you have your own independent set of routines for reading netcdf files then 
                 only a few lines need to be changed in the 'generate_grid.m' routine. These lines
                 have been marked)

Files         :  There are 3 sub-directories
                   bin/            -- this stores all the scripts used in the grid generation routine
                   examples/       -- this stores 2 examples of master scripts that call the different
                                      subroutines for creating grids. An example for a regional grid and
                                      a global grid (which has some differences) have been shown, as well
                                      as a script that is used to modify the traditional land - sea mask for
                                      WAVE WATCH III to one for the multi-grid version (version 3.10 and 
                                      higher). This is done for the regional grid assuming that it would
                                      be nested with the global grid in the multi-grid version
                   reference_data/ -- this stores all the reference data that is needed for creating grids
                                      and includes two global grids, GSHHS shoreline polygon database and 
                                      an optional user defined polygon database (combined with a flag file
                                      that determines which of these polygons are to be used) for masking
                                      out water bodies that do not play a critical role in wave propagation

Addendums     : 1. The generate_grid function now has two extra parameters that need to be set before the call can
                   be made -- a cut-off depth and a representative depth for dry cells.
                2. Matlab now has built in support for NETCDF and those have been incorporated in the generate_grid.m 
                   routine
                3. A series of bugs were cleaned up. These are 
                   a) Getting rid of spurious NaN values in generate_grid
                   b) Changing the algorithm in compute_boundary to remove errors associated with improper
                      closing of certain boundaries
                   c) Speed up in the clean_mask routine
                   d) Generating grids only in the 0 - 360 lon range (this is the range in which the 
                      boundaries are defined, and switching to -180 - 180 range was leading to improper
                      treatment of boundary closure in certain cases.

IMPORTANT     : Gridgen now does not require the grids to be rectilinear to allow for development support for
                curvilinear grids. Thus lat / lon arrays are now 2 dimensional to allow for varying 
                resololution. Gridgen will not make the arrays needed for the grids. There are 
                number of softwares available for that, but given the grids will generate all other 
                features -- bathymetry, masks and obstruction grids. See examples for how to generate the
                2D grids for rectilinear (constant spacing lat/lon) domains 

---------------------------------------------------------------------------------------------------------------
Last updated  : 21/03/2021

## Disclaimer

The United States Department of Commerce (DOC) GitHub project code is provided
on an 'as is' basis and the user assumes responsibility for its use. DOC has
relinquished control of the information and no longer has responsibility to
protect the integrity, confidentiality, or availability of the information. Any
claims against the Department of Commerce stemming from the use of its GitHub
project will be governed by all applicable Federal law. Any reference to
specific commercial products, processes, or services by service mark,
trademark, manufacturer, or otherwise, does not constitute or imply their
endorsement, recommendation or favoring by the Department of Commerce. The
Department of Commerce seal and logo, or the seal and logo of a DOC bureau,
shall not be used in any manner to imply endorsement of any commercial product
or activity by DOC or the United States Government.