EPSG Tables
	===========

The .csv files in this directory are an extract of tables from the EPSG 
projection database in CSV (comma separated value) format.  These same
files come with the source distribution in the libgeotiff/csv directory.

Detailed information on the EPSG database can be found at:

  http://www.epsg.org/

Most EPSG tables have been dumped to csv.  Unlike earlier dumps (4.3) these
are intended to be "true" csv files.  In particular quotes within quoted
strings are doubled to escape them, rather than using backslash quoting.  
Newlines may appear within quoted field values (as real raw newline 
characters).  All table names are converted to lower case, and spaces replaced
with underscores to make them more easily worked with. 

In addition to the EPSG tables dumped to csv, the following additional items
are present:

 stateplane.csv: my own effort to related "USGS" state plane numbers with their
                 currently preferred EPSG coordinate reference system 
                 counterpart. 

 pcs.csv: An attempt to collect most information about a PCS, including the
          projection parameters into one fast access file. 
 gcs.csv: An attempt to collect most information about a GCS, including
          the WGS84 shift parameters (if there is only one path in EPSG).
 projop_wparm.csv: Projection operations with projection parameters.  
          Essentially the coordinate_operation.csv table with the parameters
          from coordinate_operation_parameter_values.csv appended to each 
          record.
 build_pcs.py: a python script to build pcs.csv and gcs.csv from the other
               EPSG files. 
 csv_tools.py: supportting python functions for build_pcs.py.
 csv.txt: A definition of the csv format.
 
Libgeotiff uses the following tables.  The rest are present for completeness.

 pcs.csv
 gcs.csv
 ellipsoid.csv
 prime_meridian.csv
 unit_of_measure.csv
 datum.csv
 projop_wparm.csv


Overrides
---------

In some cases we wish to override the EPSG definition - often to provide
a single preferred towgs84 transformation for datums.  Overrides to GCS
and PCS definitions should be put in the files:

  gcs.override.csv
  pcs.override.csv

in a format the same as the pcs.csv and gcs.csv files.  Additions to these
tables should normally be accompanied by detailed comments and references
to any relavent tickets.  

Note that we deliberately keep alterations separate from the EPSG definitions
in gcs.csv and pcs.csv to avoid violating the EPSG distribution license
which requires that the definitions be distributed in unaltered form.  


Generating CSV Files
--------------------

The csv files are generated from the Postgres dump provided by EPSG.

1) Load epsg database into postgres instance named "epsg".

   1a) Insert a line "\encoding LATIN1" at start of the _Data_ sql file. 

   1b) Modify the _Table_ sql file, changing every occurance of (254) to 
   (300).  This is to ensure that text fields are still big enough 
   after Latin1 special characters are expanded into multi-byte 
   UTF8 characters. 

   1c) run "load_pg.sh" in the directory where the .sql files are found.

   eg. 
 
     ../load_pg.sh >& log

   1d) Make sure you search the log file for "error" in case something went
   wrong. 

2) Dump the database to .csv files in the libgeotiff/csv directory.

     python pg_to_csv.py

   Puts the results in the out directory.  After some inspection move them
   into this directory (libgeotiff/csv).

3) Build the pcs and gcs csv files.

   python build_pcs.py

4) Update this file to note the current version of the ESPG database being
   used.

5) Commit the changes in libgeotiff repository.


Generating Downstream Products - GDAL
-------------------------------------

Rebuild gdal_datum.csv.  Unfortunately this depends on a set of ArcGIS
.prj files that are usually only available on Frank's machine:

 python add_esri_column.py

Copy the following files from libgeotiff/csv to gdal/data:

 coordinate_axis.csv ellipsoid.csv gcs.csv gcs.override.csv
 gdal_datum.csv pcs.csv pcs.override.csv prime_meridian.csv
 projop_wparm.csv stateplane.csv unit_of_measure.csv

svn commit these files. 


Generating Downstream Products - PROJ.4
---------------------------------------

From the GDAL distribution (do after updating GDAL) do the following in
the gdal/data directory (with GDAL Python scripts operational):

  rm epsg
  epsg_tr.py --config OVERRIDE_PROJ_DATUM_WITH_TOWGS84 FALSE -proj4 -skip -list gcs.csv > epsg
  epsg_tr.py --config OVERRIDE_PROJ_DATUM_WITH_TOWGS84 FALSE -proj4 -skip -list pcs.csv >> epsg

Commit this in proj/nad.


Generating Downstream Products - PostGIS
----------------------------------------


From the GDAL distribution (do after updating GDAL) do the following in
the gdal/data directory (with GDAL Python scripts operational):

  rm spatial_ref_sys.sql
  epsg_tr.py -postgis -skip -list gcs.csv > spatial_ref_sys.sql
  epsg_tr.py -postgis -skip -list pcs.csv >> spatial_ref_sys.sql