rustmap3d 0.4.0

Python geodetic coordinate conversions written in rust

rustmap3d

Simple, fast, and ergonomic geodetic coordinate conversions

---

Installation

# add to an existing project
uv add rustmap3d
# pip install it directly
uv pip install rustmap3d

# pip install without uv
pip install rustmap3d

---

Examples

Low-level transforms api similar to pymap3d and matlab

import rustmap3d


# wgs84 geodetic conversions
lla = rustmap3d.ecef2lla(x, y, z)
ecef = rustmap3d.lla2ecef(lat, lon, alt)
...

# local conversions
ecef_uvw = rustmap3d.enu2ecef_uvw(e, n, u, lat_ref, lon_ref)
ecef = rustmap3d.enu2ecef(e, n, u, lat_ref, lon_ref)
ecef_uvw = rustmap3d.ned2ecef_uvw(n, e, d, lat_ref, lon_ref)
ecef = rustmap3d.ned2ecef(n, e, d, lat_ref, lon_ref)
# enu, ned, aer
...  

# local rotations
enu_quat = rustmap3d.enu2ecef_quat(lat, lon)
enu_dcm = rustmap3d.enu2ecef_dcm(lat, lon) 
# enu, ned

# Conversions
dd = rustmap3d.dms2dd("25:22:44.738N")  #> 25.37909389
dms = rustmap3d.dd2dms(25.37909389, is_lat=true) #> "25:22:44.738N"
lat, lon = rustmap3d.ll2dms(25.37909389, -138.7895679)  #> "25:22:44.738N", "138:47:22.444W"
...  

# distance functions
lat, lon = rustmap3d.vincenty_direct(lat_deg, lon_deg, range_m, bearing_deg)
range_m, bearing_ab, bearing_ba = rustmap3d.vincenty_inverse(lat_a, lon_a, lat_b, lon_b)

High-level GeoObject API

import math
import pydantic
import rustmap3d

# Construct a GeoPosition from either global or local coordinates
reference = rustmap3d.GeoPosition.from_lla((0.0, 0.0, 0.0))
rustmap3d.GeoPosition.from_enu(rustmap3d.DVec3(100.0, 0.0, 0.0), reference)
rustmap3d.GeoPosition.from_ned(rustmap3d.DVec3(100.0, 0.0, 0.0), reference)
# all reference locations accept LLA tuples or GeoPositions for reference locations
pos = rustmap3d.GeoPosition.from_aer(rustmap3d.DVec3(90.0, 0.0, 100.0), (0.0, 0.0, 0.0))

# Conversions
reference.aer_to(pos)
reference.ned_to(pos)
reference.enu_to(pos)

# Operations
vec = pos - reference  # > GeoVector
new_pos = reference + vec  # > GeoPosition

vel = rustmap3d.GeoVelocity.from_dir_speed(rustmap3d.DVec3(1.0, 0.0, 0.0), 100.0)
dt = 1.0
pos = reference + vel * dt  # > GeoPosition

rotation = rustmap3d.GeoOrientation.from_ecef_euler(rustmap3d.DVec3(0.0, math.pi, 0.0))
vec = rustmap3d.GeoVector.from_ecef(rustmap3d.DVec3(100.0, 0, 0.0), reference)
vec = rotation * vec

# Orientations
rot = rustmap3d.GeoOrientation.from_axis_angle(rustmap3d.DVec3(0.0, 0.0, 1), math.pi)
rot.x_axis()
rot.y_axis()
rot.z_axis()


# There is also native pydantic integration for geo objects
class MyModel(pydantic.BaseModel):
    pos: rustmap3d.GeoPosition


model = MyModel(pos=rustmap3d.GeoPosition.from_lla((0.0, 0.0, 0.0)))
dumped = model.model_dump(mode="json")
print(dumped)  # > { "pos": { "ecef": [6378137.0, 0., 0.] } }

validated = MyModel.model_validate(dumped)

Comparison with similar packages

• 🚀🚀 Blazingly fast - written in rust (see benchmarks)
• Zero dependencies
• Dead simple api modeled after pymap3d and matlab
• Exposes rotations (both quaternions and 3x3 matrices)

Benchmarks

Compared to pymap3d

Note: This is comparing calls with python scalars. Vectorized batched conversions will be implemented in the future

• ~50x faster for lla2ecef
• ~400x faster for ecef2lla

# Run benchmarks
uv run pytest --benchmark-histogram="./docs/benchmarks" bench/

Build From Source

Uses standard maturin build process

uv run maturin build -r   # build a whl
uv run maturin dev -r     # build a dev package similar to -e