crs
crs
Planetary coordinate reference systems via IAU codes.
Thin, pyproj-only helpers that resolve IAU planetary CRS and build feature-centered local projections. The body’s ellipsoid / radii are carried by the IAU code itself — nothing is looked up or hardcoded here.
PROJ ships a single IAU CRS edition (IAU_2015); there is no IAU_2009/IAU_2006/… authority, so everything here builds against IAU_2015. (This is unrelated to :mod:planetarypy.constants, which does carry multiple IAU PCK editions for body parameters.)
Body names are resolved to NAIF ids via :mod:planetarypy.constants (one shared body registry); pass a NAIF id integer to skip that import. On a fresh install, the first name resolution triggers the one-time NSSDC archive download that planetarypy.constants performs.
Examples
>>> from planetarypy.crs import body_crs, local_crs
>>> body_crs("mars") # Mars IAU sphere (a == b)
>>> body_crs(499, system="ographic") # by NAIF id
>>> local_crs(137.4, -4.6, "mars") # azeqd centered on Gale craterClasses
| Name | Description |
|---|---|
| CRSConversionWarning | Emitted when data is reprojected without the caller asking explicitly. |
CRSConversionWarning
crs.CRSConversionWarning()Emitted when data is reprojected without the caller asking explicitly.
Its own category so it can be silenced deliberately — warnings.filterwarnings("ignore", category=CRSConversionWarning) — without muting everything else.
Functions
| Name | Description |
|---|---|
| announce_conversion | Tell the user about a reprojection they did not explicitly request. |
| body_crs | Return a body’s geographic CRS from the IAU 2015 authority. |
| clear_target_crs | Forget the session-wide target CRS. |
| get_crs | craterpy-compatible alias for :func:body_crs. |
| get_target_crs | The session-wide target CRS, or None if unset. |
| local_crs | Azimuthal-Equidistant CRS centered on (lon, lat) for body. |
| projected_crs | Return one of a body’s standard projected CRS from the IAU 2015 authority. |
| resolve_crs | Pick the CRS an operation should produce, by precedence. |
| set_target_crs | Set a session-wide CRS that later operations convert their output to. |
| target_crs | Context manager form of :func:set_target_crs. |
announce_conversion
crs.announce_conversion(source, target, *, what='data')Tell the user about a reprojection they did not explicitly request.
Silent reprojection is how authority mismatches become quiet wrongness — the USGS gazetteer ships ESRI:104905 while planetarypy standardises on IAU_2015, and those differ in more than their label.
Deliberately a warnings.warn rather than a log line: planetarypy disables its loguru logger by default for library use, so logger.info here would be invisible to exactly the people who need to see it.
body_crs
crs.body_crs(body, system='sphere')Return a body’s geographic CRS from the IAU 2015 authority.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| body | str or int | Body name (resolved via :mod:planetarypy.constants) or NAIF id. |
required |
| system | (sphere, ocentric, ographic) | Which figure of the body to use. - "sphere" (default) — the IAU sphere, a == b. Defined for every body, and the common currency in planetary work: ISIS operates on spheres, many published products are on one, and a shared sphere avoids datum-shift surprises when stacking heterogeneous datasets in GIS. This is what earlier versions returned for "ocentric". - "ocentric" — planetocentric latitudes on the body’s ellipsoid. - "ographic" — planetographic latitudes on the body’s ellipsoid. The two ellipsoidal systems exist only for bodies that define an ellipsoid (Mars, Mercury, Jupiter — not the Moon, Venus or Europa). |
"sphere" |
Returns
| Name | Type | Description |
|---|---|---|
| pyproj.CRS | The figure and radii come from the IAU code itself; nothing is hardcoded here. |
Examples
>>> body_crs("mars").to_authority() # sphere, a == b
('IAU_2015', '49900')
>>> body_crs("mars", system="ocentric").to_authority()
('IAU_2015', '49902')
>>> body_crs("mars", system="ographic").to_authority()
('IAU_2015', '49901')clear_target_crs
crs.clear_target_crs()Forget the session-wide target CRS.
get_crs
crs.get_crs(body, system='default')craterpy-compatible alias for :func:body_crs.
system="default" maps to "sphere" — the IAU sphere, which is what this alias has always returned. It is spelled "sphere" rather than "ocentric" since the offset tables were corrected: offset 0 is the sphere, and "ocentric" now means the ellipsoid at offset 2.
Unlike craterpy’s original, this does NOT accept an arbitrary CRS string as system (no exception-driven passthrough) — construct such CRS with pyproj directly.
get_target_crs
crs.get_target_crs()The session-wide target CRS, or None if unset.
local_crs
crs.local_crs(lon, lat, body, *, system='sphere')Azimuthal-Equidistant CRS centered on (lon, lat) for body.
Built on the body’s IAU geodetic CRS, so its sphere/ellipsoid comes from the IAU code (nothing looked up). Use for feature-centered work — local buffering, annulus geometry, distance-true measurements near the center.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lon | float | Center longitude/latitude in degrees. | required |
| lat | float | Center longitude/latitude in degrees. | required |
| body | str or int | Body name or NAIF id. | required |
| system | str | See :func:body_crs. |
'sphere' |
Returns
| Name | Type | Description |
|---|---|---|
| pyproj.CRS | A projected CRS (metres) centered on the given point. |
projected_crs
crs.projected_crs(body, projection, system='sphere')Return one of a body’s standard projected CRS from the IAU 2015 authority.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| body | str or int | Body name (resolved via :mod:planetarypy.constants) or NAIF id. |
required |
| projection | str | Projection key, e.g. "north_polar", "equirectangular", "mercator". The *_180 variants are the clon=180 forms. |
required |
| system | (sphere, ographic, ocentric) | Figure of the body. "sphere" exists for every projection; the other two are the biaxial-ellipsoid forms and only exist for bodies that define an ographic system. |
"sphere" |
Returns
| Name | Type | Description |
|---|---|---|
| pyproj.CRS |
Examples
>>> projected_crs(499, "north_polar").to_authority()
('IAU_2015', '49930')resolve_crs
crs.resolve_crs(explicit=None, *, fallback=None)Pick the CRS an operation should produce, by precedence.
explicit (what the caller passed) beats the session target, which beats fallback (usually the body’s own IAU CRS). Returns None only when all three are None — callers should read that as “leave the data alone”.
Central so every consumer resolves precedence identically, and there is one site to change if the rules ever grow.
set_target_crs
crs.set_target_crs(crs_like)Set a session-wide CRS that later operations convert their output to.
Once set, helpers returning georeferenced data reproject to it instead of handing back whatever their upstream source happened to use — so a session mixing a USGS gazetteer shapefile (ESRI authority), a HiRISE GeoTIFF (IAU_2015) and PSA footprints stays in one frame without restating it at every call.
Returns the previous value, so it can be restored.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| crs_like | CRS or str or dict or None | Anything :meth:pyproj.CRS.from_user_input accepts. None clears it. |
required |
target_crs
crs.target_crs(crs_like)Context manager form of :func:set_target_crs.
with target_crs(“IAU_2015:49900”): … gdf = nomenclature.features(“mars”) # arrives in 49900 # previous setting restored here, even if the block raised
Nests correctly and restores on exception: the ContextVar token is reset in a finally.