gws.lib.crs

Coordinate reference systems.

This package provides gws.Crs objects, which describe coordinate reference systems and transform extents, points and resolutions between them. CRS objects are created from EPSG definitions with pyproj, and are cached, so that there is one object per SRID. Only CRSs with meter or degree units are supported. CRS objects with the same SRID compare equal.

transform_resolution samples nine points of the extent (corners, edge midpoints, centre), transforms each together with a one-pixel step in x and in y, and returns the smallest finite positive step length in the target CRS.

A CRS can be referenced by a gws.CrsName in one of these formats (see gws.CrsFormat):

  • numeric SRID: 4326

  • EPSG code: EPSG:4326

  • OGC HTTP URL: http://www.opengis.net/gml/srs/epsg.xml#4326

  • OGC experimental URN: urn:x-ogc:def:crs:EPSG:4326

  • OGC URN: urn:ogc:def:crs:EPSG::4326

  • OGC HTTP URI: http://www.opengis.net/def/crs/EPSG/0/4326

Names are case-insensitive. Some aliases, like CRS:84 or EPSG:900913, are also recognized.

The package provides:

  • predefined CRS objects WGS84 and WEBMERCATOR and related constants,

  • get, require and parse to look up a CRS by name,

  • best_match to pick a CRS from a list of supported CRSs,

  • qgis_extent_width to compute the width of a geographic extent the way QGIS does.

The gws.Crs interface itself is defined in types.pyinc.

Example:

import gws.lib.crs

crs = gws.lib.crs.require('EPSG:25832')
crs.to_string(gws.CrsFormat.urn)  # 'urn:ogc:def:crs:EPSG::25832'

ext = gws.lib.crs.WGS84.transform_extent((5.0, 47.0, 15.0, 55.0), crs)

fmt, crs = gws.lib.crs.parse('urn:ogc:def:crs:EPSG::4326')
crs.axis_for_format(fmt)  # gws.Axis.yx

Source code: gws.lib.crs

Package Contents

gws.lib.crs.best_match(crs: gws.Crs, supported_crs: list[gws.Crs]) → gws.Crs

Return a CRS from the list that most closely matches the given CRS.

If the CRS is in the list, it is returned. Otherwise, for a projected CRS, web mercator or the first projected CRS from the list is preferred, and for a geographic CRS, WGS84 or the first geographic CRS. Failing that, the first CRS from the list is returned, or the given CRS if the list is empty.

Parameters:

  • crs – Target CRS.

  • supported_crs – List of supported CRSs.

Returns:

A CRS object.

gws.lib.crs.COORDINATE_PRECISION_DEG = 7
gws.lib.crs.COORDINATE_PRECISION_M = 2
exception gws.lib.crs.Error

Bases: gws.Error

CRS error.

gws.lib.crs.get(crs_name: gws.CrsName | None) → gws.Crs | None

Get the CRS for a given CRS name or SRID.

Parameters:

crs_name – CRS name in any supported format, or an SRID.

Returns:

The CRS object, or None if the name is empty, cannot be parsed or refers to an unsupported CRS.

gws.lib.crs.METERS_PER_DEGREE = 111319.49079327358

Metres per degree at the equator; the OGC convention for scale denominators in geographic CRS (WMTS 1.0, 6.1).

class gws.lib.crs.Object(**kwargs)

Bases: gws.Crs

Coordinate reference system.

axis_for_format(fmt)

Get the axis orientation implied by a CRS name format.

