# Welcome to the SphericalPolygon package
[](https://pypi.python.org/pypi/sphericalpolygon/) [](https://pypi.python.org/pypi/sphericalpolygon/) [](https://pypi.python.org/pypi/sphericalpolygon/) [](https://GitHub.com/lcx366/SphericalPolygon/graphs/contributors/) [](https://GitHub.com/lcx366/SphericalPolygon/graphs/commit-activity) [](https://github.com/lcx366/SphericalPolygon/blob/master/LICENSE) [](http://sphericalpolygon.readthedocs.io/?badge=latest)
The SphericalPolygon package is an archive of scientific routines for handling spherical polygons. Currently, operations on spherical polygons include:
1. Calculate the area or mass(if the area density is given)
2. Calculate the perimeter
3. Identify the centroid
4. Compute the geometrical or physical moment of inertia tensor
5. Determine whether one or multiple points are inside the spherical polygon
## How to Install
On Linux, macOS and Windows architectures, the binary wheels can be installed using **pip** by executing one of the following commands:
```
pip install sphericalpolygon
pip install sphericalpolygon --upgrade # to upgrade a pre-existing installation
```
## How to use
### Create a spherical polygon
Spherical polygons can be created from a 2d array in form of `[[lat_0,lon_0],..,[lat_n,lon_n]]` with unit of degrees, or from a boundary file, such as those in [Plate boundaries for NNR-MORVEL56 model](http://geoscience.wisc.edu/~chuck/MORVEL/PltBoundaries.html). The spherical polygon accepts a latitude range of [-90,90] and a longitude range of [-180,180] or [0,360].
```python
from sphericalpolygon import Sphericalpolygon
# build a spherical polygon for Antarctica Plate
polygon = Sphericalpolygon.from_file('NnrMRVL_PltBndsLatLon/an',skiprows=1)
print(polygon)
```
<SphericalPolygon | ORIENTATION='Counterclockwise', NorthPoleInside=False, SouthPoleInside=True>
### Calculate the area
Calculate the area(or the solid angle) of a spherical polygon over a unit sphere.
```python
print(polygon.area())
```
1.4326235943514618
Calculate the mass of the spherical polygon shell with a thickness of 100km and density of 3.1g/cm3 over the Earth.
```python
from astropy import units as u
Re = 6371*u.km
thickness, density = 100*u.km, 3.1*u.g/u.cm**3
rho = thickness * density # area density
print(polygon.area(Re,rho))
```
18026399988.685192 km3 g / cm3
### Calculate the perimeter
Calculate the perimeter of a spherical polygon over a unit sphere.
```python
print(polygon.perimeter())
```
6.322665941435134
### Calculate the compactness
```python
print(polygon.compactness())
```
0.39900007344929683
### Identify the centroid
Identify the centroid of a spherical polygon over a unit sphere.
```python
print(polygon.centroid())
```
(-83.61081032380652, 57.80052886741478, 0.13827778179537864)
It shows that the centroid is close to the South Pole.
### Compute the moment of inertia tensor
Compute the geometrical moment of inertia tensor of a spherical polygon over a unit sphere. The tensor is symmetrical and has six independent components. The first three components are located diagonally, corresponding to $Q_{11}$, $Q_{22}$, and $Q_{33}$; the last three components correspond to $Q_{12}$, $Q_{13}$, and $Q_{23}$.
```python
print(polygon.inertia())
```
[ 1.32669154 1.17471081 0.36384484 -0.05095381 0.05246122 0.08126929]
Compute the physical moment of inertia tensor of the spherical polygon shell over the Earth.
```python
print(polygon.inertia(Re,rho))
```
[ 6.77582335e+17 5.99961081e+17 1.85826792e+17 -2.60236820e+16
2.67935659e+16 4.15067357e+16] g km5 / cm3
### Points are inside a polygon？
Determine if a single point or multiple points are inside a given spherical polygon.
#### single point
```python
print(polygon.contains_points([[75,152]]))
```
[False]
#### multiple points
```python
print(polygon.contains_points([[-85,130],[35,70]]))
```
[True, False]
### Change log
- **1.2.3 — Aug 22, 2025**
- `inside_polygon` is fully vectorized to handle multiple points and a single polygon efficiently.
- **1.2.2 — Mar 3, 2021**
- Add the `compactness()` method, which reflects the deviation of a polygon from a spherical cap.
- **1.2.1 — Feb 23, 2021**
- Replace the function *create_polygon* for building a spherical polygon object from a 2d array with methods `from_array` and `from_file`.
- **1.2.0 — Mar 20, 2020**
- Add the `perimeter()` method that may calculate the perimeter of a spherical polygon.
- Add the `centroid()` method that may determaine the centroid location for a spherical polygon.
## Reference
Chunxiao, Li. "Inertia Tensor for MORVEL Tectonic Plates." *ASTRONOMICAL RESEARCH AND TECHNOLOGY* 13.1 (2016).
Raw data
{
"_id": null,
"home_page": "https://github.com/lcx366/SphericalPolygon",
"name": "sphericalpolygon",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "spherical polygon, polygon area, polygon inertia tensor",
"author": "Chunxiao Li",
"author_email": "lcx366@126.com",
"download_url": null,
"platform": null,
"description": "# Welcome to the SphericalPolygon package\n\n[](https://pypi.python.org/pypi/sphericalpolygon/) [](https://pypi.python.org/pypi/sphericalpolygon/) [](https://pypi.python.org/pypi/sphericalpolygon/) [](https://GitHub.com/lcx366/SphericalPolygon/graphs/contributors/) [](https://GitHub.com/lcx366/SphericalPolygon/graphs/commit-activity) [](https://github.com/lcx366/SphericalPolygon/blob/master/LICENSE) [](http://sphericalpolygon.readthedocs.io/?badge=latest)\n\nThe SphericalPolygon package is an archive of scientific routines for handling spherical polygons. Currently, operations on spherical polygons include:\n\n1. Calculate the area or mass(if the area density is given) \n2. Calculate the perimeter\n3. Identify the centroid \n4. Compute the geometrical or physical moment of inertia tensor\n5. Determine whether one or multiple points are inside the spherical polygon\n\n## How to Install\n\nOn Linux, macOS and Windows architectures, the binary wheels can be installed using **pip** by executing one of the following commands:\n\n```\npip install sphericalpolygon\npip install sphericalpolygon --upgrade # to upgrade a pre-existing installation\n```\n\n## How to use\n\n### Create a spherical polygon\n\nSpherical polygons can be created from a 2d array in form of `[[lat_0,lon_0],..,[lat_n,lon_n]]` with unit of degrees, or from a boundary file, such as those in [Plate boundaries for NNR-MORVEL56 model](http://geoscience.wisc.edu/~chuck/MORVEL/PltBoundaries.html). The spherical polygon accepts a latitude range of [-90,90] and a longitude range of [-180,180] or [0,360].\n\n\n```python\nfrom sphericalpolygon import Sphericalpolygon\n# build a spherical polygon for Antarctica Plate\npolygon = Sphericalpolygon.from_file('NnrMRVL_PltBndsLatLon/an',skiprows=1) \nprint(polygon)\n```\n\n <SphericalPolygon | ORIENTATION='Counterclockwise', NorthPoleInside=False, SouthPoleInside=True>\n\n\n### Calculate the area\n\nCalculate the area(or the solid angle) of a spherical polygon over a unit sphere.\n\n\n```python\nprint(polygon.area())\n```\n\n 1.4326235943514618\n\n\nCalculate the mass of the spherical polygon shell with a thickness of 100km and density of 3.1g/cm3 over the Earth.\n\n\n```python\nfrom astropy import units as u\nRe = 6371*u.km\nthickness, density = 100*u.km, 3.1*u.g/u.cm**3\nrho = thickness * density # area density\nprint(polygon.area(Re,rho))\n```\n\n 18026399988.685192 km3 g / cm3\n\n\n### Calculate the perimeter\n\nCalculate the perimeter of a spherical polygon over a unit sphere.\n\n\n```python\nprint(polygon.perimeter())\n```\n\n 6.322665941435134\n\n\n### Calculate the compactness\n\n\n```python\nprint(polygon.compactness())\n```\n\n 0.39900007344929683\n\n\n### Identify the centroid\n\nIdentify the centroid of a spherical polygon over a unit sphere.\n\n\n```python\nprint(polygon.centroid())\n```\n\n (-83.61081032380652, 57.80052886741478, 0.13827778179537864)\n\n\nIt shows that the centroid is close to the South Pole.\n\n### Compute the moment of inertia tensor\n\nCompute the geometrical moment of inertia tensor of a spherical polygon over a unit sphere. The tensor is symmetrical and has six independent components. The first three components are located diagonally, corresponding to $Q_{11}$, $Q_{22}$, and $Q_{33}$; the last three components correspond to $Q_{12}$, $Q_{13}$, and $Q_{23}$.\n\n\n```python\nprint(polygon.inertia())\n```\n\n [ 1.32669154 1.17471081 0.36384484 -0.05095381 0.05246122 0.08126929]\n\n\nCompute the physical moment of inertia tensor of the spherical polygon shell over the Earth.\n\n\n```python\nprint(polygon.inertia(Re,rho))\n```\n\n [ 6.77582335e+17 5.99961081e+17 1.85826792e+17 -2.60236820e+16\n 2.67935659e+16 4.15067357e+16] g km5 / cm3\n\n\n### Points are inside a polygon\uff1f\n\nDetermine if a single point or multiple points are inside a given spherical polygon.\n\n#### single point\n\n\n```python\nprint(polygon.contains_points([[75,152]]))\n```\n\n [False]\n\n\n#### multiple points\n\n\n```python\nprint(polygon.contains_points([[-85,130],[35,70]]))\n```\n\n [True, False]\n\n\n### Change log\n- **1.2.3 \u2014 Aug 22, 2025**\n - `inside_polygon` is fully vectorized to handle multiple points and a single polygon efficiently.\n- **1.2.2 \u2014 Mar 3, 2021**\n - Add the `compactness()` method, which reflects the deviation of a polygon from a spherical cap.\n- **1.2.1 \u2014 Feb 23, 2021**\n - Replace the function *create_polygon* for building a spherical polygon object from a 2d array with methods `from_array` and `from_file`.\n- **1.2.0 \u2014 Mar 20, 2020**\n - Add the `perimeter()` method that may calculate the perimeter of a spherical polygon.\n - Add the `centroid()` method that may determaine the centroid location for a spherical polygon.\n\n## Reference\n\nChunxiao, Li. \"Inertia Tensor for MORVEL Tectonic Plates.\" *ASTRONOMICAL RESEARCH AND TECHNOLOGY* 13.1 (2016).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package to handle the spherical polygon",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/lcx366/SphericalPolygon"
},
"split_keywords": [
"spherical polygon",
" polygon area",
" polygon inertia tensor"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1d71d405194529b0d06ff8077dc788e4736ceaad65bfbbcb9ff412f2a988155f",
"md5": "257272370f5629737c6546c079246d1e",
"sha256": "22f28f31573a5191f0e39a1c7487ab65db2bd2a852f8e89a08132f1c1178e444"
},
"downloads": -1,
"filename": "sphericalpolygon-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "257272370f5629737c6546c079246d1e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 16434,
"upload_time": "2025-08-23T08:12:42",
"upload_time_iso_8601": "2025-08-23T08:12:42.114410Z",
"url": "https://files.pythonhosted.org/packages/1d/71/d405194529b0d06ff8077dc788e4736ceaad65bfbbcb9ff412f2a988155f/sphericalpolygon-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 08:12:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lcx366",
"github_project": "SphericalPolygon",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphericalpolygon"
}
JSON
