This project is a reference, well-tested implementation of conversion algorithms for Polish geobotanical grid called ATPOL.

The grid was developed in Institute of Botany, Jagiellonian University, Krakow, Poland in 1970s for the immortal work called "Distribution atlas of vascular plants in Poland". It covers 700 x 700 km area (with whole Poland inside).

The grid was initially drawn by hand on available maps, then copied also by hand, as no tools like xero were then available. When GPS tools became popular, Institute of Botany published its online version with computed coordinates (with 1 second accuracy).

These coordinates were used by researchers as a reference, however the mathematical background of this grid was never published. In Polish internet fora, there was a long discussion without any definite conclusion. The only one possible conversion was to take the tabularized grid data and to perform the linear (incorrect, but the only one possible) interpolation.

The extensive mathematical research done in 2015 uncovered the mathematical mystery of the ATPOL grid. The exact solution was found by reverse engineering of the tabularized values and fitting dozens of geographical projections. The findings and proposed algorithm was published (in Polish) in:

Ł. Komsta. ATPOL geobotanical grid revisited – a proposal of coordinate conversion algorithms. Annales UMCS Sectio E Agricultura 2016, 71, 1, 33-37.

and this is the main citing reference for OpenATPOL. As one of the reviewers of above paper explicitly asked for consulting these results with Institute of Botany before publication, the author was forced to try and got the confirmation, that this reasoning is correct. Although the projection seems to be quite strange (as there were no printed maps in such projection, moreover the assumed Earth radius is equal to 6390 km), this projection was chosen as a compromise to fit all available hand-drawn maps. Therefore, these algorithms can be surely used without any risk that they are incorrect.

## Definition

The ATPOL projection is Equidistant Conic Projection (EQDC) with one tangent (the cone touches the sphere but does not cross it) at the latitude $$\varphi_0 = 52^\circ$$N. The central (vertical) meridian is chosen to be $$\lambda_0 = 19^\circ$$E. The central point of the projection $$(52^\circ N, 19^\circ E)$$ is defined to have coordinates $$x_0 = 330$$km, $$y_0 = 350$$km. The Earth radius is chosen to be $$R = 6390$$km. The coordinates increase towards South and East (they are equal to zero in NW corner of the grid).

The first two letters denote the square with 100 km size, as in the figure above. The smaller 10 x 10km square units are denoted by two additional numbers, but in reverse way ($$y$$ is the first coordinate). The division can be done recursively, so AB1234 is a square with 1 km dimension, AB987654 is 100m, and so on.

The $$x,y$$ coordinates are never used in practice, however they represent an exact position in ATPOL projection and they are an intermediate step when geographical coordinates are converted to ATPOL grid. When grid is given, the position inside the square can be done in relative way by giving $$o_x$$ and $$o_y$$ values in range $$(0,1)$$. Two zeros means upper left (NW) corner of the square, whereas two 0.5 values means the middle of the square.

The coordinates are in currently used WGS84 coordinate system. Although the old maps could be drawn in Pulkowo 1942 coordinate systems, the difference between these coordinate systems is less than hand-copying error of the maps that time.

## Example

For example, the coordinates of the Palace of Culture and Science in Warsaw can be represented as:

1. As "lonlat" pair, $$\varphi = 21.006062^\circ$$N, $$\lambda = 52.231727^\circ$$E.
2. As "xy" pair, $$x = 467.0110005$$km, $$y = 322.2659527$$km.
3. As a point inside ED (100 x 100 km) square, with relative position inside $$o_x = 0.67011001, o_y = 0.22265953$$.
4. As a point inside ED26 (10 x 10 km) square, with relative position inside $$o_x = 0.7011001, o_y = 0.2265953$$.
5. As a point inside ED2627 (100 x 100 km) square, with relative position inside $$o_x = 0.011001, o_y = 0.2265953$$.
6. As a point inside ED262720 (100 x 100 m) square, with relative position inside $$o_x = 0.11001, o_y =0.65953$$.
7. As a point inside ED26272061 (10 x 10 m) square, with relative position inside $$o_x = 0.1001, o_y = 0.5953$$.
8. As a point inside ED2627206161 (1 x 1 m) square, with relative position inside $$o_x = 0.001, o_y = 0.953$$.
9. (and so on).

