pymap3d

library3.2.0pypypi✓ verified 24d ago

pymap3d is a pure Python library (with no external prerequisites) providing various coordinate conversions. It follows the conventions of several popular Matlab routines for geospatial and attitude transformations. The current version is 3.2.0, and it maintains an active development status with regular updates.

data serialization

pip install pymap3d

package ↗

INSTALL

IMPORT

SIG · PYMAP3D

pymap3d

datapythonv3.2.0

Install

1.6s avg

Import

67ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.068s · 18.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.066s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

geodetic2ecef

✓ from pymap3d import geodetic2ecef

ecef2geodetic

✓ from pymap3d import ecef2geodetic

ecef2eci

✓ from pymap3d import ecef2eci

enu2uvw

✓ from pymap3d import enu2uvw

This quickstart demonstrates core coordinate conversion functionalities. It converts geodetic coordinates to ECEF, then converts ECEF back to geodetic to show round-trip consistency. Finally, it illustrates conversion from ECEF to ECI, highlighting the need for a specific timestamp.

import pymap3d as pm import datetime # Example Geodetic (Lat, Lon, Alt) to ECEF (Earth-Centered, Earth-Fixed) conversion lat, lon, alt = 42.0, -82.0, 200.0 # Latitude (deg), Longitude (deg), Altitude (meters) x, y, z = pm.geodetic2ecef(lat, lon, alt) print(f"ECEF coordinates: x={x:.2f}m, y={y:.2f}m, z={z:.2f}m") # Example ECEF to Geodetic conversion lat2, lon2, alt2 = pm.ecef2geodetic(x, y, z) print(f"Geodetic coordinates: lat={lat2:.2f}deg, lon={lon2:.2f}deg, alt={alt2:.2f}m") # Example ECEF to ECI (Earth-Centered Inertial) conversion (requires datetime) # For a specific time, you need the corresponding position and velocity. time = datetime.datetime(2023, 1, 20, 12, 0, 0, tzinfo=datetime.timezone.utc) x_eci, y_eci, z_eci = pm.ecef2eci(x, y, z, time) print(f"ECI coordinates (at {time}): x={x_eci:.2f}m, y={y_eci:.2f}m, z={z_eci:.2f}m")

Debug

Known issues

breakingThe entire `pymap3d.aer` module was removed in v3.0.0. Functions like `aer2enu` and `enu2aer` must now be imported and used directly from `pymap3d`.

fix

Replace `pymap3d.aer.aer2enu(...)` with `pymap3d.aer2enu(...)` and similarly for other functions.

affects: >=3.0.0

breakingThe sign for altitude in `aer2enu` was corrected in v3.1.0. If you relied on the incorrect sign in previous versions, your altitude results will now be inverted.

fix

Review existing code using `aer2enu` and adjust expected altitude signs if upgrading from a version older than 3.1.0.

affects: >=3.1.0

gotchapymap3d explicitly follows Matlab's coordinate convention. This means input/output order (e.g., lat, lon, alt vs. lon, lat, alt), units (degrees vs. radians), and specific frame definitions might differ from other Python geospatial libraries.

fix

Always consult the function's docstring or the official documentation to confirm the exact input arguments, units, and output format. Do not assume compatibility with other libraries without verification.

affects: All versions

gotchaIn v3.0.0, the default value for the `height` parameter in `geodetic2ecef` changed from `NaN` to `0.0`. This can silently alter results if code implicitly relied on the previous `NaN` behavior without explicitly passing a `height` value.

fix

Ensure that if `geodetic2ecef` is called without a `height` argument, the implicit `0.0` meter height is the desired behavior for your application. Explicitly pass `height=...` if a different default is needed.

affects: >=3.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pymap3d'

The `pymap3d` library has not been installed in the current Python environment, or the environment where it was installed is not active.

fix

Install the library using pip: `pip install pymap3d`

AttributeError: module 'pymap3d' has no attribute 'vincenty'

This error typically occurs in older versions of `pymap3d` (e.g., 2.7.2) where the `vincenty` submodule was not directly exposed under the top-level `pymap3d` import. The functions were moved or had a different access path.

fix

Ensure you are using a recent version of `pymap3d` and import specific functions directly from their submodules, e.g., `from pymap3d.vincenty import vdist` if `vincenty` functions are still in a dedicated submodule, or directly from `pymap3d` if they've been elevated. For most modern usage, functions are directly available after `import pymap3d as pm` like `pm.geodetic2ecef`.

AttributeError: 'list' object has no attribute 'squeeze' (or similar AttributeError when passing non-scalar data without NumPy)

When NumPy is not installed, `pymap3d` functions expect scalar inputs. Attempting to pass list-like or other non-scalar data, and if the internal logic tries to call NumPy-specific methods like `.squeeze()` on non-NumPy types, an `AttributeError` can occur.

fix

Install NumPy in your environment (`pip install numpy`) to enable `pymap3d` to handle array-like inputs, or ensure all inputs are scalar Python numbers if you intend to use `pymap3d` without NumPy. If using non-scalar data without NumPy, process each scalar value individually, perhaps using a list comprehension.

TypeError: geodetic2ecef() missing 1 required positional argument: 'alt'

The `geodetic2ecef` function, and many other coordinate conversion functions in pymap3d, require all three positional arguments (latitude, longitude, and altitude).

fix

Provide the missing `alt` (altitude) argument, ensuring all three coordinate values are passed: `pymap3d.geodetic2ecef(lat, lon, alt)`

AttributeError: module 'pymap3d' has no attribute 'ecef2lla'

The function name `ecef2lla` is incorrect; the pymap3d library uses `ecef2geodetic` for converting ECEF coordinates to geodetic coordinates (latitude, longitude, altitude).

fix

Use the correct function name: `pymap3d.ecef2geodetic(x, y, z)`

Upgrade

Version history

3.2.0latest on PyPI · released Jul 8, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/pymap3d/ ↗