Skip to content
Browse files

Cleared up some documentation for adding your own grids.

Added an example grid configuration file/directory that should be
added to the swbundle from now on.
  • Loading branch information...
1 parent d0140c3 commit 666989f4344b4b759131f5d3bd34a3527e030c3e @davidh-ssec committed
View
2 py/polar2grid/doc/source/backends/ninjo.rst
@@ -17,3 +17,5 @@ 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
+
+The NinJo backend can only support the DWD Germany GPD grid at the moment.
View
40 py/polar2grid/doc/source/dev_guide/grids.rst
@@ -18,13 +18,13 @@ version of ll2cr to calculate those values from the data it is gridding.
Adding your own grid
--------------------
-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
+Polar2Grid allows users to define and add their own grids for remapping in
+any glue script. The Polar2Grid package provides a default set of grids that
+can be specified on the command line with most :term:`glue scripts`.
+This built-in configuration file can be found in the source on github
`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.
+provided set you'll have to make your own grid configuration file.
Any glue script that provides the :option:`--grid-configs` command line option
supports user-provided grids. Multiple files can be listed with this command
@@ -43,10 +43,12 @@ 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.
+ For software bundle users, there is a ``grid_configs`` directory in the
+ root of the software bundle where user configuration files can be stored.
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).
+ :ref:`grid_configuration_format` section below. This section also has
+ header comments specifying each column that can be added to your file
+ for clarity.
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
@@ -56,17 +58,34 @@ 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.
+.. note::
+
+ The decision of whether a grid is supported or not is ultimately up to
+ :doc:`the backend <../backends/index>` used by a glue script. Some
+ backends support any grid (GPD or PROJ.4) and others only a handful.
+ Check the :doc:`../backends/index` section for your specific backend.
+
+.. warning::
+
+ Some glue scripts force a certain built-in grid by default. These type
+ of glue scripts will fail if no grid is forced (:option:`-g` flag) or
+ the built-in grid configuration file is not provided.
+
.. _grid_configuration_format:
Grid Configuration File Format
------------------------------
+Example Grid Configuration File: :download:`grid_example.conf <../../../../../swbundle/grid_configs/grid_example.conf>`
+
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.
+grid configuration file for better self-documentation. The example grid
+configuration file linked to above can also be found in the software bundle in
+``swbundle/grid_configs/grid_example.conf``.
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
@@ -103,7 +122,8 @@ PROJ.4 Grids:
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
+ Size of one pixel in the Y direction in grid units (**MUST** be negative).
+ 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.
View
37 swbundle/grid_configs/grid_example.conf
@@ -0,0 +1,37 @@
+###############################################################################
+### Polar2Grid Example Grid Configuration File ###
+###############################################################################
+# Description: This file provides a few working examples of various types of
+# grids that can be added to polar2grid. This file is to help
+# a user add their own grids to polar2grid in addition to the
+# documentation at
+# http://www.ssec.wisc.edu/software/polar2grid/dev_guide/grids.html
+#
+# PROJ.4 Grids:
+# PROJ.4 grids may have 'None' for grid size, origin, or pixel size to be
+# considered 'dynamic'. PROJ.4 grid components:
+# - Grid Size (Width and Height): Number of pixels of the grid
+# - Pixel Size: Size of each individual pixel in the grid domain
+# (meters in most cases, radians for latlong projections).
+# **Y Pixel Size must be negative**
+# - Origin: The top-left location in the grid domain (meters in most cases)
+#
+# Pixel size or grid size may be unspecified (dynamic), but not both.
+# Dynamic grid attributes are calculated from the data being remapped.
+# Of the examples below only 'p4_211e' is a static PROJ.4 grid, the others
+# are dynamic in some way.
+# PROJ.4 Parameters: http://trac.osgeo.org/proj/wiki/GenParms
+#
+# grid_name, proj4, proj4_str, width, height, pixel_size_x, pixel_size_y, origin_x, origin_y
+p4_211e, proj4, +proj=lcc +datum=NAD83 +ellps=GRS80 +lat_1=25 +lon_0=-95 +no_defs, 5120, 5120, 1015.9, -1015.9, -1956254.806724622, 4364276.201489102
+lcc_fit, proj4, +proj=lcc +datum=WGS84 +ellps=WGS84 +lat_0=25 +lon_0=-95, None, None, 1000, -1000, None, None
+simple_square, proj4, +proj=lcc +datum=WGS84 +ellps=WGS84 +lat_0=25 +lon_0=-95, 1500, 1500, 1000, -1000, None, None
+wgs84_fit, proj4, +proj=latlong +datum=WGS84 +ellps=WGS84 +no_defs, None, None, 0.0001, -0.0001, None, None
+polar_canada, proj4, +proj=stere +datum=WGS84 +ellps=WGS84 +lat_0=90 +lat_ts=45.0 +lon_0=-150, None, None, 1000, -1000, None, None
+#
+#
+# GPD Grids:
+# Note that GPD grids require an external GPD file to be specified (absolute paths).
+#
+# grid_name, gpd, gpd_filename, ul_lon, ul_lat, ur_lon, ur_lat, lr_lon, lr_lat, ll_lon, ll_lat
+211e, gpd, grid211e.gpd, -123.044, 59.844, -49.385, 57.289, -65.091, 14.335, -113.133, 16.369

0 comments on commit 666989f

Please sign in to comment.
Something went wrong with that request. Please try again.