One should remember about the GPS accuracy, so the last example has any sense only with geodesic GPS receivers.

The $$o_x$$ and $$o_y$$ values are never given in publications, they are only needed to store exact position and give the ability to perform the reverse computations.

## ATPOL in GIS software

GIS software users can work with the ATPOL coordinates by setting the following custom projection:

+proj=eqdc +lat_1=52 +lat_2=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000
+b=6390000 +ellps=sphere +x_0=330000 +y_0=-350000

or, when "+axis=esu" is not supported:

+proj=eqdc +lat_1=52 +lat_2=52 +lat_0=52 +lon_0=19 +a=6390000
+b=6390000 +ellps=sphere +x_0=330000 +y_0=350000

The second case will give reversed $$y$$ coordinates, counting from lower left (SW) corner.

## Implementation strategy

Currently, VBA implementation is available as initial release (for Excel or OpenOffice).

The other languages are now tested.

Two tests for accuracy check are designed and available:

1. The short test, which computes the points given as a reference below and compares with the reference values. The sum of errors is returned, it should not exceed 1e-10.
2. The long test, which generates pseudorandom (repeatable) 10 000 pairs of "xy" points and converts each point to latitudes and longitudes. For each grid length in range 2,4,...,10,12 each point is converted to grid and back to coordinates 10 times. Maximal error is reported (it should be around 1e-15). This test is extensive and allowed to catch several floating point rounding errors and deal with them. Beware that the computation is very long, the spreadsheet can hang so do not run this function before backup or besides any production data.

## VBA implementation

VBA implementation allows to perform the coordinate conversions inside the spreadsheets:

1. ATPOL_GRID_TO_LATLON(grid, xoffset, yoffset)
-returns an array (lat, lon). The offset parameters are optional, default values are 0.5 (the middle of the square).
2. ATPOL_GRID_TO_XY(grid, xoffset, yoffset)
-returns an array (x, y). The offset parameters are optional, default values are 0.5 (the middle of the square).
3. ATPOL_LATLON_TO_GRID(lat, lon, length)
-returns an array (grid, xoffset, yoffset, x, y). The length parameter is optional (default = 8, i.e. 100 meters square).
4. ATPOL_LATLON_TO_XY(lat, lon)
-returns an array (x, y).
5. ATPOL_XY_TO_GRID(x, y, length)
-returns an array (grid, xoffset, yoffset, x, y). The length parameter is optional (default = 8, i.e. 100 meters square).
6. ATPOL_XY_TO_LATLON(x, y)
-returns an array (lat, lon)
7. ATPOL_TEST()
-runs the short test, returns sum of errors
8. ATPOL_TEST_LONG()
-runs the long test, returns maximal error (can hang the spreadsheet program, do not run before data backup).

## Computational details

The algorithm for "latlon" pair to "xy" pair conversion:

1. $$\lambda = \lambda - \lambda_0$$
2. $$r = \frac{\cos \varphi_0}{\sin \varphi_0} - \tan (\varphi - \varphi_0)$$
3. $$x = r \sin (\lambda \sin\varphi_0)$$
4. $$y = r \sin (\lambda \cos\varphi_0)$$
5. $$y = y - \frac{\cos \varphi_0}{\sin \varphi_0}$$
6. $$x = Rx + x_0$$
7. $$y = Ry + x_0$$

The algorithm for "xy" pair to "latlon" pair conversion:

1. $$x = \frac{x - x_0}{R}$$
2. $$y = \frac{y - y_0}{R}$$
3. $$y = y + \frac{\cos \varphi_0}{\sin \varphi_0}$$
4. $$\lambda = \frac{\arctan(x/y)}{\sin \varphi_0}$$
5. $$r = \sqrt{x^2+y^2}$$
6. $$\varphi = \varphi_0 - \arctan\left(\frac{r-\cos \varphi_0}{\sin \varphi_0}\right)$$
7. $$\lambda = \lambda + \lambda_0$$

The algorithm for "xy" pair to "grid" conversion:

