Merge pull request #780 from planetlabs/update_harmonize_tool-772

Updated Harmonization tool to match the openAPI spec

Author: kevinlacaille

docs/cli/cli-orders.md

@@ -467,7 +467,23 @@ curl -s https://raw.githubusercontent.com/planetlabs/planet-client-python/main/d
 
 ### Harmonize
 
-TODO
+The harmonize tool allows you to compare data to different generations of satellites by radiometrically harmonizing imagery captured by one satellite instrument type to imagery captured by another. To harmonize your data to a sensor you must define the sensor you wish to harmonize with in your `tools.json`. Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as target sensors. The Sentinel-2 target only harmonizes PSScene surface reflectance bundle types (`analytic_8b_sr_udm2`, `analytic_sr_udm2`). The PS2 target only works on analytic bundles from Dove-R (`PS2.SD`).
+
+```json
+[
+  {
+    "harmonize": {
+      "target_sensor": "Sentinel-2"
+      }
+    }
+]
+```
+
+You may create an order request by calling `tools.json` with `--tools`.
+
+```console
+planet orders request psscene analytic_sr_udm2 --name "Harmonized data" --id 20200925_161029_69_2223 --tools tools.json
+```
 
 ### STAC Metadata
 

planet/order_request.py

@@ -429,10 +429,12 @@ def toar_tool(scale_factor: Optional[int] = None, ) -> dict:
     return _tool('toar', parameters)
 
 
-def harmonize_tool() -> dict:
+def harmonize_tool(target_sensor: str) -> dict:
     '''Create the API spec representation of a harmonize tool.
 
-    Currently, only "PS2" (Dove Classic) is supported as a target sensor, and
-    it will transform only items captured by “PS2.SD” (Dove-R).
+    Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as
+    target sensors. The Sentinel-2 target only harmonizes PSScene
+    surface reflectance bundle types (analytic_8b_sr_udm2, analytic_sr_udm2).
+    The PS2 target only works on analytic bundles from Dove-R (PS2.SD).
     '''
-    return _tool('harmonize', {'target_sensor': 'PS2'})
+    return _tool('harmonize', {'target_sensor': target_sensor})

tests/unit/test_order_request.py

@@ -251,3 +251,10 @@ def test_toar_tool():
     tt_empty = order_request.toar_tool()
     expected_empty = {'toar': {}}
     assert tt_empty == expected_empty
+
+
+@pytest.mark.parametrize("target_sensor", ["PS2", "Sentinel-2"])
+def test_harmonization_tool(target_sensor):
+    ht = order_request.harmonize_tool(target_sensor)
+    expected = {'harmonize': {'target_sensor': target_sensor}}
+    assert ht == expected