0
# Geographic Features
1

2
Ready-to-use geographic features from various data sources including Natural Earth and GSHHS datasets. Features provide automatic scaling, caching, and seamless integration with matplotlib plotting.
3

4
## Capabilities
5

6
### Base Feature Classes
7

8
Abstract base classes that define the feature interface for all geographic data sources.
9

10
```python { .api }
11
class Feature:
12
    """Base class for all geographic features."""
13
    def __init__(self, crs, **kwargs): ...
14
    @property
15
    def crs(self): ...
16
    @property  
17
    def kwargs(self): ...
18
    def geometries(self): ...
19
    def intersecting_geometries(self, extent): ...
20

21
class Scaler:
22
    """Handle geometry scaling based on map extent."""
23
    def __init__(self, scale): ...
24
    @property
25
    def scale(self): ...
26
    def scale_from_extent(self, extent): ...
27

28
class AdaptiveScaler(Scaler):
29
    """Automatically select scale based on map extent."""
30
    def __init__(self, default_scale, limits): ...
31
    def scale_from_extent(self, extent): ...
32
```
33

34
### Natural Earth Features
35

36
Access to Natural Earth datasets with automatic scaling and data management.
37

38
```python { .api }
39
class NaturalEarthFeature(Feature):
40
    """Interface to Natural Earth shapefiles."""
41
    def __init__(self, category, name, scale, **kwargs): ...
42
    @property
43
    def scale(self): ...
44
    def geometries(self): ...
45
    def intersecting_geometries(self, extent): ...
46
    def with_scale(self, new_scale): ...
47

48
# Pre-defined Natural Earth features
49
BORDERS: NaturalEarthFeature  # Country boundaries
50
STATES: NaturalEarthFeature   # State/province boundaries  
51
COASTLINE: NaturalEarthFeature  # Coastlines and major islands
52
LAKES: NaturalEarthFeature    # Natural and artificial lakes
53
LAND: NaturalEarthFeature     # Land polygons
54
OCEAN: NaturalEarthFeature    # Ocean polygons
55
RIVERS: NaturalEarthFeature   # Rivers and lake centerlines
56

57
auto_scaler: AdaptiveScaler   # Default adaptive scaler
58
```
59

60
### GSHHS Features
61

62
Access to Global Self-consistent Hierarchical High-resolution Shoreline database.
63

64
```python { .api }
65
class GSHHSFeature(Feature):
66
    """Interface to GSHHS coastline dataset."""
67
    def __init__(self, scale='auto', levels=None, **kwargs): ...
68
    def geometries(self): ...
69
    def intersecting_geometries(self, extent): ...
70
```
71

72
### Custom Features
73

74
Create features from user-provided geometric data.
75

76
```python { .api }
77
class ShapelyFeature(Feature):
78
    """Feature from collection of shapely geometries."""
79
    def __init__(self, geometries, crs, **kwargs): ...
80
    def geometries(self): ...
81
```
82

83
### Web Feature Service
84

85
Access features from OGC Web Feature Services.
86

87
```python { .api }
88
class WFSFeature(Feature):
89
    """Feature collection from OGC Web Feature Service."""
90
    def __init__(self, wfs, features, **kwargs): ...
91
    def geometries(self): ...
92
    def intersecting_geometries(self, extent): ...
93
```
94

95
### Nightshade Feature
96

97
Day/night terminator visualization.
98

99
```python { .api }
100
class Nightshade(Feature):
101
    """Day/night terminator feature."""
102
    def __init__(self, date=None, delta=0.1, refraction=-0.83, 
103
                 color='k', alpha=0.5, **kwargs): ...
104
    def geometries(self): ...
105
```
106

107
## Usage Examples
108

109
### Using Pre-defined Features
110

