0
# Image Generation
1

2
Create elevation maps and visualizations as PIL images or numpy arrays with customizable color schemes, elevation ranges, and geographic bounds.
3

4
## Capabilities
5

6
### Elevation Image Generation
7

8
Generate visual representations of elevation data as images or arrays with customizable parameters for geographic bounds, resolution, and color schemes.
9

10
```python { .api }
11
class GeoElevationData:
12
    def get_image(
13
        self,
14
        size: Tuple[int, int],
15
        latitude_interval: Tuple[float, float],
16
        longitude_interval: Tuple[float, float],
17
        max_elevation: float,
18
        min_elevation: float = 0,
19
        unknown_color: Color = Color(255, 255, 255, 255),
20
        zero_color: Color = Color(0, 0, 255, 255),
21
        min_color: Color = Color(0, 0, 0, 255),
22
        max_color: Color = Color(0, 255, 0, 255),
23
        mode: str = 'image'
24
    ) -> Any: ...
25
```
26

27
**Parameters:**
28
- `size`: Tuple of (width, height) in pixels for the output image
29
- `latitude_interval`: Tuple of (min_latitude, max_latitude) defining the geographic bounds
30
- `longitude_interval`: Tuple of (min_longitude, max_longitude) defining the geographic bounds
31
- `max_elevation`: Maximum elevation value for color mapping (in meters)
32
- `min_elevation`: Minimum elevation value for color mapping (in meters). Default: 0
33
- `unknown_color`: Color for unknown/missing elevation data. Default: white
34
- `zero_color`: Color for zero elevation (sea level). Default: blue
35
- `min_color`: Color for minimum elevation values. Default: black
36
- `max_color`: Color for maximum elevation values. Default: green
37
- `mode`: Output format - 'image' for PIL Image object, 'array' for numpy array. Default: 'image'
38

39
**Returns:** PIL Image object (mode='image') or numpy array (mode='array')
40

41
**Usage Example:**
42
```python
43
import srtm
44

45
elevation_data = srtm.get_data()
46

47
# Generate elevation image for Alpine region
48
image = elevation_data.get_image(
49
    size=(800, 600),              # 800x600 pixel image
50
    latitude_interval=(45.5, 46.5),   # 1 degree latitude range
51
    longitude_interval=(7.0, 8.0),    # 1 degree longitude range  
52
    max_elevation=4000,           # Scale colors up to 4000m
53
    min_elevation=500             # Scale colors from 500m
54
)
55

56
# Save as PNG
57
image.save('alpine_elevation.png')
58

59
# Display image properties
60
print(f"Image size: {image.size}")
61
print(f"Image mode: {image.mode}")
62
```
63

64
### Custom Color Schemes
65

66
Define custom color mappings for different elevation ranges to create visually appealing and informative elevation maps.
67

68
**Usage Example:**
69
```python
70
import srtm
71
from srtm.utils import Color
72

73
elevation_data = srtm.get_data()
74

75
# Define custom colors for different elevation zones
76
image = elevation_data.get_image(
77
    size=(1000, 800),
78
    latitude_interval=(44.0, 46.0),
79
    longitude_interval=(6.0, 9.0),
80
    max_elevation=3000,
81
    min_elevation=200,
82
    # Custom color scheme
83
    unknown_color=Color(red=255, green=255, blue=255, alpha=255),  # White for unknown
84
    zero_color=Color(red=70, green=130, blue=180, alpha=255),      # Steel blue for sea level
85
    min_color=Color(red=34, green=139, blue=34, alpha=255),       # Forest green for min elevation
86
    max_color=Color(red=139, green=69, blue=19, alpha=255)        # Saddle brown for max elevation
87
)
88

89
image.save('custom_colors_elevation.png')
90
```
91

92
### Numpy Array Output
93

94
Generate elevation data as numpy arrays for scientific analysis and custom processing.
95

96
**Usage Example:**
97
```python
98
import srtm
99
import numpy as np
100
import matplotlib.pyplot as plt
101

102
elevation_data = srtm.get_data()
103

104
# Generate elevation array
105
elevation_array = elevation_data.get_image(
106
    size=(400, 300),
107
    latitude_interval=(45.0, 46.0),
108
    longitude_interval=(7.0, 8.0),
109
    max_elevation=2500,
110
    mode='array'  # Return numpy array instead of PIL image
111
)
112

113
print(f"Array shape: {elevation_array.shape}")
114
print(f"Elevation range: {elevation_array.min():.1f}m to {elevation_array.max():.1f}m")
115

116
# Create custom visualization with matplotlib
117
plt.figure(figsize=(12, 8))
118
plt.imshow(elevation_array, cmap='terrain', origin='lower')
119
plt.colorbar(label='Elevation (m)')
120
plt.title('Elevation Map - Custom Processing')
121
plt.xlabel('Longitude Index')
122
plt.ylabel('Latitude Index')
123
plt.show()
124

125
# Statistical analysis
126
mean_elevation = np.mean(elevation_array)
127
std_elevation = np.std(elevation_array)
128
print(f"Mean elevation: {mean_elevation:.1f}m")
129
print(f"Standard deviation: {std_elevation:.1f}m")
130
```
131

132
### High-Resolution Elevation Maps
133

134
Create detailed elevation maps for specific regions with high pixel density.
135

