Geospatial Metrics | NumKong for C

The native SDK exposes both the fast spherical approximation and the more accurate ellipsoidal solver, each between every row and every column of two packed point sets. Inputs are in radians. Outputs are in meters.

// Statue of Liberty (40.6892°N, 74.0445°W) and Big Ben (51.5007°N, 0.1246°W)
nk_f64_t latitudes[] = {0.7101605100, 0.8988567821}, longitudes[] = {-1.2923203180, -0.0021746802};

// A pack is built once per point set, on an `nk_default_alignment_k` boundary
nk_size_t bytes = 0;
nk_vincentys_pack_size_f64_best(2, capabilities, &bytes);
void *vincentys_pack = aligned_alloc(nk_default_alignment_k, bytes);
nk_vincentys_pack_f64_best(latitudes, longitudes, 2, vincentys_pack, capabilities, NULL);

// Every row against every column, so the diagonal is zero
nk_f64_t distances[2][2];
nk_vincentys_packed_f64_best(vincentys_pack, vincentys_pack, &distances[0][0], 2 * sizeof(nk_f64_t), capabilities,
                             NULL); // distances[0][1] ≈ 5,589,857 m on WGS-84

nk_haversines_pack_size_f64_best(2, capabilities, &bytes);
void *haversines_pack = aligned_alloc(nk_default_alignment_k, bytes);
nk_haversines_pack_f64_best(latitudes, longitudes, 2, haversines_pack, capabilities, NULL);
nk_haversines_packed_f64_best(haversines_pack, haversines_pack, &distances[0][0], 2 * sizeof(nk_f64_t),
                              capabilities, NULL); // distances[0][1] ≈ 5,574,848 m on the mean sphere, 15 km less

API

Types

nk_geospatial_pack_size_punned_tPack sizes are host arithmetic, so they take no stream.

capabilities.h:910 ↗

typedef nk_status_t(*) nk_geospatial_pack_size_punned_t(nk_size_t points, nk_size_t *bytes);

Functions

nk_sqeuclideans3d_*_best× 2Squared Euclidean distances between every row point and every column point in 3D.

geospatial.h:194 ↗

nk_status_t nk_sqeuclideans3d_i32_best(
    nk_i32_t const *a,
    nk_size_t rows,
    nk_i32_t const *b,
    nk_size_t columns,
    nk_u64_t *results,
    nk_size_t results_stride,
    nk_capability_t capabilities,
    nk_stream_t stream);

Symbol	`a, b`	`results`	Backends
`nk_sqeuclideans3d_i32_best`	`nk_i32_t`	`nk_u64_t`	6
`nk_sqeuclideans3d_f64_best`	`nk_f64_t`	`nk_f64_t`	6

Backends

nk_sqeuclideans3d_i32serialneonhaswellskylakev128relaxedrvv
nk_sqeuclideans3d_f64serialneonhaswellskylakev128relaxedrvv

Integer results are exact whenever every axis difference fits 32 bits, which Earth-fixed centimetres below 4,359 km of altitude always satisfy. F64 inputs sum their squares in Dot2.

Parameters

`a`	in	The rows, `rows` × 3 interleaved [x0,y0,z0, x1,y1,z1, ...].
`rows`	in	The number of row points.
`b`	in	The columns, `columns` × 3 interleaved.
`columns`	in	The number of column points.
`results`	out	The [rows,columns] squared distances.
`results_stride`	in	The bytes between consecutive rows of `results`.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_*_pack_size_f64_best× 2Returns the bytes a Haversine or Vincenty pack of points points takes.

geospatial.h:211 ↗

nk_status_t nk_haversines_pack_size_f64_best(
    nk_size_t points,
    nk_capability_t capabilities,
    nk_size_t *bytes);

Symbol	Backends
`nk_haversines_pack_size_f64_best`	2
`nk_vincentys_pack_size_f64_best`	2

Backends

nk_haversines_pack_size_f64serialcuda
nk_vincentys_pack_size_f64serialcuda

Parameters

`points`	in	The number of points.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`bytes`	out	The size of the pack.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_haversines_pack_f64_bestPacks points as unit vectors on the mean sphere, for nk_haversines_packed_f64_best.

geospatial.h:229 ↗

nk_status_t nk_haversines_pack_f64_best(
    nk_f64_t const *latitudes,
    nk_f64_t const *longitudes,
    nk_size_t count,
    void *packed,
    nk_capability_t capabilities,
    nk_stream_t stream);

