Elevation Queries

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

Capabilities

Factory Function

Creates the main elevation data utility object with configurable data sources, caching options, and processing modes.

def get_data(
    srtm1: bool = True,
    srtm3: bool = True, 
    leave_zipped: bool = False,
    file_handler: Optional[FileHandler] = None,
    use_included_urls: bool = True,
    batch_mode: bool = False,
    local_cache_dir: str = "",
    timeout: int = 0
) -> GeoElevationData

Parameters:

• srtm1 (bool): Enable SRTM1 data (30m resolution, US only). Default: True
• srtm3 (bool): Enable SRTM3 data (90m resolution, global). Default: True
• leave_zipped (bool): Store downloaded files as compressed zip files. Default: False
• file_handler (Optional[FileHandler]): Custom file handling implementation. Default: None
• use_included_urls (bool): Use pre-cached URL list for faster file discovery. Default: True
• batch_mode (bool): Memory-efficient mode that keeps only the most recent file in memory. Default: False
• local_cache_dir (str): Custom directory for caching SRTM files. Default: "" (uses ~/.cache/srtm/)
• timeout (int): Network timeout in seconds for file downloads. Default: 0 (uses default timeout)

Returns: GeoElevationData instance configured with specified options

Usage Example:

import srtm

# Basic usage with default settings
elevation_data = srtm.get_data()

# Custom configuration for memory-efficient processing
elevation_data = srtm.get_data(
    srtm1=False,           # Disable SRTM1 to save bandwidth
    batch_mode=True,       # Enable memory-efficient mode
    local_cache_dir="./srtm_cache",  # Custom cache location
    timeout=30             # 30-second timeout
)

Point Elevation Lookup

Retrieve elevation data for specific coordinates with optional approximation for improved accuracy.

class GeoElevationData:
    def get_elevation(self, latitude: float, longitude: float, approximate: bool = False) -> Optional[float]: ...

Parameters:

• latitude (float): Latitude coordinate (-90 to 90 degrees)
• longitude (float): Longitude coordinate (-180 to 180 degrees)
• approximate (bool): Use interpolation between nearby points for better accuracy. Default: False

Returns: Elevation in meters above sea level, or None if no data available

Usage Example:

elevation_data = srtm.get_data()

# Basic elevation lookup
elevation = elevation_data.get_elevation(45.8566, 7.8566)
print(f"Elevation: {elevation} meters")

# More accurate lookup with approximation
elevation_approx = elevation_data.get_elevation(45.8566, 7.8566, approximate=True)
print(f"Approximate elevation: {elevation_approx} meters")

# Handle missing data
elevation = elevation_data.get_elevation(0.0, 0.0)  # Ocean coordinates
if elevation is None:
    print("No elevation data available for these coordinates")

SRTM File Access

Direct access to SRTM data files and metadata for advanced processing.

class GeoElevationData:
    def get_file(self, latitude: float, longitude: float) -> Optional[GeoElevationFile]: ...
    def get_file_name(self, latitude: float, longitude: float) -> Optional[str]: ...

get_file() returns the SRTM file object containing the specified coordinates:

• Parameters: latitude (float), longitude (float)
• Returns: GeoElevationFile instance or None if no file covers the coordinates

get_file_name() returns the standard SRTM filename for the coordinates:

• Parameters: latitude (float), longitude (float)
• Returns: Filename string (e.g., "N45E007.hgt") or None if no file exists

Usage Example:

elevation_data = srtm.get_data()

# Get the SRTM file for specific coordinates
srtm_file = elevation_data.get_file(45.8566, 7.8566)
if srtm_file:
    print(f"File: {srtm_file.file_name}")
    print(f"Coverage: {srtm_file.latitude}, {srtm_file.longitude}")
    print(f"Resolution: {srtm_file.resolution} degrees per pixel")

# Get just the filename
filename = elevation_data.get_file_name(45.8566, 7.8566)
print(f"SRTM filename: {filename}")

SRTM File Operations

Direct operations on individual SRTM files for granular control over elevation queries.

class GeoElevationFile:
    file_name: str
    latitude: float
    longitude: float
    resolution: float
    square_side: int
    
    def get_elevation(self, latitude: float, longitude: float, approximate: bool = False) -> Optional[float]: ...
    def get_row_and_column(self, latitude: float, longitude: float) -> Tuple[int, int]: ...
    def get_lat_and_long(self, row: int, column: int) -> Tuple[float, float]: ...
    def get_elevation_from_row_and_column(self, row: int, column: int) -> Optional[float]: ...
    def parse_file_name_starting_position(self) -> None: ...

Properties:

• file_name: SRTM filename (e.g., "N45E007.hgt")
• latitude: Lower-left latitude of file coverage
• longitude: Lower-left longitude of file coverage
• resolution: Degrees per pixel
• square_side: File dimensions in pixels (typically 1201 or 3601)

get_elevation(): Get elevation from this specific file

• Validates that coordinates are within file bounds
• Same parameters and behavior as GeoElevationData.get_elevation()

get_row_and_column(): Convert geographic coordinates to pixel indices

• Returns: Tuple of (row, column) indices within the file

get_lat_and_long(): Convert pixel indices back to geographic coordinates

• Parameters: row (int), column (int)
• Returns: Tuple of (latitude, longitude) coordinates

get_elevation_from_row_and_column(): Get elevation value from specific pixel location

• Parameters: row (int), column (int) - Pixel indices within the file
• Returns: Elevation in meters, or None if invalid location or no data

parse_file_name_starting_position(): Parse SRTM filename to extract geographic bounds

• Parameters: None (uses internal file_name attribute)
• Returns: None (sets internal latitude and longitude attributes)

Usage Example:

elevation_data = srtm.get_data()
srtm_file = elevation_data.get_file(45.8566, 7.8566)

if srtm_file:
    # Get elevation from specific file
    elevation = srtm_file.get_elevation(45.8566, 7.8566)
    
    # Convert coordinates to pixel indices
    row, col = srtm_file.get_row_and_column(45.8566, 7.8566)
    print(f"Pixel location: row {row}, column {col}")
    
    # Get elevation directly from pixel coordinates
    pixel_elevation = srtm_file.get_elevation_from_row_and_column(int(row), int(col))
    print(f"Pixel elevation: {pixel_elevation}m")
    
    # Convert back to coordinates
    lat, lon = srtm_file.get_lat_and_long(int(row), int(col))
    print(f"Coordinates: {lat}, {lon}")
    
    # Display file information
    print(f"File: {srtm_file}")  # Uses __str__ method

Error Handling

Common error conditions when working with elevation queries:

• Network Errors: Connection failures during SRTM file downloads
• Missing Data: No SRTM coverage for requested coordinates (returns None)
• Invalid Coordinates: Latitude/longitude values outside valid ranges
• File Corruption: Downloaded SRTM files that are corrupted or invalid
• Disk Space: Insufficient space for downloading and caching SRTM files
• Permission Errors: Unable to write to cache directory