Discontinue use of deprecated Proj4 API and switch to Proj6 API

[tvrusso]

Proj 5 has a new API that is very different from the one in Proj.4. Proj 5 still supports the Proj4 API, but this API is deprecated in 6.0 and will be removed in 7.0.

To remain even as relevant as it is, DFLib ought to use the Proj5.0 API.

Unfortunately, the use of the Proj4 API pervades DFLib, and qDF makes heavy use of DF_Proj_Point, the one with the use of the Proj4 API most likely to be difficult to migrate.

See https://proj.org/development/migration.html for the barest hint of how this will have to go. Basically, where we used to specify from and to coordinate systems, the new API is much more focused on the "to" --- making assumptions about the "from" that I am not yet sure how to deal with. Sadly, a lot of the documentation of the new API appears to be blank in the proj4.org site.

[tvrusso]

See also this page to see what other projects are using the deprecated API and their status:

https://github.com/OSGeo/proj.4/wiki/proj.h-adoption-status

[tvrusso]

The actual users of DFLib are all in DFLib's demo programs and in the associated GUI program, qDF. None of these do anything truly fancy with respect to coordinate conversion --- DFLib's demo programs all mostly work in either NAD27 or NAD83 from the user end, either in UTM or LatLon, and internally do all computations in mercator wgs84. That is, we are explicitly acting as if transformation from user coordinates to internal coordinates can always be done by first converting the user coordinates to WGS84 lat/lon, then the WGS84 lat/lon to mercator. This can, of course, also be done in the proj5 api, it's just not as simply as saying "these coordinates are in this coordinate system". One has to explicitly set up a transformation pipeline that converts user coordinates to WGS84 lat/lon, possibly involving a datum shift (the details of which were generally just hidden in the proj4 api).

The affected classes would be DF_LatLon_Point and DF_Proj_Point, and a couple of demo programs (nonoise and testlsDFfix, SimpleDF, SimpleDF2, and ProjUnitTests). The pyProjPoint Python demo would also need fixing.

Instead of specifying the user coord as simply "proj=foo datum=bar" one would have to specify the part of a transformation pipeline that takes "proj=foo datum=bar" into lat/lon WGS84, and then DFLib would simply tack on the last step of the transformation pipeline, that takes lat/lon to mercator on the WGS84 ellipsoid.

The impact will very much change the footprint of a few class methods, but should not really be a huge deal. Just more of a deal than is currently warranted now that the people for whom DFLib was originally written (New Mexico search and rescue volunteers searching for missing aircraft) hardly ever even perform the DF data reduction provided by this library and qDF, OR even the original "ELT-DFer" program that inspired it.

In the meantime, should Proj6.0 come out before I get to this work, there is at least a way to continue using the old API until it's really removed in Proj7.0. That requires adding -DACCEPT_USE_OF_DEPRECATED_PROJ_API_H=1 to the CFLAGS (or just #define that macro before including proj_api.h).

[tvrusso]

The migration pages have been moved. The new one documenting migration from proj.4 to proj.5 API is:
https://proj.org/development/migration.html#version-4-to-5-api-migration

And then from proj 4 to 6: https://proj.org/development/migration.html

Proj 6 is already out and all over the place. DFLib won't build against it yet.

[tvrusso]

Note also that there is a proj_create_crs_to_crs function that may be the easiest way to go forward with this. We currently just create projPJ objects for the mercator projection and another for the "user" projection, and use pj_transform to go back and forth. The thing returned by proj_create_crs_to_crs can be used in a proj_trans() call with the PJ_FWD or PJ_INV direction to go back and forth instead. This would not be a huge modification.

[tvrusso]

Changing title. No point going to the proj5 API now that 6 is already out. Let's go right to the current one.

[tvrusso]

Also, qDF has a "coordinate system builder" that returns lists of old-style proj.4 arguments, instead of a single string of "+" arguments (e.g. 'proj=latlon' and 'datum=NAD27' instead of "+proj=latlon +datum=NAD27"). This vector is passed into DFLib's current constructor for the DF_Proj_Point class. To maintain backward compatibility of the interface, we can continue to support this constructor and simply concatenate the strings with "+" prefixing them all before calling the proj_create_crs_to_crs function.

We should have a second constructor that just takes the single string directly. Let's deprecate the one that qDF uses, and then we can change qDF, too.

[tvrusso]

See also: https://www.gaia-gis.it/fossil/libspatialite/wiki?name=PROJ.6

If we are happy to pitch the proj.4 style altogether, we can perhaps simplify specification of CRS using WKT format instead of proj strings.

The mercator projection used internally by the DF_Proj* classes is just:

PROJ.4 string:
+proj=merc +lat_ts=0 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs +type=crs

WKT2:2019 string:
PROJCRS["unknown",
    BASEGEOGCRS["unknown",
        DATUM["World Geodetic System 1984",
            ELLIPSOID["WGS 84",6378137,298.257223563,
                LENGTHUNIT["metre",1]],
            ID["EPSG",6326]],
        PRIMEM["Greenwich",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8901]]],
    CONVERSION["unknown",
        METHOD["Mercator (variant B)",
            ID["EPSG",9805]],
        PARAMETER["Latitude of 1st standard parallel",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8823]],
        PARAMETER["Longitude of natural origin",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8802]],
        PARAMETER["False easting",0,
            LENGTHUNIT["metre",1],
            ID["EPSG",8806]],
        PARAMETER["False northing",0,
            LENGTHUNIT["metre",1],
            ID["EPSG",8807]]],
    CS[Cartesian,2],
        AXIS["(E)",east,
            ORDER[1],
            LENGTHUNIT["metre",1,
                ID["EPSG",9001]]],
        AXIS["(N)",north,
            ORDER[2],
            LENGTHUNIT["metre",1,
                ID["EPSG",9001]]]]

(this is the output of projinfo using the old-style projection specification, showing how it translates into WKT)

But DFLib's use is so simple this may be overkill, and maybe sticking to proj format is fine.

[tvrusso]

One thing that is slowing me down on working on this --- the old Proj library had a function 'dmstor" that converted degrees, minutes, seconds format of the string form that cs2cs likes into radians, and I use that silly function in the demo programs that I use for testing. This function is no longer part of the public interface to proj, and is basically treated as an internal function for use in proj's own programs.

I will have to come up with a substitute for parsing the input files that programs like SimpleDF use, so that I can actually run tests like I did when developing DFLib. This isn't rocket science, but is something I just have to find the time to write and test properly so it can be a drop-in replacement for what Proj no longer lets me use.