67 handle optional grids

ruminations/002-rumination.md

@@ -5,7 +5,7 @@
 Thomas Knudsen <[email protected]>
 Sean Rennie <[email protected]>
 
-2021-08-20. Last [revision](#document-history) 2023-10-19
+2021-08-20. Last [revision](#document-history) 2023-11-02
 
 ### Abstract
 
@@ -304,7 +304,7 @@ The `gridshift` operator implements datum shifts by interpolation in correction
 | Parameter | Description |
 |-----------|-------------|
 | `inv` | Inverse operation: output-to-input datum. For 2-D and 3-D cases, this involves an iterative refinement, typically converging after less than 5 iterations |
-| `grids` | Name of the grid file to use. RG supports only one file for each operation, but maintains the plural form of the `grids` option for alignment with the PROJ precedent |
+| `grids` | Name of the grid files to use. RG supports multiple comma separated grids where the first one to contain the point is the one used. Grids are considered optional if they are prefixed with `@` and do not error the operator if they aren't available. Additionally the `@null` parameter can be specified as the last grid which will prevent errors in shifts from stomping on the coordinate. That is to say the coordinate passes through unchanged. |
 
 The `gridshift` operator has built in support for the **Gravsoft** grid format. Support for additional file formats depends on the `Context` in use.
 
@@ -315,6 +315,10 @@ For grids with angular (geographical) spatial units, the corrections are suppose
 
 ```term
 geo:in | gridshift grids=ed50.datum | geo:out
+
+geo:in | gridshift grids=ed50.datum,@null | geo:out
+
+geo:in | gridshift [email protected],ed50.datum | geo:out
 ```
 
 **See also:** PROJ documentation, [`hgridshift`](https://proj.org/operations/transformations/hgridshift.html) and [`vgridshift`](https://proj.org/operations/transformations/vgridshift.html). RG combines the functionality of the two: The dimensionality of the grid determines whether a plane or a vertical transformation is carried out.
@@ -738,4 +742,5 @@ Major revisions and additions:
   registered update on 2022-05-08. a large number of new operators
   have been included and described
 - 2023-07-09: dm and dms liberated from their NMEA overlord
-- 2023-10-19: Add `somerc` operator description
+- 2023-10-19: Add `somerc` operator description
+- 2023-11-02: Update `gridshift` operator description with multi, optional and null grid support

src/inner_op/deformation.rs

@@ -268,18 +268,25 @@ pub fn new(parameters: &RawParameters, ctx: &dyn Context) -> Result<Op, Error> {
             continue;
         }
 
-        // TODO: Handle @optional grids
-
-        let grid = ctx.get_grid(&grid_name)?;
-        let n = grid.bands();
-        if n != 3 {
-            return Err(Error::Unexpected {
-                message: "Bad dimensionality of deformation model grid".to_string(),
-                expected: "3".to_string(),
-                found: n.to_string(),
-            });
+        match ctx.get_grid(&grid_name) {
+            Ok(grid) => {
+                let n = grid.bands();
+                if n != 3 {
+                    return Err(Error::Unexpected {
+                        message: "Bad dimensionality of deformation model grid".to_string(),
+                        expected: "3".to_string(),
+                        found: n.to_string(),
+                    });
+                }
+                params.grids.push(grid);
+            }
+            Err(e) => {
+                if grid_name.contains("@") {
+                    continue;
+                }
+                return Err(e);
+            }
         }
-        params.grids.push(grid);
     }
 
     let fwd = InnerOp(fwd);

src/inner_op/gridshift.rs

@@ -134,10 +134,15 @@ pub fn new(parameters: &RawParameters, ctx: &dyn Context) -> Result<Op, Error> {
             continue;
         }
 
-        // TODO: Handle @optional grids
-
-        let grid = ctx.get_grid(&grid_name)?;
-        params.grids.push(grid);
+        match ctx.get_grid(&grid_name) {
+            Ok(grid) => params.grids.push(grid),
+            Err(e) => {
+                if grid_name.contains("@") {
+                    continue;
+                }
+                return Err(e);
+            }
+        }
     }
 
     let fwd = InnerOp(fwd);
@@ -237,6 +242,34 @@ mod tests {
 
         Ok(())
     }
+
+    #[test]
+    fn optional_grid() -> Result<(), Error> {
+        let mut ctx = Plain::default();
+        let op = ctx.op("gridshift [email protected],../../geodesy/datum/test.datum")?;
+        let cph = Coor4D::geo(55., 12., 0., 0.);
+        let mut data = [cph];
+
+        ctx.apply(op, Fwd, &mut data)?;
+        let res = data[0].to_geo();
+        assert!((res[0] - 55.015278).abs() < 1e-6);
+        assert!((res[1] - 12.003333).abs() < 1e-6);
+
+        ctx.apply(op, Inv, &mut data)?;
+        assert!((data[0][0] - cph[0]).abs() < 1e-10);
+        assert!((data[0][1] - cph[1]).abs() < 1e-10);
+
+        Ok(())
+    }
+
+    #[test]
+    fn missing_grid() -> Result<(), Error> {
+        let mut ctx = Plain::default();
+        let op = ctx.op("gridshift grids=missing.gsb");
+        assert!(op.is_err());
+
+        Ok(())
+    }
 }
 
 // See additional tests in src/grid/mod.rs