Generic coordinates #431

busstoptaktik · 2016-10-11T16:41:08Z

This is the first in a series of pull requests reimplementing the functionality of PR #388 "Transformation pipelines" in a more modular way.

This first step introduces the OBSERVATION data type, and a number of additions to the PJ object, intended as the basis for extended geodetic transformation functionality.

It also introduces the elemens of a new minimalistic geodetic API, orthogonal to the original proj_api.h API

Inroducing the OBSERVATION data type as the basis for generic geodetic transformations. Also introducing the elements of a new minimalistic API focused on generic geodetic transformations. This API is documented in the new proj.h header, and is orthogonal (non-intrusive) wrt. the existing API from proj_api.h Finally added a large amount of comments to the somewhat intractable projects.h, and extended the PJ object with a number of additional ellipsoidal parameters of general geodetic usefulness.

…_coordinates

QuLogic · 2016-10-11T20:00:27Z

Can you remove the extra merges?

kbevers · 2016-10-12T06:13:00Z

Can you remove the extra merges?

@QuLogic Don't worry about those, they can be squashed before merging.

kbevers

Thanks, Thomas. I like this new no-nonsense API!

A few general comments:

There's mixed use of tabs and spaces in proj.h and projects.h. I have tried to point them out with line comments.
- A documentation page with a few examples and explanations would be really good to have before merging this.
- I like the restructured projects.h. Much easier to navigate in now.

kbevers · 2016-10-12T08:24:26Z

src/proj.h

