Move raster footprint functionality into a class (#396)

* feat: sinusoidal projection raster footprint geometry

- supplements existing raster footprint with new densification method and projection to lon/lat that does not wrap longitudes

* refactor: a little cleaner subclassing, better projection parameters

* refactor: separate out a base class

- 2 subclasses: default and sinusoidal

* wip

* refactor: make single class

- add instance creation methods
- remove sinusoidal class

* fix: remove unnecessary change from test_raster_footprint.py

* fix: remove unneccessary modis test files

* fix: prevent potential subclassing problem

- return `cls` rather than `RasterFootprint` from a classmethod

* fix: generalize return types from class methods

* fix: docstring fixups

* refactor: free `reproject_polygon()`

* docs: deprecated existing free functions

* refactor: make optional argument order consistent

* docs: remove unrelated doc changes

- Removes doc and docstring edits to the round utility, which are more
appropriately addressed in a new PR.

* fix: modify cogify_subdatasets tests to pass

* fix: revert test_subdataset test

* fixups: PR review fixups

* feat: update cli and add densify tests

- update cli to use new RasterFootprint class method
- test densification methods

* chore: update CHANGELOG

* docs: update footprint.rst contents

* fix: add accidentally deleted changelog contents

Author: pjhartzell

CHANGELOG.md

@@ -10,12 +10,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `stactools.core.utils.round` for rounding Item geometry and Item and Collection bboxes to a specified precision ([#384](https://github.com/stac-utils/stactools/pull/384))
+- `stactools.core.utils.raster_footprint.densify_by_distance` for densifying polygons at distance intervals ([#396](https://github.com/stac-utils/stactools/pull/396))
+- `stactools.core.utils.raster_footprint.reproject_polgyon` for reprojecting a polygon and removing duplicate vertices caused by rounding ([#396](https://github.com/stac-utils/stactools/pull/396))
+- `stactools.core.utils.raster_footprint.RasterFootprint` class for customizing raster data footrpint creation behaviour via subclassing ([#396](https://github.com/stac-utils/stactools/pull/396))
 
 ### Changed
 
 - Freed `recursive_round` function from `round_coordinates` in `stactools.core.utils.round` ([#390](https://github.com/stac-utils/stactools/pull/390))
+- Exposed the private `_densify` function as `densify_by_factor` in `stactools.core.utils.raster_footprint` ([#396](https://github.com/stac-utils/stactools/pull/396))
 
-### [0.4.3] - 2022-12-16
+### Deprecated
+
+- `update_geometry_from_asset_footprint`, `data_footprints_for_data_assets`, and `data_footprint` functions will be removed from `stactools.core.utils.raster_footprint` in v0.6.0 ([#396](https://github.com/stac-utils/stactools/pull/396))
+
+## [0.4.3] - 2022-12-16
 
 ### Added
 

docs/api.rst

@@ -86,7 +86,7 @@ Reprojection
 .. automodule:: stactools.core.projection
     :members:
 
-Raster Footprint Generation
+Raster footprint generation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: stactools.core.utils.raster_footprint

docs/footprint.rst

@@ -11,7 +11,7 @@ bounding box of the entire image, both
 data and no data. By footprint, we mean a vector that balances many competing
 factors, and generally represents a shape
 covering the data in an image. Figuring out the right parameter values to the
-methods in the ``raster_footprint``
+methods in the :mod:`~stactools.core.utils.raster_footprint`
 module will usually require some experimental validation, to find exactly the
 right values for your data, CRS, and
 use cases.
@@ -74,9 +74,9 @@ result in false positives where a search geometry intersects the
 geometry of an Item, but the only pixels within the
 geometry are no data, but in practice this is rarely a problem.
 
-When using the raster_footprint functions, the ``no_data`` parameter
-value can be used to pass in the value
-used for no data if it not defined in the image metadata.
+When using the :mod:`~stactools.core.utils.raster_footprint` functions, the
+``no_data`` parameter value can be used to pass in the value
+used for no data if it is not defined in the image metadata.
 
 Reprojected Geometry Accurately Represents the Footprint
 --------------------------------------------------------
@@ -90,15 +90,15 @@ to EPSG:4326, it will still result in a 5 point
 polygon, as the points have simply been reprojected into the new CRS.
 This new polygon may not accurately represent
 original polygon if there is significant curved distortion between
-the CRSes. An example of this is most apparent in
+the CRSs. An example of this is most apparent in
 reprojecting the sinusoidal geometry of MODIS to EPSG:4326. Simply
 reprojecting the 5 point polygon would result in
 a parallelogram, whereas a more accurate representation is two
 parallel straight sides and two curved sides.
 
 .. image:: _static/modis.png
 
-The increase the accuracy of the reprojected shape, we can first
+To increase the accuracy of the reprojected shape, we can first
 densify the polygon. Here we add additional, redundant
 points between existing points in the polygon, so that the
 reprojected shape will have points that more closely match
@@ -108,9 +108,9 @@ each "side" of the polygon has 11 points representing it instead
 of 2, and we get a "curved" side that more closely
 matches the raster reprojection.
 
-When using the raster_footprint functions, the
-``densification_factor`` parameter can be used to densify the
-geometry before reprojection. This will require some
+When using the methods in the :mod:`~stactools.core.utils.raster_footprint`
+module, the ``densification_factor`` or ``densification_distance`` parameter
+can be used to densify the geometry before reprojection. This will require some
 experimentation to find the appropriate value for the CRS of your data.
 
 Simplifying the Geometry
@@ -122,17 +122,14 @@ it is a 2400x2400 pixel image and two sides are curves after reprojection.
 However, a polygon this dense both makes
 the Item body very large and increases the computation required to perform
 an intersects calculation during search,
-with little benefit. These polygons can be simplified by defining a minimum
-distance, in degrees, for which two points
-may be collapsed into one. This is also useful when the polygon in the native
+with little benefit. These polygons can be simplified by defining a maximum
+distance, in degrees, within which the simplified polygon must be to original
+polygon points. This is also useful when the polygon in the native
 CRS has a large number of points, so
 that the end result is a polygon of a more manageable size.
 
-When using the raster_footprint functions, the ``simplify_tolerance`` parameter
-defines the a minimum distance,
-in degrees, for which points should be combined. This will require some
-experimentation to find the appropriate
-value for the CRS of your data.
-
-
-
+When using the methods in the :mod:`~stactools.core.utils.raster_footprint`
+module, the ``simplify_tolerance`` parameter defines the distance within which
+the simplified polygon must be to the original polygon points. This will
+require some experimentation to find the appropriate value for the CRS of your
+data.

src/stactools/cli/commands/update_geometry.py

@@ -37,6 +37,12 @@ def create_update_geometry_command(cli: Group) -> Command:
         type=int,
         help="The factor by which to increase point density within the polygon.",
     )
+    @click.option(
+        "-i",
+        "--densification-distance",
+        type=float,
+        help="The distance interval at which to increase point density within the polygon",
+    )
     @click.option(
         "-s",
         "--simplify-tolerance",
@@ -60,28 +66,40 @@ def create_update_geometry_command(cli: Group) -> Command:
         default="1",
         show_default=True,
     )
+    @click.option(
+        "-e",
+        "--skip-errors",
+        help="Do not raise errors for missing hrefs or footprint calculation failures",
+        type=bool,
+        default=True,
+        show_default=True,
+    )
     def update_geometry_command_raster_command(
         item_path: str,
         asset_names: List[str],
         precision: int,
         densification_factor: Optional[int],
+        densification_distance: Optional[float],
         simplify_tolerance: Optional[float],
         no_data: Optional[int],
         bands: str,
+        skip_errors: bool,
     ) -> None:
         item = Item.from_file(item_path)
         if bands.lower() == "all":
             band_list = []
         else:
             band_list = list(int(band) for band in bands.split(","))
-        success = raster_footprint.update_geometry_from_asset_footprint(
+        success = raster_footprint.RasterFootprint.update_geometry_from_asset_footprint(
             item,
             asset_names=asset_names,
             precision=precision,
             densification_factor=densification_factor,
+            densification_distance=densification_distance,
             simplify_tolerance=simplify_tolerance,
             no_data=no_data,
             bands=band_list,
+            skip_errors=skip_errors,
         )
         if success:
             item.save_object()