A re-rationalized API for PROJ.4

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

A re-rationalized API for PROJ.4

Kristian Evers-2

Hello everybody,

 

I want to direct your attention to the work Thomas Knudsen is doing on a new and more homogenous API for PROJ.4. Thomas presented his first ideas about a new API earlier this year when talk about transformation pipelines first started. Since then the initial pipeline pull request has been withdrawn and the changes needed to make transformation pipelines happen are broken into smaller more logical chunks. A new API being one of those smaller chunks. Before anyone gets their knickers in a twist, let me just stress the fact that this DOES NOT change the behavior of the old API (projects.h/proj_api.h), it merely adds a cleaner interface that will make usage of PROJ.4 a lot easier in the future.

Thomas has already typed up a description of his work but until now it has only been available on the GitHub page. This is his introduction to the new API:

 

The original proj API (defined in projects.h) has grown organically

over the years, but it has also grown somewhat messy.

 

The same has happened with the newer high level API (defined in

proj_api.h): To support various historical objectives, proj_api.h

contains a rather complex combination of conditional defines and

typedefs. Probably for good (historical) reasons, which are not

always evident from today's perspective.

 

This is an evolving attempt at creating a re-rationalized API

with primary design goals focused on sanitizing the namespaces.

Hence, all symbols exposed are being moved to the pj_ namespace,

while all data types are being moved to the PJ_ namespace.

 

Please note that this API is *orthogonal* to  the previous APIs:

Apart from some inclusion guards, projects.h and proj_api.h are not

touched - if you do not include proj.h, the projects and proj_api

APIs should work as they always have.

 

A few implementation details:

 

Apart from the namespacing efforts, I'm trying to eliminate three

proj_api elements, which I have found especially confusing.

 

FIRST and foremost, I try to avoid typedef'ing away pointer

semantics. I agree that it can be occasionally useful, but I

prefer having the pointer nature of function arguments being

explicitly visible.

 

Hence, projCtx has been replaced by PJ_CONTEXT *.

 

SECOND, I try to eliminate cases of information hiding implemented

by redefining data types to void pointers.

 

I prefer using a combination of forward declarations and typedefs.

Hence:

    typedef void *projCtx;

Has been replaced by:

    struct projCtx_t;

    typedef struct projCtx_t PJ_CONTEXT;

This makes it possible for the calling program to know that the

PJ_CONTEXT data type exists, and handle pointers to that data type

without having any idea about its internals.

 

(obviously, in this example, struct projCtx_t should also be moved

to struct pj_ctx some day...)

 

THIRD, I try to eliminate implicit type punning. Hence this API

introduces the OBSERVATION data type, for generic coordinate and

ancillary data handling.

 

It includes the PJ_SPATIOTEMPORAL and PJ_TRIPLET unions

making it possible to make explicit the previously used

"implicit type punning", where a XY is turned into a LP by

re#defining both as UV, behind the back of the user.

 

The bare essentials API presented here follows the PROJ.4

convention of sailing the coordinate to be reprojected, up on

the stack ("call by value"), and symmetrically returning the

result on the stack. Although the OBSERVATION object is 4 times

as large as the traditional XY and LP objects, timing results

have shown the overhead to be very reasonable.

 

See pj_proj_test.c for an example of how to use the API.

 

The pull request is found at https://github.com/OSGeo/proj.4/pull/445 and the example code can be found here: https://github.com/busstoptaktik/proj.4/blob/pipeline_plus_api/examples/pj_proj_test.c

 

Please share your thoughts on the new API that Thomas has been working on. There has already been some discussion about how to expose the thread-contexts of the PJ-objects. In the current incarnation they are somewhat hidden to the user compared the what’s in proj_api.h. On top of that, Thomas and I have personally discussed the projFileAPI which does not seem to be used outside of PROJ.4 itself (at least nothing shows up on google, closed source we have no idea about). Is this something people actually need?

 

/Kristian


_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj
Reply | Threaded
Open this post in threaded view
|

Re: A re-rationalized API for PROJ.4

support-2

ok,


... but NO thanks! .. if it does not add anything new .. for example a new projection .. we do NOT want to have it!! --- it is just some rewriting which forces all users to do some tricks and hours of extra work etc. with their working code without actually adding anything usable.

