0
# Cartopy
1

2
A comprehensive Python library for cartographic visualizations with Matplotlib. Cartopy provides object-oriented projection definitions, coordinate transformations, and seamless integration with Matplotlib for advanced mapping capabilities through an intuitive interface.
3

4
## Package Information
5

6
- **Package Name**: cartopy
7
- **Language**: Python
8
- **Installation**: `pip install cartopy`
9
- **Version Access**: `import cartopy; print(cartopy.__version__)`
10

11
## Core Imports
12

13
```python
14
import cartopy
15
```
16

17
Common imports for working with projections and features:
18

19
```python
20
import cartopy.crs as ccrs
21
import cartopy.feature as cfeature
22
```
23

24
For matplotlib integration:
25

26
```python
27
import matplotlib.pyplot as plt
28
# GeoAxes are created via projection parameter
29
```
30

31
## Basic Usage
32

33
```python
34
import matplotlib.pyplot as plt
35
import cartopy.crs as ccrs
36
import cartopy.feature as cfeature
37

38
# Create a figure with a GeoAxes subplot using PlateCarree projection
39
fig = plt.figure(figsize=(12, 8))
40
ax = plt.axes(projection=ccrs.PlateCarree())
41

42
# Add map features
43
ax.add_feature(cfeature.LAND)
44
ax.add_feature(cfeature.OCEAN)
45
ax.add_feature(cfeature.COASTLINE)
46
ax.add_feature(cfeature.BORDERS, linestyle=':')
47

48
# Set global extent
49
ax.set_global()
50

51
# Add gridlines
52
ax.gridlines(draw_labels=True)
53

54
plt.title('Basic World Map')
55
plt.show()
56
```
57

58
## Architecture
59

60
Cartopy's design is built around several key components:
61

62
- **Coordinate Reference Systems (CRS)**: Define map projections and coordinate transformations
63
- **Features**: Geographic data sources for map elements (coastlines, borders, etc.)
64
- **Matplotlib Integration**: GeoAxes extends matplotlib with cartographic projection support
65
- **IO System**: Handles data retrieval from various sources (Natural Earth, GSHHS, web services)
66

67
This architecture enables cartopy to serve as the primary cartographic library for Python scientific computing, providing robust support for geospatial data visualization, meteorological applications, and scientific mapping workflows.
68

69
## Capabilities
70

71
### Coordinate Reference Systems
72

73
Complete collection of map projections including cylindrical, conic, azimuthal, and pseudocylindrical projections. Provides coordinate transformations between different reference systems and supports custom projections.
74

75
```python { .api }
76
class CRS:
77
    def transform_point(self, x, y, src_crs): ...
78
    def transform_points(self, src_crs, x, y, z=None): ...
79

80
class PlateCarree(CRS): ...
81
class Mercator(CRS): ...
82
class LambertConformal(CRS): ...
83
class Orthographic(CRS): ...
84
class Stereographic(CRS): ...
85
```
86

87
[Coordinate Reference Systems](./coordinate-systems.md)
88

89
### Geographic Features
90

91
Ready-to-use geographic features from Natural Earth and GSHHS datasets. Includes coastlines, country borders, land/ocean polygons, rivers, and lakes with automatic scaling based on map extent.
92

93
```python { .api }
94
class Feature:
95
    def geometries(self): ...
96
    def intersecting_geometries(self, extent): ...
97

98
class NaturalEarthFeature(Feature): ...
99
class GSHHSFeature(Feature): ...
100
class ShapelyFeature(Feature): ...
101

102
# Pre-defined features
103
LAND: NaturalEarthFeature
104
OCEAN: NaturalEarthFeature  
105
COASTLINE: NaturalEarthFeature
106
BORDERS: NaturalEarthFeature
107
```
108

109
[Geographic Features](./geographic-features.md)
110

111
### Data Input/Output
112

113
Access to various geospatial data sources including web tile services, elevation data, and shapefile readers. Supports caching and automatic data downloading.
114

115
```python { .api }
116
class Downloader:
117
    def path(self, format_dict): ...
118
    def acquire_resource(self, target_path, format_dict): ...
119

120
def natural_earth(resolution='110m', category='physical', name='coastline'): ...
121
def gshhs(scale='c', level=1): ...
122

123
class OSM: ...
124
class GoogleTiles: ...
125
class SRTM3Source: ...
126
```
127

128
[Data Input/Output](./data-io.md)
129

130
### Matplotlib Integration
131

132
Enhanced matplotlib axes with cartographic projection support. Provides specialized plotting functions, coordinate transformations, and gridline management for geographic data visualization.
133

134
```python { .api }  
135
class GeoAxes:
136
    def set_global(self): ...
137
    def set_extent(self, extents, crs=None): ...
138
    def add_feature(self, feature, **kwargs): ...
139
    def coastlines(self, resolution=None, **kwargs): ...
140
    def gridlines(self, **kwargs): ...
141
    def stock_img(self): ...
142

143
class Gridliner:
144
    def xlabel_style: dict
145
    def ylabel_style: dict
146
```
147

148
[Matplotlib Integration](./matplotlib-integration.md)
149

150
### Image and Vector Transformations
151

152
Functions for transforming raster images and vector data between different coordinate systems. Includes regridding, warping, and mesh generation capabilities.
153

154
```python { .api }
155
def warp_array(array, target_proj, source_proj=None, target_res=(400, 200), **kwargs): ...
156
def warp_img(fname, target_proj, source_proj=None, target_res=(400, 200)): ...
157
def vector_scalar_to_grid(src_crs, target_proj, regrid_shape, x, y, u, v, *scalars, **kwargs): ...
158
def add_cyclic_point(data, coord=None, axis=-1): ...
159
```
160

161
[Transformations](./transformations.md)
162

163
### Geodesic Calculations
164

165
Great circle computations, distance calculations, and geodesic operations on ellipsoidal Earth models. Essential for navigation, surveying, and geographic analysis.
166

167
```python { .api }
168
class Geodesic:
169
    def __init__(self, radius=6378137.0, flattening=1/298.257223563): ...
170
    def direct(self, points, azimuths, distances): ...
171
    def inverse(self, points, endpoints): ...
172
    def circle(self, lon, lat, radius, n_samples=180): ...
173
    def geometry_length(self, geometry): ...
174
```
175

176
[Geodesic Calculations](./geodesic.md)
177

178
## Configuration
179

180
```python { .api }
181
config: dict  # Global configuration dictionary with keys:
182
# - 'data_dir': Directory for downloaded data
183
# - 'cache_dir': Directory for cached tiles  
184
# - 'pre_existing_data_dir': Directory for existing data
185
# - 'downloaders': Dictionary of data downloaders
186
```
187

188
## Types
189

190
```python { .api }
191
from typing import Tuple, Optional, Union, List
192
import numpy as np
193
from shapely.geometry import Polygon, MultiPolygon
194

195
Extent = Tuple[float, float, float, float]  # (x0, x1, y0, y1)
196
Resolution = Tuple[int, int]  # (width, height)
197
ArrayLike = Union[np.ndarray, List]
198
GeometryLike = Union[Polygon, MultiPolygon]
199
```