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)¶ Define a Coordinate Reference System using proj.
 Parameters
proj4_params (iterable of keyvalue 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. SeeGlobe
for details.

as_geocentric
(self)¶ Return a new Geocentric CRS with the same ellipse/datum as this CRS.

as_geodetic
(self)¶ Return a new Geodetic CRS with the same ellipse/datum as this CRS.

is_geodetic
(self)¶

transform_point
(self, double x, double y, CRS src_crs, trap=True)¶ transform_point(x, y, src_crs)
Transform the given float64 coordinate pair, in the given source coordinate system (
src_crs
), to this coordinate system. Parameters
x – the x coordinate, in
src_crs
coordinates, to transformy – the y coordinate, in
src_crs
coordinates, to transformsrc_crs – instance of
CRS
that represents the coordinate system ofx
andy
.trap – Whether proj errors for “latitude or longitude exceeded limits” and “tolerance condition error” should be trapped.
 Returns
(x, y) in this coordinate system

transform_points
(self, CRS src_crs, ndarray x, ndarray y, ndarray z=None)¶ transform_points(src_crs, x, y[, z])
Transform the given coordinates, in the given source coordinate system (
src_crs
), to this coordinate system. Parameters
src_crs – instance of
CRS
that represents the coordinate system ofx
,y
andz
.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. Its shape must match that of x.z (optional) – the z coordinates (array), in
src_crs
coordinates, to transform. Defaults to None. If supplied, its shape must match that of x.
 Returns
Array of shape
x.shape + (3, )
in this coordinate system.

transform_vectors
(self, src_proj, x, y, u, v)¶ transform_vectors(src_proj, x, y, u, v)
Transform the given vector components, with coordinates in the given source coordinate system (
src_proj
), to this coordinate system. The vector components must be given relative to the source projection’s coordinate reference system (grid eastward and grid northward). Parameters
src_proj – The
CRS.Projection
that represents the coordinate system the vectors are defined in.x – The x coordinates of the vectors in the source projection.
y – The y coordinates of the vectors in the source projection.
u – The grideastward components of the vectors.
v – The gridnorthward components of the vectors.
Note
x, y, u and v may be 1 or 2 dimensional, but must all have matching shapes.
 Returns
ut, vt (The transformed vector components.)
Note
The algorithm used to transform vectors is an approximation rather than an exact transform, but the accuracy should be good enough for visualization purposes.
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
(self, datum=None, ellipse='WGS84', semimajor_axis=None, semiminor_axis=None, flattening=None, inverse_flattening=None, towgs84=None, nadgrids=None)¶ Define an ellipsoid and, optionally, how to relate it to the real world.
 Parameters
datum – Proj “datum” definition. Defaults to None.
ellipse – Proj “ellps” definition. Defaults to ‘WGS84’.
semimajor_axis – Semimajor axis of the spheroid / ellipsoid. Defaults to None.
semiminor_axis – Semiminor axis of the ellipsoid. Defaults to None.
flattening – Flattening of the ellipsoid. Defaults to None.
inverse_flattening – Inverse flattening of the ellipsoid. Defaults to None.
towgs84 – Passed through to the Proj definition. Defaults to None.
nadgrids – Passed through to the Proj definition. Defaults to None.
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
[source]¶ Define a projected coordinate system with flat topology and Euclidean distance.
 Parameters
proj4_params (iterable of keyvalue 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. SeeGlobe
for details.

project_geometry
(geometry, src_crs=None)[source]¶ Project the given geometry into this projection.
 Parameters
geometry – The geometry to (re)project.
src_crs (optional) –
The source CRS. Defaults to None.
If src_crs is None, the source CRS is assumed to be a geodetic version of the target CRS.
 Returns
geometry – The projected result (a shapely geometry).

quick_vertices_transform
(vertices, src_crs)[source]¶ Where possible, return a vertices array transformed to this CRS from the given vertices array of shape
(n, 2)
and the source CRS.Note
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 nonProjection
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
(self, globe=None)¶ Define a latitude/longitude coordinate system with spherical topology, geographical distance and coordinates are measured in degrees.
 Parameters
globe (A
cartopy.crs.Globe
, optional) – Defaults to a “WGS84” datum.

class
cartopy.crs.
Geocentric
(self, globe=None)¶ Define a Geocentric coordinate system, where x, y, z are Cartesian coordinates from the center of the Earth.
 Parameters
globe (A
cartopy.crs.Globe
, optional) – Defaults to a “WGS84” datum.

class
cartopy.crs.
RotatedGeodetic
(pole_longitude, pole_latitude, central_rotated_longitude=0.0, globe=None)[source]¶ Define a rotated latitude/longitude coordinate system with spherical topology and geographical distance.
Coordinates are measured in degrees.
The class uses proj to perform an ob_tran operation, using the pole_longitude to set a lon_0 then performing two rotations based on pole_latitude and central_rotated_longitude. This is equivalent to setting the new pole to a location defined by the pole_latitude and pole_longitude values in the GeogCRS defined by globe, then rotating this new CRS about it’s pole using the central_rotated_longitude value.
 Parameters
pole_longitude – Pole longitude position, in unrotated degrees.
pole_latitude – Pole latitude position, in unrotated degrees.
central_rotated_longitude (optional) – Longitude rotation about the new pole, in degrees. Defaults to 0.
globe (optional) – A
cartopy.crs.Globe
. Defaults to a “WGS84” datum.
There is also a function for calling epsg.io with a specified code, returning the corresponding cartopy projection, see below.

cartopy.crs.
epsg
(code)[source]¶ Return the projection which corresponds to the given EPSG code.
The EPSG code must correspond to a “projected coordinate system”, so EPSG codes such as 4326 (WGS84) which define a “geodetic coordinate system” will not work.
Note
The conversion is performed by querying https://epsg.io/ so a live internet connection is required.