Please, do not make such changes that are not required!! -- fix bugs and add some **useful** features ... but do not play with the coding ... since that already works! (We actually PREFER to have it old fashion than anything new and stupid!) --- if you like to make a "clean" Proj.4 for yourself just rename it something else and use it! --- but do not mess with the current version ... we have had enough about those idiots that believe they have some KING ideas how everybody should write programs. And then after next 10 years comes the next one ... and the next one ... and the next one ... all are pushing some strange ideas to play with other programmers and make lot of work that is not at all required! Let it be!!


Rename it and do what ever you like but stop ***playing*** with the original Proj.4 source code, thanks!


Janne.


------------------------------------------------------------


Kristian Evers kirjoitti 2016-11-03 16:40:

Hello everybody,

 

I want to direct your attention to the work Thomas Knudsen is doing on a new and more homogenous API for PROJ.4. Thomas presented his first ideas about a new API earlier this year when talk about transformation pipelines first started. Since then the initial pipeline pull request has been withdrawn and the changes needed to make transformation pipelines happen are broken into smaller more logical chunks. A new API being one of those smaller chunks. Before anyone gets their knickers in a twist, let me just stress the fact that this DOES NOT change the behavior of the old API (projects.h/proj_api.h), it merely adds a cleaner interface that will make usage of PROJ.4 a lot easier in the future.

Thomas has already typed up a description of his work but until now it has only been available on the GitHub page. This is his introduction to the new API:

 

The original proj API (defined in projects.h) has grown organically

over the years, but it has also grown somewhat messy.

 

The same has happened with the newer high level API (defined in

proj_api.h): To support various historical objectives, proj_api.h

contains a rather complex combination of conditional defines and

typedefs. Probably for good (historical) reasons, which are not

always evident from today's perspective.

 

This is an evolving attempt at creating a re-rationalized API

with primary design goals focused on sanitizing the namespaces.

Hence, all symbols exposed are being moved to the pj_ namespace,

while all data types are being moved to the PJ_ namespace.

 

Please note that this API is *orthogonal* to  the previous APIs:

Apart from some inclusion guards, projects.h and proj_api.h are not

touched - if you do not include proj.h, the projects and proj_api

APIs should work as they always have.

 

A few implementation details:

 

Apart from the namespacing efforts, I'm trying to eliminate three

proj_api elements, which I have found especially confusing.

 

FIRST and foremost, I try to avoid typedef'ing away pointer

semantics. I agree that it can be occasionally useful, but I

prefer having the pointer nature of function arguments being

explicitly visible.

 

Hence, projCtx has been replaced by PJ_CONTEXT *.

 

SECOND, I try to eliminate cases of information hiding implemented

by redefining data types to void pointers.

 

I prefer using a combination of forward declarations and typedefs.

Hence:

    typedef void *projCtx;

Has been replaced by:

    struct projCtx_t;

    typedef struct projCtx_t PJ_CONTEXT;

This makes it possible for the calling program to know that the

PJ_CONTEXT data type exists, and handle pointers to that data type

without having any idea about its internals.

 

(obviously, in this example, struct projCtx_t should also be moved

to struct pj_ctx some day...)

 

THIRD, I try to eliminate implicit type punning. Hence this API

introduces the OBSERVATION data type, for generic coordinate and

ancillary data handling.

 

It includes the PJ_SPATIOTEMPORAL and PJ_TRIPLET unions

making it possible to make explicit the previously used

"implicit type punning", where a XY is turned into a LP by

re#defining both as UV, behind the back of the user.

 

The bare essentials API presented here follows the PROJ.4

convention of sailing the coordinate to be reprojected, up on

the stack ("call by value"), and symmetrically returning the

result on the stack. Although the OBSERVATION object is 4 times

as large as the traditional XY and LP objects, timing results

have shown the overhead to be very reasonable.

 

See pj_proj_test.c for an example of how to use the API.

 

The pull request is found at https://github.com/OSGeo/proj.4/pull/445 and the example code can be found here: https://github.com/busstoptaktik/proj.4/blob/pipeline_plus_api/examples/pj_proj_test.c

 

Please share your thoughts on the new API that Thomas has been working on. There has already been some discussion about how to expose the thread-contexts of the PJ-objects. In the current incarnation they are somewhat hidden to the user compared the what’s in proj_api.h. On top of that, Thomas and I have personally discussed the projFileAPI which does not seem to be used outside of PROJ.4 itself (at least nothing shows up on google, closed source we have no idea about). Is this something people actually need?

 