For CRSs with a lat/lon axis, the orientation depends on how the CRS is named. We adhere to the GeoServer convention: the srid, epsg, url and uri formats imply XY, the urn and urnx formats imply YX (see https://docs.geoserver.org/latest/en/user/services/wfs/axis_order.html). For XY CRSs, the own axis is always returned.

Parameters:

fmt – CRS name format.

Returns:

The axis orientation.

clip_wgs_extent(wgs_extent)

Clip a WGS extent to the maximal extent of this CRS.

Parameters:

wgs_extent – Extent in the WGS projection.

Returns:

The clipped extent in the WGS projection, or None if there is no intersection.

extent_size_in_meters(extent)

Calculate the width and height of an extent in meters.

For projected CRSs, the extent size is returned as is. For geographic CRSs, geodesic distances on the WGS84 ellipsoid are measured along the middle latitude and the middle longitude of the extent.

Parameters:

extent – Extent in this CRS.

Returns:

A (width, height) tuple in meters.

Raises:

gws.lib.crs.Error – If this is a projected CRS with units other than meters.

point_offset_in_meters(xy, dist, az)

Calculate a point at a given distance and direction from another point.

Parameters:

  • xy – Point in this CRS.

  • dist – Distance in meters.

  • az – Azimuth in degrees (0 = North, 90 = East, etc.).

Returns:

The offset point in this CRS.

Raises:

gws.lib.crs.Error – If this is a projected CRS with units other than meters.

to_geojson()

Return a GeoJSON representation of the CRS.

The CRS is represented as a “named CRS” with its urn name, as per the 2008 GeoJSON specification (https://geojson.org/geojson-spec#named-crs).

Returns:

A GeoJSON crs dict.

to_string(fmt=None)

Return the name of the CRS in a given format.

Parameters:

fmt – Format to use, CrsFormat.epsg by default.

Returns:

The CRS name, like EPSG:3857.

transform_extent(ext, crs_to)

Transform an Extent from this CRS to another.

The transformation goes through WGS84. If the extent is very large (almost the whole world) and the target CRS has a limited area of use, the result is computed by sampling points, so that it stays finite.

Parameters:

  • extent – Extent in this CRS.

  • crs_to – Target CRS.

Returns:

The transformed Extent, with min and max values in order.

transform_resolution(extent, res, crs_to)

Transform a resolution over an extent from this CRS to another.

The returned resolution is the finest one found at a set of sample points of the extent, so that the target resolution is never coarser than the source resolution anywhere in the extent.

Parameters:

  • extent – Extent in this CRS.

  • res – Resolution in units of this CRS per pixel.

  • crs_to – Target CRS.

Returns:

The resolution in units of the target CRS per pixel, or 0.0 if the transformation fails.

transformer(crs_to)

Create a transformer function to another CRS.

The function always uses the XY (easting/longitude first) axis order.

Parameters:

crs_to – Target CRS.

Returns:

A function that takes x, y and returns a transformed (x, y) tuple.

gws.lib.crs.parse(crs_name: gws.CrsName) → tuple[gws.CrsFormat, gws.Crs | None]

Parse a CRS name into its format and the CRS itself.

Parameters:

crs_name – CRS name in any supported format, or an SRID.

Returns:

A tuple of the name format and the CRS object. If the name cannot be parsed, (CrsFormat.none, None). If the CRS is unknown or unsupported, the CRS is None.

gws.lib.crs.qgis_extent_width(extent: gws.Extent) → float

Compute the width of a geographic extent in meters, the way QGIS does.

This is a port of QgsScaleCalculator::calculateGeographicDistance from QGIS. The distance is measured along the middle latitude of the extent.

Parameters:

extent – Extent in degrees.

Returns:

The width in meters.

gws.lib.crs.require(crs_name: gws.CrsName) → gws.Crs

Get the CRS for a given CRS name or SRID, and fail if there is none.

Parameters:

crs_name – CRS name in any supported format, or an SRID.

Returns:

The CRS object.

Raises:

Error – If the name cannot be parsed or refers to an unknown or unsupported CRS.

gws.lib.crs.WEBMERCATOR: gws.Crs

3857).

Type:

WGS 84 / Pseudo-Mercator CRS (EPSG

gws.lib.crs.WEBMERCATOR_RADIUS = 6378137

Radius of the web mercator sphere (the WGS84 semi-major axis), metres.

gws.lib.crs.WEBMERCATOR_SQUARE

Square web mercator extent that covers the whole world width, in meters.

gws.lib.crs.WGS84: gws.Crs

4326).

Type:

WGS 84 geographic CRS (EPSG