Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -299,6 +299,10 @@ set(OTHER_SOURCE_FILES
src/apps/testapps/testConformanceHierarchy.c
src/apps/testapps/testConformanceSets.c
src/apps/testapps/testConformanceRegions.c
src/apps/testapps/testConformanceEdges.c
src/apps/testapps/testConformanceVertexes.c
src/apps/testapps/testConformanceFloatsEdges.c
src/apps/testapps/testConformanceFloatsVertexes.c
src/apps/testapps/testConformanceManifest.c
src/apps/testapps/mkConformance.c
src/apps/miscapps/cellToBoundaryHier.c
Expand Down
21 changes: 21 additions & 0 deletions CMakeTests.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -248,10 +248,31 @@ foreach(file ${conformance_files})
File)
endforeach()

file(GLOB conformance_files tests/inputfiles/edges/*.jsonl)
foreach(file ${conformance_files})
add_h3_test_with_arg(testConformanceEdges
src/apps/testapps/testConformanceEdges.c ${file} File)
endforeach()

file(GLOB conformance_files tests/inputfiles/vertexes/*.jsonl)
foreach(file ${conformance_files})
add_h3_test_with_arg(testConformanceVertexes
src/apps/testapps/testConformanceVertexes.c ${file}
File)
endforeach()

add_h3_test_with_arg(testConformanceFloatsCells
src/apps/testapps/testConformanceFloatsCells.c
${CMAKE_CURRENT_SOURCE_DIR}/tests/inputfiles/floats/cells.jsonl
File)
add_h3_test_with_arg(testConformanceFloatsEdges
src/apps/testapps/testConformanceFloatsEdges.c
${CMAKE_CURRENT_SOURCE_DIR}/tests/inputfiles/floats/edges.jsonl
File)
add_h3_test_with_arg(testConformanceFloatsVertexes
src/apps/testapps/testConformanceFloatsVertexes.c
${CMAKE_CURRENT_SOURCE_DIR}/tests/inputfiles/floats/vertexes.jsonl
File)

file(GLOB all_centers tests/inputfiles/rand*centers.txt)
foreach(file ${all_centers})
Expand Down
94 changes: 89 additions & 5 deletions dev-docs/conformance.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,10 +121,14 @@ tests/inputfiles/
sets/curated.jsonl
regions/polygons.jsonl
regions/curated.jsonl
edges/cells.jsonl
vertexes/cells.jsonl
floats/edges.jsonl
floats/vertexes.jsonl
```

The remaining groups of the suite (`edges`, `vertexes`, the other `floats`
files and `digests`) are added group by group; the generator already writes all
The remaining files of the suite (`floats/distances.jsonl`,
`floats/resolutions.jsonl` and `digests`) are added group by group; the generator already writes all
of them, and each is specified here when its files land.

`manifest.json` is the only file a consumer opens by name. Every record file
Expand Down Expand Up @@ -276,9 +280,9 @@ Example:

The floating-point functions, every value compared under the manifest
tolerances: points by angular distance, measures by relative error.
Subjects are valid cells (see Sampling). Further `floats` files cover
directed edges, vertexes, great-circle distances and the per-resolution
averages.
Subjects are valid cells and the edges and vertexes drawn from them (see
Sampling). Further `floats` files cover great-circle distances and the
per-resolution averages.

`floats/cells.jsonl`, one line per cell:

Expand All @@ -298,6 +302,24 @@ Example:
{"index":"8009fffffffffff","center":[64.700000127934885,10.536199075467678],"boundary":[[63.095054077525454,-10.444977544778341],[55.706768465152265,5.5236465492903184],[58.401544870352687,25.082722326707898],[68.929957881939814,31.831280499087402],[73.310223685444001,0.32561035194323518]],"areaRads2":0.063123898710068072,"areaKm2":2562182.1629555039,"areaM2":2562182162955.5039,"interiorRes":2,"interior":[[63.897527102730166,0.045610765344669346],[60.203384296543575,8.0299228123789987],[61.55077249914379,17.809460701087787],[66.814979004937356,21.183739787277538],[69.00511190668945,5.4309047137054565]],"interiorCells":["82091ffffffffff","82098ffffffffff","8208affffffffff","8208c7fffffffff","820957fffffffff"]}
```

`floats/edges.jsonl`, one line per directed edge:

| Key | Function | Type |
|---|---|---|
| `index` | the subject edge | index string |
| `lengthRads`, `lengthKm`, `lengthM` | `edgeLengthRads`, `edgeLengthKm`, `edgeLengthM` | number |
| `boundary` | `directedEdgeToBoundary(index)` | sequence of points, in the reference's order |

`floats/vertexes.jsonl`, one line per vertex: `index` and `latLng`, which
is `vertexToLatLng(index)`.

Examples:

```json
{"index":"14001fffffffffff","lengthRads":0.19076599177033998,"lengthKm":1215.3715034438708,"lengthM":1215371.5034438707,"boundary":[[73.310223685444001,0.32561035194323518],[68.929957881939828,31.831280499087395]]}
{"index":"23001fffffffffff","latLng":[87.364695323196472,145.55819769133689]}
```

### `traversal`

One line per **valid cell and target**. The sampled file draws the target
Expand Down Expand Up @@ -497,6 +519,52 @@ Example:
{"id":"8009fffffffffff:1","polygon":{"outer":[[63.41604328760733,-6.2487422207291372],[57.505414797708795,6.5261570545257905],[59.661235921869135,22.173417676459856],[68.083966331138825,27.572264214363457],[71.588178973942178,2.3677280966481229]],"holes":[]},"res":1,"cells":["81083ffffffffff","8108bffffffffff","8108fffffffffff","81093ffffffffff","81097ffffffffff","8109bffffffffff"],"center":["81083ffffffffff","8108bffffffffff","8108fffffffffff","81093ffffffffff","81097ffffffffff","8109bffffffffff"],"full":["81083ffffffffff"],"overlapping":["81083ffffffffff","8108bffffffffff","8108fffffffffff","81093ffffffffff","81097ffffffffff","8109bffffffffff"],"overlappingBbox":["81013ffffffffff","81017ffffffffff","81073ffffffffff","81077ffffffffff","8107bffffffffff","81083ffffffffff","8108bffffffffff","8108fffffffffff","81093ffffffffff","81097ffffffffff","8109bffffffffff","81113ffffffffff","81117ffffffffff","81193ffffffffff","81197ffffffffff","811f3ffffffffff","811f7ffffffffff"],"multiPolygon":[{"outer":[[56.632952719050827,18.275235951757786],[58.401544870352701,25.082722326707874],[62.478113451924763,24.517172437523488],[64.873036611864293,31.517537185292614],[68.929957881939814,31.831280499087395],[70.052151519508882,20.597244293835026],[73.487456497717517,14.551845028116778],[73.310223685443972,0.32561035194322951],[69.273859191908159,-1.6665855042241828],[67.153547845205082,-10.558792289389457],[63.095054077525454,-10.444977544778338],[61.545509577880757,-2.2975260876218235],[57.689497374592854,-0.93158716351061854],[55.70676846515228,5.5236465492903095],[58.130531165851423,11.555977692900695]],"holes":[]}]}
```

### `edges`

One line per **valid cell**, paired with a `target` drawn from its 1-disk.
The target is the cell itself about one time in seven, which makes
`cellsToDirectedEdge` fail with `E_NOT_NEIGHBORS`.

| Key | Function | Type |
|---|---|---|
| `index` | the subject cell | index string |
| `edges` | `originToDirectedEdges(index)`, with `0` padding removed | set of index strings |
| `destinations` | `getDirectedEdgeDestination(e)` for each `e` in `edges`, in the written (ascending) order | sequence of index strings |
| `reverses` | `reverseDirectedEdge(e)` for each `e` in `edges`, in the written order | sequence of index strings |
| `vertexes` | `edgeToVertexes(e)` for each `e` in `edges`, in the written order, as `[v1, v2]` | sequence of pairs of index strings |
| `target` | the second cell of the pair | index string |
| `edge` | `cellsToDirectedEdge(index, target)` | index string, or error |

A consumer must also check that `isValidDirectedEdge(e)` holds,
`getDirectedEdgeOrigin(e) == index`, and `directedEdgeToCells(e)` is `index`
followed by the matching entry of `destinations`, for every `e` in `edges`.

Example:

```json
{"index":"8005fffffffffff","edges":["11005fffffffffff","12005fffffffffff","13005fffffffffff","14005fffffffffff","15005fffffffffff","16005fffffffffff"],"destinations":["800dfffffffffff","8015fffffffffff","8017fffffffffff","8001fffffffffff","8003fffffffffff","800bfffffffffff"],"reverses":["1600dfffffffffff","15015fffffffffff","14017fffffffffff","13001fffffffffff","16003fffffffffff","1100bfffffffffff"],"vertexes":[["23005fffffffffff","21003fffffffffff"],["21005fffffffffff","22005fffffffffff"],["22005fffffffffff","23005fffffffffff"],["23001fffffffffff","22001fffffffffff"],["21003fffffffffff","23001fffffffffff"],["22001fffffffffff","21005fffffffffff"]],"target":"8003fffffffffff","edge":"15005fffffffffff"}
```

### `vertexes`

One line per **valid cell**. A pentagon has no vertex number 5, so
`cellToVertex` fails with `E_DOMAIN` there.

| Key | Function | Type |
|---|---|---|
| `index` | the subject cell | index string |
| `vertexes` | `cellToVertexes(index)`, with `0` padding removed | set of index strings |
| `byNumber` | `cellToVertex(index, n)` for `n` from 0 to 5, in that order | sequence of six entries, each an index string or error |

A consumer must also check that `isValidVertex(v)` holds for every `v` in
`vertexes`. `vertexToLatLng` belongs to the floats group.

Example:

```json
{"index":"8009fffffffffff","vertexes":["20001fffffffffff","21009fffffffffff","22009fffffffffff","25001fffffffffff","25007fffffffffff"],"byNumber":["25007fffffffffff","21009fffffffffff","22009fffffffffff","20001fffffffffff","25001fffffffffff",{"err":"E_DOMAIN"}]}
```

## Curated files

Seeded sampling gives coverage density but is blind to the particular inputs
Expand Down Expand Up @@ -713,6 +781,13 @@ vertex of `cellToBoundary` in its order. Degrees are what the file holds, so
a generator converts the points to its implementation's units rather than
interpolating in radians.

`edges.jsonl`: valid-cell subjects with `n` = 16. Then for each subject,
take its `originToDirectedEdges` array (six slots, a zero where a pentagon
has no edge) and twice: draw 6 and emit the edge at that slot if it is
non-zero and was not already emitted for this subject.

`vertexes.jsonl`: the same with `cellToVertexes`.

### `traversal/cells.jsonl`

Valid-cell subjects with `n` = 16. Then for each subject, `target` is drawn
Expand Down Expand Up @@ -780,6 +855,15 @@ For each subject `h` at resolution `res`, four lines:
`cellToCenterChild(h, res + 1)` scaled by 1.2, filled at `res + 2`;
4. the boundary of `h` scaled by 1.2 with no hole, filled at 16.

### `edges/cells.jsonl`

Valid-cell subjects with `n` = 16. Then for each subject, `target` is drawn
from its 1-disk.

### `vertexes/cells.jsonl`

Valid-cell subjects with `n` = 16. No further draws.

### Curated files

No draws. The subjects are the tables under Curated files, written in the
Expand Down
88 changes: 88 additions & 0 deletions src/apps/testapps/testConformanceEdges.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
/*
* Copyright 2026 Uber Technologies, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @file
* @brief Conformance runner for the `edges` group
* (dev-docs/conformance.md).
*
* usage: `testConformanceEdges <record-file>`
*
* Each line holds one valid cell with its directed edges, their
* destinations, reverses and vertexes, and `cellsToDirectedEdge` to a
* target drawn from the cell's 1-disk, which is the cell itself about one
* time in seven.
*/

#include "conformance.h"
#include "h3api.h"

#define NUM_EDGES 6

static void checkEdges(const cJSON *record) {
H3Index h = jsonIndex(record, "index");
H3Index target = jsonIndex(record, "target");

H3Index edges[NUM_EDGES] = {0};
c_assert(!H3_EXPORT(originToDirectedEdges)(h, edges),
"originToDirectedEdges");
assertIndexSet(jsonArray(record, "edges"), edges, NUM_EDGES, "edges");
int64_t count = normalizeIndexSet(edges, NUM_EDGES);

// destinations, reverses and vertexes follow the edges in ascending
// order.
const cJSON *vertexes = jsonArray(record, "vertexes");
c_assert(cJSON_GetArraySize(vertexes) == count,
"vertexes: not one pair per edge");
H3Index destinations[NUM_EDGES];
H3Index reverses[NUM_EDGES];
for (int64_t i = 0; i < count; i++) {
c_assert(H3_EXPORT(isValidDirectedEdge)(edges[i]),
"edges: not a valid directed edge");
H3Index origin;
c_assert(!H3_EXPORT(getDirectedEdgeOrigin)(edges[i], &origin),
"getDirectedEdgeOrigin");
c_assert(origin == h, "edges: origin is not the cell");
c_assert(
!H3_EXPORT(getDirectedEdgeDestination)(edges[i], &destinations[i]),
"getDirectedEdgeDestination");
H3Index cells[2];
c_assert(!H3_EXPORT(directedEdgeToCells)(edges[i], cells),
"directedEdgeToCells");
c_assert(cells[0] == h && cells[1] == destinations[i],
"directedEdgeToCells: not the origin and destination");
c_assert(!H3_EXPORT(reverseDirectedEdge)(edges[i], &reverses[i]),
"reverseDirectedEdge");
H3Index ends[2];
c_assert(!H3_EXPORT(edgeToVertexes)(edges[i], &ends[0], &ends[1]),
"edgeToVertexes");
assertIndexSequence(cJSON_GetArrayItem(vertexes, (int)i), ends, 2,
"vertexes");
}
assertIndexSequence(jsonArray(record, "destinations"), destinations, count,
"destinations");
assertIndexSequence(jsonArray(record, "reverses"), reverses, count,
"reverses");

const cJSON *edgeItem = jsonItem(record, "edge");
H3Index edge;
H3Error err = H3_EXPORT(cellsToDirectedEdge)(h, target, &edge);
if (!expectResult(edgeItem, err, "edge")) {
assertIndex(edgeItem, edge, "edge");
}
}

int main(int argc, char *argv[]) {
return conformanceMain(argc, argv, checkEdges);
}
49 changes: 49 additions & 0 deletions src/apps/testapps/testConformanceFloatsEdges.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
/*
* Copyright 2026 Uber Technologies, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @file
* @brief Conformance runner for `floats/edges.jsonl`
* (dev-docs/conformance.md).
*
* usage: `testConformanceFloatsEdges <record-file>`
*
* Each line holds one directed edge with its lengths and boundary,
* compared under the manifest tolerances.
*/

#include "conformance.h"
#include "h3api.h"

static void checkFloatEdge(const cJSON *record) {
H3Index edge = jsonIndex(record, "index");

double length;
H3Error err = H3_EXPORT(edgeLengthRads)(edge, &length);
assertMeasure(record, "lengthRads", err, length, UNIT_RADS);
err = H3_EXPORT(edgeLengthKm)(edge, &length);
assertMeasure(record, "lengthKm", err, length, UNIT_KM);
err = H3_EXPORT(edgeLengthM)(edge, &length);
assertMeasure(record, "lengthM", err, length, UNIT_M);

CellBoundary boundary;
c_assert(!H3_EXPORT(directedEdgeToBoundary)(edge, &boundary),
"directedEdgeToBoundary");
assertPointSequence(jsonItem(record, "boundary"), boundary.verts,
boundary.numVerts, "boundary");
}

int main(int argc, char *argv[]) {
return conformanceMain(argc, argv, checkFloatEdge);
}
38 changes: 38 additions & 0 deletions src/apps/testapps/testConformanceFloatsVertexes.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
/*
* Copyright 2026 Uber Technologies, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @file
* @brief Conformance runner for `floats/vertexes.jsonl`
* (dev-docs/conformance.md).
*
* usage: `testConformanceFloatsVertexes <record-file>`
*
* Each line holds one vertex and `vertexToLatLng` of it, compared under
* the angular tolerance.
*/

#include "conformance.h"
#include "h3api.h"

static void checkFloatVertex(const cJSON *record) {
H3Index vertex = jsonIndex(record, "index");
LatLng point;
c_assert(!H3_EXPORT(vertexToLatLng)(vertex, &point), "vertexToLatLng");
assertPoint(jsonItem(record, "latLng"), &point, "latLng");
}

int main(int argc, char *argv[]) {
return conformanceMain(argc, argv, checkFloatVertex);
}
Loading
Loading