deformation: Replace +t_obs with +dt

The +t_obs parameter was confusing for users since it effectively
overwrote the observation time in input coordinates. To make it more clear
what is the operation is doing, users are now required to directly specify
the time span for which they wish to apply a given deformation. The parameter
+dt has been added for that purpose. The new parameter is mutually
exclusive with +t_epoch. +dt is used when deformation
for a set amount of time is needed and +t_epoch is used (in
conjunction with the observation time of the input coordinate) when
deformation from a specific epoch to the observation time is needed.

5 files changed, 40 insertions, 29 deletions

diff --git a/src/apps/gie.cpp b/src/apps/gie.cpp
index c3622d52..abed11c0 100644
--- a/src/apps/gie.cpp
+++ b/src/apps/gie.cpp
@@ -1082,6 +1082,7 @@ static const struct errno_vs_err_const lookup[] = {
     {"pjd_err_too_many_inits"           ,  -57},
     {"pjd_err_invalid_arg"              ,  -58},
     {"pjd_err_inconsistent_unit"        ,  -59},
+    {"pjd_err_mutually_exclusive_args"  ,  -60},
     {"pjd_err_dont_skip"                ,  5555},
     {"pjd_err_unknown"                  ,  9999},
     {"pjd_err_enomem"                   ,  ENOMEM},
diff --git a/src/proj_internal.h b/src/proj_internal.h
index 9ffcc2b3..b7e3de9e 100644
--- a/src/proj_internal.h
+++ b/src/proj_internal.h
@@ -677,6 +677,7 @@ struct FACTORS {
 #define PJD_ERR_TOO_MANY_INITS          -57
 #define PJD_ERR_INVALID_ARG             -58
 #define PJD_ERR_INCONSISTENT_UNIT       -59
+#define PJD_ERR_MUTUALLY_EXCLUSIVE_ARGS -60
 /* NOTE: Remember to update src/strerrno.cpp, src/apps/gie.cpp and transient_error in */
 /* src/transform.cpp when adding new value */
 
diff --git a/src/strerrno.cpp b/src/strerrno.cpp
index 13e9c757..01097a42 100644
--- a/src/strerrno.cpp
+++ b/src/strerrno.cpp
@@ -68,6 +68,7 @@ pj_err_list[] = {
     "only one +init allowed for non-pipeline operations",              /* -57 */
     "argument not numerical or out of range",                          /* -58 */
     "inconsistent unit type between input and output",                 /* -59 */
+    "arguments are mutually exclusive",                                /* -60 */
 
     /* When adding error messages, remember to update ID defines in
        projects.h, and transient_error array in pj_transform                  */
diff --git a/src/transform.cpp b/src/transform.cpp
index 486178d0..d111d835 100644
--- a/src/transform.cpp
+++ b/src/transform.cpp
@@ -75,14 +75,15 @@ static int adjust_axis( projCtx ctx, const char *axis, int denormalize_flag,
 **
 */
 
-static const int transient_error[60] = {
+static const int transient_error[70] = {
     /*             0  1  2  3  4  5  6  7  8  9   */
     /* 0 to 9 */   0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
     /* 10 to 19 */ 0, 0, 0, 0, 1, 1, 0, 1, 1, 1,
     /* 20 to 29 */ 1, 0, 0, 0, 0, 0, 0, 1, 0, 0,
     /* 30 to 39 */ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
     /* 40 to 49 */ 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,
-    /* 50 to 59 */ 1, 0, 1, 0, 1, 1, 1, 1, 0, 0 };
+    /* 50 to 59 */ 1, 0, 1, 0, 1, 1, 1, 1, 0, 0,
+    /* 60 to 69 */ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,};
 
 
 /* -------------------------------------------------------------------- */
diff --git a/src/transformations/deformation.cpp b/src/transformations/deformation.cpp
index 14f34e4e..c28e1489 100644
--- a/src/transformations/deformation.cpp
+++ b/src/transformations/deformation.cpp
@@ -65,7 +65,7 @@ PROJ_HEAD(deformation, "Kinematic grid shift");
 
 namespace { // anonymous namespace
 struct pj_opaque {
-    double t_obs;
+    double dt;
     double t_epoch;
     PJ *cart;
 };
@@ -167,23 +167,20 @@ static PJ_XYZ forward_3d(PJ_LPZ lpz, PJ *P) {
     struct pj_opaque *Q = (struct pj_opaque *) P->opaque;
     PJ_COORD out, in;
     PJ_XYZ shift;
-    double dt = 0.0;
     in.lpz = lpz;
     out = in;
 
-    if (Q->t_obs != HUGE_VAL) {
-        dt = Q->t_obs - Q->t_epoch;
-    } else {
+    if (Q->dt == HUGE_VAL) {
         out = proj_coord_error(); /* in the 3D case +t_obs must be specified */
-        proj_log_debug(P, "deformation: +t_obs must be specified");
+        proj_log_debug(P, "deformation: +dt must be specified");
         return out.xyz;
     }
 
     shift = get_grid_shift(P, in.xyz);
 
-    out.xyz.x += dt * shift.x;
-    out.xyz.y += dt * shift.y;
-    out.xyz.z += dt * shift.z;
+    out.xyz.x += Q->dt * shift.x;
+    out.xyz.y += Q->dt * shift.y;
+    out.xyz.z += Q->dt * shift.z;
 
     return out.xyz;
 }
@@ -195,10 +192,10 @@ static PJ_COORD forward_4d(PJ_COORD in, PJ *P) {
     PJ_XYZ shift;
     PJ_COORD out = in;
 
-    if (Q->t_obs != HUGE_VAL) {
-            dt = Q->t_obs - Q->t_epoch;
-        } else {
-            dt = in.xyzt.t - Q->t_epoch ;
+    if (Q->dt != HUGE_VAL) {
+        dt = Q->dt;
+    } else {
+        dt = in.xyzt.t - Q->t_epoch ;
     }
 
     shift = get_grid_shift(P, in.xyz);
@@ -215,18 +212,15 @@ static PJ_COORD forward_4d(PJ_COORD in, PJ *P) {
 static PJ_LPZ reverse_3d(PJ_XYZ in, PJ *P) {
     struct pj_opaque *Q = (struct pj_opaque *) P->opaque;
     PJ_COORD out;
-    double dt = 0.0;
     out.xyz = in;
 
-    if (Q->t_obs != HUGE_VAL) {
-        dt = Q->t_obs - Q->t_epoch;
-    } else {
+    if (Q->dt == HUGE_VAL) {
         out = proj_coord_error(); /* in the 3D case +t_obs must be specified */
-        proj_log_debug(P, "deformation: +t_obs must be specified");
+        proj_log_debug(P, "deformation: +dt must be specified");
         return out.lpz;
     }
 
-    out.xyz = reverse_shift(P, in, dt);
+    out.xyz = reverse_shift(P, in, Q->dt);
 
     return out.lpz;
 }
@@ -237,8 +231,8 @@ static PJ_COORD reverse_4d(PJ_COORD in, PJ *P) {
     double dt;
 
 
-    if (Q->t_obs != HUGE_VAL) {
-            dt = Q->t_obs - Q->t_epoch;
+    if (Q->dt != HUGE_VAL) {
+            dt = Q->dt;
         } else {
             dt = in.xyzt.t - Q->t_epoch;
     }
@@ -298,16 +292,29 @@ PJ *TRANSFORMATION(deformation,1) {
         return destructor(P, PJD_ERR_FAILED_TO_LOAD_GRID);
     }
 
-    Q->t_obs = HUGE_VAL;
-    if (pj_param(P->ctx, P->params, "tt_obs").i) {
-       Q->t_obs = pj_param(P->ctx, P->params, "dt_obs").f;
+    Q->dt = HUGE_VAL;
+    if (pj_param(P->ctx, P->params, "tdt").i) {
+       Q->dt = pj_param(P->ctx, P->params, "ddt").f;
+    }
+
+    if (pj_param_exists(P->params, "t_obs")) {
+        proj_log_error(P, "deformation: +t_obs parameter is deprecated. Use +dt instead.");
+        return destructor(P, PJD_ERR_MISSING_ARGS);
     }
 
+    Q->t_epoch = HUGE_VAL;
     if (pj_param(P->ctx, P->params, "tt_epoch").i) {
         Q->t_epoch = pj_param(P->ctx, P->params, "dt_epoch").f;
-    } else {
-       proj_log_error(P, "deformation: +t_epoch parameter missing.");
-       return destructor(P, PJD_ERR_MISSING_ARGS);
+    }
+
+    if (Q->dt == HUGE_VAL && Q->t_epoch == HUGE_VAL) {
+        proj_log_error(P, "deformation: either +dt or +t_epoch needs to be set.");
+        return destructor(P, PJD_ERR_MISSING_ARGS);
+    }
+
+    if (Q->dt != HUGE_VALL && Q->t_epoch != HUGE_VALL) {
+        proj_log_error(P, "deformation: +dt or +t_epoch are mutually exclusive.");
+        return destructor(P, PJD_ERR_MUTUALLY_EXCLUSIVE_ARGS);
     }
 
     P->fwd4d = forward_4d;