Metadata-Version: 2.4
Name: finproj
Version: 0.1.1
Summary: Pure-Python Finnish coordinate reference systems (KKJ, EUREF-FIN, TM35FIN, ETRS-GKn)
Author-email: Kimmo Korhonen <kimmo.korhonen@iki.fi>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kkorhone/finproj
Project-URL: Repository, https://github.com/kkorhone/finproj
Project-URL: Issues, https://github.com/kkorhone/finproj/issues
Project-URL: Documentation, https://finproj.readthedocs.io
Keywords: finland,geodesy,coordinate-reference-system,projection,kkj,euref-fin,tm35fin,etrs-gk,jhs-196,jhs-197
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo; extra == "docs"
Dynamic: license-file

# finproj

A pure-Python library for Finnish coordinate reference systems. It implements Transverse Mercator projections for ETRS-TM35FIN, KKJ zones 0–5, and ETRS-GKn zones 19–31, as well as the triangle-network affine transformation between YKJ (KKJ zone 3) and ETRS-TM35FIN. This is a standalone implementation — it is not a wrapper around PROJ or any other external library, and it covers only Finnish CRSs.

## Installation

Once published on PyPI:

```
pip install finproj
```

Install directly from source:

```
pip install git+https://github.com/kkorhone/finproj.git
```

## Usage

### TM35FIN projection of a point

```python
import finproj

# Project EUREF-FIN geographic coordinates to TM35FIN
lat, lon = 60.385107, 19.848137
E, N = finproj.TM35FIN.project(lat, lon)
print(f"E = {E:.3f}, N = {N:.3f}")

# Inverse projection
lat2, lon2 = finproj.TM35FIN.inverse_project(E, N)
```

### YKJ ↔ ETRS-TM35FIN transformation

```python
import finproj

# Transform YKJ (KKJ zone 3) coordinates to ETRS-TM35FIN
x_ykj, y_ykj = 3_500_000.0, 6_800_000.0
x_tm35, y_tm35 = finproj.ykj_to_tm35fin(x_ykj, y_ykj)

# And back
x_back, y_back = finproj.tm35fin_to_ykj(x_tm35, y_tm35)
```

## Supported coordinate reference systems

- **ETRS-TM35FIN** — the national projected CRS of Finland (`finproj.TM35FIN`)
- **KKJ zones 0–5** — the legacy Finnish national CRS (`finproj.KKJ0` through `finproj.KKJ5`, or `finproj.KKJ[i]`)
- **ETRS-GKn zones 19–31** — the narrow-zone Gauss–Krüger projections (`finproj.GK19` through `finproj.GK31`, or `finproj.GK[z]`)
- **YKJ ↔ ETRS-TM35FIN** — triangle-network affine transformation between YKJ (KKJ zone 3, EPSG:2393) and ETRS-TM35FIN (EPSG:3067) (`finproj.ykj_to_tm35fin`, `finproj.tm35fin_to_ykj`)

## Accuracy

The library achieves sub-mm agreement with tabulated Finnish geodetic reference values (JHS 197 Liite 3). This is validated by the test suite, which checks forward and inverse projection against the G4 (Geta) and G42 (Kymi) reference points.

The library implements the coordinate systems and transformations specified by JHS 197 (2016; supersedes JHS 154 (2008)), with mathematical formulas from Häkli et al. (2009). It does **not** implement the coarser 3D 7-parameter similarity transformation of JHS 197 §7.1 (formerly JHS 153 §6.1), which has ~2 m residuals at national borders and is not recommended for precise work.

## Transformation topology

The diagram below shows the transformation paths between coordinate systems. The function names shown are from the pre-restructure API; see the mapping table.

![Transformation topology](docs/xform_paths.png)

| Old API | New API |
|---|---|
| `tm.TM35_PROJECTION.project` | `finproj.TM35FIN.project` |
| `tm.TM35_PROJECTION.inverse_project` | `finproj.TM35FIN.inverse_project` |
| `tm.KKJ3_PROJECTION.project` | `finproj.KKJ3.project` |
| `tm.KKJ3_PROJECTION.inverse_project` | `finproj.KKJ3.inverse_project` |
| `tm.GK25_PROJECTION.project` | `finproj.GK25.project` |
| `eureffin.transform_KKJ3_to_TM35` | `finproj.ykj_to_tm35fin` |
| `eureffin.transform_TM35_to_KKJ3` | `finproj.tm35fin_to_ykj` |

## References

1. **Julkisen hallinnon suositus JHS 197** (2016, v1.1 / 9.12.2016), *EUREF-FIN -koordinaattijärjestelmät, niihin liittyvät muunnokset ja karttalehtijako.* JUHTA — Julkisen hallinnon tietohallinnon neuvottelukunta. Defines ETRS-TM35FIN (§6.1.1) and ETRS-GKn (§6.1.3); specifies the triangle-network affine transformation between YKJ (KKJ zone 3) and ETRS-TM35FIN as the recommended precise 2D transformation (§7.2, with the triangle network, method and accuracy documented in Liite 7); §7.5 directs users to MML for the reference vertex data and transformation program. Supersedes JHS 154 (2008).

2. **Julkisen hallinnon suositus JHS 196** (2016), *EUREF-FIN -järjestelmän mukaiset koordinaatit Suomessa.* JUHTA. Defines EUREF-FIN as the Finnish realisation of ETRS89. The coarser 3D 7-parameter similarity transformation between EUREF-FIN and KKJ (~metre-level residuals inland, up to ~2 m at national borders — NOT the transformation this library implements) has moved to JHS 197 §7.1 (Liite 6); JHS 197 depends on JHS 196 only for the datum definition. Supersedes JHS 153 (2008).

3. **Häkli, P., Puupponen, J., Koivula, H., Poutanen, M.** (2009). *Suomen geodeettiset koordinaatistot ja niiden väliset muunnokset.* Geodeettisen laitoksen tiedotteita 30. Geodeettinen laitos, Kirkkonummi. ISBN 978-951-711-273-4 (print), 978-951-711-274-1 (PDF). Krüger-n Transverse Mercator formulas (Appendix B); least-squares determination of per-triangle affine parameters (Appendix C3.1). Written as the mathematical companion to JHS 154 (2008) — which was superseded by JHS 197 (2016) with the same formulas retained — it provides the derivations that the JHS documents recommend but do not derive in full.

4. **Maanmittauslaitos (MML)**. MML is the successor of the Finnish Geodetic Institute (Geodeettinen laitos, which authored GLtiedote 30 and merged into MML on 1 January 2015). Per JHS 197 §7.5 (formerly JHS 154 §6.2.3), MML publishes both the reference vertex coordinates and the reference transformation program. Data licensed under CC BY 4.0.

5. **JHS 197 Liite 3** (2016, v1.0 / 7.2.2016), *Projektiolaskujen esimerkit* — §1 gives the G4 (Geta) forward/inverse projection example for ETRS-TM35FIN, and §2 gives the G42 (Kymi) forward/inverse projection examples for the ETRS-GKn zones 19–31. Liite 3 gives φ in radians to 15 significant figures, which is where the high-precision G4 latitude φ = 1.053918934984532 rad (≈ 60.38510692353° N) used in the tests comes from; JHS 196 Liite 1 gives the same point in DMS rounded to 5 decimals of arcseconds (60° 23' 6.38474"), which discards ~5 mm of precision.

## License

This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
