@spec egm96_ellipsoidal_height_m(number(), number(), number()) :: float()

Ellipsoidal height h = H + N (metres) from an orthometric height, using the embedded genuine EGM96 1-degree model. Position in radians.

@spec egm96_orthometric_height_m(number(), number(), number()) :: float()

Orthometric height H = h - N (metres) from an ellipsoidal height, using the embedded genuine EGM96 1-degree model. Position in radians.

@spec egm96_undulation(number(), number()) :: float()

Geoid undulation N (metres) at a geodetic position in radians, from the embedded genuine EGM96 1-degree global grid.

This is the recommended zero-setup default for metre-class datum work: its bilinear lookup agrees with the full 15-arcminute EGM96 grid to ~0.4 m RMS, far better than the coarse 30-degree built-in undulation/2.

@spec egm96_undulations([{number(), number()}]) :: [float()]

Embedded EGM96 1-degree undulations N (metres) for positions in radians.

@spec egm96_undulations_deg([{number(), number()}]) :: [float()]

Embedded EGM96 1-degree undulations N (metres) for positions in degrees.

@spec ellipsoidal_height_m(number(), number(), number()) :: float()

Ellipsoidal height h = H + N (metres) from an orthometric height, using the built-in grid. Position in radians.

@spec from_egm96_dac(binary()) :: {:ok, grid()} | {:error, term()}

Alias for load_egm96_dac/1.

@spec from_egm2008_raster(binary(), egm2008_spacing()) ::
  {:ok, grid()} | {:error, term()}

Alias for load_egm2008_raster/2.

@spec from_egm2008_raster_window(binary(), Sidereon.Geoid.Egm2008RasterWindow.t()) ::
  {:ok, grid()} | {:error, term()}

Alias for load_egm2008_raster_window/2.

@spec from_proj_egm96_gtx(binary()) :: {:ok, grid()} | {:error, term()}

Alias for load_proj_egm96_gtx/1, matching the core GeoidGrid constructor.

@spec from_text(binary()) :: {:ok, grid()} | {:error, term()}

Alias for load_grid/1, matching the Python GeoidGrid.from_text name.

@spec grid(
  number(),
  number(),
  number(),
  number(),
  non_neg_integer(),
  non_neg_integer(),
  [number()]
) ::
  {:ok, grid()} | {:error, term()}

Build a geoid grid handle from its origin, spacing, dimensions, and row-major samples (metres).

values_m is a flat list of n_lat * n_lon floats. Returns {:ok, reference()} or {:error, reason}.

@spec grid_ellipsoidal_height_deg(grid(), number(), number(), number()) :: float()

Loaded-grid ellipsoidal height h = H + N (metres), position in degrees.

@spec grid_ellipsoidal_height_rad(grid(), number(), number(), number()) :: float()

Loaded-grid ellipsoidal height h = H + N (metres), position in radians.

@spec grid_orthometric_height_deg(grid(), number(), number(), number()) :: float()

Loaded-grid orthometric height H = h - N (metres), position in degrees.

@spec grid_orthometric_height_rad(grid(), number(), number(), number()) :: float()

Loaded-grid orthometric height H = h - N (metres), position in radians.

@spec grid_undulation_deg(grid(), number(), number()) :: float()

Bilinearly interpolated undulation N (metres) from a loaded grid handle, at a geodetic position in degrees.

@spec grid_undulation_proj_rad(
  grid(),
  number(),
  number(),
  proj_vgridshift_arithmetic()
) ::
  {:ok, float()} | {:error, Sidereon.Geoid.ProjVgridshiftError.t()}

Interpolate a loaded EGM96 GTX grid using PROJ 9.3.0's radian indexing and blend order.

arithmetic must be :separate_multiply_add or :fused_multiply_add. PROJ's source does not prescribe floating-point contraction, so the mode is required rather than inferred from the current CPU. Invalid coordinates return a typed ProjVgridshiftError and are never clamped or extrapolated.

@spec grid_undulation_rad(grid(), number(), number()) :: float()

Bilinearly interpolated undulation N (metres) from a loaded grid handle, at a geodetic position in radians.

@spec grid_undulations_deg(grid(), [{number(), number()}]) :: [float()]

Bilinearly interpolated undulations N (metres) from a loaded grid, with positions in degrees.

@spec grid_undulations_rad(grid(), [{number(), number()}]) :: [float()]

Bilinearly interpolated undulations N (metres) from a loaded grid, with positions in radians.

@spec load_egm96_dac(binary()) :: {:ok, grid()} | {:error, term()}

Parse a full EGM96 WW15MGH.DAC byte buffer into a grid handle.

@spec load_egm2008_raster(binary(), egm2008_spacing()) ::
  {:ok, grid()} | {:error, term()}

Parse a full NGA EGM2008 interpolation raster into a grid handle.

spacing is :one_minute or :two_point_five_minute. The returned handle uses the same grid_undulation_* and height-conversion functions as every loaded grid.

@spec load_egm2008_raster_window(binary(), Sidereon.Geoid.Egm2008RasterWindow.t()) ::
  {:ok, grid()} | {:error, term()}

Parse a cropped EGM2008 interpolation-raster window descriptor into a grid handle.

@spec load_egm2008_raster_window(
  binary(),
  egm2008_spacing(),
  number(),
  number(),
  pos_integer(),
  pos_integer()
) :: {:ok, grid()} | {:error, term()}

Parse a cropped NGA EGM2008 interpolation-raster window into a grid handle.

lat_min_deg and lon_min_deg are the southwest node of the crop in degrees. n_lat and n_lon are the row and column counts carried by bytes.

@spec load_grid(binary()) :: {:ok, grid()} | {:error, term()}

Parse a geoid grid in the crate's documented text format into a handle.

The format is whitespace-delimited with # comments: a six-field header lat_min lon_min dlat dlon n_lat n_lon (degrees) followed by n_lat * n_lon undulation samples in metres, row-major (latitude ascending outer). Returns {:ok, reference()} or {:error, reason}.

@spec load_proj_egm96_gtx(binary()) :: {:ok, grid()} | {:error, term()}

Parse PROJ's public EGM96 15-arcminute egm96_15.gtx into a grid handle.

Query the returned handle with grid_undulation_proj_rad/4. The ordinary loaded-grid functions retain Sidereon's general interpolation contract.

@spec orthometric_height_m(number(), number(), number()) :: float()

Orthometric height H = h - N (metres) from an ellipsoidal height, using the built-in grid. Position in radians.

@spec undulation(number(), number()) :: float()

Built-in coarse-grid geoid undulation N (metres) at a geodetic position in radians.

@spec undulations([{number(), number()}]) :: [float()]

Built-in coarse-grid geoid undulations N (metres) for positions in radians.

@spec undulations_deg([{number(), number()}]) :: [float()]

Built-in coarse-grid geoid undulations N (metres) for positions in degrees.