136
**Usage Example:**
137
```python
138
import srtm
139

140
elevation_data = srtm.get_data(
141
    srtm1=True,  # Use higher resolution SRTM1 data where available
142
    srtm3=True
143
)
144

145
# Generate high-resolution image of mountain peak area
146
high_res_image = elevation_data.get_image(
147
    size=(2000, 2000),           # High resolution 2000x2000
148
    latitude_interval=(45.95, 46.05),  # Small area (0.1 degrees)
149
    longitude_interval=(7.85, 7.95),   # Small area (0.1 degrees)
150
    max_elevation=4500,
151
    min_elevation=1500
152
)
153

154
# Save high-quality image
155
high_res_image.save('mountain_peak_hd.png', 'PNG', quality=95)
156
print(f"Generated {high_res_image.size[0]}x{high_res_image.size[1]} elevation map")
157
```
158

159
### Batch Image Generation
160

161
Generate multiple elevation images for different regions or zoom levels efficiently.
162

163
**Usage Example:**
164
```python
165
import srtm
166
import os
167

168
elevation_data = srtm.get_data(batch_mode=True)  # Memory efficient
169

170
# Define regions of interest
171
regions = [
172
    {'name': 'Alps_North', 'lat': (46.0, 47.0), 'lon': (7.0, 8.0)},
173
    {'name': 'Alps_Central', 'lat': (45.5, 46.5), 'lon': (7.5, 8.5)},
174
    {'name': 'Alps_South', 'lat': (45.0, 46.0), 'lon': (8.0, 9.0)},
175
]
176

177
output_dir = 'elevation_maps'
178
os.makedirs(output_dir, exist_ok=True)
179

180
for region in regions:
181
    print(f"Generating image for {region['name']}...")
182
    
183
    image = elevation_data.get_image(
184
        size=(800, 600),
185
        latitude_interval=region['lat'],
186
        longitude_interval=region['lon'],
187
        max_elevation=4000,
188
        min_elevation=500
189
    )
190
    
191
    filename = os.path.join(output_dir, f"{region['name']}_elevation.png")
192
    image.save(filename)
193
    print(f"Saved {filename}")
194

195
print(f"Generated {len(regions)} elevation maps in {output_dir}/")
196
```
197

198
### Comparative Elevation Analysis
199

200
Generate multiple images with different parameters to compare elevation representations.
201

202
**Usage Example:**
203
```python
204
import srtm
205

206
elevation_data = srtm.get_data()
207

208
# Same region with different elevation scaling
209
region_bounds = {
210
    'size': (600, 400),
211
    'latitude_interval': (45.2, 45.8),
212
    'longitude_interval': (7.2, 7.8)
213
}
214

215
# Full elevation range
216
full_range = elevation_data.get_image(
217
    **region_bounds,
218
    max_elevation=4000,
219
    min_elevation=0
220
)
221
full_range.save('elevation_full_range.png')
222

223
# Mid-elevation focus  
224
mid_elevation = elevation_data.get_image(
225
    **region_bounds,
226
    max_elevation=2500,
227
    min_elevation=1000
228
)
229
mid_elevation.save('elevation_mid_range.png')
230

231
# High elevation focus
232
high_elevation = elevation_data.get_image(
233
    **region_bounds,
234
    max_elevation=4000,
235
    min_elevation=2000
236
)
237
high_elevation.save('elevation_high_range.png')
238

239
print("Generated comparative elevation maps:")
240
print("- elevation_full_range.png (0-4000m)")
241
print("- elevation_mid_range.png (1000-2500m)") 
242
print("- elevation_high_range.png (2000-4000m)")
243
```
244

245
## Color Specification
246

247
Colors can be specified using the Color namedtuple or as keyword arguments:
248

249
```python { .api }
250
from collections import namedtuple
251
Color = namedtuple('Color', ['red', 'green', 'blue', 'alpha'])
252
```
253

254
**Color Parameters:**
255
- `red`: Red component (0-255)
256
- `green`: Green component (0-255)
257
- `blue`: Blue component (0-255)
258
- `alpha`: Alpha/transparency component (0-255)
259

260
**Usage Example:**
261
```python
262
from srtm.utils import Color
263

264
# Define colors as namedtuples
265
water_color = Color(red=65, green=105, blue=225, alpha=255)  # Royal blue
266
land_color = Color(red=34, green=139, blue=34, alpha=255)   # Forest green
267

268
# Use in image generation
269
image = elevation_data.get_image(
270
    size=(400, 300),
271
    latitude_interval=(45.0, 46.0), 
272
    longitude_interval=(7.0, 8.0),
273
    max_elevation=2000,
274
    zero_color=water_color,  # Use for sea level
275
    min_color=land_color     # Use for minimum elevation
276
)
277
```
278

279
## Output Formats
280

281
### PIL Image Output (Default)
282
- Returns PIL Image object
283
- Supports standard image operations (save, resize, rotate, etc.)
284
- Compatible with image processing libraries
285
- Easy conversion to different formats (PNG, JPEG, TIFF, etc.)
286

287
### Numpy Array Output  
288
- Returns numpy array with elevation values
289
- Enables scientific computing and analysis
290
- Compatible with matplotlib, scipy, scikit-image
291
- Allows custom visualization and processing algorithms
292

293
## Performance and Memory Considerations
294

295
- **Large Images**: High-resolution images require significant memory
296
- **Geographic Bounds**: Larger areas require more SRTM file downloads
297
- **Batch Mode**: Use `batch_mode=True` for generating multiple images
298
- **Caching**: SRTM files are cached locally to speed up subsequent operations
299
- **Memory Management**: Arrays are more memory-efficient than images for large datasets