+#endif
+
+/* Avoid preprocessor renaming and implicit type-punning: Use a union to make it explicit */
+union PJ_TRIPLET {


Mixed whitespace in this block

kbevers · 2016-10-12T08:25:39Z

src/projects.h

+
+    **************************************************************************************
+
+	    For projection xxx, these are pointers to functions in the corresponding


Mixed whitespace in this comment section

kbevers · 2016-10-12T08:29:28Z

src/projects.h

+		a name which is currently hidden behind the magic curtain of the PROJECTION
+		macro.
+
+		As the PROJ.4 de-macroization project expands its coverage, this will change,


I suggest leaving this paragraph out. The odds of this message surviving the intendd de-macroization are quite high and will most likely lead to confusion for future readers of the code.

kbevers · 2016-10-12T08:35:48Z

src/projects.h

+
+    int     datum_type;                /* PJD_UNKNOWN/3PARAM/7PARAM/GRIDSHIFT/WGS84 */
+    double  datum_params[7];           /* Parameters for 3PARAM and 7PARAM */
+    struct _pj_gi **gridlist;          /* Description needed */


"Description needed" is not a very useful comment. It would be good to have those descriptions made before merging. Or at least a ticket so it is not forgotten once this PR is merged.

kbevers · 2016-10-12T08:44:14Z

src/projects.h

 #ifdef PJ_LIB__
-/* repetitive projection code */
+/* repetitive projection code (most of them eliminated now) */


Elimaniting these macros is a very good idea. Could you create a ticket that describes this effort? It will be easier to keep track of that way, and there's a bigger change someone will pick it up and do the work.

kbevers · 2016-10-12T08:49:12Z

src/pj_observation.c

+
+
+/* Direction: "+1" forward, "-1" reverse, 0: roundtrip precision check (not fully done) */
+OBSERVATION pj_apply (PJ *P, int direction, OBSERVATION obs) {


I bet I'll have to look up the meaning og +1, -1 and 0 everytime I use it. Declaring constants like PJ_FORWARD, PJ_REVERSE and PJ_ROUNDTRIP (or something similar) will make calls to pj_apply() self-documenting.

Challenge: Come up with a self-documenting function name that isn't already use :) pj_transform would be a perfect name for this, but is already used... Anyone?

@kbevers

…sponse to code review by @kbevers. The PJ elements fwdobs and invobs extend fwd3d and inv3d in a homologous way to how fwd3d and inv3d extend fwd and inv.

busstoptaktik · 2016-10-12T11:28:41Z

Thanks, @kbevers - I have implemented the requested improvements, and added a few missing details logically belonging to this PR.

busstoptaktik · 2016-10-12T11:37:44Z

@QuLogic - does this update look sensible to you (given that commits are squashed on merge)

QuLogic · 2016-10-12T23:45:31Z

src/Makefile.am

@@ -72,7 +72,9 @@ libproj_la_SOURCES = \
 	pj_apply_gridshift.c pj_datums.c pj_datum_set.c pj_transform.c \
 	geocent.c geocent.h pj_utils.c pj_gridinfo.c pj_gridlist.c \
 	jniproj.c pj_mutex.c pj_initcache.c pj_apply_vgridshift.c geodesic.c \
-	pj_strtod.c
+	pj_strtod.c \
+	\


Why the extra line?

Because a new block starts here: During the reimplementation of pipelines additional files will be added to this block

QuLogic · 2016-10-12T23:54:37Z

src/pj_observation.c

+    g.anc.opk.k  = k;
+    g.id         = id;
+    g.flags      = flags;
+	return g;


There's a tab here instead of the spaces above. Not sure what the convention is for proj.4, but I guess it should be consistent.

Thanks for spotting this - apparently a last minute touch up after having done "convert tabs to spaces".

QuLogic · 2016-10-12T23:55:08Z

src/pj_observation.c

+	switch (direction) {
+	    case 1:
+            obs.coo.xyz  =  pj_fwd3d (obs.coo.lpz, P);
+			return obs;


These lines are a very complicated mix of tabs and spaces.

Yes - that's certainly an odd mix. Probably from a cut/paste operation made in hell. Cleaned up now

QuLogic · 2016-10-12T23:56:12Z

src/makefile.vc

@@ -58,9 +58,11 @@ support = \
 	pj_ctx.obj pj_fileapi.obj pj_log.obj pj_apply_vgridshift.obj \
 	pj_strtod.obj pj_run_selftests.obj pj_generic_selftest.obj

+pipeline = \
+	pj_observation.obj


Blank line after (and there probably should have been one after geodesic, I imagine.)

Your imagination is right :-)

QuLogic · 2016-10-13T00:00:19Z

src/proj.h

+#endif  /* ndef PROJECTS_H */
+
+/* Data type for generic geodetic 3D data */
+union PJ_TRIPLET;


Is there a reason to declare this instead of moving the typedef after the definition?

Mostly to get a preamble style overview of "what's being defined in this file", by having declarations before the more messy definitions. During development, and the combinatorial puzzle of getting projects.h and proj.h to play nice together, the preamble sunk down below the conditional redefinitions of the proj pair/triplet types.

I have moved them back to the top, and hope you see the usefulness of the preamble style.

QuLogic · 2016-10-13T00:02:19Z

src/proj.h

+OBSERVATION pj_apply (PJ *P, int direction, OBSERVATION obs);
+
+/* Direction: "+" forward, "-" reverse, 0: roundtrip precision check */
+enum pj_apply_direction {PJ_APPLY_FWD = -1, PJ_APPLY_ROUNDTRIP = 0, PJ_APPLY_INV = 1};


Should this not be used in pj_apply's declaration (not that it makes much difference in C)? Also, I think this should go on multiple lines.

I'm slightly undecided on this... I introduced the enum in response to a comment by @kbevers who felt the need for a linguistic, rather than mathematical, reminder of "what is what".

My own feeling is that having the "direction" argument directly indicate the (mathematically interpreted) power of the operator (1 forward, -1 inverse) would make ample sense. And since in geodesy numerical stability is important, I would like to have an additional version of the roundtrip test, where e.g. direction=2000 would mean "deviation from input observation for a series of 2000 roundtrips".

Hence, I would prefer to keep the direction argument an int, for future use

QuLogic · 2016-10-13T00:02:30Z

src/proj.h

+#ifndef PROJECTS_H
+OBSERVATION pj_apply (PJ *P, int direction, OBSERVATION obs);
+
+/* Direction: "+" forward, "-" reverse, 0: roundtrip precision check */


Direction of what?

Direction of transformation - apply the forward (1) or inverse (-1) transformation. I have added a few explanatory comments for the pj_apply function

QuLogic · 2016-10-13T00:07:39Z

src/projects.h

+    void (*spc)(LP, PJ *, struct FACTORS *);
+
+    void (*pfree)(PJ *);
+


I'm not sure three empty lines plus the asterisks is really necessary.

QuLogic · 2016-10-13T00:15:00Z

src/projects.h

+struct ARG_list {
+    paralist *next;
+    char used;
+    char param[1];    /* This probably should be [0] to be fully standards compliant? */


No, this is correct; [0] would be an empty array. What the code does is allocate the size of this structure + the length of the string. The extra 1 here accounts for the NUL terminator on the string.

Yes, I understand the reason for the 1. It just that in most historical cases of the "struct hack", param[0] was used. For many years it was a matter of heated discussion whether this was standards conforming or not. C99 (or was it C11?) solved this - but not as I seemed to remember when I wrote the comment, by requiring a 0 index, but rather by requiring the declaration to be incomplete, i.e. param[].

Hence, for C99 (11?) this is definitely non-conforming (but probably portable among all relevant platforms). For C89 it has apparently not led to any problems, despite potential non-conformality.

Given this non-straightforward state of things, I chose to remove the comment in order not to add further confusion to an already muddy matter :-)

QuLogic · 2016-10-13T00:16:44Z

src/projects.h

 #define IS_ANAL_XL_YL 01    /* derivatives of lon analytic */
 #define IS_ANAL_XP_YP 02    /* derivatives of lat analytic */
-#define IS_ANAL_HK    04    /* h and k analytic */
+#define IS_ANAL_HK  04      /* h and k analytic */


Not sure this needed to move?

Well - its mostly a matter of putting less important stuff lower in the file. I've responded by moving a large group of related material (defines and the definition of the projCtx_t) down into the same block of the file.

I didn't mean in the file; just the spacing left to right.

Sorry - missed that one. Corrected now

@QuLogic - So with this final (?) correction, can you approve the review?

Corrections of whitespace blunders minor reorganization of projects.h a number of additional comments

busstoptaktik · 2016-10-13T11:26:18Z

Thanks, @QuLogic - I have implemented (and/or elaborated on) the requested improvements, and added a small number of related corrections/improvements of consistency.

…_coordinates

micahcochran · 2016-10-21T14:44:10Z

src/proj.h

+#define TODEG(rad)  ((rad)*180/M_PI)
+#endif
+#ifndef TORAD
+#define TORAD(deg)  ((deg)*M_PI/180)


Would you mind using 180.0 for these two macros? I seem to remember Visual C++ giving warnings about implicit typecasting.

Thanks for spotting this @micahcochran - not being a MSVC user myself, I am probably too unaware of MSVC peculiarities.

While writing 180.0 a place, where the type promotion rules are clear, makes the code look somewhat Fortran-ish, I find it important to get rid of that kind of noise, which may divert attention away from more important warnings.

Can you approve the change?

… by Micah Cochran Silence MSVC warnings about promotion of int to double, by changing 180 to Fortran style 180.0. As the promotion is exactly as specified in the standard it is slightly odd to warn about it. But minimizing the number of warnings makes it easier to focus on actually helpful warnings about incidentally introduced potential dangers.

busstoptaktik · 2016-10-24T09:28:25Z

I believe this PR is ready for merging now.

rouault · 2016-10-24T09:49:16Z

src/pj_observation.c

+int pj_show_triplet (FILE *stream, const char *banner, PJ_TRIPLET point) {
+    int i = 0;
+    if (banner)
+        fprintf (stream, "%s", banner);


Probably i+= missing here ?

Thanks - added now

rouault · 2016-10-24T09:53:10Z

src/proj.h

+******************************************************************************/
+
+/* Data type for generic geodetic observations */
+struct OBSERVATION;


Wouldn't PJ_OBSERVATION be more consistant ?

It would, and I have now moved as much as possible into the PJ_ namespace. Although I find it ugly, and have numerous reservations, they are not so relevant as they used to be: Now, in most cases, union selectors (which are non-prefixed, variable-style names) will be used to address each of these types.

So I get what I want (explicit expression of "what kind of data are we working on" plus minimizing the amount of PJ_'ing). The rest of the world gets what it wants (avoid stomping on user namespaces) :-)

rouault · 2016-10-24T09:55:14Z

src/proj.h

+typedef struct PJconsts PJ;         /* the PJ object herself */
+
+/* Omega, Phi, Kappa: Rotations */
+typedef struct {double o, p, k;}  OPK;


Given the shortness of their names and thus risk of name clash, shouldn't all those structures be PJ_ prefixed if they are intended to be in a public .h file ? (at least for the new ones)

(cf the reply to your previous comment)

rouault · 2016-10-24T09:56:01Z

src/proj.h

+};
+
+struct OBSERVATION {
+    PJ_SPATIOTEMPORAL coo;


Perhaps some comment to explain 'coo' and 'anc' ?

I have added some inline comments elaborating this

rouault · 2016-10-24T09:59:36Z

src/proj.h

+
+#ifndef PROJECTS_H
+/* Apply transformation to observation - in forward or inverse direction */
+OBSERVATION pj_apply (PJ *P, int direction, OBSERVATION obs);


"enum pj_apply_direction direction" instead of "int direction" ? Or maybe create a typedef

@QuLogic mentioned the same thing. This is my reply to him:

I'm slightly undecided on this... I introduced the enum in response to a comment by @kbevers who felt the need for a linguistic, rather than mathematical, reminder of "what is what".

My own feeling is that having the "direction" argument directly indicate the (mathematically interpreted) power of the operator (1 forward, -1 inverse) would make ample sense. And since in geodesy numerical stability is important, I would like to have an additional version of the roundtrip test, where e.g. direction=2000 would mean "deviation from input observation for a series of 2000 roundtrips".

Hence, I would prefer to keep the direction argument an int, for future use

I never really commented on that... Why not keep the roundtrip testing in a separate function? It will probably be a lot simpler and it make it easier to create function calls that explain what they do without having to look at the API docs.

Something like

int pj_roundtrip_test(PJ *P, int direction, OBSERVATION obs, unsigned int n_roundtrips);

could be used to wrap pj_apply and keep the test logic in a predictable place.

@rouault and @QuLogic: I have now followed this suggestion by @kbevers, and think it will satisfy your comments as well :-)

rouault · 2016-10-24T10:06:32Z

src/proj.h

@@ -0,0 +1,205 @@
+/******************************************************************************


I'm not sure how much we care about that but it would seem that /usr/include/proj.h is(was?) a SGI include file... https://www.google.fr/?gws_rd=ssl#q=%22%2Fusr%2Finclude%2Fproj.h%22

Your google-fu is better than mine :-)

I have discussed the subject with @kbevers, and I think the common ground is that we could change the name if anyone comes up with a good one. proj4.h was mentioned...

rouault · 2016-10-24T10:08:52Z

src/proj.h

+typedef struct { double d, m,  s; }  DMS;
+
+/* Geoid undulation and deflections of the vertical */
+typedef struct { double   N,   z,  e; }  PJ_ANC_GEOIDAL;


What does ANC stand for here ?

Ancillary data. There's a comment about it a few lines up - I have now also added some inline comments, and changed the PJ_ANC_* names for consistency

rouault · 2016-10-24T10:09:16Z

src/proj.h

+#ifndef PROJECTS_H
+    OPK    opk;
+    ENH    enh;
+    PJ_ANC_GEOIDAL     nze;


What does nze stand for ?

"N" is the commonly used designation for the geoid undulation. "z" and "e" are latinizations of the greek zeta and eta, which are commonly used designations for the components of the deflection of the vertical.

rouault · 2016-10-24T10:10:33Z

src/proj.h

+#define TORAD(deg)  ((deg)*M_PI/180.0)
+#endif
+
+extern int pj_errno;                    /* global error return code */


Do we want to advertize this old/deprecated global way of getting errors in the new header file ?

Probably a cut/paste going wrong - removed now. Thanks for spotting!

rouault · 2016-10-24T10:11:25Z

src/proj.h

+
+extern int pj_errno;                    /* global error return code */
+void pj_free(PJ *P);
+PJ *pj_init_plus(const char *init_string);


Why not pj_init_plus_ctx ?

As for pj_errno and pj_free, this is simply a cut/paste error. Eliminated now

More consistent use of the PJ_ namespace + additional improvements

@kbevers

Following a suggestion by @kbevers

…declarations

busstoptaktik · 2016-10-24T14:32:04Z

Hopefully ready for merging now... Thanks you to @QuLogic @kbevers @rouault and @micahcochran for excellent and useful reviews!

hobu · 2016-10-24T15:33:51Z

I'm 👍 to merge this too, but it should be a squash/rebase as a single commit onto master.

kbevers · 2016-10-24T16:22:40Z

Squashed and merged. Nice work, @busstoptaktik. While merging all the commits to one I've modified the initial commit message slightly:

Pipeline preliminaries

Introducing the PJ_OBSERVATION data type as the basis for generic geodetic
transformations.

Also introducing the elements of a new minimalistic API focused on
generic geodetic transformations. This API is documented in the new
proj.h header, and is orthogonal (non-intrusive) wrt. the existing API
from proj_api.h

Finally added a large amount of comments to the somewhat intractable
projects.h, and extended the PJ object with a number of additional
ellipsoidal parameters of general geodetic usefulness.

The PJ elements fwdobs and invobs extend fwd3d and inv3d in a homologous
way to how fwd3d and inv3d extend fwd and inv.

I guess the next step is to document this new API. Here's a ticket for that: #442

Thomas Knudsen added 3 commits September 29, 2016 09:40

Merge remote-tracking branch 'refs/remotes/OSGeo/master'

f949617

Merge remote-tracking branch 'refs/remotes/OSGeo/master' into generic…

b364376

…_coordinates

busstoptaktik self-assigned this Oct 12, 2016

busstoptaktik added the C: Core label Oct 12, 2016

kbevers requested changes Oct 12, 2016

View reviewed changes

busstoptaktik mentioned this pull request Oct 12, 2016

Eliminate some unnecessary macros #432

Closed

Add OBSERVATION style callbacks to PJ object plus minor changes in re…

df6672c

…sponse to code review by @kbevers. The PJ elements fwdobs and invobs extend fwd3d and inv3d in a homologous way to how fwd3d and inv3d extend fwd and inv.

busstoptaktik mentioned this pull request Oct 12, 2016

Improve comments in projects.h #433

Closed

kbevers approved these changes Oct 12, 2016

View reviewed changes

QuLogic reviewed Oct 13, 2016

View reviewed changes

Minor corrections in response to review by @QuLogic

782d31c

Corrections of whitespace blunders minor reorganization of projects.h a number of additional comments

Thomas Knudsen added 2 commits October 21, 2016 13:38

Merge remote-tracking branch 'refs/remotes/OSGeo/master' into generic…

d9e2371

…_coordinates

Another minor correction in response to review by QuLogic

a5e211b

micahcochran reviewed Oct 21, 2016

View reviewed changes

QuLogic approved these changes Oct 22, 2016

View reviewed changes

rouault reviewed Oct 24, 2016

View reviewed changes

Thomas Knudsen added 4 commits October 24, 2016 15:18

Improvements in response to a review by Even Rouault

0e60a8a

More consistent use of the PJ_ namespace + additional improvements

Split transformation application and roundtrip testing

0851dda

Following a suggestion by @kbevers

A few corrections of object names in comments, to reflect changes in …

6ff73e0

…declarations

Whitespace normalization

b51de47

kbevers merged commit 6a9bec7 into OSGeo:master Oct 24, 2016

kbevers mentioned this pull request Oct 24, 2016

Document the API in proj.h #442

Closed

busstoptaktik deleted the generic_coordinates branch October 24, 2016 17:32


		**************************************************************************************

		For projection xxx, these are pointers to functions in the corresponding



		/* Direction: "+1" forward, "-1" reverse, 0: roundtrip precision check (not fully done) */
		OBSERVATION pj_apply (PJ *P, int direction, OBSERVATION obs) {

		void (spc)(LP, PJ , struct FACTORS *);

		void (pfree)(PJ );

		@@ -0,0 +1,205 @@
		/******************************************************************************

Generic coordinates #431

Generic coordinates #431

Conversation

busstoptaktik commented Oct 11, 2016

QuLogic commented Oct 11, 2016

kbevers commented Oct 12, 2016

kbevers left a comment

Choose a reason for hiding this comment

kbevers Oct 12, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

busstoptaktik commented Oct 12, 2016

busstoptaktik commented Oct 12, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

busstoptaktik commented Oct 13, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

busstoptaktik commented Oct 24, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

busstoptaktik commented Oct 24, 2016

hobu commented Oct 24, 2016

kbevers commented Oct 24, 2016 • edited Loading

kbevers Oct 12, 2016 •

edited

Loading

kbevers commented Oct 24, 2016 •

edited

Loading