Permalink
Browse files

Added functionality for the user to add their own grids.

Includes documentation for adding your own grids.
Includes viirs2ninjo documenation and NinJo backend documentation.
  • Loading branch information...
1 parent 46f1e8a commit cd80d12034f76b299c1525d0c572c8eb0ae76d01 @davidh-ssec committed Mar 19, 2013
Showing with 473 additions and 75 deletions.
  1. +0 −14 py/polar2grid/doc/source/backends/awips_netcdf.rst
  2. +1 −0 py/polar2grid/doc/source/backends/index.rst
  3. +19 −0 py/polar2grid/doc/source/backends/ninjo.rst
  4. +1 −0 py/polar2grid/doc/source/conf.py
  5. +133 −14 py/polar2grid/doc/source/dev_guide/grids.rst
  6. +2 −2 py/polar2grid/doc/source/frontends/viirs.rst
  7. +1 −0 py/polar2grid/doc/source/glue_scripts/index.rst
  8. +10 −0 py/polar2grid/doc/source/glue_scripts/modis2awips.rst
  9. +10 −0 py/polar2grid/doc/source/glue_scripts/viirs2awips.rst
  10. +10 −0 py/polar2grid/doc/source/glue_scripts/viirs2binary.rst
  11. +10 −0 py/polar2grid/doc/source/glue_scripts/viirs2gtiff.rst
  12. +87 −0 py/polar2grid/doc/source/glue_scripts/viirs2ninjo.rst
  13. +3 −1 py/polar2grid/doc/source/grids.rst
  14. +8 −0 py/polar2grid/doc/source/polar2grid.modis.rst
  15. +27 −0 py/polar2grid/doc/source/polar2grid.ninjo.rst
  16. +32 −0 py/polar2grid/doc/source/polar2grid.rst
  17. +32 −1 py/polar2grid/doc/source/utilscripts.rst
  18. +22 −14 py/polar2grid/polar2grid/modis2awips.py
  19. +6 −3 py/polar2grid/polar2grid/ninjo/ninjo_backend.py
  20. +9 −2 py/polar2grid/polar2grid/viirs2awips.py
  21. +11 −3 py/polar2grid/polar2grid/viirs2binary.py
  22. +11 −3 py/polar2grid/polar2grid/viirs2gtiff.py
  23. +9 −2 py/polar2grid/polar2grid/viirs2ninjo.py
  24. +10 −4 py/polar2grid_core/polar2grid/core/roles.py
  25. +1 −9 py/polar2grid_modis/polar2grid/modis/modis_guidebook.py
  26. +3 −2 py/polar2grid_modis/polar2grid/modis/modis_to_swath.py
  27. +1 −1 py/polar2grid_viirs/polar2grid/viirs/viirs_guidebook.py
  28. +4 −0 py/polar2grid_viirs/polar2grid/viirs/viirs_imager_to_swath.py
