# PyNautical
[](https://pypi.org/project/pynautical/)
[](https://www.python.org/downloads/)
[](https://choosealicense.com/licenses/mit/)
**PyNautical** is a lightweight Python library for performing core navigational and maritime calculations.
It offers a set of simple, stateless functions to handle:
- Unit conversion between nautical miles and other distance units
- Degree and DMS (degrees-minutes-seconds) coordinate conversions
- Rhumbline and great circle course (bearing) computations
- Distance measurement on both spherical and WGS84 ellipsoidal models
- Coordinate interpolation along rhumbline and great circle routes
Designed for clarity and portability:
- No external dependencies (uses only the Python standard library)
- Suitable for route planning, marine simulations, GIS tools, and education
- Easy to integrate into both small scripts and larger navigation systems
## Installation
### For Users
PyNautical requires Python 3.9 or newer. You can use the package manager [pip](https://pip.pypa.io/en/stable/) install the latest release of `pynautical` from PyPI:
```bash
pip install pynautical
```
### For Developers
To install the latest development version from source:
```bash
git clone https://github.com/s-w-chen/pynautical.git
cd pynautical
pip install -e .
```
## Function Reference
| Module | Function | Description | Return Type |
|:--:|:--:|--|:--:|
| `units` | `to_nm` | Convert distance from unit to nautical miles | `float` |
| `units` | `nm_to` | Convert nautical miles to specified unit | `float` |
| `units` | `deg_to_dms` | Convert decimal degrees to DMS tuple | `tuple` |
| `units` | `dms_to_deg` | Convert DMS (deg, min, sec) to decimal degrees | `float` |
| `course` | `RL_COG` | Calculate rhumbline course (bearing) | `float` |
| `course` | `GC_COG` | Calculate great circle initial bearing | `float` |
| `distance` | `RL_DIST` | Rhumbline distance (spherical model) | `float` |
| `distance` | `GC_DIST` | Great circle distance (spherical model) | `float` |
| `distance` | `RL_DIST_WGS84` | Rhumbline distance (WGS84 ellipsoid) | `float` |
| `distance` | `GC_DIST_WGS84` | Great circle distance (WGS84 ellipsoid) | `float` |
| `route` | `RL_Slerp` | Interpolate points along rhumbline route | `tuple` |
| `route` | `GC_Slerp` | Interpolate points along great circle route | `tuple` |
## Usage
Import functions from submodules as needed:
```python
# Unit conversion functions
from pynautical.units import to_nm, nm_to, deg_to_dms, dms_to_deg
# Course (bearing) calculations
from pynautical.course import RL_COG, GC_COG # Course Over the Ground
# Distance calculations
from pynautical.distance import RL_DIST, GC_DIST # Spherical model
from pynautical.distance import RL_DIST_WGS84, GC_DIST_WGS84 # WGS84 ellipsoidal model
# Route coordinate calculations
from pynautical.route import RL_Slerp, GC_Slerp # Interpolated waypoints along the route
```
If re-exported through the package root, you may also:
```python
import pynautical
```
## Examples
### Unit Conversion
Convert between nautical miles and other distance units.
```python
from pynautical.units import to_nm, nm_to
# Convert 26 kilometers to nautical miles
nm = to_nm(26, unit="km")
# Output: 14.038876
print(nm)
# Convert 2 nautical miles to feet
meters = nm_to(2, unit="ft")
# Output: 12152.230972
print(meters)
```
### Coordinate Conversion
Convert between decimal degrees and degrees-minutes-seconds (DMS).
```python
from pynautical.units import deg_to_dms, dms_to_deg
# Convert 9.487 degrees latitude to DMS
dms = deg_to_dms(9.487, coord_type="lat")
# Output: (9, 29, 13.2, 'N')
print(dms)
# Convert 25°7'22.8" N to decimal degrees
decimal_deg = dms_to_deg(26, 2, 9.1, direction="N")
# Output: 26.035861
print(decimal_deg)
```
### Course Calculation
Calculate rhumbline bearings (constant heading) and great circle bearings (initial azimuth at departure).
```python
from pynautical.course import RL_COG, GC_COG
# Rhumbline course (bearing) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)
rl_bearing = RL_COG(25.17, 121.75, 33.71, -118.25)
# Output: 85.321161
print(rl_bearing)
# Great circle initial course from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)
gc_bearing = GC_COG(25.17, 121.75, 33.71, -118.25)
# Output: 46.686927
print(gc_bearing)
```
### Distance Calculation
Compute rhumbline and great circle distances in nautical miles using spherical or WGS84 ellipsoidal models.
```python
from pynautical.distance import RL_DIST, RL_DIST_WGS84, GC_DIST, GC_DIST_WGS84
# Rhumbline distance (spherical) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)
rl_dist = RL_DIST(25.17, 121.75, 33.71, -118.25)
# Output: 6285.925260
print(rl_dist)
# Rhumbline distance (WGS84) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)
rl_dist_wgs84 = RL_DIST_WGS84(25.17, 121.75, 33.71, -118.25)
# Output: 6298.061801
print(rl_dist_wgs84)
# Great circle distance (spherical) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)
gc_dist = GC_DIST(25.17, 121.75, 33.71, -118.25)
# Output: 5888.213488
print(gc_dist)
# Great circle distance (WGS84) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)
gc_dist_wgs84 = GC_DIST_WGS84(25.17, 121.75, 33.71, -118.25)
# Output: 5898.666636
print(gc_dist_wgs84)
```
### Route Coordinate Interpolation
Interpolate intermediate points along rhumbline or great circle routes.
```python
from pynautical.route import RL_Slerp, GC_Slerp
# Interpolate 25% along the rhumbline path
rl_point = RL_Slerp(25.17, 121.75, 33.71, -118.25, f=0.25)
# Output: (27.371492, 151.750000)
print(rl_point)
# Interpolate halfway along the great circle path
gc_point = GC_Slerp(25.17, 121.75, 33.71, -118.25, f=0.5)
# Output: (48.386373, 177.575501)
print(gc_point)
```
## Future Plans
Future versions of PyNautical aim to extend beyond route and distance calculations.
A key planned feature is support for AIS (Automatic Identification System) message encoding and decoding, allowing the library to:
- Parse raw AIS messages into structured data
- Encode structured AIS data into standard AIS message formats
- Provide utility functions for common AIS message types
This will expand PyNautical's capabilities for use in maritime tracking, simulation, and data analysis.
## License
MIT License ([MIT](https://choosealicense.com/licenses/mit/))
Copyright (c) 2025 Sheng-Wen,Chen
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://github.com/s-w-chen/pynautical",
"name": "PyNautical",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "nautical, navigation, geodesy, marine, coordinates, distance, course, bearing, rhumbline, great circle, WGS84, python",
"author": "Sheng-Wen,Chen",
"author_email": "dannis.sw.chen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/26/11/4f3f63ae351c2b5d41096b3f19a5d7cced3042b25094851a840643667a60/pynautical-0.1.tar.gz",
"platform": null,
"description": "# PyNautical\r\n\r\n[](https://pypi.org/project/pynautical/)\r\n[](https://www.python.org/downloads/)\r\n[](https://choosealicense.com/licenses/mit/)\r\n\r\n**PyNautical** is a lightweight Python library for performing core navigational and maritime calculations.\r\n\r\nIt offers a set of simple, stateless functions to handle:\r\n\r\n- Unit conversion between nautical miles and other distance units\r\n- Degree and DMS (degrees-minutes-seconds) coordinate conversions\r\n- Rhumbline and great circle course (bearing) computations\r\n- Distance measurement on both spherical and WGS84 ellipsoidal models\r\n- Coordinate interpolation along rhumbline and great circle routes\r\n\r\nDesigned for clarity and portability:\r\n\r\n- No external dependencies (uses only the Python standard library)\r\n- Suitable for route planning, marine simulations, GIS tools, and education\r\n- Easy to integrate into both small scripts and larger navigation systems\r\n## Installation\r\n\r\n### For Users\r\n\r\nPyNautical requires Python 3.9 or newer. You can use the package manager [pip](https://pip.pypa.io/en/stable/) install the latest release of `pynautical` from PyPI:\r\n\r\n```bash\r\n pip install pynautical\r\n```\r\n\r\n### For Developers\r\n\r\nTo install the latest development version from source:\r\n\r\n```bash\r\n git clone https://github.com/s-w-chen/pynautical.git\r\n cd pynautical\r\n pip install -e .\r\n```\r\n## Function Reference\r\n\r\n| Module | Function | Description | Return Type |\r\n|:--:|:--:|--|:--:|\r\n| `units` | `to_nm` | Convert distance from unit to nautical miles | `float` |\r\n| `units` | `nm_to` | Convert nautical miles to specified unit | `float` |\r\n| `units` | `deg_to_dms` | Convert decimal degrees to DMS tuple | `tuple` |\r\n| `units` | `dms_to_deg` | Convert DMS (deg, min, sec) to decimal degrees | `float` |\r\n| `course` | `RL_COG` | Calculate rhumbline course (bearing) | `float` |\r\n| `course` | `GC_COG` | Calculate great circle initial bearing | `float` |\r\n| `distance` | `RL_DIST` | Rhumbline distance (spherical model) | `float` |\r\n| `distance` | `GC_DIST` | Great circle distance (spherical model) | `float` |\r\n| `distance` | `RL_DIST_WGS84` | Rhumbline distance (WGS84 ellipsoid) | `float` |\r\n| `distance` | `GC_DIST_WGS84` | Great circle distance (WGS84 ellipsoid) | `float` |\r\n| `route` | `RL_Slerp` | Interpolate points along rhumbline route | `tuple` |\r\n| `route` | `GC_Slerp` | Interpolate points along great circle route | `tuple` |\r\n\r\n## Usage\r\n\r\nImport functions from submodules as needed:\r\n\r\n```python\r\n# Unit conversion functions\r\nfrom pynautical.units import to_nm, nm_to, deg_to_dms, dms_to_deg\r\n\r\n# Course (bearing) calculations\r\nfrom pynautical.course import RL_COG, GC_COG # Course Over the Ground\r\n\r\n# Distance calculations\r\nfrom pynautical.distance import RL_DIST, GC_DIST # Spherical model\r\nfrom pynautical.distance import RL_DIST_WGS84, GC_DIST_WGS84 # WGS84 ellipsoidal model\r\n\r\n# Route coordinate calculations\r\nfrom pynautical.route import RL_Slerp, GC_Slerp # Interpolated waypoints along the route\r\n```\r\n\r\nIf re-exported through the package root, you may also:\r\n\r\n```python\r\nimport pynautical\r\n```\r\n\r\n## Examples\r\n\r\n### Unit Conversion\r\n\r\nConvert between nautical miles and other distance units.\r\n\r\n```python\r\nfrom pynautical.units import to_nm, nm_to\r\n\r\n# Convert 26 kilometers to nautical miles\r\nnm = to_nm(26, unit=\"km\")\r\n# Output: 14.038876\r\nprint(nm)\r\n\r\n# Convert 2 nautical miles to feet\r\nmeters = nm_to(2, unit=\"ft\")\r\n# Output: 12152.230972\r\nprint(meters)\r\n```\r\n\r\n### Coordinate Conversion\r\n\r\nConvert between decimal degrees and degrees-minutes-seconds (DMS).\r\n\r\n```python\r\nfrom pynautical.units import deg_to_dms, dms_to_deg\r\n\r\n# Convert 9.487 degrees latitude to DMS\r\ndms = deg_to_dms(9.487, coord_type=\"lat\")\r\n# Output: (9, 29, 13.2, 'N')\r\nprint(dms)\r\n\r\n# Convert 25\u00b07'22.8\" N to decimal degrees\r\ndecimal_deg = dms_to_deg(26, 2, 9.1, direction=\"N\")\r\n# Output: 26.035861\r\nprint(decimal_deg)\r\n```\r\n\r\n### Course Calculation\r\n\r\nCalculate rhumbline bearings (constant heading) and great circle bearings (initial azimuth at departure).\r\n\r\n```python\r\nfrom pynautical.course import RL_COG, GC_COG\r\n\r\n# Rhumbline course (bearing) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)\r\nrl_bearing = RL_COG(25.17, 121.75, 33.71, -118.25)\r\n# Output: 85.321161\r\nprint(rl_bearing)\r\n\r\n# Great circle initial course from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)\r\ngc_bearing = GC_COG(25.17, 121.75, 33.71, -118.25)\r\n# Output: 46.686927\r\nprint(gc_bearing)\r\n```\r\n\r\n### Distance Calculation\r\n\r\nCompute rhumbline and great circle distances in nautical miles using spherical or WGS84 ellipsoidal models.\r\n\r\n```python\r\nfrom pynautical.distance import RL_DIST, RL_DIST_WGS84, GC_DIST, GC_DIST_WGS84\r\n\r\n# Rhumbline distance (spherical) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)\r\nrl_dist = RL_DIST(25.17, 121.75, 33.71, -118.25)\r\n# Output: 6285.925260\r\nprint(rl_dist)\r\n\r\n# Rhumbline distance (WGS84) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)\r\nrl_dist_wgs84 = RL_DIST_WGS84(25.17, 121.75, 33.71, -118.25)\r\n# Output: 6298.061801\r\nprint(rl_dist_wgs84)\r\n\r\n# Great circle distance (spherical) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)\r\ngc_dist = GC_DIST(25.17, 121.75, 33.71, -118.25)\r\n# Output: 5888.213488\r\nprint(gc_dist)\r\n\r\n# Great circle distance (WGS84) from TWKEL(25.17, 121.75) to USLSA(33.71, -118.25)\r\ngc_dist_wgs84 = GC_DIST_WGS84(25.17, 121.75, 33.71, -118.25)\r\n# Output: 5898.666636\r\nprint(gc_dist_wgs84)\r\n```\r\n\r\n### Route Coordinate Interpolation\r\n\r\nInterpolate intermediate points along rhumbline or great circle routes.\r\n\r\n```python\r\nfrom pynautical.route import RL_Slerp, GC_Slerp\r\n\r\n# Interpolate 25% along the rhumbline path\r\nrl_point = RL_Slerp(25.17, 121.75, 33.71, -118.25, f=0.25)\r\n# Output: (27.371492, 151.750000)\r\nprint(rl_point)\r\n\r\n# Interpolate halfway along the great circle path\r\ngc_point = GC_Slerp(25.17, 121.75, 33.71, -118.25, f=0.5)\r\n# Output: (48.386373, 177.575501)\r\nprint(gc_point)\r\n```\r\n## Future Plans\r\n\r\nFuture versions of PyNautical aim to extend beyond route and distance calculations.\r\n\r\nA key planned feature is support for AIS (Automatic Identification System) message encoding and decoding, allowing the library to:\r\n\r\n- Parse raw AIS messages into structured data\r\n- Encode structured AIS data into standard AIS message formats\r\n- Provide utility functions for common AIS message types\r\n\r\nThis will expand PyNautical's capabilities for use in maritime tracking, simulation, and data analysis.\r\n## License\r\n\r\nMIT License ([MIT](https://choosealicense.com/licenses/mit/))\r\n\r\nCopyright (c) 2025 Sheng-Wen,Chen\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A nautical library for calculations in Python.",
"version": "0.1",
"project_urls": {
"Documentation": "https://github.com/s-w-chen/pynautical#readme",
"Homepage": "https://github.com/s-w-chen/pynautical",
"Source": "https://github.com/s-w-chen/pynautical"
},
"split_keywords": [
"nautical",
" navigation",
" geodesy",
" marine",
" coordinates",
" distance",
" course",
" bearing",
" rhumbline",
" great circle",
" wgs84",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "659a17f77198ac6c43fe41c1c06c19a3b6b1e0b84e0b151621cc7392421b3095",
"md5": "08f5250f20425ad13cee64c97b6f93f8",
"sha256": "d5c679cac68e79c5d89f62242292bf0a0a87515c1a475ed232db08e405fff616"
},
"downloads": -1,
"filename": "pynautical-0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "08f5250f20425ad13cee64c97b6f93f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12363,
"upload_time": "2025-07-12T09:29:25",
"upload_time_iso_8601": "2025-07-12T09:29:25.258730Z",
"url": "https://files.pythonhosted.org/packages/65/9a/17f77198ac6c43fe41c1c06c19a3b6b1e0b84e0b151621cc7392421b3095/pynautical-0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26114f3f63ae351c2b5d41096b3f19a5d7cced3042b25094851a840643667a60",
"md5": "12a9d7745676032bab881f18f56b300e",
"sha256": "d8beb8024fe0ae584d64b79e5766cded20d9a441b1a708748ea4c951eaba8280"
},
"downloads": -1,
"filename": "pynautical-0.1.tar.gz",
"has_sig": false,
"md5_digest": "12a9d7745676032bab881f18f56b300e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10668,
"upload_time": "2025-07-12T09:29:26",
"upload_time_iso_8601": "2025-07-12T09:29:26.657065Z",
"url": "https://files.pythonhosted.org/packages/26/11/4f3f63ae351c2b5d41096b3f19a5d7cced3042b25094851a840643667a60/pynautical-0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 09:29:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "s-w-chen",
"github_project": "pynautical",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pynautical"
}
JSON
