diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 120 |
1 files changed, 117 insertions, 3 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c8c8411..5a0840d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,120 @@ -# How to contribute to proj-datumgrid-geotiff +# How to contribute to PROJ-data -Consult [PROJ CONTRIBUTING.md](https://github.com/OSGeo/proj.4/blob/master/CONTRIBUTING.md) +Consult [PROJ CONTRIBUTING.md](https://github.com/OSGeo/PROJ/blob/master/CONTRIBUTING.md) for general principles. -TODO. Mention the scripts currently at https://github.com/rouault/sample_proj_gtiff_grids/ +This document focuses on how to specifically contribute a new grid to PROJ-data + +Preliminary: +* The grid must be in the + [Geodetic TIFF grids (GTG)](https://github.com/OSGeo/PROJ/blob/master/docs/source/specifications/geodetictiffgrids.rst) format. + The [grid_tools](grid_tools) directory contains tools to convert grids in other format such as NTv2 (.gsb) or GTX to GTG) +* The grid must be freely licensed as mentionned in [README.DATA](README.DATA). +* We consider that you are familiar with the basic [GitHub workflow to submit a pull request](https://help.github.com/en/articles/creating-a-pull-request) + +Grids are organized by producing agencies, with a short identifier. +The short identifier is built as: +{two_letter_country_code_of_agency_nationality}_{short_name_for_agency} +For example `fr_ign`, for IGN France. +If a new agency has to be created: +1. Create a new directory whose name is based on the above naming scheme +2. Go in that directory +3. Create a {agency_id}_README.txt file whose content is inspired from similar existing files +4. Create a .github subdirectory +5. Create a symbolic link from the file created at 3. as README.md: ln -s ../{agency_id}_README.txt README.md +6. Edit CMakeLists.txt at the root of the repository to package the new directory + +The steps for adding a GeoTIFF grid to an existing subdirectory are: +1. Make sure the naming convention for the grid is {agency_id}_{some_name}.tif +2. Add it into the directory +2. Edit the {agency_id}_README.txt file. You should mention its + source/provenance, its license, its format (GTiff), the source and + target coordinate reference systems of the grid, its accuracy when known, + and all other relevant information. + For a vertical shift grid, mention the horizontal CRS (interpolation CRS) + to use. + Replicating an existing entry will be the easiest. +3. Add the grid name in `travis/expected_main.lst`, sorted alphabetically. +4. Add to git the new and modified files +5. git commit +6. Run the regenerate_index_html.py file (requires Python 3 and GDAL Python bindings) +7. git commit +8. git push and issue the pull request + +Adding a grid in a package of grids is not enough to make it directly and transparently +usable by PROJ. If the source and target coordinate reference systems are known of +the PROJ database (typically they have a EPSG code), a transformation for them using +the grid must be referenced in the PROJ database. Generally, the EPSG database will +already have an entry for the grid, sometimes with a slightly different name. +The relevant file to look into is [grid_transformation.sql](https://github.com/OSGeo/PROJ/blob/master/data/sql/grid_transformation.sql). +If the gris is not yet registered in the EPSG database, you are *strongly* encouraged to +engage with EPSG to register it. This will make its addition to PROJ and its later maintainance +much easier. http://www.epsg.org/EPSGDataset/Makechangerequest.aspx explains the procedure +to follow to submit a change request to EPSG. + +You may find an entry like the following one: +``` +INSERT INTO "grid_transformation" VALUES( + 'EPSG','15958', -- transformation code + 'RGF93 to NTF (2)', -- transformation name + NULL,NULL, + 'EPSG','9615','NTv2', -- transformation method + 'EPSG','4171', -- source CRS + 'EPSG','4275', -- target CRS + 'EPSG','3694', -- area of use + 1.0, -- accuracy + 'EPSG','8656','Latitude and longitude difference file','rgf93_ntf.gsb', -- grid name + NULL,NULL,NULL,NULL, + NULL,NULL, -- interpolation CRS + 'ESRI-Fra 1m emulation', + 0); +``` +This is a transformation from EPSG:4171 (RGF93) to EPSG:4275 (NTF) using the rgf93_ntf.gsb grid. + +Or for a vertical transformation +``` +INSERT INTO "grid_transformation" VALUES( + 'EPSG','7001','ETRS89 to NAP height (1)', + NULL,NULL, + 'EPSG','9665','Geographic3D to GravityRelatedHeight (US .gtx)', + 'EPSG','4937', + 'EPSG','5709', + 'EPSG','1275', + 0.01, + 'EPSG','8666','Geoid (height correction) model file','naptrans2008.gtx', + NULL,NULL,NULL,NULL, + 'EPSG','4289', -- interpolation CRS has been manually added + 'RDNAP-Nld 2008',0); +``` + +If the EPSG dataset does not include an entry, a custom entry may be added in the [grid_transformation_custom.sql](https://github.com/OSGeo/PROJ/blob/master/data/sql/grid_transformation_custom.sql) file. + +For this grid to be completely known of PROJ, we must add an entry in the database to describe the grid. + +This is done in the [grid_alternatives.sql](https://github.com/OSGeo/PROJ/blob/master/data/sql/grid_alternatives.sql) file. + +``` +INSERT INTO grid_alternatives(original_grid_name, + proj_grid_name, + old_proj_grid_name, + proj_grid_format, + proj_method, + inverse_direction, + package_name, + url, direct_download, open_license, directory) + +VALUES ('rgf93_ntf.gsb', -- grid name as in the grid_transformation.sql file. + 'fr_ign_ntf_r93.tif', -- PROJ grid name + NULL, -- should be NULL for new grids + 'GTiff', -- format. Should be GTiff + 'hgridshift', -- one of hgridshift (for horizontal shift grids), vgridshift (for vertical<-->vertical adjustmenents) or geoid_like (for transformations between vertical and ellipsoidal heights) + 1, -- 0 in most cases. Here, 1 because of the inverse direction of that particular case + NULL, -- should be NULL + 'https://cdn.proj.org/fr_ign_ntf_r93.tif', -- should be 'https://cdn.proj.org/' + proj_grid_format + 1, -- should be 1 + 1, -- should be 1 + NULL -- should be NULL +); +``` + +After rebuilding the PROJ database (`make`), you can check the output of `src/projinfo -s EPSG:XXXX -t EPSG:YYYY --spatial-test intersects` if the grid is properly recognized. |