obs_api revision and improvements: new namespace etc. (#530)

* obs_api revision and improvements: new namespace etc.

* Minor corrections: use unused functions, add missing prototype, added fwd/invcoord to PJ

* Minor correction: MSVC barfs on va_arg type specification. Trying once more with added parens

* Reverting paren correction, which appears to be a non-solution

* Significant improvements to the OBS_API, plus a number of corrections, mostly in test code, to reflect API changes

* Added two missing prototypes

* Adding the proj_transform function and some related checks

* Improvements to proj_transform etc. based on suggestions from Even Rouault

* Reducing the libc include footprint of proj.h - again based on suggestions from Even Rouault

* A few minor corrections

* Eliminate a MSVC warning about non-initialized usage. Not an actual issue, as another check has locked the path, but at least this should calm down MSVC

* Improved support for the errno reset/restore paradigm

* Introduced the internal header proj_internal.h; Moved most non-API stuff from pj_obs_api.c to pj_internal.c

* Adding proj_internal.h to HEADERS_LIBPROJ to solve build problems

* Correcting a few pj...proj blunders in PJ_pipeline.c

* Correcting a few additional blunders in PJ_pipeline.c

* Changed angle-brackets to quotation marks in includes of proj_internal.h

* Some minor build system repairs

* Some PJ_CONTEXT usage simplifications following suggestions by Kristian Evers @kbevers

* Added version numbering to proj.h - Fixes #529

* remove proj_errno_restore macro, provide function implementation

* Add proj_get_definition. Fixes #538

* Added library specific deallocator proj_buffer_free, eliminating a potential cross heap issues on Windows. Thx to Even Rouault for spotting this

* Got rid of a meaningless cast in proj_buffer_free

* Added some missing functions to proj.def (again spotted by @rouault); removed some not-yet-implemented material from proj.h

* Renamed proj_get_definition/proj_buffer_free to proj_definition_create/proj_definition_destroy, for symmetry and clarity

* Renaming the definition handlers to proj_definition_retrieve / proj_free

* Renaming proj_free to proj_release

1 files changed, 66 insertions, 0 deletions

diff --git a/examples/pj_obs_api_mini_demo.c b/examples/pj_obs_api_mini_demo.c
new file mode 100644
index 00000000..855c37f8
--- /dev/null
+++ b/examples/pj_obs_api_mini_demo.c
@@ -0,0 +1,66 @@
+/*******************************************************************************
+    Tiny test of an evolving new API, demonstrating simple examples of
+    2D and 3D transformations.
+
+    The main transformation setup object is PJ, well known from the two
+    former proj APIs (projects.h and proj_api.h)
+
+    The main data objects PJ_COORD and PJ_OBS are new, but encapsulate
+    the older LP, XY etc. objects in a framework for storing a 3D
+    observation taken at a 4D point in space-time, and including some
+    additional metadata (e.g. a serial number or an epsg code).
+
+    PJ_OBS and PJ_COORD use unions to enforce explicit statement of what
+    kind of coordinates are expected at a given spot in the code, where
+    the old API uses type punning, implicitly assuming that "you know what
+    you do". For backward compatibility, the new API is not really type
+    safe in the sense that you cannot use a cartesian coordinate where a
+    geographic is expected - but it makes it possible to explicitly state
+    in the code whet the programmer expected and intended.
+
+    The proj thread contexts have not seen widespread use, so one of the
+    intentions with this new API is to make them less visible on the API
+    surface.
+    
+    A series of experiments have, however, shown that they, for (mostly)
+    historical reasons, are very hard to eliminate totally. But we have
+    reduced their API surface presence to a constructor and a destructor,
+    plus an extra argument to the PJ constructor, pj_create().
+    
+    For single threaded programs, the calls to the context constructor
+    and destructor may be left out, and the default context selected
+    by passing a null-pointer to pj_create.
+
+    Thomas Knudsen, 2016-10-30/2017-07-06
+*******************************************************************************/
+#include <stdio.h>
+#include <proj.h>
+
+int main (void) {
+    PJ_CONTEXT *C;
+    PJ *P;
+    PJ_COORD a, b;
+    
+    /* or you may set C=0 if you are sure you will use PJ objects from only one thread */
+    C = proj_context_create();
+
+    P = proj_create (C, "+proj=utm +zone=32 +ellps=GRS80");
+    if (0==P)
+        return puts ("Oops"), 0;
+
+    /* a coordinate union representing Copenhagen: 55d N, 12d E    */
+    /* note: PROJ.4 works in radians, hence the proj_torad() calls */
+    a = proj_coord (proj_torad(12), proj_torad(55), 0, 0);
+
+    /* transform to UTM zone 32, then back to geographical */
+    /* note the use of union selectors to indicate what kind of coordinates are expected */
+    b = proj_trans_coord (P, PJ_FWD, a);
+    printf ("easting: %g, northing: %g\n", b.en.e, b.en.n);
+    b = proj_trans_coord (P, PJ_INV, b);
+    printf ("longitude: %g, latitude: %g\n", b.lp.lam, b.lp.phi);
+
+    /* Clean up */
+    proj_destroy (P);
+    proj_context_destroy (C); /* may be omitted in the single threaded case */
+    return 0;
+}