0
# SRTM.py
1

2
A comprehensive Python library for parsing and working with Shuttle Radar Topography Mission (SRTM) elevation data. It enables developers to retrieve elevation information for specific coordinates, process GPS tracks by adding elevation data, and generate elevation images for geographic regions.
3

4
## Package Information
5

6
- **Package Name**: SRTM.py
7
- **Language**: Python
8
- **Installation**: `pip install SRTM.py`
9

10
## Core Imports
11

12
```python
13
import srtm
14
```
15

16
## Basic Usage
17

18
```python
19
import srtm
20

21
# Create elevation data object
22
elevation_data = srtm.get_data()
23

24
# Get elevation for specific coordinates (latitude, longitude)
25
elevation = elevation_data.get_elevation(50.8682, 7.1377)
26
print(f"Elevation: {elevation} meters")
27

28
# Get elevation with approximation for better accuracy
29
elevation_approx = elevation_data.get_elevation(50.8682, 7.1377, approximate=True)
30
print(f"Approximate elevation: {elevation_approx} meters")
31
```
32

33
## Architecture
34

35
SRTM.py uses a modular architecture for efficient elevation data management:
36

37
- **Data Factory**: The `get_data()` function creates configured elevation data objects
38
- **Automatic Caching**: SRTM files are automatically downloaded and cached locally for reuse
39
- **Multi-Resolution Support**: Supports both SRTM1 (30m resolution, US only) and SRTM3 (90m resolution, global)
40
- **Memory Management**: Batch mode available for processing large datasets efficiently
41
- **Interpolation Engine**: Advanced algorithms for accurate elevation estimation between data points
42

43
## Capabilities
44

45
### Elevation Queries
46

47
Core functionality for retrieving elevation data at specific coordinates with support for both SRTM1 and SRTM3 data sources, automatic file downloading, and interpolation options.
48

49
```python { .api }
50
def get_data(
51
    srtm1: bool = True,
52
    srtm3: bool = True, 
53
    leave_zipped: bool = False,
54
    file_handler: Optional[FileHandler] = None,
55
    use_included_urls: bool = True,
56
    batch_mode: bool = False,
57
    local_cache_dir: str = "",
58
    timeout: int = 0
59
) -> GeoElevationData
60
```
61

62
```python { .api }
63
class GeoElevationData:
64
    def get_elevation(self, latitude: float, longitude: float, approximate: bool = False) -> Optional[float]: ...
65
    def get_file(self, latitude: float, longitude: float) -> Optional[GeoElevationFile]: ...
66
    def get_file_name(self, latitude: float, longitude: float) -> Optional[str]: ...
67
```
68

69
[Elevation Queries](./elevation-queries.md)
70

71
### GPX Track Processing
72

73
Integration with GPX files to add elevation data to GPS tracks, with options for smoothing, interpolation, and batch processing of multiple tracks.
74

75
```python { .api }
76
class GeoElevationData:
77
    def add_elevations(
78
        self, 
79
        gpx, 
80
        only_missing: bool = False, 
81
        smooth: bool = False, 
82
        gpx_smooth_no: int = 0
83
    ) -> None: ...
84
```
85

86
[GPX Processing](./gpx-processing.md)
87

88
### Image Generation
89

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

92
```python { .api }
93
class GeoElevationData:
94
    def get_image(
95
        self,
96
        size: Tuple[int, int],
97
        latitude_interval: Tuple[float, float],
98
        longitude_interval: Tuple[float, float],
99
        max_elevation: float,
100
        min_elevation: float = 0,
101
        unknown_color: Color = Color(255, 255, 255, 255),
102
        zero_color: Color = Color(0, 0, 255, 255),
103
        min_color: Color = Color(0, 0, 0, 255),
104
        max_color: Color = Color(0, 255, 0, 255),
105
        mode: str = 'image'
106
    ) -> Any: ...
107
```
108

109
[Image Generation](./image-generation.md)
110

111
### Data Management
112

113
File handling, caching, and configuration options for managing SRTM data files including custom cache directories, batch processing modes, and network settings.
114

115
```python { .api }
116
class FileHandler:
117
    def __init__(self, local_cache_dir: Optional[str] = None): ...
118
    def exists(self, file_name: str) -> bool: ...
119
    def write(self, file_name: str, contents: bytes) -> None: ...
120
    def read(self, file_name: str) -> bytes: ...
121
```
122

123
[Data Management](./data-management.md)
124

125
### Advanced Interpolation
126

127
Sophisticated algorithms for elevation estimation including Inverse Distance Weighted (IDW) interpolation and approximation methods for improved accuracy between data points.
128

129
```python { .api }
130
class GeoElevationData:
131
    def _IDW(self, latitude: float, longitude: float, radius: float = 1) -> Optional[float]: ...
132

133
class GeoElevationFile:
134
    def approximation(self, latitude: float, longitude: float) -> Optional[float]: ...
135
    def _InverseDistanceWeighted(self, latitude: float, longitude: float, radius: float = 1) -> Optional[float]: ...
136
```
137

138
[Advanced Interpolation](./advanced-interpolation.md)
139

140
### Command Line Tools
141

142
The package includes the `gpxelevations` command-line utility for adding elevation data to GPX files directly from the command line.
143

144
```bash { .api }
145
gpxelevations [-h] [-o] [-p] [-s] [-c] [-f FILE] [-v] [gpx_files ...]
146
```
147

148
**Options:**
149
- `-h, --help`: Show help message and exit
150
- `-o, --overwrite`: Overwrite existing elevations (otherwise will add elevations only where not yet present)
151
- `-p, --approximate`: Approximate elevations with neighbour points elevation
152
- `-s, --smooth`: Smooth elevations
153
- `-c, --calculate`: Calculate elevations (but don't change the GPX file)
154
- `-f FILE, --file FILE`: Output filename
155
- `-v, --verbose`: Verbose output
156

157
**Usage Example:**
158
```bash
159
# Add elevations to a GPX file
160
gpxelevations track.gpx
161

162
# Add smoothed elevations with verbose output
163
gpxelevations -s -v hiking_track.gpx
164

165
# Calculate elevations without modifying the file
166
gpxelevations -c route.gpx
167
```
168

169
### Utility Functions
170

171
Core utility functions for distance calculations, color operations, and data processing.
172

173
```python { .api }
174
from srtm.utils import Color, distance, get_color_between
175

176
def distance(latitude_1: float, longitude_1: float, latitude_2: float, longitude_2: float) -> float: ...
177
def get_color_between(color1: Color, color2: Color, i: float) -> Color: ...
178

179
# Constants
180
ONE_DEGREE: float  # Meters per degree (approximately 111,000)
181
DEFAULT_TIMEOUT: int  # Default network timeout in seconds (15)
182
```
183

184
## Types
185

186
```python { .api }
187
from typing import Optional, Tuple, Any, NamedTuple
188

189
class Color(NamedTuple):
190
    red: int
191
    green: int 
192
    blue: int
193
    alpha: int
194

195
class GeoElevationFile:
196
    file_name: str
197
    latitude: float
198
    longitude: float
199
    resolution: float
200
    square_side: int
201
```