Coordinate reference systems in Cartopy

The cartopy.crs.CRS class is the very core of cartopy, all coordinate reference systems in cartopy have CRS as a parent class, meaning all projections have the interface described below.

class cartopy.crs.CRS(proj4_params, globe=None)

Defines a Coordinate Reference System using proj.4.

Parameters :

proj4_params : iterable of key-value pairs

The proj4 parameters required to define the desired CRS. The parameters should not describe the desired elliptic model, instead create an appropriate Globe instance. The proj4_params parameters will override any parameters that the Globe defines.

globe : Globe instance, optional

If omitted, the default Globe instance will be created. See Globe for details.

globe

The Globe instance of this CRS.

as_geocentric()

Returns a new Geocentric CRS with the same ellipse/datum as this CRS.

as_geodetic()

Returns a new Geodetic CRS with the same ellipse/datum as this CRS.

transform_point(x, y, src_crs)

Transform the given float64 coordinate pair, in the given source coordinate system (src_crs), to this coordinate system.

Args:

• x - the x coordinate, in src_crs coordinates, to transform

• y - the y coordinate, in src_crs coordinates, to transform

• src_crs - instance of CRS that represents the coordinate

  system of x and y.

Returns:

(x, y) - in this coordinate system

transform_points(src_crs, x, y[, z])

Transform the given coordinates, in the given source coordinate system (src_crs), to this coordinate system.

Args:

• src_crs - instance of CRS that represents the coordinate

  system of x, y and z.

• x - the x coordinates (array), in src_crs coordinates,

  to transform. May be 1 or 2 dimensional.

• y - the y coordinates (array), in src_crs coordinates,

  to transform

• z - (optional) the z coordinates (array), in src_crs

  coordinates, to transform.

Returns:

Array of shape x.shape + (3, ) in this coordinate system.

The Globe class is used to encapsulate the underlying sphere or ellipsoid of any cartopy CRS. All CRSs have an associated Globe, though often it is just the default Globe which represents the reference ellipsoid (i.e. “wgs84”).

class cartopy.crs.Globe(datum=None, ellipse='WGS84', semimajor_axis=None, semiminor_axis=None, flattening=None, inverse_flattening=None, towgs84=None)

Defines an ellipsoid and, optionally, how to relate it to the real world.

Keywords:

• datum - Proj4 “datum” definiton. Default to no datum.
• ellipse - Proj4 “ellps” definiton. Default to ‘WGS84’.
• semimajor_axis - Semimajor axis of the spheroid / ellipsoid.
• semiminor_axis - Semiminor axis of the ellipsoid.
• flattening - Flattening of the ellipsoid.
• inverse_flattening - Inverse flattening of the ellipsoid.
• towgs84 - Passed through to the Proj4 definition.
• nadgrids - Passed through to the Proj4 definition.

The most common CRS subclass is itself another abstract class; the cartopy.crs.Projection class represents a 2 dimensional coordinate system which could be drawn directly as a map (i.e. on a flat piece of paper). Projection is the parent class of all projections in the Cartopy projection list.

class cartopy.crs.Projection

Defines a projected coordinate system with flat topology and Euclidean distance.

Parameters :

proj4_params : iterable of key-value pairs

The proj4 parameters required to define the desired CRS. The parameters should not describe the desired elliptic model, instead create an appropriate Globe instance. The proj4_params parameters will override any parameters that the Globe defines.

globe : Globe instance, optional

If omitted, the default Globe instance will be created. See Globe for details.

project_geometry(geometry, src_crs=None)

Projects the given geometry into this projection.

Parameters:

• geometry – The geometry to (re-)project.
• src_crs – The source CRS, or geodetic CRS if None.

Return type:

Shapely geometry.

If src_crs is None, the source CRS is assumed to be a geodetic version of the target CRS.

quick_vertices_transform(vertices, src_crs)

Where possible, return a vertices array transformed to this CRS from the given vertices array of shape (n, 2) and the source CRS.

Important

This method may return None to indicate that the vertices cannot be transformed quickly, and a more complex geometry transformation is required (see cartopy.crs.Projection.project_geometry()).

There are a few non-Projection subclasses. These represent coordinate reference systems which are 3 dimensional and could not be drawn directly on a piece of paper.

class cartopy.crs.Geodetic(globe=None)

Defines a latitude/longitude coordinate system with spherical topology, geographical distance and coordinates are measured in degrees.

Kwargs:

• globe - A cartopy.crs.Globe.

  Defaults to a “WGS84” datum.

class cartopy.crs.Geocentric(globe=None)

Defines a Geocentric coordinate system, where x, y, z are Cartesian coordinates from the center of the Earth.

Kwargs:

• globe - A cartopy.crs.Globe.

  Defaults to a “WGS84” datum.

class cartopy.crs.RotatedGeodetic(pole_longitude, pole_latitude, globe=None)

Defines a rotated latitude/longitude coordinate system with spherical topology and geographical distance.

Coordinates are measured in degrees.

Create a RotatedGeodetic CRS.

Args:

• pole_longitude - Pole longitude position, in unrotated degrees.
• pole_latitude - Pole latitude position, in unrotated degrees.

Kwargs:

• globe - An optional cartopy.crs.Globe.

  Defaults to a “WGS84” datum.