polar2wgs84 1.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,186 @@
1
+ Metadata-Version: 2.4
2
+ Name: polar2wgs84
3
+ Version: 1.0.2
4
+ Summary: Global geometry processing utilities for GeoJSON-safe WGS84 polygons.
5
+ Author: Jean-Christophe Malapert
6
+ Author-email: Jean-Christophe Malapert <jean-christophe.malapert@cnes.fr>
7
+ License-Expression: Apache-2.0
8
+ Requires-Dist: cartopy==0.25.0
9
+ Requires-Dist: loguru==0.7.3
10
+ Requires-Dist: matplotlib==3.11.1
11
+ Requires-Dist: numba==0.67.0
12
+ Requires-Dist: numpy==2.5.2
13
+ Requires-Dist: pyproj==3.7.2
14
+ Requires-Dist: shapely==2.1.2
15
+ Requires-Python: >=3.12
16
+ Description-Content-Type: text/markdown
17
+
18
+ # Polar to WGS84 Converter
19
+
20
+ [![image](https://img.shields.io/badge/Maintained%3F-yes-green.svg)]()
21
+
22
+ [![Quality gate](https://sonarqube.cnes.fr/api/project_badges/quality_gate?project=CNES.UL%3Apdssp%3Apolar2wgs84&token=sqb_daa1ae20d805694245113eccad26aa053aba0877)](https://sonarqube.cnes.fr/dashboard?id=CNES.UL%3Apdssp%3Apolar2wgs84)
23
+
24
+ [![Coverage](https://sonarqube.cnes.fr/api/project_badges/measure?project=CNES.UL%3Apdssp%3Apolar2wgs84&metric=coverage&token=sqb_daa1ae20d805694245113eccad26aa053aba0877)](https://sonarqube.cnes.fr/dashboard?id=CNES.UL%3Apdssp%3Apolar2wgs84)
25
+
26
+ [![Lines of Code](https://sonarqube.cnes.fr/api/project_badges/measure?project=CNES.UL%3Apdssp%3Apolar2wgs84&metric=ncloc&token=sqb_daa1ae20d805694245113eccad26aa053aba0877)](https://sonarqube.cnes.fr/dashboard?id=CNES.UL%3Apdssp%3Apolar2wgs84)
27
+
28
+ Global geometry processing utilities for GeoJSON-safe WGS84 polygons.
29
+
30
+ ## Stable release
31
+
32
+ To install Polar to WGS84 Converter, run this command in your
33
+ terminal:
34
+
35
+ ``` console
36
+ $ pip install git+https://gitlab.cnes.fr/pdssp/common/polar2wgs84.git
37
+ ```
38
+
39
+ This is the preferred method to install Polar to WGS84 Converter,
40
+ as it will always install the most recent stable release.
41
+
42
+ If you don\'t have [pip](https://pip.pypa.io) installed, this [Python
43
+ installation
44
+ guide](http://docs.python-guide.org/en/latest/starting/installation/)
45
+ can guide you through the process.
46
+
47
+ ## Installing UV
48
+
49
+ To manage the dependencies of Polar to WGS84 Converter, we use
50
+ \[UV\](<https://docs.astral.sh/uv/>). If you don\'t have UV
51
+ installed, follow these steps:
52
+
53
+ 1. **Install UV**:
54
+
55
+ > ``` shell
56
+ > $ curl -LsSf https://astral.sh/uv/install.sh | sh
57
+ > ```
58
+
59
+ 2. **Verify the installation**:
60
+
61
+ > ``` console
62
+ > $ uv --version
63
+ > ```
64
+
65
+ Please note that this project has been tested with UV version 0.9.15.
66
+
67
+ ## From sources
68
+
69
+ The sources for Polar to WGS84 Converter can be downloaded from
70
+ the [Gitlab repo]().
71
+
72
+ You can either clone the public repository:
73
+
74
+ ``` console
75
+ $ git clone https://gitlab.cnes.fr/pdssp/common/polar2wgs84.git
76
+ ```
77
+
78
+ Or download the
79
+ [tarball]():
80
+
81
+ ``` console
82
+ $ curl -OJL https://gitlab.cnes.fr/pdssp/common/polar2wgs84/tarball/main
83
+ ```
84
+
85
+ Once you have a copy of the source, you can install it with:
86
+
87
+ ``` console
88
+ $ make # install
89
+ ```
90
+
91
+ ## Development
92
+
93
+ ``` console
94
+ $ git clone polar2wgs84.git
95
+ $ cd polar2wgs84
96
+ $ make prepare-dev
97
+ $ source .venv/bin/activate
98
+ $ make install-dev
99
+ ```
100
+
101
+ To get more information about the preconfigured tasks:
102
+
103
+ ``` console
104
+ $ make help
105
+ ```
106
+
107
+ ## Usage
108
+
109
+ To use Polar to WGS84 Converter in a project:
110
+
111
+ ``` python
112
+ from polar2wgs84 import Footprint
113
+ from shapely import Polygon
114
+
115
+ # Define the vertices of your spherical polygon as a list of (longitude, latitude) tuples.
116
+ # Example: A polygon with 4 vertices (e.g., a rectangle near the North Pole).
117
+ polygon_vertices = [
118
+ (longitude_1, latitude_1), # First vertex
119
+ (longitude_2, latitude_2), # Second vertex
120
+ (longitude_3, latitude_3), # Third vertex
121
+ (longitude_4, latitude_4), # Fourth vertex
122
+ (longitude_1, latitude_1), # Close the polygon by repeating the first vertex
123
+ ]
124
+
125
+ # Create a Shapely Polygon from the vertices
126
+ polygon = Polygon(polygon_vertices)
127
+
128
+ # Instantiate the Footprint class with the polygon
129
+ footprint = Footprint(polygon)
130
+
131
+ # Convert the polygon to a valid GeoJSON-compatible geometry.
132
+ # This ensures the geometry is either a Polygon or MultiPolygon,
133
+ # which are the only types supported by the GeoJSON standard.
134
+ valid_geom = footprint.make_valid_geojson_geometry()
135
+
136
+ # Interpolate the geometry to the Plate Carrée (CAR) projection (EPSG:4326)
137
+ # and simplify it to reduce complexity while preserving its shape.
138
+ # This is useful for visualization and further processing.
139
+ simplified_valid_geom = footprint.to_wgs84_plate_carre(valid_geom)
140
+ # Additional arguments can be provided to control polygon densification and geometry simplification.
141
+ ```
142
+
143
+ With command line:
144
+
145
+ ``` shell
146
+
147
+ $ polar2wgs84 -h
148
+
149
+ ```
150
+
151
+ ## Run tests
152
+
153
+ To run automatic tests
154
+
155
+ ``` console
156
+ $make tests
157
+ ```
158
+
159
+ To run manual tests
160
+
161
+ ``` console
162
+ pytest -m "manual" -s
163
+ ```
164
+
165
+ ## Documentation
166
+
167
+ The documentation is automatically deployed on
168
+ <https://pdssp.io.cnes.fr/>polar2wgs84 based on main branch
169
+
170
+ ## Container
171
+
172
+ A container is automatically created on https://gitlab.cnes.fr/pdssp/common/polar2wgs84/container_registry
173
+
174
+ ## Author
175
+
176
+ 👤 **Jean-Christophe Malapert**
177
+
178
+ ## 🤝 Contributing
179
+
180
+ Contributions, issues and feature requests are welcome!\<br /\>Feel free
181
+ to check \[issues page\](https://gitlab.cnes.fr/pdssp/common/polar2wgs84/issues). You can
182
+ also take a look at the \[contributing guide\](https://gitlab.cnes.fr/pdssp/common/polar2wgs84/blob/main/CONTRIBUTING.rst)
183
+
184
+ ## 📝 License
185
+
186
+ This project is \[Apache V2.0\](https://gitlab.cnes.fr/pdssp/common/polar2wgs84/blob/main/LICENSE) licensed.
@@ -0,0 +1,169 @@
1
+ # Polar to WGS84 Converter
2
+
3
+ [![image](https://img.shields.io/badge/Maintained%3F-yes-green.svg)]()
4
+
5
+ [![Quality gate](https://sonarqube.cnes.fr/api/project_badges/quality_gate?project=CNES.UL%3Apdssp%3Apolar2wgs84&token=sqb_daa1ae20d805694245113eccad26aa053aba0877)](https://sonarqube.cnes.fr/dashboard?id=CNES.UL%3Apdssp%3Apolar2wgs84)
6
+
7
+ [![Coverage](https://sonarqube.cnes.fr/api/project_badges/measure?project=CNES.UL%3Apdssp%3Apolar2wgs84&metric=coverage&token=sqb_daa1ae20d805694245113eccad26aa053aba0877)](https://sonarqube.cnes.fr/dashboard?id=CNES.UL%3Apdssp%3Apolar2wgs84)
8
+
9
+ [![Lines of Code](https://sonarqube.cnes.fr/api/project_badges/measure?project=CNES.UL%3Apdssp%3Apolar2wgs84&metric=ncloc&token=sqb_daa1ae20d805694245113eccad26aa053aba0877)](https://sonarqube.cnes.fr/dashboard?id=CNES.UL%3Apdssp%3Apolar2wgs84)
10
+
11
+ Global geometry processing utilities for GeoJSON-safe WGS84 polygons.
12
+
13
+ ## Stable release
14
+
15
+ To install Polar to WGS84 Converter, run this command in your
16
+ terminal:
17
+
18
+ ``` console
19
+ $ pip install git+https://gitlab.cnes.fr/pdssp/common/polar2wgs84.git
20
+ ```
21
+
22
+ This is the preferred method to install Polar to WGS84 Converter,
23
+ as it will always install the most recent stable release.
24
+
25
+ If you don\'t have [pip](https://pip.pypa.io) installed, this [Python
26
+ installation
27
+ guide](http://docs.python-guide.org/en/latest/starting/installation/)
28
+ can guide you through the process.
29
+
30
+ ## Installing UV
31
+
32
+ To manage the dependencies of Polar to WGS84 Converter, we use
33
+ \[UV\](<https://docs.astral.sh/uv/>). If you don\'t have UV
34
+ installed, follow these steps:
35
+
36
+ 1. **Install UV**:
37
+
38
+ > ``` shell
39
+ > $ curl -LsSf https://astral.sh/uv/install.sh | sh
40
+ > ```
41
+
42
+ 2. **Verify the installation**:
43
+
44
+ > ``` console
45
+ > $ uv --version
46
+ > ```
47
+
48
+ Please note that this project has been tested with UV version 0.9.15.
49
+
50
+ ## From sources
51
+
52
+ The sources for Polar to WGS84 Converter can be downloaded from
53
+ the [Gitlab repo]().
54
+
55
+ You can either clone the public repository:
56
+
57
+ ``` console
58
+ $ git clone https://gitlab.cnes.fr/pdssp/common/polar2wgs84.git
59
+ ```
60
+
61
+ Or download the
62
+ [tarball]():
63
+
64
+ ``` console
65
+ $ curl -OJL https://gitlab.cnes.fr/pdssp/common/polar2wgs84/tarball/main
66
+ ```
67
+
68
+ Once you have a copy of the source, you can install it with:
69
+
70
+ ``` console
71
+ $ make # install
72
+ ```
73
+
74
+ ## Development
75
+
76
+ ``` console
77
+ $ git clone polar2wgs84.git
78
+ $ cd polar2wgs84
79
+ $ make prepare-dev
80
+ $ source .venv/bin/activate
81
+ $ make install-dev
82
+ ```
83
+
84
+ To get more information about the preconfigured tasks:
85
+
86
+ ``` console
87
+ $ make help
88
+ ```
89
+
90
+ ## Usage
91
+
92
+ To use Polar to WGS84 Converter in a project:
93
+
94
+ ``` python
95
+ from polar2wgs84 import Footprint
96
+ from shapely import Polygon
97
+
98
+ # Define the vertices of your spherical polygon as a list of (longitude, latitude) tuples.
99
+ # Example: A polygon with 4 vertices (e.g., a rectangle near the North Pole).
100
+ polygon_vertices = [
101
+ (longitude_1, latitude_1), # First vertex
102
+ (longitude_2, latitude_2), # Second vertex
103
+ (longitude_3, latitude_3), # Third vertex
104
+ (longitude_4, latitude_4), # Fourth vertex
105
+ (longitude_1, latitude_1), # Close the polygon by repeating the first vertex
106
+ ]
107
+
108
+ # Create a Shapely Polygon from the vertices
109
+ polygon = Polygon(polygon_vertices)
110
+
111
+ # Instantiate the Footprint class with the polygon
112
+ footprint = Footprint(polygon)
113
+
114
+ # Convert the polygon to a valid GeoJSON-compatible geometry.
115
+ # This ensures the geometry is either a Polygon or MultiPolygon,
116
+ # which are the only types supported by the GeoJSON standard.
117
+ valid_geom = footprint.make_valid_geojson_geometry()
118
+
119
+ # Interpolate the geometry to the Plate Carrée (CAR) projection (EPSG:4326)
120
+ # and simplify it to reduce complexity while preserving its shape.
121
+ # This is useful for visualization and further processing.
122
+ simplified_valid_geom = footprint.to_wgs84_plate_carre(valid_geom)
123
+ # Additional arguments can be provided to control polygon densification and geometry simplification.
124
+ ```
125
+
126
+ With command line:
127
+
128
+ ``` shell
129
+
130
+ $ polar2wgs84 -h
131
+
132
+ ```
133
+
134
+ ## Run tests
135
+
136
+ To run automatic tests
137
+
138
+ ``` console
139
+ $make tests
140
+ ```
141
+
142
+ To run manual tests
143
+
144
+ ``` console
145
+ pytest -m "manual" -s
146
+ ```
147
+
148
+ ## Documentation
149
+
150
+ The documentation is automatically deployed on
151
+ <https://pdssp.io.cnes.fr/>polar2wgs84 based on main branch
152
+
153
+ ## Container
154
+
155
+ A container is automatically created on https://gitlab.cnes.fr/pdssp/common/polar2wgs84/container_registry
156
+
157
+ ## Author
158
+
159
+ 👤 **Jean-Christophe Malapert**
160
+
161
+ ## 🤝 Contributing
162
+
163
+ Contributions, issues and feature requests are welcome!\<br /\>Feel free
164
+ to check \[issues page\](https://gitlab.cnes.fr/pdssp/common/polar2wgs84/issues). You can
165
+ also take a look at the \[contributing guide\](https://gitlab.cnes.fr/pdssp/common/polar2wgs84/blob/main/CONTRIBUTING.rst)
166
+
167
+ ## 📝 License
168
+
169
+ This project is \[Apache V2.0\](https://gitlab.cnes.fr/pdssp/common/polar2wgs84/blob/main/LICENSE) licensed.
@@ -0,0 +1,90 @@
1
+ [tool.bandit]
2
+ exclude_dirs = [
3
+ "tests",
4
+ ".venv",
5
+ ".cache",
6
+ ]
7
+
8
+ [tool.black]
9
+ line-length = 88
10
+ include = '\.pyi?$'
11
+ exclude = '''
12
+ /(
13
+ \.git
14
+ | \.hg
15
+ | \.mypy_cache
16
+ | \.tox
17
+ | \.venv
18
+ | docs
19
+ | scripts
20
+ | docker
21
+ | _build
22
+ | buck-out
23
+ | build
24
+ | dist
25
+ )/
26
+ '''
27
+
28
+ [project]
29
+ name = "polar2wgs84"
30
+ readme = "README.md"
31
+ description = "Global geometry processing utilities for GeoJSON-safe WGS84 polygons."
32
+ license = "Apache-2.0"
33
+ homepage = "https://gitlab.cnes.fr/pdssp/common/polar2wgs84"
34
+ version = "1.0.2"
35
+ requires-python = ">=3.12"
36
+ dependencies = [
37
+ "cartopy==0.25.0",
38
+ "loguru==0.7.3",
39
+ "matplotlib==3.11.1",
40
+ "numba==0.67.0",
41
+ "numpy==2.5.2",
42
+ "pyproj==3.7.2",
43
+ "shapely==2.1.2",
44
+ ]
45
+
46
+ [[project.authors]]
47
+ name = "Jean-Christophe Malapert"
48
+ email = "jean-christophe.malapert@cnes.fr"
49
+
50
+ [[project.packages]]
51
+ include = "polar2wgs84"
52
+
53
+ [project.scripts]
54
+ polar2wgs84 = "polar2wgs84.__main__:run"
55
+
56
+ [build-system]
57
+ requires = ["uv_build>=0.9.14,<0.10.0"]
58
+ build-backend = "uv_build"
59
+
60
+ [dependency-groups]
61
+ dev = [
62
+ "dockerfile-parse>=2.0.1",
63
+ "bump-my-version>=1.2.4",
64
+ "coverage>=7.12.0",
65
+ "mkdocs>=1.6.1",
66
+ "mkdocs-gen-files>=0.6.0",
67
+ "mkdocs-literate-nav>=0.6.2",
68
+ "mkdocs-macros-plugin>=1.5.0",
69
+ "mkdocs-material>=9.7.0",
70
+ "mkdocs-with-pdf>=0.9.3",
71
+ "mkdocstrings[python]>=1.0.0",
72
+ "pip-licenses>=5.5.0",
73
+ "pre-commit>=4.5.0",
74
+ "pre-commit-hooks>=6.0.0",
75
+ "pytest>=9.0.1",
76
+ "pytest-cov>=7.1.0",
77
+ "pytest-html>=4.1.1",
78
+ "pytest-json-report>=1.5.0",
79
+ "pytest-profiling>=1.8.1",
80
+ "docker>=7.1.0",
81
+ "pytest-mock>=3.15.1",
82
+ "black>=25.11.0",
83
+ "tox>=4.32.0",
84
+ "flake8>=7.3.0",
85
+ "mccabe>=0.7.0",
86
+ "mypy>=1.19.0",
87
+ "pylint>=4.0.4",
88
+ "toml>=0.10.2",
89
+ "mkdocs-gallery==0.10.4",
90
+ ]
@@ -0,0 +1,80 @@
1
+ [tool.bandit]
2
+ exclude_dirs = ["tests", ".venv", ".cache"]
3
+
4
+ [tool.black]
5
+ line-length = 88
6
+ include = '\.pyi?$'
7
+ exclude = '''
8
+ /(
9
+ \.git
10
+ | \.hg
11
+ | \.mypy_cache
12
+ | \.tox
13
+ | \.venv
14
+ | docs
15
+ | scripts
16
+ | docker
17
+ | _build
18
+ | buck-out
19
+ | build
20
+ | dist
21
+ )/
22
+ '''
23
+
24
+ [project]
25
+ name = "polar2wgs84"
26
+ readme = "README.md"
27
+ description = "Global geometry processing utilities for GeoJSON-safe WGS84 polygons."
28
+ authors = [{name="Jean-Christophe Malapert", email="jean-christophe.malapert@cnes.fr"}, ]
29
+ license = "Apache-2.0"
30
+ packages = [{include = "polar2wgs84"}]
31
+ homepage = "https://gitlab.cnes.fr/pdssp/common/polar2wgs84"
32
+ version = "1.0.2"
33
+ requires-python = ">=3.12"
34
+ dependencies = [
35
+ "cartopy==0.25.0",
36
+ "loguru==0.7.3",
37
+ "matplotlib==3.11.1",
38
+ "numba==0.67.0",
39
+ "numpy==2.5.2",
40
+ "pyproj==3.7.2",
41
+ "shapely==2.1.2",
42
+ ]
43
+ [project.scripts]
44
+ polar2wgs84 = "polar2wgs84.__main__:run"
45
+
46
+ [build-system]
47
+ requires = ["uv_build>=0.9.14,<0.10.0"]
48
+ build-backend = "uv_build"
49
+
50
+ [dependency-groups]
51
+ dev = [
52
+ "dockerfile-parse>=2.0.1",
53
+ "bump-my-version>=1.2.4",
54
+ "coverage>=7.12.0",
55
+ "mkdocs>=1.6.1",
56
+ "mkdocs-gen-files>=0.6.0",
57
+ "mkdocs-literate-nav>=0.6.2",
58
+ "mkdocs-macros-plugin>=1.5.0",
59
+ "mkdocs-material>=9.7.0",
60
+ "mkdocs-with-pdf>=0.9.3",
61
+ "mkdocstrings[python]>=1.0.0",
62
+ "pip-licenses>=5.5.0",
63
+ "pre-commit>=4.5.0",
64
+ "pre-commit-hooks>=6.0.0",
65
+ "pytest>=9.0.1",
66
+ "pytest-cov>=7.1.0",
67
+ "pytest-html>=4.1.1",
68
+ "pytest-json-report>=1.5.0",
69
+ "pytest-profiling>=1.8.1",
70
+ "docker>=7.1.0",
71
+ "pytest-mock>=3.15.1",
72
+ "black>=25.11.0",
73
+ "tox>=4.32.0",
74
+ "flake8>=7.3.0",
75
+ "mccabe>=0.7.0",
76
+ "mypy>=1.19.0",
77
+ "pylint>=4.0.4",
78
+ "toml>=0.10.2",
79
+ "mkdocs-gallery==0.10.4",
80
+ ]
@@ -0,0 +1,70 @@
1
+ # Polar to WGS84 Converter - Global geometry processing utilities for GeoJSON-safe WGS84 polygons.
2
+ # Copyright (C) 2025 - CNES (Jean-Christophe Malapert for PDSSP)
3
+ # This file is part of Polar to WGS84 Converter <https://gitlab.cnes.fr/pdssp/common/polar2wgs84>
4
+ # SPDX-License-Identifier: Apache-2.0
5
+ """
6
+ Global geometry processing utilities for GeoJSON-safe WGS84 polygons.
7
+
8
+ This module provides a complete, geodesically correct pipeline for
9
+ processing global-scale polygon geometries expressed in longitude/
10
+ latitude (WGS84). It is specifically designed to handle edge cases
11
+ that commonly break GeoJSON validity when geometries span large
12
+ distances or interact with global discontinuities.
13
+
14
+ Core capabilities
15
+ -----------------
16
+ 1. **Geodesic densification**
17
+ Polygon edges are densified along great-circle paths on the sphere
18
+ prior to projection. This preserves geometric fidelity for:
19
+ - Large-area polygons
20
+ - High-latitude regions
21
+ - Near-polar geometries
22
+
23
+ 2. **Projection-aware simplification**
24
+ Geometries are temporarily projected to a Plate Carrée
25
+ (equirectangular) coordinate system to enable robust, topology-
26
+ preserving simplification. The simplified geometry based is then
27
+ re-projected back to WGS84.
28
+
29
+ 3. **GeoJSON validity enforcement**
30
+ The module automatically detects and resolves global geometry
31
+ pathologies, including:
32
+ - **Polar inclusion** (North or South Pole enclosed by a polygon)
33
+ - **Antimeridian crossing** (±180° longitude discontinuity)
34
+ - **Equator crossing** (multi-hemisphere geometries)
35
+
36
+ Specialized algorithms are applied depending on the spatial
37
+ classification of each geometry to ensure GeoJSON compliance.
38
+
39
+ Design principles
40
+ -----------------
41
+ - **Spherical correctness**: All long edges are treated as geodesics,
42
+ not planar segments.
43
+ - **Explicit decision hierarchy**: Polar handling takes precedence
44
+ over antimeridian logic; equator-crossing geometries follow a
45
+ separate processing path.
46
+ - **Topology preservation**: Simplification never introduces self-
47
+ intersections or invalid rings.
48
+ - **Performance-oriented**: Critical numeric routines are accelerated
49
+ using Numba.
50
+ - **Standards-aware**: Output geometries conform to GeoJSON winding
51
+ and continuity rules.
52
+ """
53
+ from ._version import __author__
54
+ from ._version import __author_email__
55
+ from ._version import __copyright__
56
+ from ._version import __description__
57
+ from ._version import __license__
58
+ from ._version import __name_soft__
59
+ from ._version import __title__
60
+ from ._version import __url__
61
+ from ._version import __version__
62
+ from .footprint import Footprint
63
+ from .logging_config import get_logger
64
+
65
+ logger = get_logger(__name__)
66
+
67
+ info_format = "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <level>{message}</level>"
68
+ logger.info(f"{__name_soft__} V{__version__} imported")
69
+
70
+ __all__ = ["Footprint"]