[Proj] Some need for updated proj-4 manuals

[support.mn at elisanet.fi]

"Gerald I. Evenden" <geraldi.evenden at gmail.com> kirjoitti: 

> Between answering all the emails I sometime work on the manual .
> 
> Have you looked at the libproj4 manual.pdf on:
> 
> http://members.verizon.net/~gerald.evenden/proj4/
> 

It is very good, but as you said it is more targeted to the programmer and
implementer of the proj library. It tells how it was done and all the details.
But that is mostly what the end users (in my case) do not want to know. They
want to know "How to use it?" and all the other details they just let somebody
else (like you and me) to figure out.

Our end users only see the proj-4 projection-datum declaration
(or header). They have to figure out what header is needed
for different areas of the earth and different kind of maps. They
are conserned about what is mostly used there and how
to calibrate those maps to be used in computers. They have no idea
what calculations are done and when... and they also do not have to,
since the idea is just that. To provide a system that lets the computer
do the navigation and map projections and datum shifts. And lets
the user consentrate to his business... maybe getting to some point 
on earth.

Our map headers look like below, and that is all the end users
have to deal when using the program. The proj routines are
called and datums changed as needed.

# Google Earth view over North Europe
proj=nsper
lat_0=63d04’24.33"N
lon_0=24d45'52.42"E
k=1.000000
x_0=0
y_0=0
a=6371000
h=2310420
units=m
no_defs

(There should be the "datum=WGS84" line also to be exact. But
since it is so large view, it does not make a huge difference )

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

Let's take an example: We have some Windows Vista user. All he wants
to know is, what does he have to do to store the family photo album
into the computers HDD. He is not interested to know how the color
correction is calculated mathematically. He just wants to know how to
apply such a correction to a photo before storing it. So we never load
his brain with such details. It is completly an internal matter of the
Windows OS, nobody knows... and nobody cares (except the programmers
of course). He only needs some basic information what the color correction
does. but to know how it is done, just is waste of time for him.

Now we have a similar situation with this (navigation) program. The end user
only wants to know what are the parameters he have to enter with the
maps to make them work. All the details are not required.

-----

Now the average user opens some help page and trys to figure out what
is the projection. Does it look like Mercator or is it maybe Lamberts Conformal
Conic... Then he finds a list like on a help page:

"Proj-4 Parameters"

aea : Albers Equal Area
  Conic Sph&Ell
  lat_1= lat_2=

aeqd : Azimuthal Equidistant
  Azi, Sph&Ell
  lat_0 guam

etc. etc.


But he has no idea, what numbers should be given in lat_1 for "aea".

--------

Then he opens a new document... called

"Cartographic Projection Procedures for the UNIX
Environment—A User’s Manual"

He is trying to figure out how to use "aea" and what on earth is
"lat_1"?

But the manual starts to tell him how to program that library.
No... that is not what he is looking for. Then he finds that there
is a chapter

"Projection descriptions"

Now that what he is looking fo.

Usage and options: +proj=aea +lat 0=ö0 +lat 1=ö1 +lat 2=ö2

Still he does not know what is lat_0 called? Is it "standard parallel" or
"latitude of origin" or "what ever" ??

And where are all the new projections? There seems to be a second
and third manual descriping more projections....

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

The point is that the end user needs a manual where only the projections
and datums are descriped with the information how some change of
value affects the result. All other information just overloads his brain and
makes him angry and frustrated. ;)

> It is 123 pages but getting a bit old.  The version in my machine is up to 128 
> pages plus corrections and I am working on an improved TM section which will 
> add 7 or 8 pages.  The sections on cylindricals and pseudocylindricals are 
> fairly complete.  Most work is needed on conic.  Miscellaneous is fairly 
> complete.  The math for all projections is given so one can see how the 
> various options relate to the computations.  Internal library procedures are 
> fairly complete.
> 

As said, the point would be to separate those pages into two manuals:

1) Programmer's Manual
- all talk about implementation, how to use it, how it was done, and
the details

2) End User's Manual
- a list of available projections and datums and how to use them
and what are the parameters and how they affect the projection or
datum if altered...

> The above manual does not cover lproj options (-x etc.) but they are almost 
> identical to older documentation of proj.
> 

Well, the idea would be to keep the manual up to date with the library... at
least to some level.

> I would like some detailed illustrations related to things like local grid 
> systems but at the moment I do not have sufficiently detailed coastline file 
> to do them.
> 

That is exactly what is required: What is "Swiis Grid"?, what are the English
grid letters and numbers? Where goes Swedish grid. Australians seem to
have their own grid system. USA NAD grids are also rather soooky.. and
how to convert them to some meaningfull parameters when using
proj-4 defined maps. My opinion is that mostly you just omit the special
grid systems, since they usually just rename the projected plane's
coordinates with some minor shifts in numbers (maybe some false
northing and easting matter).

In our application the user only needs to know how to convert the grid
numbering to actual easting and northing values generated by the
calculations. So the local grid is more or less a "local joke"...

> My manuals do not do datums.
> 

Somebody should add the information related to datums, so that the end user
could use them correctly.

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

Our application's manuals tell what projections and datums are. What is
needed is "how to use them", "how does a change of some parameter
affect the projection", "what are the exact names of those parameters",
"which way towgs84 numbers should be given", "what projections are
used and how in different parts of the earth", etc.

Regards: Janne.