Backends

nk_haversines_pack_f64serialcuda

Parameters

`latitudes`	in	Latitudes, in radians.
`longitudes`	in	Longitudes, in radians.
`count`	in	The number of points.
`packed`	out	The pack, on an `nk_default_alignment_k` boundary.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_vincentys_pack_f64_bestPacks points as their longitudes and the sines and cosines of their reduced latitudes on the ellipsoid, for nk_vincentys_packed_f64_best; parameters as nk_haversines_pack_f64_best.

geospatial.h:235 ↗

nk_status_t nk_vincentys_pack_f64_best(
    nk_f64_t const *latitudes,
    nk_f64_t const *longitudes,
    nk_size_t count,
    void *packed,
    nk_capability_t capabilities,
    nk_stream_t stream);

Backends

nk_vincentys_pack_f64serialcuda

nk_haversines_packed_f64_bestGreat-circle metres between every row and every column point on the mean sphere.

geospatial.h:251 ↗

nk_status_t nk_haversines_packed_f64_best(
    void const *a_packed,
    void const *b_packed,
    nk_f64_t *results,
    nk_size_t results_stride,
    nk_capability_t capabilities,
    nk_stream_t stream);

Backends

nk_haversines_packed_f64serialneonhaswellskylakev128relaxedrvvcuda

Parameters

`a_packed`	in	The row points, as `nk_haversines_pack_f64_best` packed them.
`b_packed`	in	The column points, packed the same way.
`results`	out	The [rows,columns] distances.
`results_stride`	in	The bytes between consecutive rows of `results`.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_vincentys_packed_f64_bestGeodesic metres on the WGS-84 ellipsoid between every row and every column point, from packs of nk_vincentys_pack_f64_best; parameters as nk_haversines_packed_f64_best.

geospatial.h:257 ↗

nk_status_t nk_vincentys_packed_f64_best(
    void const *a_packed,
    void const *b_packed,
    nk_f64_t *results,
    nk_size_t results_stride,
    nk_capability_t capabilities,
    nk_stream_t stream);

Backends

nk_vincentys_packed_f64serialneonhaswellskylakev128relaxedrvvcuda

nk_terrain_pack_size_f32_bestReturns the bytes the terrain pack of a rows × columns grid takes.

geospatial.h:271 ↗

nk_status_t nk_terrain_pack_size_f32_best(
    nk_size_t rows,
    nk_size_t columns,
    nk_capability_t capabilities,
    nk_size_t *bytes);

Backends

nk_terrain_pack_size_f32serialcuda

Parameters

`rows`	in	The grid rows.
`columns`	in	The grid columns.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`bytes`	out	The size of the pack.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_terrain_pack_f32_bestPacks the maxima of every 2ᵏ × 2ᵏ block of a north-up grid, its shape and scale.

geospatial.h:290 ↗

nk_status_t nk_terrain_pack_f32_best(
    nk_f32_t const *heights,
    nk_size_t rows,
    nk_size_t columns,
    nk_size_t heights_stride,
    nk_f64_t row_metres,
    nk_f64_t column_metres,
    void *packed,
    nk_capability_t capabilities,
    nk_stream_t stream);

Backends

nk_terrain_pack_f32serialcuda

Parameters

`heights`	in	The [rows,columns] heights in metres, row 0 at the north edge; NaN marks a missing cell. Every later call names the same buffer again.
`rows`	in	The grid rows.
`columns`	in	The grid columns.
`heights_stride`	in	The bytes between consecutive rows of `heights`.
`row_metres`	in	The ground length of one row step, constant over the grid.
`column_metres`	in	The ground length of one column step, constant over the grid.
`packed`	out	The pack, on an `nk_default_alignment_k` boundary.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_terrain_heights_packed_f32_bestBilinear terrain heights under count points.

geospatial.h:307 ↗

nk_status_t nk_terrain_heights_packed_f32_best(
    nk_f32_t const *heights,
    void const *packed,
    nk_f32_t const *points,
    nk_size_t count,
    nk_f32_t *results,
    nk_capability_t capabilities,
    nk_stream_t stream);

Backends

nk_terrain_heights_packed_f32serialcuda

Parameters

`heights`	in	The grid `packed` was built from.
`packed`	in	The grid's terrain pack.
`points`	in	The `count` × 2 interleaved [column,row] cell coordinates of the points.
`count`	in	The number of points.
`results`	out	The `count` heights in metres, NaN off the grid or beside a missing cell.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_clearances_packed_f32_bestClearances in metres from every row viewpoint to every column target over one terrain, as Clearance defines them.

