# How GSD (Ground Sample Distance) Is Approximated in God's Eye View

> Learn how God's Eye View approximates Ground Sample Distance GSD. Discover the formula used to calculate resolution per pixel and ensure valid results.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-09-09

---

**God's Eye View approximates Ground Sample Distance (GSD) by multiplying the camera's altitude in meters by 0.000375 to derive resolution in meters per pixel, clamping the result to a minimum of 0.01 m to prevent invalid zero or negative values.**

The **Ground Sample Distance (GSD)** metric quantifies the real-world ground area represented by each pixel in aerial or satellite imagery. In the **bilawalsidhu/gods-eye-view** repository, this approximation powers the Heads-Up Display (HUD) resolution readout and serves as the input for calculating National Imagery Interpretability Rating Scale (NIIRS) scores.

## The Linear Altitude-to-GSD Formula

The core GSD approximation resides in [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js) at lines 324–332 within the IntelHUD component. During each telemetry tick, the system executes:

```javascript
// src/hud.js – lines 324-332
// GSD (Ground Sample Distance): approximate resolution in meters per pixel
// derived from camera altitude.
const gsd = Math.max(0.01, altM * 0.000375);      // ≈ 0.375 mm per meter of altitude
const gsdInches = gsd * 39.37;
const niirs = Math.max(0,
    Math.min(9, 10.25 - 3.32 * Math.log10(gsdInches)));

```

**Key parameters in this calculation:**

- **`altM`** — The raw ellipsoidal camera height in meters provided by the Cesium viewer.
- **`0.000375`** — An empirically chosen conversion factor representing approximately 0.375 millimeters of ground distance per meter of altitude, establishing a linear relationship between camera height and pixel resolution.
- **`Math.max(0.01, ...)`** — A clamping mechanism ensuring GSD never drops below **0.01 meters**, which prevents division-by-zero errors or nonsensical resolution values at extremely low altitudes.

This linear model yields straightforward approximations: at **1 km altitude**, GSD equals **0.375 m/pixel**; at **10 km altitude**, GSD scales to **3.75 m/pixel**.

## Integration with the IntelHUD Telemetry Loop

The GSD calculation executes client-side within a **4 Hz telemetry loop** managed by the `IntelHUD` class. Each cycle invokes `this._updateCameraData()`, which retrieves the current camera altitude from Cesium’s `viewer.camera` object and applies the GSD formula.

The computed value propagates to two destinations:

1. **HUD Display** — Updated via `document.getElementById('hud-gsd')` to show the user a real-time readout (e.g., "GSD: 2.34 m").
2. **NIIRS Calculation** — The GSD value converts to inches (`gsd * 39.37`) and feeds into the simplified General Image Quality Equation (GIQE) to generate a 0–9 NIIRS rating.

No external web services are required for this computation; all logic executes directly in the browser using the Cesium JavaScript API.

## Standalone GSD Implementation

You can reproduce the repository's GSD logic for custom scripts or unit testing using this isolated function:

```javascript
/**
 * Approximate Ground Sample Distance from camera altitude.
 *
 * @param {number} altitudeM – Camera altitude in metres (ellipsoidal height).
 * @returns {number} GSD in metres per pixel (minimum 0.01 m).
 */
function computeGSD(altitudeM) {
  // 0.000375 m/pixel per metre of altitude (empirically chosen for visual realism)
  const rawGSD = altitudeM * 0.000375;
  // Clamp to a sensible lower bound
  return Math.max(0.01, rawGSD);
}

// Example usage:
const altitude = 5000; // 5 km
const gsd = computeGSD(altitude);
console.log(`Altitude: ${altitude} m → GSD ≈ ${gsd.toFixed(2)} m/pixel`);
// Output: Altitude: 5000 m → GSD ≈ 1.88 m/pixel

```

This implementation mirrors the production code in [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js), ensuring consistency between preprocessing scripts and the live HUD display.

## Summary

- **GSD approximation** in God's Eye View uses a linear formula (`altM * 0.000375`) implemented in [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js) lines 324–332.
- The **0.000375 factor** converts camera altitude to meters-per-pixel, producing roughly 0.375 m/pixel at 1 km altitude.
- A **0.01 m floor** prevents invalid GSD values at extremely low altitudes.
- The calculation runs client-side at **4 Hz**, deriving input from Cesium's camera telemetry and outputting to both the HUD display and NIIRS rating algorithm.

## Frequently Asked Questions

### What does the 0.000375 constant represent in the GSD calculation?

The constant **0.000375** represents an empirically selected scaling factor of 0.375 millimeters of ground resolution per meter of camera altitude. This linear coefficient approximates the relationship between height and pixel density for the specific camera parameters and viewport settings used in God's Eye View, balancing computational simplicity with visual realism for intelligence analysis scenarios.

### How does camera altitude affect the GSD value in God's Eye View?

GSD scales linearly with altitude because the formula multiplies the raw altitude (`altM`) directly by the constant factor. Doubling the altitude doubles the GSD, meaning each pixel represents twice the ground distance. For example, increasing altitude from 2,000 m to 4,000 m changes the GSD from approximately 0.75 m/pixel to 1.5 m/pixel, halving the ground resolution.

### What is the relationship between GSD and NIIRS in this implementation?

The **NIIRS** (National Imagery Interpretability Rating Scale) rating derives directly from the computed GSD using the General Image Quality Equation (GIQE). After calculating GSD in meters, the code converts it to inches (`gsdInches = gsd * 39.37`) and applies the formula `NIIRS = 10.25 - 3.32 * log10(gsdInches)`. Lower GSD values (finer resolution) produce higher NIIRS scores, capped at 9.0 and floored at 0.0.

### Where is the GSD value displayed to the user?

The calculated GSD updates the HUD (Heads-Up Display) DOM element identified by `hud-gsd` in [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js). This real-time readout appears in the intelligence overlay, typically formatted as "GSD: [value] m", allowing analysts to instantly assess the ground resolution of the current satellite or drone view without interfacing with the underlying Cesium camera controls directly.