MAP_INSTALL

Revised version by Gilles Duvert on July 2014
Small revision by Alain on Jan. 2019 (mostly GSHHS --> GSHHG)
Removed gshhs[g] stuff now that IDLffShape works. (GD)
Revised version by Gilles Duvert on May 2019

==============================INTRODUCTION=================================

To provide map projections support your first need to make sure the
proj library available at https://proj.org (formerly proj4.org)
It is probably already installed on your computer.

If GDL does not find (lib)PROJ files automatically, use 
"-DLIBPROJ=YES" "-DLIBPROJDIR=DIR" as arguments for cmake. 
(were 'DIR' is the location of the compiled library.

==============================MAP_* COMMANDS in GDL=======================

The complete suite of projection-related commands is available with GDL
(map_set, map_proj_init, map_horizon, map_continents...). The main difference
with IDL is that GDL provides the same interface, but for all of the 150 or so projections
of the PROJ library!

This is done, at a cost: projections are internally represented in a compact(!) 
form in IDL via the !MAP structure. We maintain a minimum compatibility with
the original IDL structure, that is, a !MAP structure made with IDL that would
be passed 'as is' in GDL using, e.g., a save file, would still "work". The contrary
is impossible, as the GDL structure encodes more projections. PROJ aficionados will quickly
realize that they can define projections in GDL as easily as with the 'proj' program.

MAP_CONTINENTS is now implemented in GDL as a procedure using maintly the Natural Earth 
(http://www.naturalearthdata.com/, hereafter NE) shapefiles plus gshhs shapefiles 
(https://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html) for continental outlines, and our 
new support for reading the ESRI Shapefile format in which one can find any number of geospatial informations.
Since we added support for IDLffShape (meaning IDL f[ile] f[ormat] Shape[file] tool)
one can now use shapefile tools to do more useful work than just MAP_CONTINENTS. 
pro/gdlDrawShapefile.pro is such an utility. See also
coyote's http://www.idlcoyote.com/idldoc/maps/cgdrawshapes.html
 
The necessary shapefiles for MAP_CONTINENTS are now shipped with GDL (in !DIR+"/share/gnudatalanguage/maps")
However a knowledgeable user may use a more recent version by setting the variable
!GDL_MAPS_DIR directly such as
GDL> !GDL_MAPS_DIR="/a/path/to/the/data"

The FILLing of Natural Earth shapefiles is not possible as these are not closed, oriented, shapes.
This is why we used also gshhs shapefiles (seriously edited with qgis ( https://www.qgis.org ).
We'll be happy to hear about better opensource shapefiles than those provided with GDL.

==================================DEMO=======================================

see "test_map.pro" in the testsuite/

============================TWEAKING NEW PROJECTIONS==========================

The file resource/map/projections.ods is made to keep all the info about PROJ's projections needed by
GDL, however GDL procedures use a digested version of this file, "projDefinitions.sav" also present in
resource/map/.

projections.ods is the file to update to add more projections when they are available in PROJ.
the format is very simple: PROJ little name, commonly accepted name, one possible alias,
hints about projection type, required parameters, accepted parameters.
Pay attention to the hints. the general projection type (conic, cylindric ...) is used to guess the horizons.
noRot is crucial to avoid problems with the rare projections that crashes when used with PROJ's general oblique
transformation (the way GDL copes with non-null center latitude when the projection does not accept lat_0 keyword. aitoff is an example). 
 
Once projections.ods has been updated, make a copy as a CSV file (projections.csv) and use the following commands:
?DL> csv_proj=read_csv("projections.csv",n_table=1)
?DL>save,csv_proj,filename="csv.sav"

Then, a conversion from the comma separated value text to the save file used internaly by GDL is
done using the "map_proj_auxiliary_read_csv" procedure hidden in the map_proj_init.pro file. Simple enough.
The procedure produces a new "projDefinitions.sav" that must be installed in resource/map/. 
The new projections.ods should be reported here (GitHub). the csv files can be deleted.

Incidentally, this projections.ods file is apparently also the one and only place on the Net where all the PROJ projections
and their associated parameters happens to be available at a glance...