/Kristian


_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj


--
MNS Support
NNS Master Navigator Software
Copyright © Sapper Oy
www.mnspoint.com
[hidden email]

_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj
Reply | Threaded
Open this post in threaded view
|

Re: A re-rationalized API for PROJ.4

Mikael Rittri
In reply to this post by Kristian Evers-2

I just want to say that, although I personally will probably not bother to change to the new API, I have always found the traditional source code of Proj.4 difficult to read, and I am happy to see a new enthusiastic group of developers taking care of Proj.4.  The period of stagnation a few years ago was unfortunate.

 

Mikael Rittri

Carmenta

Sweden
http://www.carmenta.com

 


From: [hidden email] [mailto:[hidden email]] On Behalf Of Kristian Evers
Sent: Thursday, November 03, 2016 3:41 PM
To: PROJ.4 and general Projections Discussions
Subject: [Proj] A re-rationalized API for PROJ.4

 

Hello everybody,

 

I want to direct your attention to the work Thomas Knudsen is doing on a new and more homogenous API for PROJ.4. Thomas presented his first ideas about a new API earlier this year when talk about transformation pipelines first started. Since then the initial pipeline pull request has been withdrawn and the changes needed to make transformation pipelines happen are broken into smaller more logical chunks. A new API being one of those smaller chunks. Before anyone gets their knickers in a twist, let me just stress the fact that this DOES NOT change the behavior of the old API (projects.h/proj_api.h), it merely adds a cleaner interface that will make usage of PROJ.4 a lot easier in the future.

Thomas has already typed up a description of his work but until now it has only been available on the GitHub page. This is his introduction to the new API:

 

The original proj API (defined in projects.h) has grown organically

over the years, but it has also grown somewhat messy.

 

The same has happened with the newer high level API (defined in

proj_api.h): To support various historical objectives, proj_api.h

contains a rather complex combination of conditional defines and

typedefs. Probably for good (historical) reasons, which are not

always evident from today's perspective.

 

This is an evolving attempt at creating a re-rationalized API

with primary design goals focused on sanitizing the namespaces.

Hence, all symbols exposed are being moved to the pj_ namespace,

while all data types are being moved to the PJ_ namespace.

 

Please note that this API is *orthogonal* to  the previous APIs:

Apart from some inclusion guards, projects.h and proj_api.h are not

touched - if you do not include proj.h, the projects and proj_api

APIs should work as they always have.

 

A few implementation details:

 

Apart from the namespacing efforts, I'm trying to eliminate three

proj_api elements, which I have found especially confusing.

 

FIRST and foremost, I try to avoid typedef'ing away pointer

semantics. I agree that it can be occasionally useful, but I

prefer having the pointer nature of function arguments being

explicitly visible.

 

Hence, projCtx has been replaced by PJ_CONTEXT *.

 

SECOND, I try to eliminate cases of information hiding implemented

by redefining data types to void pointers.

 

I prefer using a combination of forward declarations and typedefs.

Hence:

    typedef void *projCtx;

Has been replaced by:

    struct projCtx_t;

    typedef struct projCtx_t PJ_CONTEXT;

This makes it possible for the calling program to know that the

PJ_CONTEXT data type exists, and handle pointers to that data type

without having any idea about its internals.

 

(obviously, in this example, struct projCtx_t should also be moved

to struct pj_ctx some day...)

 

THIRD, I try to eliminate implicit type punning. Hence this API

introduces the OBSERVATION data type, for generic coordinate and

ancillary data handling.

 

It includes the PJ_SPATIOTEMPORAL and PJ_TRIPLET unions

making it possible to make explicit the previously used

"implicit type punning", where a XY is turned into a LP by

re#defining both as UV, behind the back of the user.

 

The bare essentials API presented here follows the PROJ.4

convention of sailing the coordinate to be reprojected, up on

the stack ("call by value"), and symmetrically returning the

result on the stack. Although the OBSERVATION object is 4 times

as large as the traditional XY and LP objects, timing results

have shown the overhead to be very reasonable.

 

See pj_proj_test.c for an example of how to use the API.

 