geospatial.h:332 ↗

nk_status_t nk_clearances_packed_f32_best(
    nk_f32_t const *heights,
    void const *packed,
    nk_f32_t const *viewpoints,
    nk_f32_t const *views,
    nk_size_t rows,
    nk_f32_t const *targets,
    nk_size_t columns,
    nk_f64_t refraction,
    nk_f32_t *results,
    nk_size_t results_stride,
    nk_capability_t capabilities,
    nk_stream_t stream);

Backends

nk_clearances_packed_f32serialcuda

Parameters

`heights`	in	The grid `packed` was built from.
`packed`	in	The grid's terrain pack.
`viewpoints`	in	The rows, `rows` × 3 interleaved [column, row, height].
`views`	in	Null, seeing everywhere without limit, or `rows` × 4 interleaved [azimuth, elevation, field, range]: radians clockwise from the grid's north and above the horizon, the full cone angle in radians, and metres.
`rows`	in	The number of viewpoints.
`targets`	in	The columns, `columns` × 3 interleaved [column, row, height].
`columns`	in	The number of targets.
`refraction`	in	The refraction coefficient: 1/7 for light, 0.25 for radio, 0 for none.
`results`	out	The [rows,columns] clearances.
`results_stride`	in	The bytes between consecutive rows of `results`.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_sqeuclideans3d_output_dtypeReturns the output dtype of sqeuclideans3d: exact u64 for i32, f64 for f64.

geospatial.h:504 ↗

nk_dtype_t nk_sqeuclideans3d_output_dtype(nk_dtype_t dtype);

nk_geodesics_output_dtypeReturns the output dtype of haversines and vincentys.

geospatial.h:513 ↗

nk_dtype_t nk_geodesics_output_dtype(nk_dtype_t dtype);

nk_clearances_output_dtypeReturns the output dtype of clearances.

geospatial.h:518 ↗

nk_dtype_t nk_clearances_output_dtype(nk_dtype_t dtype);

nk_haversines_error_boundReturns the error bound of a Haversine central angle in radians, relative to one plus the angle: 3 sines and cosines per unit vector at 3.5 ULP, the Dot2 norms, 2 roots and the arctangent.

geospatial.h:524 ↗

nk_f64_t nk_haversines_error_bound(nk_dtype_t dtype);

nk_vincentys_error_boundReturns the error bound of a Vincenty angular distance, in radians: the longitude the iteration stops within, and 20 roundings on the longest path from the reduced latitudes through one iteration and the series.

geospatial.h:529 ↗

nk_f64_t nk_vincentys_error_bound(nk_dtype_t dtype);

nk_geospatial_find_kernelFinds the geospatial kernel of kind for dtype, from the best of capabilities.

geospatial.h:545 ↗

nk_status_t nk_geospatial_find_kernel(
    nk_kernel_kind_t kind,
    nk_dtype_t dtype,
    nk_capability_t capabilities,
    nk_kernel_punned_t *kernel,
    nk_capability_t *capability);

Parameters

`kind`	in	The verb whose kernel to find.
`dtype`	in	The input type the kernel reads.
`capabilities`	in	The mask to pick the best capability from.
`kernel`	out	The kernel, or null when no capability in `capabilities` has it.
`capability`	out	The capability the kernel belongs to, or zero.

Statuses

nk_missing_kernel_k
nk_missing_library_k Header-only.

Macros

NUMKONG_EARTH_MEAN_RADIUSThe IUGG mean radius R₁, in metres, of the Haversine sphere and the terrain curvature.

geospatial.h:153 ↗

#define NUMKONG_EARTH_MEAN_RADIUS (6371008.8)

NUMKONG_EARTH_ELLIPSOID_EQUATORIAL_RADIUSThe WGS-84 semi-major axis, in metres; the polar radius derives as a × (1 − f).

geospatial.h:158 ↗

#define NUMKONG_EARTH_ELLIPSOID_EQUATORIAL_RADIUS (6378137.0)

NUMKONG_EARTH_ELLIPSOID_INVERSE_FLATTENINGThe WGS-84 inverse flattening.

geospatial.h:163 ↗

#define NUMKONG_EARTH_ELLIPSOID_INVERSE_FLATTENING (298.257223563)