1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
# How to contribute to PROJ-data
Consult [PROJ CONTRIBUTING.md](https://github.com/OSGeo/PROJ/blob/master/CONTRIBUTING.md)
for general principles.
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 mentioned 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 .github/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
3. 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.
4. Add the grid name in `travis/expected_main.lst`, sorted alphabetically.
5. Mention copyright & license information in copyright_and_licenses.csv
Use [SPDX license identifiers](https://spdx.org/licenses/) where possible.
6. Add to git the new and modified files
7. git commit
8. Run the regenerate_index_html.py file (requires Python 3 and GDAL Python bindings)
9. git commit
10. 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 grid 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 maintenance
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.
|
