Expose pj_factors and pj_deriv in public API. (#546)

Expose pj_factors and pj_deriv in public API.

proj_derivatives() and proj_factors() has been
introduced to the public proj.h API. The new functions are simply
wrappers for the original functions. The h argument of the two functions
has been omitted in the new wrappers as it does not seem to be used very
much (if at all?).

src/PJ_cart.c

@@ -236,6 +236,8 @@ int pj_cart_selftest (void) {
     PJ *P;
     PJ_OBS a, b, obs[2];
     PJ_COORD coord[2];
+    PJ_DERIVS derivs;
+    PJ_FACTORS factors;
     int err;
     size_t n, sz;
     double dist, h, t;
@@ -506,6 +508,36 @@ int pj_cart_selftest (void) {
         return 73;
 
 
+    /* test proj_derivatives_retrieve() and proj_factors_retrieve() */
+    P = proj_create(0, "+proj=merc");
+    a = proj_obs_null;
+    a.coo.lp.lam = PJ_TORAD(12);
+    a.coo.lp.phi = PJ_TORAD(55);
+
+    derivs = proj_derivatives(P, a.coo.lp);
+    if (proj_errno(P))
+        return 80; /* derivs not created correctly */
+
+    if ( fabs(derivs.x_l - 1.0)     > 1e-5 )   return 81;
+    if ( fabs(derivs.x_p - 0.0)     > 1e-5 )   return 82;
+    if ( fabs(derivs.y_l - 0.0)     > 1e-5 )   return 83;
+    if ( fabs(derivs.y_p - 1.73959) > 1e-5 )   return 84;
+
+
+    factors = proj_factors(P, a.coo.lp);
+    if (proj_errno(P))
+        return 85; /* factors not created correctly */
+
+    /* check a few key characteristics of the Mercator projection */
+    if (factors.omega != 0.0)       return 86; /* angular distortion should be 0 */
+    if (factors.thetap != M_PI_2)   return 87; /* Meridian/parallel angle should be 90 deg */
+    if (factors.conv != 0.0)        return 88; /* meridian convergence should be 0 */
+
+
+    proj_destroy(P);
+
     return 0;
 }
+
+
 #endif

src/pj_obs_api.c

@@ -37,7 +37,6 @@
 #include "proj_internal.h"
 #include "projects.h"
 #include <geodesic.h>
-
 #include <stddef.h>
 #include <errno.h>
 
@@ -517,7 +516,56 @@ char *proj_definition_retrieve (PJ *P) {
     return pj_get_def(P, 0);
 }
 
-/* ...and get rid of it safely */
+
+/*****************************************************************************/
+PJ_DERIVS proj_derivatives(const PJ *P, const LP lp) {
+/******************************************************************************
+    Derivatives of coordinates.
+
+    returns PJ_DERIVS. If unsuccessfull error number is set and the returned
+    struct contains NULL data.
+
+******************************************************************************/
+    PJ_DERIVS derivs;
+
+    /* casting to struct DERIVS for compatibility reasons */
+    if (pj_deriv(lp, 1e-5, (PJ *)P, (struct DERIVS *)&derivs)) {
+        /* errno set in pj_derivs */
+        memset(&derivs, 0, sizeof(PJ_DERIVS));
+    }
+
+    return derivs;
+}
+
+
+/*****************************************************************************/
+PJ_FACTORS proj_factors(const PJ *P, const LP lp) {
+/******************************************************************************
+    Cartographic characteristics at point lp.
+
+    Characteristics include meridian, parallel and areal scales, angular
+    distortion, meridian/parallel, meridian convergence and scale error.
+
+    returns PJ_FACTORS. If unsuccessfull error number is set and the returned
+    struct contains NULL data.
+
+******************************************************************************/
+    PJ_FACTORS factors;
+
+    /* pj_factors rely code being zero */
+    factors.code = 0;
+
+    /* casting to struct FACTORS for compatibility reasons */
+    if (pj_factors(lp, (PJ *)P, 0.0, (struct FACTORS *)&factors)) {
+        /* errno set in pj_factors */
+        memset(&factors, 0, sizeof(PJ_FACTORS));
+    }
+
+    return factors;
+}
+
+
+/* Release, or free, memory that was retrieved by the above functions */
 void *proj_release (void *buffer) {
     return pj_dealloc (buffer);
 }
@@ -537,3 +585,5 @@ double proj_dmstor(const char *is, char **rs) {
 char*  proj_rtodms(char *s, double r, int pos, int neg) {
     return rtodms(s, r, pos, neg);
 }
+
+

src/proj.def

@@ -129,11 +129,15 @@ EXPORTS
     proj_log_trace                 @120
 
     proj_definition_retrieve       @121
-    proj_release                   @122
-    proj_torad                     @123
-    proj_todeg                     @124
-    proj_has_inverse               @125
-    proj_rtodms                    @126
-    proj_dmstor                    @127
+    proj_derivatives               @122
+    proj_factors                   @123
+    proj_release                   @124
 
-    pj_find_file                   @128
+    proj_torad                     @125
+    proj_todeg                     @126
+    proj_has_inverse               @127
+    proj_rtodms                    @128
+    proj_dmstor                    @129
+
+
+    pj_find_file                   @130

src/proj.h

@@ -182,6 +182,12 @@ typedef union PJ_TRIPLET PJ_TRIPLET;
 union PJ_COORD;
 typedef union PJ_COORD PJ_COORD;
 
+struct PJ_DERIVS;
+typedef struct PJ_DERIVS PJ_DERIVS;
+
+struct PJ_FACTORS;
+typedef struct PJ_FACTORS PJ_FACTORS;
+
 /* Data type for projection/transformation information */
 struct PJconsts;
 typedef struct PJconsts PJ;         /* the PJ object herself */
@@ -269,12 +275,26 @@ struct PJ_OBS {
     unsigned int flags;  /* additional data, intended for flags */
 };
 
+struct PJ_DERIVS {
+    double x_l, x_p;       /* derivatives of x for lambda-phi */
+    double y_l, y_p;       /* derivatives of y for lambda-phi */
+};
+
+struct PJ_FACTORS {
+    struct PJ_DERIVS der;
+    double h, k;           /* meridional, parallel scales */
+    double omega, thetap;  /* angular distortion, theta prime */
+    double conv;           /* convergence */
+    double s;              /* areal scale factor */
+    double a, b;           /* max-min scale error */
+    int code;              /* info as to analytics, see following */
+};
+
+
 /* The context type - properly namespaced synonym for projCtx */
 struct projCtx_t;
 typedef struct projCtx_t PJ_CONTEXT;
 
-
-
 /* A P I */
 
 
@@ -356,6 +376,8 @@ int proj_has_inverse(PJ *P);
 double proj_dmstor(const char *is, char **rs);
 char*  proj_rtodms(char *s, double r, int pos, int neg);
 
+PJ_DERIVS  proj_derivatives(const PJ *P, const LP lp);
+PJ_FACTORS proj_factors(const PJ *P, const LP lp);
 
 #ifdef __cplusplus
 }