111
```python
112
import matplotlib.pyplot as plt
113
import cartopy.crs as ccrs
114
import cartopy.feature as cfeature
115

116
# Create map with pre-defined features
117
fig = plt.figure(figsize=(12, 8))
118
ax = plt.axes(projection=ccrs.PlateCarree())
119

120
# Add various features
121
ax.add_feature(cfeature.LAND, color='lightgray')
122
ax.add_feature(cfeature.OCEAN, color='lightblue')
123
ax.add_feature(cfeature.COASTLINE, linewidth=0.5)
124
ax.add_feature(cfeature.BORDERS, linestyle=':', linewidth=0.5)
125
ax.add_feature(cfeature.RIVERS, color='blue', linewidth=0.5)
126
ax.add_feature(cfeature.LAKES, color='blue', alpha=0.7)
127

128
ax.set_global()
129
plt.show()
130
```
131

132
### Creating Custom Features
133

134
```python
135
import cartopy.crs as ccrs
136
import cartopy.feature as cfeature
137
from shapely.geometry import Polygon
138

139
# Create custom feature from shapely geometries
140
# Example: highlight specific regions
141
custom_regions = [
142
    Polygon([(-74, 40.5), (-74, 41), (-73.5, 41), (-73.5, 40.5)]),  # NYC area
143
    Polygon([(-118.5, 33.5), (-118.5, 34.5), (-117.5, 34.5), (-117.5, 33.5)])  # LA area
144
]
145

146
custom_feature = cfeature.ShapelyFeature(
147
    custom_regions, 
148
    ccrs.PlateCarree(),
149
    facecolor='red',
150
    alpha=0.5,
151
    edgecolor='darkred'
152
)
153

154
# Use in plot
155
fig = plt.figure(figsize=(12, 8))
156
ax = plt.axes(projection=ccrs.PlateCarree())
157
ax.add_feature(cfeature.LAND)
158
ax.add_feature(cfeature.OCEAN)
159
ax.add_feature(custom_feature)
160
ax.set_extent([-125, -65, 25, 50])  # Continental US
161
```
162

163
### Natural Earth Feature Customization
164

165
```python
166
import cartopy.feature as cfeature
167

168
# Create custom Natural Earth feature
169
rivers_50m = cfeature.NaturalEarthFeature(
170
    'physical', 'rivers_lake_centerlines', '50m',
171
    edgecolor='blue', facecolor='none', linewidth=1.0
172
)
173

174
# Use specific scale
175
land_10m = cfeature.LAND.with_scale('10m')
176

177
# Custom scaler for different zoom levels
178
from cartopy.feature import AdaptiveScaler
179
custom_scaler = AdaptiveScaler('110m', (('50m', 30), ('10m', 10)))
180
coastline_adaptive = cfeature.NaturalEarthFeature(
181
    'physical', 'coastline', custom_scaler,
182
    edgecolor='black', facecolor='none'
183
)
184
```
185

186
### GSHHS Features
187

188
```python
189
import cartopy.feature as cfeature
190

191
# Different GSHHS scales and levels
192
coastline_auto = cfeature.GSHHSFeature(scale='auto', levels=[1])
193
coastline_high = cfeature.GSHHSFeature(scale='high', levels=[1, 2])
194

195
# Use in high-resolution coastal maps
196
fig = plt.figure(figsize=(12, 8))
197
ax = plt.axes(projection=ccrs.PlateCarree())
198
ax.add_feature(coastline_high)
199
ax.set_extent([-10, 5, 45, 60])  # Western Europe coast
200
```
201

202
### Nightshade Feature
203

204
```python
205
from datetime import datetime
206
from cartopy.feature.nightshade import Nightshade
207

208
# Add day/night terminator for specific date
209
date = datetime(2023, 6, 21, 12, 0)  # Summer solstice, noon UTC
210
night_shade = Nightshade(date, alpha=0.25)
211

212
fig = plt.figure(figsize=(12, 8))
213
ax = plt.axes(projection=ccrs.PlateCarree())
214
ax.add_feature(cfeature.LAND)
215
ax.add_feature(cfeature.OCEAN)
216
ax.add_feature(night_shade)
217
ax.set_global()
218
```
219

220
## Constants and Color Schemes
221

222
```python { .api }
223
COLORS: dict = {
224
    'land': np.array((240, 240, 220)) / 256.,
225
    'land_alt1': np.array((220, 220, 220)) / 256., 
226
    'water': np.array((152, 183, 226)) / 256.
227
}
228
```