| Name | pymap3d JSON |
| Version |
3.1.0
JSON |
| download |
| home_page | |
| Summary | pure Python (no prereqs) coordinate conversions, following convention of several popular Matlab routines. |
| upload_time | 2024-02-11 00:59:07 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
coordinate-conversion
geodesy
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python 3-D coordinate conversions
[](https://doi.org/10.5281/zenodo.213676)
[](https://doi.org/10.21105/joss.00580)
[](https://codecov.io/gh/geospace-code/pymap3d)
[](https://pypi.python.org/pypi/pymap3d)
[](http://pepy.tech/project/pymap3d)
Pure Python (no prerequistes beyond Python itself) 3-D geographic coordinate conversions and geodesy.
Function syntax is roughly similar to Matlab Mapping Toolbox.
PyMap3D is intended for non-interactive use on massively parallel (HPC) and embedded systems.
[API docs](https://geospace-code.github.io/pymap3d/)
Thanks to our [contributors](./.github/contributors.md).
## Similar toolboxes in other code languages
* [Matlab, GNU Octave](https://github.com/geospace-code/matmap3d)
* [Fortran](https://github.com/geospace-code/maptran3d)
* [Rust](https://github.com/gberrante/map_3d)
* [C++](https://github.com/ClancyWalters/cppmap3d)
## Prerequisites
Numpy and AstroPy are optional.
Algorithms from Vallado and Meeus are used if AstroPy is not present.
## Install
```sh
python3 -m pip install pymap3d
```
or for the latest development code:
```sh
git clone https://github.com/geospace-code/pymap3d
pip install -e pymap3d
```
One can verify Python functionality after installation by:
```sh
pytest pymap3d
```
## Usage
Where consistent with the definition of the functions, all arguments may
be arbitrarily shaped (scalar, N-D array).
```python
import pymap3d as pm
x,y,z = pm.geodetic2ecef(lat,lon,alt)
az,el,range = pm.geodetic2aer(lat, lon, alt, observer_lat, observer_lon, 0)
```
[Python](https://www.python.org/dev/peps/pep-0448/)
[argument unpacking](https://docs.python.org/3/tutorial/controlflow.html#unpacking-argument-lists)
can be used for compact function arguments with scalars or arbitrarily
shaped N-D arrays:
```python
aer = (az,el,slantrange)
obslla = (obs_lat ,obs_lon, obs_alt)
lla = pm.aer2geodetic(*aer, *obslla)
```
where tuple `lla` is comprised of scalar or N-D arrays `(lat,lon,alt)`.
Example scripts are in the [examples](./Examples) directory.
Native Python float is typically [64 bit](https://docs.python.org/3/library/stdtypes.html#typesnumeric).
Numpy can select real precision bits: 32, 64, 128, etc.
### Functions
Popular mapping toolbox functions ported to Python include the
following, where the source coordinate system (before the "2") is
converted to the desired coordinate system:
```
aer2ecef aer2enu aer2geodetic aer2ned
ecef2aer ecef2enu ecef2enuv ecef2geodetic ecef2ned ecef2nedv
ecef2eci eci2ecef eci2aer aer2eci geodetic2eci eci2geodetic
enu2aer enu2ecef enu2geodetic
geodetic2aer geodetic2ecef geodetic2enu geodetic2ned
ned2aer ned2ecef ned2geodetic
azel2radec radec2azel
lookAtSpheroid
track2 departure meanm
rcurve rsphere
geod2geoc geoc2geod
geodetic2spherical spherical2geodetic
```
Vincenty functions "vincenty.vreckon" and "vincenty.vdist" are accessed like:
```python
import pymap3d.vincenty as pmv
lat2, lon2 = pmv.vreckon(lat1, lon1, ground_range_m, azimuth_deg)
dist_m, azimuth_deg = pmv.vdist(lat1, lon1, lat2, lon2)
```
Additional functions:
* loxodrome_inverse: rhumb line distance and azimuth between ellipsoid points (lat,lon) akin to Matlab `distance('rh', ...)` and `azimuth('rh', ...)`
* loxodrome_direct
* geodetic latitude transforms to/from: parametric, authalic, isometric, and more in pymap3d.latitude
Abbreviations:
* [AER: Azimuth, Elevation, Range](https://en.wikipedia.org/wiki/Spherical_coordinate_system)
* [ECEF: Earth-centered, Earth-fixed](https://en.wikipedia.org/wiki/ECEF)
* [ECI: Earth-centered Inertial using IERS](https://www.iers.org/IERS/EN/Home/home_node.html) via `astropy`
* [ENU: East North Up](https://en.wikipedia.org/wiki/Axes_conventions#Ground_reference_frames:_ENU_and_NED)
* [NED: North East Down](https://en.wikipedia.org/wiki/North_east_down)
* [radec: right ascension, declination](https://en.wikipedia.org/wiki/Right_ascension)
### Ellipsoid
Numerous functions in pymap3d use an ellipsoid model.
The default is WGS84 Ellipsoid.
Numerous other ellipsoids are available in pymap3d.Ellipsoid.
Print available ellipsoid models:
```python
import pymap3d as pm
print(pm.Ellipsoid.models)
```
Specify GRS80 ellipsoid:
```python
import pymap3d as pm
ell = pm.Ellipsoid.from_name('grs80')
```
### array vs scalar
Use of pymap3d on embedded systems or other streaming data applications often deal with scalar position data.
These data are handled efficiently with the Python math stdlib module.
Vector data can be handled via list comprehension.
Those needing multidimensional data with SIMD and other Numpy and/or PyPy accelerated performance can do so automatically by installing Numpy.
pymap3d seamlessly falls back to Python's math module if Numpy isn't present.
To keep the code clean, only scalar data can be used without Numpy.
As noted above, use list comprehension if you need vector data without Numpy.
### Caveats
* Atmospheric effects neglected in all functions not invoking AstroPy.
Would need to update code to add these input parameters (just start a GitHub Issue to request).
* Planetary perturbations and nutation etc. not fully considered.
## Compare to Matlab Mapping and Aerospace Toolbox
The tests in files tests/test_matlab*.py selected by
```sh
pytest -k matlab
# run from pymap3d/ top-level directory
```
use
[Matlab Engine for Python](https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html)
to compare Python PyMap3D output with Matlab output using Matlab functions.
## Notes
As compared to [PyProj](https://github.com/jswhit/pyproj):
* PyMap3D does not require anything beyond pure Python for most transforms
* Astronomical conversions are done using (optional) AstroPy for established accuracy
* PyMap3D API is similar to Matlab Mapping Toolbox, while PyProj's interface is quite distinct
* PyMap3D intrinsically handles local coordinate systems such as ENU,
while PyProj ENU requires some [additional effort](https://github.com/jswhit/pyproj/issues/105).
* PyProj is oriented towards points on the planet surface, while PyMap3D handles points on or above the planet surface equally well, particularly important for airborne vehicles and remote sensing.
### AstroPy.Units.Quantity
At this time,
[AstroPy.Units.Quantity](http://docs.astropy.org/en/stable/units/)
is not supported.
Let us know if this is of interest.
Impacts on performance would have to be considered before making Quantity a first-class citizen.
For now, you can workaround by passing in the `.value` of the variable.
Raw data
{
"_id": null,
"home_page": "",
"name": "pymap3d",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "coordinate-conversion,geodesy",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/a2/2c/12ca273a905c245bdfdae07679f6cb65eefb07ee54d1313fac65598336b1/pymap3d-3.1.0.tar.gz",
"platform": null,
"description": "# Python 3-D coordinate conversions\n\n[](https://doi.org/10.5281/zenodo.213676)\n[](https://doi.org/10.21105/joss.00580)\n[](https://codecov.io/gh/geospace-code/pymap3d)\n\n\n[](https://pypi.python.org/pypi/pymap3d)\n[](http://pepy.tech/project/pymap3d)\n\nPure Python (no prerequistes beyond Python itself) 3-D geographic coordinate conversions and geodesy.\nFunction syntax is roughly similar to Matlab Mapping Toolbox.\nPyMap3D is intended for non-interactive use on massively parallel (HPC) and embedded systems.\n\n[API docs](https://geospace-code.github.io/pymap3d/)\n\nThanks to our [contributors](./.github/contributors.md).\n\n## Similar toolboxes in other code languages\n\n* [Matlab, GNU Octave](https://github.com/geospace-code/matmap3d)\n* [Fortran](https://github.com/geospace-code/maptran3d)\n* [Rust](https://github.com/gberrante/map_3d)\n* [C++](https://github.com/ClancyWalters/cppmap3d)\n\n## Prerequisites\n\nNumpy and AstroPy are optional.\nAlgorithms from Vallado and Meeus are used if AstroPy is not present.\n\n## Install\n\n```sh\npython3 -m pip install pymap3d\n```\n\nor for the latest development code:\n\n```sh\ngit clone https://github.com/geospace-code/pymap3d\n\npip install -e pymap3d\n```\n\nOne can verify Python functionality after installation by:\n\n```sh\npytest pymap3d\n```\n\n## Usage\n\nWhere consistent with the definition of the functions, all arguments may\nbe arbitrarily shaped (scalar, N-D array).\n\n```python\nimport pymap3d as pm\n\nx,y,z = pm.geodetic2ecef(lat,lon,alt)\n\naz,el,range = pm.geodetic2aer(lat, lon, alt, observer_lat, observer_lon, 0)\n```\n\n[Python](https://www.python.org/dev/peps/pep-0448/)\n[argument unpacking](https://docs.python.org/3/tutorial/controlflow.html#unpacking-argument-lists)\ncan be used for compact function arguments with scalars or arbitrarily\nshaped N-D arrays:\n\n```python\naer = (az,el,slantrange)\nobslla = (obs_lat ,obs_lon, obs_alt)\n\nlla = pm.aer2geodetic(*aer, *obslla)\n```\n\nwhere tuple `lla` is comprised of scalar or N-D arrays `(lat,lon,alt)`.\n\nExample scripts are in the [examples](./Examples) directory.\n\nNative Python float is typically [64 bit](https://docs.python.org/3/library/stdtypes.html#typesnumeric).\nNumpy can select real precision bits: 32, 64, 128, etc.\n\n### Functions\n\nPopular mapping toolbox functions ported to Python include the\nfollowing, where the source coordinate system (before the \"2\") is\nconverted to the desired coordinate system:\n\n```\naer2ecef aer2enu aer2geodetic aer2ned\necef2aer ecef2enu ecef2enuv ecef2geodetic ecef2ned ecef2nedv\necef2eci eci2ecef eci2aer aer2eci geodetic2eci eci2geodetic\nenu2aer enu2ecef enu2geodetic\ngeodetic2aer geodetic2ecef geodetic2enu geodetic2ned\nned2aer ned2ecef ned2geodetic\nazel2radec radec2azel\nlookAtSpheroid\ntrack2 departure meanm\nrcurve rsphere\ngeod2geoc geoc2geod\ngeodetic2spherical spherical2geodetic\n```\n\nVincenty functions \"vincenty.vreckon\" and \"vincenty.vdist\" are accessed like:\n\n```python\nimport pymap3d.vincenty as pmv\n\nlat2, lon2 = pmv.vreckon(lat1, lon1, ground_range_m, azimuth_deg)\ndist_m, azimuth_deg = pmv.vdist(lat1, lon1, lat2, lon2)\n```\n\nAdditional functions:\n\n* loxodrome_inverse: rhumb line distance and azimuth between ellipsoid points (lat,lon) akin to Matlab `distance('rh', ...)` and `azimuth('rh', ...)`\n* loxodrome_direct\n* geodetic latitude transforms to/from: parametric, authalic, isometric, and more in pymap3d.latitude\n\nAbbreviations:\n\n* [AER: Azimuth, Elevation, Range](https://en.wikipedia.org/wiki/Spherical_coordinate_system)\n* [ECEF: Earth-centered, Earth-fixed](https://en.wikipedia.org/wiki/ECEF)\n* [ECI: Earth-centered Inertial using IERS](https://www.iers.org/IERS/EN/Home/home_node.html) via `astropy`\n* [ENU: East North Up](https://en.wikipedia.org/wiki/Axes_conventions#Ground_reference_frames:_ENU_and_NED)\n* [NED: North East Down](https://en.wikipedia.org/wiki/North_east_down)\n* [radec: right ascension, declination](https://en.wikipedia.org/wiki/Right_ascension)\n\n### Ellipsoid\n\nNumerous functions in pymap3d use an ellipsoid model.\nThe default is WGS84 Ellipsoid.\nNumerous other ellipsoids are available in pymap3d.Ellipsoid.\n\nPrint available ellipsoid models:\n\n```python\nimport pymap3d as pm\n\nprint(pm.Ellipsoid.models)\n```\n\nSpecify GRS80 ellipsoid:\n\n```python\nimport pymap3d as pm\n\nell = pm.Ellipsoid.from_name('grs80')\n```\n\n### array vs scalar\n\nUse of pymap3d on embedded systems or other streaming data applications often deal with scalar position data.\nThese data are handled efficiently with the Python math stdlib module.\nVector data can be handled via list comprehension.\n\nThose needing multidimensional data with SIMD and other Numpy and/or PyPy accelerated performance can do so automatically by installing Numpy.\npymap3d seamlessly falls back to Python's math module if Numpy isn't present.\nTo keep the code clean, only scalar data can be used without Numpy.\nAs noted above, use list comprehension if you need vector data without Numpy.\n\n### Caveats\n\n* Atmospheric effects neglected in all functions not invoking AstroPy.\n Would need to update code to add these input parameters (just start a GitHub Issue to request).\n* Planetary perturbations and nutation etc. not fully considered.\n\n## Compare to Matlab Mapping and Aerospace Toolbox\n\nThe tests in files tests/test_matlab*.py selected by\n\n```sh\npytest -k matlab\n# run from pymap3d/ top-level directory\n```\n\nuse\n[Matlab Engine for Python](https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html)\nto compare Python PyMap3D output with Matlab output using Matlab functions.\n\n## Notes\n\nAs compared to [PyProj](https://github.com/jswhit/pyproj):\n\n* PyMap3D does not require anything beyond pure Python for most transforms\n* Astronomical conversions are done using (optional) AstroPy for established accuracy\n* PyMap3D API is similar to Matlab Mapping Toolbox, while PyProj's interface is quite distinct\n* PyMap3D intrinsically handles local coordinate systems such as ENU,\n while PyProj ENU requires some [additional effort](https://github.com/jswhit/pyproj/issues/105).\n* PyProj is oriented towards points on the planet surface, while PyMap3D handles points on or above the planet surface equally well, particularly important for airborne vehicles and remote sensing.\n\n### AstroPy.Units.Quantity\n\nAt this time,\n[AstroPy.Units.Quantity](http://docs.astropy.org/en/stable/units/)\nis not supported.\nLet us know if this is of interest.\nImpacts on performance would have to be considered before making Quantity a first-class citizen.\nFor now, you can workaround by passing in the `.value` of the variable.\n",
"bugtrack_url": null,
"license": "",
"summary": "pure Python (no prereqs) coordinate conversions, following convention of several popular Matlab routines.",
"version": "3.1.0",
"project_urls": null,
"split_keywords": [
"coordinate-conversion",
"geodesy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6107a2fff88ae09b86cfea037afcef6ba46974ae59c6f0b3def87859005efc3d",
"md5": "1595070fece7891c9030428af3745670",
"sha256": "8231b7dde0289ae8e2681261a79c80a990dba0a4bdfc443717dd02d1fd37c522"
},
"downloads": -1,
"filename": "pymap3d-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1595070fece7891c9030428af3745670",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 60563,
"upload_time": "2024-02-11T00:59:05",
"upload_time_iso_8601": "2024-02-11T00:59:05.785785Z",
"url": "https://files.pythonhosted.org/packages/61/07/a2fff88ae09b86cfea037afcef6ba46974ae59c6f0b3def87859005efc3d/pymap3d-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a22c12ca273a905c245bdfdae07679f6cb65eefb07ee54d1313fac65598336b1",
"md5": "327ab8476b7eb71b3e164b1af8082186",
"sha256": "c1a83fc2732234b6763f0372ad2628dd24b13a1e6a64e9f7825be4112463f369"
},
"downloads": -1,
"filename": "pymap3d-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "327ab8476b7eb71b3e164b1af8082186",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 47736,
"upload_time": "2024-02-11T00:59:07",
"upload_time_iso_8601": "2024-02-11T00:59:07.712390Z",
"url": "https://files.pythonhosted.org/packages/a2/2c/12ca273a905c245bdfdae07679f6cb65eefb07ee54d1313fac65598336b1/pymap3d-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-11 00:59:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pymap3d"
}