The pull request is found at https://github.com/OSGeo/proj.4/pull/445 and the example code can be found here: https://github.com/busstoptaktik/proj.4/blob/pipeline_plus_api/examples/pj_proj_test.c

 

Please share your thoughts on the new API that Thomas has been working on. There has already been some discussion about how to expose the thread-contexts of the PJ-objects. In the current incarnation they are somewhat hidden to the user compared the what’s in proj_api.h. On top of that, Thomas and I have personally discussed the projFileAPI which does not seem to be used outside of PROJ.4 itself (at least nothing shows up on google, closed source we have no idea about). Is this something people actually need?

 

/Kristian


_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj
Reply | Threaded
Open this post in threaded view
|

Re: A re-rationalized API for PROJ.4

Roger Oberholtzer-2
+1 Mikael

On Mon, Nov 14, 2016 at 1:02 PM, Mikael Rittri <[hidden email]> wrote:

I just want to say that, although I personally will probably not bother to change to the new API, I have always found the traditional source code of Proj.4 difficult to read, and I am happy to see a new enthusiastic group of developers taking care of Proj.4.  The period of stagnation a few years ago was unfortunate.

 

Mikael Rittri

Carmenta

Sweden
http://www.carmenta.com

 


From: [hidden email] [mailto:[hidden email]] On Behalf Of Kristian Evers
Sent: Thursday, November 03, 2016 3:41 PM
To: PROJ.4 and general Projections Discussions
Subject: [Proj] A re-rationalized API for PROJ.4

 

Hello everybody,

 

I want to direct your attention to the work Thomas Knudsen is doing on a new and more homogenous API for PROJ.4. Thomas presented his first ideas about a new API earlier this year when talk about transformation pipelines first started. Since then the initial pipeline pull request has been withdrawn and the changes needed to make transformation pipelines happen are broken into smaller more logical chunks. A new API being one of those smaller chunks. Before anyone gets their knickers in a twist, let me just stress the fact that this DOES NOT change the behavior of the old API (projects.h/proj_api.h), it merely adds a cleaner interface that will make usage of PROJ.4 a lot easier in the future.

Thomas has already typed up a description of his work but until now it has only been available on the GitHub page. This is his introduction to the new API:

 

The original proj API (defined in projects.h) has grown organically

over the years, but it has also grown somewhat messy.

 

The same has happened with the newer high level API (defined in

proj_api.h): To support various historical objectives, proj_api.h

contains a rather complex combination of conditional defines and

typedefs. Probably for good (historical) reasons, which are not

always evident from today's perspective.

 

This is an evolving attempt at creating a re-rationalized API

with primary design goals focused on sanitizing the namespaces.

Hence, all symbols exposed are being moved to the pj_ namespace,

while all data types are being moved to the PJ_ namespace.

 

Please note that this API is *orthogonal* to  the previous APIs:

Apart from some inclusion guards, projects.h and proj_api.h are not

touched - if you do not include proj.h, the projects and proj_api

APIs should work as they always have.

 

A few implementation details:

 

Apart from the namespacing efforts, I'm trying to eliminate three

proj_api elements, which I have found especially confusing.

 

FIRST and foremost, I try to avoid typedef'ing away pointer

semantics. I agree that it can be occasionally useful, but I

prefer having the pointer nature of function arguments being

explicitly visible.

 

Hence, projCtx has been replaced by PJ_CONTEXT *.

 

SECOND, I try to eliminate cases of information hiding implemented

by redefining data types to void pointers.

 

I prefer using a combination of forward declarations and typedefs.

Hence:

    typedef void *projCtx;

Has been replaced by:

    struct projCtx_t;

    typedef struct projCtx_t PJ_CONTEXT;

This makes it possible for the calling program to know that the

PJ_CONTEXT data type exists, and handle pointers to that data type

without having any idea about its internals.

 

(obviously, in this example, struct projCtx_t should also be moved

to struct pj_ctx some day...)

 

THIRD, I try to eliminate implicit type punning. Hence this API

introduces the OBSERVATION data type, for generic coordinate and

ancillary data handling.

 

It includes the PJ_SPATIOTEMPORAL and PJ_TRIPLET unions

making it possible to make explicit the previously used

"implicit type punning", where a XY is turned into a LP by

re#defining both as UV, behind the back of the user.

 

The bare essentials API presented here follows the PROJ.4