@@ -53,17 +53,3 @@ Grid Name NCML File
204 `grid204.ncml <https://github.com/davidh-ssec/polar2grid/blob/master/py/polar2grid/polar2grid/awips/ncml/grid204.ncml>`_
========= =========
-More Text for testing
-
-+----------+--------------------------------------------------------------------+
-|Grid Name | NCML File |
-+==========+====================================================================+
-| 213e | `grid213e.ncml <https://github.com/davidh-ssec/polar2grid/bloml>`_ |
-+----------+--------------------------------------------------------------------+
-| 213w | `grid213w.ncml <https://github.com/davidh-ssec/polar2grid/bloml>`_ |
-+----------+--------------------------------------------------------------------+
-| 213 | `grid213.ncml <https://github.com/davidh-ssec/polar2grid/blob>`_ |
-+----------+--------------------------------------------------------------------+
-| 214 | `grid214.ncml <https://github.com/davidh-ssec/polar2grid/blob>`_ |
-+----------+--------------------------------------------------------------------+
-
@@ -14,4 +14,5 @@ simple to swap backends to make new polar2grid :term:`glue scripts`.
awips_netcdf
gtiff
binary
+ ninjo
@@ -0,0 +1,19 @@
+NinJo
+=====
+
+The NinJo Workstation Project is a meteorological workstation system for
+viewing various weather images. NinJo in some ways is like AWIPS is to
+the United States Nation Weather Service (NWS), but is used by various
+countries around the world.
+
+The NinJo backend for polar2grid was specifically developed to assist the
+"Deutscher Wetterdienst" (DWD) in displaying NPP VIIRS data in NinJo.
+This partnership between the DWD and |ssec| lead to a fairly specialized
+system that creates NinJo compatible TIFF images. NinJo allows for
+multiple "readers" or plugins to its system to allow for various formats
+to be read. The polar2grid backend is specifically for the TIFF reader
+used by the DWD. These files are different
+from regular TIFF images in that they have a number of tags for describing
+the data and the location of that data to NinJo.
+
+TODO: Rescaling
@@ -29,6 +29,7 @@ def setup(app):
rst_epilog = """
.. |ssec| replace:: :abbr:`SSEC (Space Science and Engineering Center)`
.. |viirs| replace:: :abbr:`VIIRS (Visible/Infrared Imager Radiometer Suite)`
+.. |default_grid_config| replace:: "grids.conf"
"""
# If your documentation needs a minimal Sphinx version, state it here.
@@ -18,21 +18,140 @@ version of ll2cr to calculate those values from the data it is gridding.
Adding your own grid
--------------------
-The grids module requires 1 configuration file to define the information about
-each grid. This file can be found in the source
+The grids module provides a configuration file to define the information about
+each grid that the user can specify. This file can be found in the source
`here <https://github.com/davidh-ssec/polar2grid/tree/master/py/polar2grid/polar2grid/grids/grids.conf>`_.
+If you wish to add your own grids as a replacement for or in addition to the
+provided set you'll have to make your own grid configuration file. For the
+format of a grid configuration file see the :ref:`grid_configuration_format`
+section below.
+
+Any glue script that provides the :option:`--grid-configs` command line option
+supports user-provided grids. Multiple files can be listed with this command
+line flag (space separated). If you would like to add your grids in addition
+to the package provided set of grids you must specify "grids.conf" as one of
+the files on the command line.
+
+Configuration files are processed in the order they are specified. If more
+than one grid configuration file specifies the same grid the most recently
+processed file's entry is
+used. It is recommended that you don't reuse a package-provided grid's name
+so there is no confusion about the configuration of that grid when viewing
+polar2grid products.
+
+The following steps will add a configuration file to polar2grid in addition
+to the built-in grids:
+
+1. Create a text file named anything besides "grids.conf". Open it for editing.
+2. Add a line for each grid you would like to add to polar2grid. Follow the
+ :ref:`grid_configuration_format` section below. Optionally, add a header
+ comment listing what each column is (see :ref:`grid_configuration_format`
+ for header comments).
+3. Call any polar2grid glue script and add the command line option
+ ``--grid-configs grids.conf <your-file.conf>``. If you would like only
+ your grids and not the package provided grids don't include the
+ "grids.conf" in the command line option.
+
+If you are unsure which type of grid to make, it is recommended that you
+create a PROJ.4 grid as there is more online documentation for this format
+and also allows for dynamic parameters.
+
+.. _grid_configuration_format:
+
+Grid Configuration File Format
+------------------------------
-At the time of this writing the grids module's only way of receiving
-alternative configuration files is through environment variables. The API
-allows for grids to be added, but it is up to :term:`glue scripts` to provide
-that functionality to the user.
-
-.. envvar:: POLAR2GRID_GRIDS_CONFIG
-
- The environment variable set to the path to the grid configuration file.
- See `grids.conf <https://github.com/davidh-ssec/polar2grid/tree/master/py/polar2grid/polar2grid/grids/grids.conf>`_
- for formatting details. The value of this should be an absolute path
- (starting with a '/').
+Grid configuration files are comma-separated text files with 2 possible types
+of entries, PROJ.4 grids and GPD grids. Comments can be added by prefixing lines
+with a ``#`` character. Spaces are allowed between values to make aligning columns
+easier. The following describes the 2 types of grids and each column that must
+be specified (in order). A sample header comment is also provided to add to your
+grid configuration file for better self-documentation.
+
+As discussed in the introduction of this section, PROJ.4 grids can be
+dynamic or static, but GPD grids can only be static. Of the 3 dynamic
+grid attributes (grid size, pixel size, grid origin) a maximum of 2 can
+be dynamic at a time for a single grid.
+
+PROJ.4 Grids:
+
+# grid_name,proj4,proj4_str,width,height,pixel_size_x,pixel_size_y,origin_x,origin_y
+
+ #. **grid_name**:
+ A unique grid name describing the behavior of the grid. Grid name's should not contain spaces.
+ #. **proj4**:
+ A constant value, "proj4" without the quotes. This tells the software
+ reading the configuration file that this grid is a PROJ.4 grid.
+ #. **proj4_str**:
+ A PROJ.4 projection definition string. Some examples can be found in the
+ :doc:`../grids` list, but for more information on possible parameters see
+ `PROJ.4 GenParams <http://trac.osgeo.org/proj/wiki/GenParms>`_. Note that
+ compatiblity with certain PROJ.4 string components may be dependent on the
+ version of the PROJ.4(pyproj) library that polar2grid uses, so testing
+ should be done to verify that your string works properly.
+ #. **width**:
+ Width of the grid in number of pixels. This value may be 'None' if it
+ should be dynamically determined. Width and height must both be specified
+ or both not specified.
+ #. **height**:
+ Height of the grid in number of pixels. This value may be 'None' if it
+ should be dynamically determined. Width and height must both be specified
+ or both not specified.
+ #. **pixel_size_x**:
+ Size of one pixel in the X direction in grid units. Most grids are in
+ metered units, except for ``+proj=latlong`` which expects radians.
+ This value may be 'None' if it should be dynamically determined.
+ X and Y pixel size must both be specified or both not specified.
+ #. **pixel_size_y**:
+ Size of one pixel in the Y direction in grid units. Most grids are in
+ metered units, except for ``+proj=latlong`` which expects radians.
+ This value may be 'None' if it should be dynamically determined.
+ X and Y pixel size must both be specified or both not specified.
+ #. **origin_x**:
+ The grid's top left corner's X coordinate in grid units. Most grids are in
+ metered units, except for ``+proj=latlong`` which expects radians.
+ This value may be 'None' if it should be dynamically determined.
+ X and Y origin coordinates must both be specified or both not specified.
+ For help with converting lon/lat values into X/Y values see the
+ documentation for the utility script :ref:`util_p2g_proj`.
+ #. **origin_y**:
+ The grid's top left corner's Y coordinate in grid units. Most grids are in
+ metered units, except for ``+proj=latlong`` which expects radians.
+ This value may be 'None' if it should be dynamically determined.
+ X and Y origin coordinates must both be specified or both not specified.
+ For help with converting lon/lat values into X/Y values see the
+ documentation for the utility script :ref:`util_p2g_proj`.
+
+GPD Grids:
+
+# grid_name,gpd,gpd_filename,ul_lon,ul_lat,ur_lon,ur_lat,lr_lon,lr_lat,ll_lon,ll_lat
+
+ #. **grid_name**:
+ A unique grid name describing the behavior of the grid. Grid name's should not contain spaces.
+ #. **gpd**:
+ A constant value, "gpd", without the quotes. This tells the software
+ reading the configuration file that this grid is a PROJ.4 grid.
+ #. **gpd_filename**:
+ Absolute path to a GPD file. See the
+ `ms2gt documentation <http://geospatialmethods.org/documents/ppgc/ppgc.html>`_
+ for syntax
+ and format of GPD files.
+ #. **ul_lon**:
+ Longitude of the upper left corner of the grid.
+ #. **ul_lat**:
+ Latitude of the upper left corner of the grid.
+ #. **ur_lon**:
+ Longitude of the upper right corner of the grid.
+ #. **ur_lat**:
+ Latitude of the upper right corner of the grid.
+ #. **lr_lon**:
+ Longitude of the lower right corner of the grid.
+ #. **lr_lat**:
+ Latitude of the lower right corner of the grid.
+ #. **ll_lon**:
+ Longitude of the lower left corner of the grid.
+ #. **ll_lat**:
+ Latitude of the lower left corner of the grid.
Grid corners are used during :term:`grid determination` to define a polygon
describing the grid. PROJ.4 grids' corners are calculated when needed, but
@@ -41,7 +160,7 @@ GPD grids must have their corners specified in the configuration file.
Understanding the grids module
------------------------------
-The grids module's main points of access is the
+The grids module's main points of access are the
:py:class:`polar2grid.grids.grids.Cartographer` class and the
:py:func:`polar2grid.grids.grids.create_grid_jobs` function. The
``Cartographer`` class stores all information of the grids it knows and
@@ -69,8 +69,8 @@ Histogram Equalization
TODO
-Local Histogram Equalization
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Local Histogram Equalization (Adaptive)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
@@ -58,6 +58,7 @@ The following glue scripts are included with polar2grid:
viirs2awips
viirs2gtiff
viirs2binary
+ viirs2ninjo
modis2awips
@@ -35,6 +35,16 @@ Command Line Options
the grid determination step. More than one grid can be specified at a
time. All possible grid names can be found :doc:`here <../grids>`.
+.. cmdoption:: --grid-configs <grid_config.conf> [<grid_config.conf> ...]
+
+ Specify the grid configuration files to use. If the grids being
+ specified should be added to the built-in set of grids, the first
+ argument should be |default_grid_config|. Config. files are processed
+ in the order they are specified. If a grid is specified in more than
+ one config. file the most recently processed file's entry will be used.
+ See the :doc:`../dev_guide/grids` section for information on creating
+ and adding your own grids.
+
.. cmdoption:: --fornav-d <float>
Specify the '-d' option for the fornav command line. From the fornav
@@ -38,6 +38,16 @@ Command Line Options
the grid determination step. More than one grid can be specified at a
time. All possible grid names can be found :doc:`here <../grids>`.
+.. cmdoption:: --grid-configs <grid_config.conf> [<grid_config.conf> ...]
+
+ Specify the grid configuration files to use. If the grids being
+ specified should be added to the built-in set of grids, the first
+ argument should be |default_grid_config|. Config. files are processed
+ in the order they are specified. If a grid is specified in more than
+ one config. file the most recently processed file's entry will be used.
+ See the :doc:`../dev_guide/grids` section for information on creating
+ and adding your own grids.
+
.. cmdoption:: --fornav-d <float>
Specify the '-d' option for the fornav command line. From the fornav
@@ -31,6 +31,16 @@ Command Line Options
the grid name 'all'. All possible grid names can be found
:doc:`here <../grids>`.
+.. cmdoption:: --grid-configs <grid_config.conf> [<grid_config.conf> ...]
+
+ Specify the grid configuration files to use. If the grids being
+ specified should be added to the built-in set of grids, the first
+ argument should be |default_grid_config|. Config. files are processed
+ in the order they are specified. If a grid is specified in more than
+ one config. file the most recently processed file's entry will be used.
+ See the :doc:`../dev_guide/grids` section for information on creating
+ and adding your own grids.
+
.. cmdoption:: --fornav-d <float>
Specify the '-d' option for the fornav command line. From the fornav
@@ -31,6 +31,16 @@ Command Line Options
the grid name 'all'. All possible grid names can be found
:doc:`here <../grids>`.
+.. cmdoption:: --grid-configs <grid_config.conf> [<grid_config.conf> ...]
+
+ Specify the grid configuration files to use. If the grids being
+ specified should be added to the built-in set of grids, the first
+ argument should be |default_grid_config|. Config. files are processed
+ in the order they are specified. If a grid is specified in more than
+ one config. file the most recently processed file's entry will be used.
+ See the :doc:`../dev_guide/grids` section for information on creating
+ and adding your own grids.
+
.. cmdoption:: --fornav-d <float>
Specify the '-d' option for the fornav command line. From the fornav
@@ -0,0 +1,87 @@
+viirs2ninjo
+===========
+
+.. |this_frontend| replace:: :doc:`VIIRS Frontend <../frontends/viirs>`
+.. |this_backend| replace:: :doc:`NinJo Backend <../backends/ninjo>`
+.. |this_glue| replace:: viirs2ninjo
+
+:Python Script: ``polar2grid.viirs2ninjo``
+:Bundle Script: ``viirs2ninjo.sh``
+
+This script is used to process
+:doc:`VIIRS imager data <../frontends/viirs>`
+into
+:doc:`NinJo compatible TIFF <../backends/ninjo>`
+files.
+
+`viirs2ninjo` does not have any special restrictions on the bands that can
+be provided. This glue script will also scale the DNB data using the method
+described :ref:`here <prescale_viirs_dnb>`.
+
+See the :doc:`../backends/ninjo` backend for more
+information on what scaling it does to prepare the data for the
+NinJo compatible TIFF file.
+
+.. program:: viirs2ninjo
+
+.. include:: common_opts.rst
+
+Command Line Options
+--------------------
+
+.. cmdoption:: -g <grid_name> [<grid_name> ...]
+ --grids <grid_name> [<grid_name> ...]
+
+ Specify the gpd grids to be gridded to. Specifying this option will skip
+ the grid determination step. More than one grid can be specified at a
+ time. All possible grid names can be found :doc:`here <../grids>`.
+
+.. cmdoption:: --grid-configs <grid_config.conf> [<grid_config.conf> ...]
+
+ Specify the grid configuration files to use. If the grids being
+ specified should be added to the built-in set of grids, the first
+ argument should be |default_grid_config|. Config. files are processed
+ in the order they are specified. If a grid is specified in more than
+ one config. file the most recently processed file's entry will be used.
+ See the :doc:`../dev_guide/grids` section for information on creating
+ and adding your own grids.
+
+.. cmdoption:: --fornav-d <float>
+
+ Specify the '-d' option for the fornav command line. From the fornav
+ documentation::
+
+ weight_distance_max: distance in grid cell units at which to apply a
+ weight of weight_min. Default is 1.0. Must be greater than 0.
+
+ The default for this glue script is 2.
+
+.. cmdoption:: --fornav-D <float>
+
+ Specify the '-D' option for the fornav command line. From the fornav
+ documentation::
+
+ weight_delta_max: maximum distance in grid cells in each grid
+ dimension over which to distribute a single swath cell.
+ Default is 10.0.
+
+ The default for this glue script is 40.
+
+.. cmdoption:: --num-procs <int>
+
+ Specify the number of processes in the pool that ll2cr/fornav
+ jobs are assigned to. The default is 1, meaning if multiple ll2cr
+ jobs are to be run, they will be run 1 at a time. If this flag is
+ set to 4, for example, then up to 4 ll2cr jobs can be run at once (in
+ parallel), then 4 fornav jobs can be run at once.
+
+.. cmdoption:: --sp
+
+ Force processing of navigation sets to happen serially instead of in
+ parallel. This does not affect the `--num-procs` option described above.
+
+.. cmdoption:: --rescale-config <rescale configuration>
+
+ Specify the rescaling configuration to be used by the |this_backend|. If
+ one is not specified the backend will decide which configuration is best
+ for the format and data type specified.
Oops, something went wrong.

0 comments on commit cd80d12

Please sign in to comment.