1. Convert $$x$$ and $$y$$ to meters and round it to create an integer values $$x_s$$ and $$y_s$$
2. Convert to 6-character string with optional leading zeros.
3. Create a grid string, by taking the first character of $$x_s$$ and the first of $$y_s$$, increasing the ASCII value by 17 (zero becomes A and so on).
4. For $$i = 1 \dots 5$$ append to the grid $$i$$-th character of $$y_s$$ followed by $$i$$-th character of $$x_s$$.
5. Create $$o_x$$ and $$o_y$$ strings, containing the $$x$$ and $$y$$ values expressed as milimeters (multiply by 1e6) and convert to string with length equal to 9, optionally panned with leading zeros.
6. Take the last $$9 - l/2$$ characters of $$o_x$$ and $$o_y$$ and add zero with decimal point at the beginning.
7. Convert $$o_x$$ and $$o_y$$ from string to float.
8. Return $$l$$ first characters of grid together with $$o_x$$ and $$o_y$$.

The algorithm for "grid" to "xy" conversion:

1. Create $$x_s$$ by taking the first character of grid, decreasing ASCII value by 17 (A becomes 0 and so on).
2. Create $$y_s$$ by taking the second character of grid, decreasing ASCII value by 17 (A becomes 0 and so on).
3. For $$i = 1 \dots l/2$$: append $$x_s$$ with the $$(2i+1)$$-th character of the grid, then append $$y_s$$ with the $$2i$$-th character of the grid.
4. Append zeros to $$x_s$$ and $$y_s$$ until their length is equal to 6.
5. Convert $$x_s$$ and $$y_s$$ from string to int.
6. $$x = x_s/1000 + 10^{3-l/2}o_x$$
7. $$y = y_s/1000 + 10^{3-l/2}o_y$$

### Reference values

These reference values (beware of exponents after "b" letter) were computed up to 90 significant digits using Maxima Computer Algebra System. They were also checked in R using MPFR multiple precision library interface.

  lat = 55, lon = 24
x = 6.500315410 9413219363 4638921909
2919102347 6549426346 4294406114
1134263122 2586709523 6877638936 b2
y = 4.106161777 0643609028 0069398239
9868109797 7416098516 8475411589
7741848959 9526507236 9127814945 b0

lat = 49, lon = 15
x = 3.707418900 7307473069 6146050746
2762635775 1822453853 9452623925
1805565421 1002353757 3371334723 b1
y = 6.768262355 9270039774 4316813206
3136538237 1028407494 1210768315
2116602614 4742493968 5399610358 b2

lat = 49, lon = 24
x = 6.960533606 1617843913 9749832254
1755018117 4703675369 6342716067
6503001532 8499992312 2712744907 b2
y = 6.722945679 5827199940 2311874332
7574763977 2116443227 5129393298
2056341816 4582670512 9387468615 b2

lat = 52, lon = 19
x = 330
y = 350

x = 0, y = 0
lat = 5.503040399 3648806391 6131639786
9569363580 3219644367 1837742899
2831279682 1573747622 5554628753 b1
lon = 1.384022731 8521004431 6191689836
7708417395 0606591263 3069285468
7864255005 5905203650 9154275744 b1

x = 700, y = 0
lat = 5.500351550 5218481835 1436251940
2356517141 5525549010 2366181839
2910549810 8234368660 1539449084 b1
lon = 2.478270718 4271129766 1229102707
7864236604 5958438506 2611201880
3643885511 3577052279 0628302380 b1

x = 0, y = 700
lat = 4.877384783 4747808675 2723438685
7484285450 8438794922 2721477719
9175666700 1434651537 3381662738 b1
lon = 1.451445359 4615022781 0015146712
5841166221 7940635007 0428788960
0558335581 1832098353 1992814714 b1

x = 700, y = 700
lat = 4.875047607 0495021286 9950531623
1417070334 8694846514 1777654287
4672439505 7853796537 0474833601 b1
lon = 2.402761076 3560529927 7468614203
6788418600 5147161668 5964092529
8571408752 0740760263 6494787753 b1

OpenATPOL is created and maintaned by Łukasz Komsta. Released under GPLv3 license. Last update: 2017.02.09