convention of sailing the coordinate to be reprojected, up on

the stack ("call by value"), and symmetrically returning the

result on the stack. Although the OBSERVATION object is 4 times

as large as the traditional XY and LP objects, timing results

have shown the overhead to be very reasonable.

 

See pj_proj_test.c for an example of how to use the API.

 

The pull request is found at https://github.com/OSGeo/proj.4/pull/445 and the example code can be found here: https://github.com/busstoptaktik/proj.4/blob/pipeline_plus_api/examples/pj_proj_test.c

 

Please share your thoughts on the new API that Thomas has been working on. There has already been some discussion about how to expose the thread-contexts of the PJ-objects. In the current incarnation they are somewhat hidden to the user compared the what’s in proj_api.h. On top of that, Thomas and I have personally discussed the projFileAPI which does not seem to be used outside of PROJ.4 itself (at least nothing shows up on google, closed source we have no idea about). Is this something people actually need?

 

/Kristian


_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj



--
Roger Oberholtzer

_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj
Reply | Threaded
Open this post in threaded view
|

Re: A re-rationalized API for PROJ.4

Howard Butler-3
In reply to this post by support-2

> On Nov 14, 2016, at 3:42 AM, [hidden email] wrote:
>
> ok,
>
>
>
> ... but NO thanks! .. if it does not add anything new .. for example a new projection .. we do NOT want to have it!! --- it is just some rewriting which forces all users to do some tricks and hours of extra work etc. with their working code without actually adding anything usable.
>
> Please, do not make such changes that are not required!! -- fix bugs and add some **useful** features ... but do not play with the coding ... since that already works! (We actually PREFER to have it old fashion than anything new and stupid!) --- if you like to make a "clean" Proj.4 for yourself just rename it something else and use it! --- but do not mess with the current version ... we have had enough about those idiots that believe they have some KING ideas how everybody should write programs. And then after next 10 years comes the next one ... and the next one ... and the next one ... all are pushing some strange ideas to play with other programmers and make lot of work that is not at all required! Let it be!!
>
>
>
> Rename it and do what ever you like but stop ***playing*** with the original Proj.4 source code, thanks!
>

Janne,

You misunderstand the concept of open source software and your company's usage and relationship to it. You are essentially proposing is that we the community only fix bugs that impact your company's usage of Proj.4. As I've stated before, there's nothing that prevents you from using older versions of the software. If your company's software is not robust to changes in Proj.4, it is not the Proj.4 project's fault. It is your company's for not putting enough engineering and testing around your product's (free) use of it.

Some interesting things I've found while researching Gerald and his software for the article [1] I've been working on:

- Proj.4's original code style was evolved from Gerald's work on other programs such as Mapgen and WOLF. He refined his style by applying lessons of the previous system he developed, like any good programmer.
- There were wildly varying code styles for large C projects evolving in the mid 1980s as evidenced by the evolution of C++ and rise of object oriented programming. Typical GNU-style C hadn't taken hold, and the patterns which we take for granted in many C libraries today, such as opaque object APIs, public vs. private API, and include file management were not widely settled.
- 30+ year old compilers were not very good. Code styles often reflected compiler deficiencies as much as they did explicit design choices.

Please consider Proj.4 in that context. I presume the idiots you're talking about are the fashion-concious, fad-applying programmers, and not Thomas or any of the rest of us contributing and working to improve the manageability, usefulness, and professionalism of the Proj.4 codebase and its website at http://proj4.org. If you've been following any of the thread that Thomas has been writing in github and on the mailing list, you'll know that his improvements are not simply for his edification. It's still C, and the only software fashionability that could ever possibly be achieved is hipster irony.

Here's a list of things the Proj.4 project now has that it did not when Gerald was just tossing tarballs into the ether:

- revision control
- bug listing/tracking
- automated tests
- automated tests that run every time code is committed
- a website that is generated every time code is committed
- releases
- contributors

Each of these things improve the Proj.4 to make your company's (free) use of the software more valuable. None of them would exist if people like Thomas were not committed to keeping Proj.4 viable and alive as an ongoing open source software project. Your company benefits from that, and if you think it doesn't, please internally fork the code and do your own thing. When you do, we will be ahead of you at every iteration.

Howard


[1] http://lists.maptools.org/pipermail/proj/2016-September/007493.html


_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj