gps-denied-desktop/docs/02_components/helpers/h02_gsd_calculator_spec.md

GSD Calculator Helper

Interface Definition

Interface Name: IGSDCalculator

Interface Methods

class IGSDCalculator(ABC):
    @abstractmethod
    def compute_gsd(self, altitude: float, camera_params: CameraParameters) -> float:
        pass
    
    @abstractmethod
    def altitude_to_scale(self, altitude: float, focal_length: float) -> float:
        pass
    
    @abstractmethod
    def meters_per_pixel(self, lat: float, zoom: int) -> float:
        pass
    
    @abstractmethod
    def gsd_from_camera(self, altitude: float, focal_length: float, sensor_width: float, image_width: int) -> float:
        pass

Component Description

Ground Sampling Distance computations for altitude and coordinate systems.

API Methods

compute_gsd(altitude: float, camera_params: CameraParameters) -> float

Description: Computes GSD from altitude and camera parameters.

Formula:

GSD = (altitude * sensor_width) / (focal_length * image_width)

Example: altitude=800m, focal=24mm, sensor=36mm, width=6000px → GSD=0.2 m/pixel

---

altitude_to_scale(altitude: float, focal_length: float) -> float

Description: Converts altitude to scale factor for VO.

---

meters_per_pixel(lat: float, zoom: int) -> float

Description: Computes GSD for Web Mercator tiles at zoom level.

Formula:

meters_per_pixel = 156543.03392 * cos(lat * π/180) / 2^zoom

Example: lat=48°N, zoom=19 → ~0.3 m/pixel

---

gsd_from_camera(altitude: float, focal_length: float, sensor_width: float, image_width: int) -> float

Description: Direct GSD calculation from parameters.

Dependencies

External: numpy

Test Cases

1. Standard camera at 800m → GSD ~0.1-0.3 m/pixel
2. Web Mercator zoom 19 at Ukraine → ~0.3 m/pixel