wip

docs/Makefile

@@ -18,3 +18,6 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/index.rst

@@ -6,21 +6,91 @@
 raster-footprint
 ================
 
-A Python package for creating polygons surrounding valid data in a raster, i.e.,
-creating raster footprints.
+A Python package for creating GeoJSON containing polygons surrounding valid data in a
+geospatial raster.
 
 .. note::
 
    This package is in Beta development status. Use at your own risk.
 
+What is a raster footprint?
+---------------------------
+
+One or more polygons that surround valid data in a geospatial raster, or a single
+polygon surrounding the entire raster grid. The polygon data is stored in a GeoJSON
+geometry object. For example:
+
+.. code-block:: json
+
+   {
+      "type": "Polygon",
+      "coordinates": [
+         [
+            [1.0, -1.0],
+            [1.0, -7.0],
+            [7.0, -7.0],
+            [7.0, -1.0],
+            [1.0, -1.0]
+         ]
+      ]
+   }
+
+Per the GeoJSON `specification <https://datatracker.ietf.org/doc/html/rfc7946>`_, the
+coordinate reference system (CRS) for all GeoJSON coordinates is WGS84 (EPSG:4326).
+However, it is possible to specify the a CRS other than WGS84 for the generated
+footprint.
+
+Why use raster-footprint?
+-------------------------
+
+It provides options for mitigating projection distortion and a number of ways to
+simplify footprints (reduce coordinate count). For example, a basic footprint extraction
+and reprojection to WGS84 for a MODIS raster produces a footprint with gaps and gores
+and over 1,000 vertices:
+
+If we use raster-footprint and specify a densification distance of 10,000 meters and a
+simplification tolerance of 1000 meters, we greatly reduce the projection error while
+reducing the number of vertices to 100
+
+What does raster-footprint provide?
+-----------------------------------
+
+A convenient interface for creating and tuning raster footprints via a relatively thin
+wrapper around `rasterio <https://rasterio.readthedocs.io/en/stable/index.html>`_ and
+`Shapely <https://shapely.readthedocs.io/en/stable/manual.html>`_. Options include:
+
+*Flexible data sources:*
+
+- Any raster file format openable by rasterio
+- Rasterio dataset reader objects
+- NumPy arrays of raster data
+- NumPy arrays of mask values (arrays of 0s and 255s for nodata/data pixels)
+
+*Band selection:*
+
+- Choose one or more bands from a multiband raster for footprint creation
+
+*Distortion mitigation:*
+
+- Densify by factor before reprojection
+- Densify by distance before reprojection
+
+*Simplification options:*
+
+- Use the entire raster grid, i.e., include nodata pixels
+- Apply a convex hull to the footprint
+- Discard polygon holes
+- Simplify the footprint using the Douglas-Peucker algorithm
+
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    api
 
 
-
 Indices and tables
 ==================
 

pyproject.toml

@@ -21,6 +21,7 @@ dev = [
     "pre-commit~=3.3",
     "pytest~=7.4",
     "ruff==0.0.282",
+    "sphinx-autobuild~=2021.3",
     "tomli~=2.0; python_version<'3.11'",
 ]
 docs = ["sphinx~=7.1", "pydata-sphinx-theme~=0.13"]

src/raster_footprint/footprint.py

@@ -13,8 +13,6 @@
 from .reproject import DEFAULT_PRECISION, reproject_geometry
 from .simplify import simplify_geometry
 
-# TODO: change holes default to False
-
 
 def footprint_from_mask(
     mask: npt.NDArray[np.uint8],