Skip to content

API Reference

luciole_toolbox.geo

CRSType

Bases: Enum

Define the supported coordinate reference systems (CRS).

  • WGS84: Geodetic CRS, EPSG:4326 (lat/lon).
  • LV03: Swiss projected CRS, EPSG:21781.
  • LV95: Swiss projected CRS, EPSG:2056.

epsg property

Return the EPSG code of this CRS.

from_epsg_code(epsg_code) classmethod

Return the CRS corresponding to the given EPSG code.

round_to_conventional_precision(coords)

Snap a coordinate pair to this CRS's conventional precision.

LocationInfo dataclass

Administrative context of a point: BFS/OFS commune number (COFS), commune, canton and country. Names are exactly as published by swisstopo, not translated by this module - the country name comes out German ("Schweiz", "Liechtenstein"), commune/canton names in their own official language. canton is None for a Liechtenstein point, since it isn't part of the Swiss canton system.

convert_coordinates(cx, cy, target=CRSType.LV03, source=None)

Convert a (cx, cy) pair to target (CRSType.LV03 by default).

source may be given explicitly as CRSType.WGS84/LV03/LV95 to skip detection. Left at its default (None), it is auto-detected via get_CRS; unrecognized input returns None rather than converting.

Values are rounded to 0 decimal for LV03 & LV95, 6 decimals for WGS84.

An invalid target raises ValueError instead of returning None: it is a caller configuration mistake, not messy row data, so it should fail loudly rather than silently propagate through a pipeline.

get_CKM2(cx, cy)

Return the 6-digit Swiss kilometre-square grid code (3-digit easting + 3-digit northing), officially defined on LV03 coordinates.

cx/cy are expected in LV03. LV95 is also accepted: its fixed +2,000,000/+1,000,000 easting/northing offset over LV03 is stripped via % 1_000_000, which is only an approximation of the true LV03 value - LV95 isn't a pure translation of LV03, so they differ by up to ~1.5 m depending on location (see the FINELTRA reframe correction). Close enough for a 1 km grid cell; not an exact reprojection. No CRS detection is performed - callers needing an exact conversion or WGS84 support should convert to LV03 via convert_coordinates first.

get_CNHA(cx, cy)

Return the 8-digit Swiss hectometre-square grid code (4-digit easting + 4-digit northing), officially defined on LV03 coordinates.

Same LV03/LV95 handling and caveats as get_CKM2 - see that docstring.

get_CRS(cx, cy)

Detect the coordinate reference system of a (cx, cy) pair: WGS84 (decimal degrees or DMS, e.g. 46° 23' 06.06" N) or LV03/LV95 (planar easting/northing in metres, told apart by their non-overlapping magnitude ranges - see _LV_SLOTS). Returns None for any other or unrecognized format.

get_altitude(cx, cy, source=None, session=None)

Look up the DHM25 altitude (metres) of a point, via swisstopo's public height API.

cx/cy are detected/converted the same way as convert_coordinates (source skips detection). Returns None if the coordinate can't be resolved, or if the height API rejects the query with an HTTP 400 - in practice this means the point falls outside the height model's coverage, so like get_location_info, a resolved point with no data is None rather than an exception, even though swisstopo signals that case as an HTTP 400 here (vs. an empty result set for get_location_info). Any other HTTP error still propagates to the caller rather than being swallowed.

get_location_info(cx, cy, source=None, session=None)

Look up the Swiss/Liechtenstein commune, canton and country a point falls in, via swisstopo's public identify API.

cx/cy are detected/converted the same way as convert_coordinates (source skips detection); the point is then queried against swisstopo's LV95 administrative-boundary layers. Returns None if the coordinate can't be resolved, or falls outside Switzerland/Liechtenstein entirely. Network errors from the underlying request propagate to the caller rather than being swallowed into a None return, since that would be indistinguishable from a point genuinely outside CH/LI.

is_in_switzerland_bbox(cx, cy, source=None)

Return whether (cx, cy) falls within Switzerland/Liechtenstein's bounding box - a fast rectangular approximation, not the precise border polygon (see get_location_info for that, at the cost of a network call).

Accepts the same input as convert_coordinates: WGS84 (decimal degrees or DMS), LV03 or LV95, auto-detected unless source is given explicitly. Returns None if the coordinate can't be parsed/detected at all, so callers can tell "unrecognized input" apart from "recognized but outside the box" instead of both reading as one falsy value.