diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml index 468c072..eb1eb60 100644 --- a/.github/workflows/pr-check.yml +++ b/.github/workflows/pr-check.yml @@ -32,3 +32,6 @@ jobs: - name: Test run: yarn test + + - name: Build docs + run: yarn docs:build diff --git a/docs/.vitepress/theme/components/DggsD3HierarchyDemo.vue b/docs/.vitepress/theme/components/DggsD3HierarchyDemo.vue index a37de2a..a81ff13 100644 --- a/docs/.vitepress/theme/components/DggsD3HierarchyDemo.vue +++ b/docs/.vitepress/theme/components/DggsD3HierarchyDemo.vue @@ -10,6 +10,7 @@ const state = reactive({ selectedCell: null, selectedRes: null, parentCell: null, + allParentCells: [], childrenCells: [], neighborCells: [], addressInfo: null, @@ -107,9 +108,16 @@ function selectCell(cellId, resolution) { state.neighborCells = [] } try { - state.parentCell = resolution > 0 ? dggs.sequenceNumParent([cellId], resolution)[0] : null + if (resolution > 0) { + state.allParentCells = dggs.sequenceNumAllParents([cellId], resolution)[0] + state.parentCell = state.allParentCells[0] ?? null + } else { + state.allParentCells = [] + state.parentCell = null + } } catch { state.parentCell = null + state.allParentCells = [] } try { state.childrenCells = dggs.sequenceNumChildren([cellId], resolution)[0] @@ -144,14 +152,14 @@ function drawScene(cellId, resolution) { const childrenGeom = dggs.sequenceNumToGridFeatureCollection(state.childrenCells, resolution + 1) let parentGeom = null - if (state.parentCell !== null && resolution > 0) { - parentGeom = dggs.sequenceNumToGridFeatureCollection([state.parentCell], resolution - 1) + if (state.allParentCells.length > 0 && resolution > 0) { + parentGeom = dggs.sequenceNumToGridFeatureCollection(state.allParentCells, resolution - 1) } // Draw order: parent -> neighbors -> children -> center const features = [] if (parentGeom) { - features.push(...parentGeom.features.map(f => ({ ...f, _type: 'parent', _res: resolution - 1 }))) + features.push(...parentGeom.features.map((f, i) => ({ ...f, _type: i === 0 ? 'parent' : 'parent-secondary', _res: resolution - 1 }))) } features.push(...neighborGeom.features.map(f => ({ ...f, _type: 'neighbor', _res: resolution }))) features.push(...childrenGeom.features.map(f => ({ ...f, _type: 'child', _res: resolution + 1 }))) @@ -177,6 +185,7 @@ function drawScene(cellId, resolution) { const colorMap = { parent: '#33cc33', + 'parent-secondary': '#88cc88', neighbor: '#3399ff', center: '#ff3333', child: '#ffcc00', @@ -184,6 +193,7 @@ function drawScene(cellId, resolution) { const opacityMap = { parent: 0.25, + 'parent-secondary': 0.15, neighbor: 0.85, center: 0.35, child: 0.6, @@ -218,13 +228,15 @@ function drawScene(cellId, resolution) { // Parent outline on top if (parentGeom) { - svg.append('polygon') - .attr('points', parentGeom.features[0].geometry.coordinates[0].map(c => proj(c)).join(' ')) - .attr('fill', 'none') - .attr('stroke', '#33cc33') - .attr('stroke-width', 2.5) - .attr('stroke-dasharray', '6,3') - .attr('pointer-events', 'none') + parentGeom.features.forEach((f, i) => { + svg.append('polygon') + .attr('points', f.geometry.coordinates[0].map(c => proj(c)).join(' ')) + .attr('fill', 'none') + .attr('stroke', i === 0 ? '#33cc33' : '#88cc88') + .attr('stroke-width', i === 0 ? 2.5 : 1.5) + .attr('stroke-dasharray', '6,3') + .attr('pointer-events', 'none') + }) } // Center outline on top @@ -236,7 +248,7 @@ function drawScene(cellId, resolution) { .attr('pointer-events', 'none') // Draw index labels on cells (skip parent — too large) - const labelFeatures = features.filter(f => f._type !== 'parent') + const labelFeatures = features.filter(f => f._type !== 'parent' && f._type !== 'parent-secondary') const labelGroup = svg.append('g').attr('pointer-events', 'none') labelGroup.selectAll('text.cell-label') @@ -420,12 +432,15 @@ function loadScript(src) {
-
Parent
-
- +
Parents ({{ state.allParentCells.length }})
+
+
Root
@@ -646,6 +661,14 @@ function loadScript(src) { color: var(--vp-c-text-2); } .btn-parent { border-left: 3px solid #33cc33; } +.btn-primary-parent { font-weight: 600; } +.primary-tag { + font-size: 9px; + color: #1a8a1a; + margin-left: 4px; + text-transform: uppercase; + font-weight: 600; +} .btn-neighbor { border-left: 3px solid #3399ff; } .btn-child { border-left: 3px solid #ffcc00; } .muted { diff --git a/docs/.vitepress/theme/components/DggsGlobe.vue b/docs/.vitepress/theme/components/DggsGlobe.vue index f1c509a..3d04a23 100644 --- a/docs/.vitepress/theme/components/DggsGlobe.vue +++ b/docs/.vitepress/theme/components/DggsGlobe.vue @@ -59,6 +59,7 @@ const selectedCellId = ref(null) const selectedCellRes = ref(null) const hierarchyInfo = reactive({ parent: null, + allParents: [], children: [], neighbors: [], }) @@ -209,6 +210,7 @@ function generateGrid() { selectedCellId.value = null selectedCellRes.value = null hierarchyInfo.parent = null + hierarchyInfo.allParents = [] hierarchyInfo.children = [] hierarchyInfo.neighbors = [] removeHierarchyMapLayers() @@ -370,8 +372,14 @@ function selectCell(cellId, resolution) { hierarchyInfo.neighbors = webdggrid.sequenceNumNeighbors([seqnum], resolution)[0] } catch { hierarchyInfo.neighbors = [] } try { - hierarchyInfo.parent = resolution > 0 ? webdggrid.sequenceNumParent([seqnum], resolution)[0] : null - } catch { hierarchyInfo.parent = null } + if (resolution > 0) { + hierarchyInfo.allParents = webdggrid.sequenceNumAllParents([seqnum], resolution)[0] + hierarchyInfo.parent = hierarchyInfo.allParents[0] ?? null + } else { + hierarchyInfo.allParents = [] + hierarchyInfo.parent = null + } + } catch { hierarchyInfo.parent = null; hierarchyInfo.allParents = [] } try { hierarchyInfo.children = webdggrid.sequenceNumChildren([seqnum], resolution)[0] } catch { hierarchyInfo.children = [] } @@ -383,6 +391,7 @@ function clearSelection() { selectedCellId.value = null selectedCellRes.value = null hierarchyInfo.parent = null + hierarchyInfo.allParents = [] hierarchyInfo.children = [] hierarchyInfo.neighbors = [] removeHierarchyMapLayers() @@ -424,23 +433,38 @@ function updateHierarchyLayers(seqnum, resolution) { // Remove previous MapLibre hierarchy layers removeHierarchyMapLayers() - // --- Parent polygon --- - if (hierarchyInfo.parent !== null && resolution > 0) { + // --- Parent polygons (all touching parents) --- + if (hierarchyInfo.allParents.length > 0 && resolution > 0) { try { - const parentFc = sanitizeFc(webdggrid.sequenceNumToGridFeatureCollection([hierarchyInfo.parent], resolution - 1)) - console.log('Parent cell geometry:', JSON.stringify(parentFc.features[0]?.geometry)) + const parentFc = sanitizeFc(webdggrid.sequenceNumToGridFeatureCollection(hierarchyInfo.allParents, resolution - 1)) + // Tag primary vs secondary parents + parentFc.features.forEach((f, i) => { + f.properties._primary = i === 0 + }) map.addSource('hier-parent', { type: 'geojson', data: parentFc }) - map.addLayer({ id: 'hier-parent-fill', type: 'fill', source: 'hier-parent', paint: { 'fill-color': '#33cc33', 'fill-opacity': 0.15 } }) - map.addLayer({ id: 'hier-parent-line', type: 'line', source: 'hier-parent', paint: { 'line-color': '#33cc33', 'line-width': 3, 'line-dasharray': [3, 2] } }) - - // Parent label — offset upward so it doesn't overlap selected cell - const geo = webdggrid.sequenceNumToGeo([hierarchyInfo.parent], resolution - 1)[0] - const parentLabelFc = { type: 'FeatureCollection', features: [{ - type: 'Feature', - geometry: { type: 'Point', coordinates: [geo[0], geo[1]] }, - properties: { label: getCellIndexLabel(hierarchyInfo.parent, resolution - 1) }, - }] } - map.addSource('hier-labels-parent', { type: 'geojson', data: parentLabelFc }) + map.addLayer({ id: 'hier-parent-fill', type: 'fill', source: 'hier-parent', paint: { + 'fill-color': ['case', ['get', '_primary'], '#22cc55', '#66dd88'], + 'fill-opacity': ['case', ['get', '_primary'], 0.35, 0.25], + } }) + map.addLayer({ id: 'hier-parent-line', type: 'line', source: 'hier-parent', paint: { + 'line-color': ['case', ['get', '_primary'], '#11aa33', '#44bb66'], + 'line-width': ['case', ['get', '_primary'], 3.5, 2.5], + 'line-dasharray': [3, 2], + } }) + + // Parent labels + const parentLabelFeatures = hierarchyInfo.allParents.map((p, i) => { + const geo = webdggrid.sequenceNumToGeo([p], resolution - 1)[0] + return { + type: 'Feature', + geometry: { type: 'Point', coordinates: [geo[0], geo[1]] }, + properties: { + label: getCellIndexLabel(p, resolution - 1), + primary: i === 0, + }, + } + }) + map.addSource('hier-labels-parent', { type: 'geojson', data: { type: 'FeatureCollection', features: parentLabelFeatures } }) map.addLayer({ id: 'hier-labels-parent-text', type: 'symbol', @@ -448,11 +472,15 @@ function updateHierarchyLayers(seqnum, resolution) { layout: { 'text-field': ['get', 'label'], 'text-font': ['Open Sans Bold', 'Arial Unicode MS Bold'], - 'text-size': 13, + 'text-size': ['case', ['get', 'primary'], 13, 11], 'text-offset': [0, -2], 'text-allow-overlap': false, }, - paint: { 'text-color': '#1a8a1a', 'text-halo-color': 'rgba(255,255,255,0.95)', 'text-halo-width': 2 }, + paint: { + 'text-color': ['case', ['get', 'primary'], '#1a8a1a', '#5a9a5a'], + 'text-halo-color': 'rgba(255,255,255,0.95)', + 'text-halo-width': 2, + }, }) } catch (err) { console.error('Parent geometry error:', err) } } @@ -814,11 +842,13 @@ defineExpose({ getMap: () => map })
-
+
- Parent (res {{ selectedCellRes - 1 }}) + Parents ({{ hierarchyInfo.allParents.length }}, res {{ selectedCellRes - 1 }}) +
+
+ {{ p.toString() }}primary
-
{{ hierarchyInfo.parent.toString() }}
@@ -1136,6 +1166,15 @@ defineExpose({ getMap: () => map }) color: var(--vp-c-text-1); word-break: break-all; } +.hier-chip-parent { border-left: 2px solid #33cc33; } +.hier-chip-primary { font-weight: 600; } +.hier-primary-badge { + font-size: 8px; + font-weight: 600; + color: #1a8a1a; + margin-left: 3px; + text-transform: uppercase; +} .hier-chip-child { border-left: 2px solid #ffcc00; } .hier-chip-neighbor { border-left: 2px solid #3399ff; } .hier-hint { diff --git a/docs/api/classes/Webdggrid.md b/docs/api/classes/Webdggrid.md index af99777..70b7eda 100644 --- a/docs/api/classes/Webdggrid.md +++ b/docs/api/classes/Webdggrid.md @@ -2,7 +2,7 @@ # Class: Webdggrid -Defined in: [webdggrid.ts:252](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L252) +Defined in: [webdggrid.ts:252](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L252) Main entry point for the WebDggrid library. @@ -45,7 +45,7 @@ the returned instance throughout your application. Call > `protected` **\_module**: `any` -Defined in: [webdggrid.ts:275](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L275) +Defined in: [webdggrid.ts:275](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L275) *** @@ -53,7 +53,7 @@ Defined in: [webdggrid.ts:275](https://github.com/am2222/webDggrid/blob/16f19ca1 > **dggs**: [`IDGGSProps`](../interfaces/IDGGSProps.md) = `DEFAULT_DGGS` -Defined in: [webdggrid.ts:261](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L261) +Defined in: [webdggrid.ts:261](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L261) The active DGGS configuration used by all conversion and statistics methods. Change it at any time via [setDggs](#setdggs). @@ -67,7 +67,7 @@ pole at 0° N 0° E, azimuth 0°). > **resolution**: `number` = `DEFAULT_RESOLUTION` -Defined in: [webdggrid.ts:273](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L273) +Defined in: [webdggrid.ts:273](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L273) The active grid resolution. Higher values produce finer, smaller cells. The valid range depends on the aperture — for aperture 4 the practical @@ -78,13 +78,163 @@ argument to any conversion method. Defaults to `1`. +*** + +### Z3\_BITS\_PER\_DIGIT + +> `readonly` `static` **Z3\_BITS\_PER\_DIGIT**: `2n` = `2n` + +Defined in: [webdggrid.ts:1571](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1571) + +**`Internal`** + +*** + +### Z3\_DIGIT\_MASK + +> `readonly` `static` **Z3\_DIGIT\_MASK**: `3n` = `3n` + +Defined in: [webdggrid.ts:1572](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1572) + +**`Internal`** + +*** + +### Z3\_MAX\_RES + +> `readonly` `static` **Z3\_MAX\_RES**: `30` = `30` + +Defined in: [webdggrid.ts:1570](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1570) + +**`Internal`** + +*** + +### Z3\_QUAD\_MASK + +> `readonly` `static` **Z3\_QUAD\_MASK**: `17293822569102704640n` = `0xF000000000000000n` + +Defined in: [webdggrid.ts:1574](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1574) + +**`Internal`** + +*** + +### Z3\_QUAD\_OFFSET + +> `readonly` `static` **Z3\_QUAD\_OFFSET**: `60n` = `60n` + +Defined in: [webdggrid.ts:1573](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1573) + +**`Internal`** + +*** + +### Z7\_BITS\_PER\_DIGIT + +> `readonly` `static` **Z7\_BITS\_PER\_DIGIT**: `3n` = `3n` + +Defined in: [webdggrid.ts:1564](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1564) + +**`Internal`** + +*** + +### Z7\_DIGIT\_MASK + +> `readonly` `static` **Z7\_DIGIT\_MASK**: `7n` = `7n` + +Defined in: [webdggrid.ts:1565](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1565) + +**`Internal`** + +*** + +### Z7\_MAX\_RES + +> `readonly` `static` **Z7\_MAX\_RES**: `20` = `20` + +Defined in: [webdggrid.ts:1563](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1563) + +**`Internal`** + +*** + +### Z7\_QUAD\_MASK + +> `readonly` `static` **Z7\_QUAD\_MASK**: `17293822569102704640n` = `0xF000000000000000n` + +Defined in: [webdggrid.ts:1567](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1567) + +**`Internal`** + +*** + +### Z7\_QUAD\_OFFSET + +> `readonly` `static` **Z7\_QUAD\_OFFSET**: `60n` = `60n` + +Defined in: [webdggrid.ts:1566](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1566) + +**`Internal`** + +*** + +### ZORDER\_BITS\_PER\_DIGIT + +> `readonly` `static` **ZORDER\_BITS\_PER\_DIGIT**: `2n` = `2n` + +Defined in: [webdggrid.ts:1578](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1578) + +**`Internal`** + +*** + +### ZORDER\_DIGIT\_MASK + +> `readonly` `static` **ZORDER\_DIGIT\_MASK**: `3n` = `3n` + +Defined in: [webdggrid.ts:1579](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1579) + +**`Internal`** + +*** + +### ZORDER\_MAX\_RES + +> `readonly` `static` **ZORDER\_MAX\_RES**: `30` = `30` + +Defined in: [webdggrid.ts:1577](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1577) + +**`Internal`** + +*** + +### ZORDER\_QUAD\_MASK + +> `readonly` `static` **ZORDER\_QUAD\_MASK**: `17293822569102704640n` = `0xF000000000000000n` + +Defined in: [webdggrid.ts:1581](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1581) + +**`Internal`** + +*** + +### ZORDER\_QUAD\_OFFSET + +> `readonly` `static` **ZORDER\_QUAD\_OFFSET**: `60n` = `60n` + +Defined in: [webdggrid.ts:1580](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1580) + +**`Internal`** + ## Methods ### \_main() > **\_main**(): `any` -Defined in: [webdggrid.ts:386](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L386) +Defined in: [webdggrid.ts:386](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L386) **`Internal`** @@ -101,7 +251,7 @@ Not intended for production use. > **cellAreaKM**(`resolution?`): `number` -Defined in: [webdggrid.ts:457](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L457) +Defined in: [webdggrid.ts:457](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L457) Returns the average area of a single cell in square kilometres at the given resolution. @@ -134,7 +284,7 @@ Average cell area in km². > **cellDistKM**(`resolution?`): `number` -Defined in: [webdggrid.ts:500](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L500) +Defined in: [webdggrid.ts:500](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L500) Returns the average centre-to-centre distance between neighbouring cells in kilometres at the given resolution. @@ -167,7 +317,7 @@ Average cell spacing in km. > **geoToGeo**(`coordinates`, `resolution?`): `Position`[] -Defined in: [webdggrid.ts:720](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L720) +Defined in: [webdggrid.ts:720](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L720) Snaps an array of geographic coordinates to the centroid of the DGGS cell that contains each point. @@ -217,7 +367,7 @@ Array of `[lng, lat]` cell centroid positions, one per input > **geoToPlane**(`coordinates`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1544](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1544) +Defined in: [webdggrid.ts:1845](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1845) Converts geographic coordinates to PLANE coordinates. @@ -247,7 +397,7 @@ Array of `{x, y}` plane coordinates > **geoToProjtri**(`coordinates`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1565](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1565) +Defined in: [webdggrid.ts:1866](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1866) Converts geographic coordinates to PROJTRI coordinates. @@ -277,7 +427,7 @@ Array of `{tnum, x, y}` projection triangle coordinates > **geoToQ2dd**(`coordinates`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1590](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1590) +Defined in: [webdggrid.ts:1891](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1891) Converts geographic coordinates to Q2DD coordinates. @@ -307,7 +457,7 @@ Array of `{quad, x, y}` quad 2D double coordinates > **geoToQ2di**(`coordinates`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1615](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1615) +Defined in: [webdggrid.ts:1916](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1916) Converts geographic coordinates to Q2DI coordinates. @@ -337,7 +487,7 @@ Array of `{quad, i, j}` quad 2D integer coordinates > **geoToSequenceNum**(`coordinates`, `resolution?`): `bigint`[] -Defined in: [webdggrid.ts:601](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L601) +Defined in: [webdggrid.ts:601](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L601) Converts an array of geographic coordinates to their corresponding DGGS cell sequence numbers (cell IDs) at the given resolution. @@ -389,7 +539,7 @@ Array of `BigInt` sequence numbers, one per input coordinate, > **getResolution**(): `number` -Defined in: [webdggrid.ts:362](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L362) +Defined in: [webdggrid.ts:362](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L362) Returns the currently active grid resolution. @@ -410,7 +560,7 @@ The current resolution level. > **gridStatCLS**(`resolution?`): `number` -Defined in: [webdggrid.ts:544](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L544) +Defined in: [webdggrid.ts:544](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L544) Returns the characteristic length scale (CLS) of the grid at the given resolution — defined as the square root of the average cell area. @@ -444,7 +594,7 @@ Grid CLS value. > **nCells**(`resolution?`): `number` -Defined in: [webdggrid.ts:414](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L414) +Defined in: [webdggrid.ts:414](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L414) Returns the total number of cells that tile the entire globe at the given resolution under the current DGGS configuration. @@ -486,7 +636,7 @@ Total number of cells at the given resolution. > **projtriToGeo**(`coords`, `resolution?`): `Position`[] -Defined in: [webdggrid.ts:1962](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1962) +Defined in: [webdggrid.ts:2263](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2263) Converts PROJTRI coordinates to geographic coordinates. @@ -516,7 +666,7 @@ Array of `[lng, lat]` positions > **projtriToPlane**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1999](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1999) +Defined in: [webdggrid.ts:2300](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2300) Converts PROJTRI coordinates to PLANE coordinates. @@ -546,7 +696,7 @@ Array of `{x, y}` plane coordinates > **projtriToQ2dd**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:2021](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L2021) +Defined in: [webdggrid.ts:2322](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2322) Converts PROJTRI coordinates to Q2DD coordinates. @@ -576,7 +726,7 @@ Array of `{quad, x, y}` quad 2D double coordinates > **projtriToQ2di**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:2047](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L2047) +Defined in: [webdggrid.ts:2348](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2348) Converts PROJTRI coordinates to Q2DI coordinates. @@ -606,7 +756,7 @@ Array of `{quad, i, j}` quad 2D integer coordinates > **projtriToSequenceNum**(`coords`, `resolution?`): `bigint`[] -Defined in: [webdggrid.ts:1984](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1984) +Defined in: [webdggrid.ts:2285](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2285) Converts PROJTRI coordinates to sequence numbers. @@ -636,7 +786,7 @@ Array of cell IDs > **q2ddToGeo**(`coords`, `resolution?`): `Position`[] -Defined in: [webdggrid.ts:1847](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1847) +Defined in: [webdggrid.ts:2148](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2148) Converts Q2DD coordinates to geographic coordinates. @@ -666,7 +816,7 @@ Array of `[lng, lat]` positions > **q2ddToPlane**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1884](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1884) +Defined in: [webdggrid.ts:2185](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2185) Converts Q2DD coordinates to PLANE coordinates. @@ -696,7 +846,7 @@ Array of `{x, y}` plane coordinates > **q2ddToProjtri**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1906](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1906) +Defined in: [webdggrid.ts:2207](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2207) Converts Q2DD coordinates to PROJTRI coordinates. @@ -726,7 +876,7 @@ Array of `{tnum, x, y}` projection triangle coordinates > **q2ddToQ2di**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1932](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1932) +Defined in: [webdggrid.ts:2233](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2233) Converts Q2DD coordinates to Q2DI coordinates. @@ -756,7 +906,7 @@ Array of `{quad, i, j}` quad 2D integer coordinates > **q2ddToSequenceNum**(`coords`, `resolution?`): `bigint`[] -Defined in: [webdggrid.ts:1869](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1869) +Defined in: [webdggrid.ts:2170](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2170) Converts Q2DD coordinates to sequence numbers. @@ -786,7 +936,7 @@ Array of cell IDs > **q2diToGeo**(`coords`, `resolution?`): `Position`[] -Defined in: [webdggrid.ts:1732](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1732) +Defined in: [webdggrid.ts:2033](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2033) Converts Q2DI coordinates to geographic coordinates. @@ -816,7 +966,7 @@ Array of `[lng, lat]` positions > **q2diToPlane**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1769](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1769) +Defined in: [webdggrid.ts:2070](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2070) Converts Q2DI coordinates to PLANE coordinates. @@ -846,7 +996,7 @@ Array of `{x, y}` plane coordinates > **q2diToProjtri**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1791](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1791) +Defined in: [webdggrid.ts:2092](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2092) Converts Q2DI coordinates to PROJTRI coordinates. @@ -876,7 +1026,7 @@ Array of `{tnum, x, y}` projection triangle coordinates > **q2diToQ2dd**(`coords`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1817](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1817) +Defined in: [webdggrid.ts:2118](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2118) Converts Q2DI coordinates to Q2DD coordinates. @@ -906,7 +1056,7 @@ Array of `{quad, x, y}` quad 2D double coordinates > **q2diToSequenceNum**(`coords`, `resolution?`): `bigint`[] -Defined in: [webdggrid.ts:1754](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1754) +Defined in: [webdggrid.ts:2055](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2055) Converts Q2DI coordinates to sequence numbers. @@ -932,11 +1082,64 @@ Array of cell IDs *** +### sequenceNumAllParents() + +> **sequenceNumAllParents**(`sequenceNum`, `resolution?`): `bigint`[][] + +Defined in: [webdggrid.ts:1082](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1082) + +Returns **all** parent cells that touch each input cell at the coarser +resolution (resolution - 1). + +Unlike [sequenceNumParent](#sequencenumparent) which returns only the primary +(containing) parent, this method returns every parent cell whose area +overlaps with the child cell. For interior cells this is typically 1; +for cells on a parent boundary it may be 2 or more. + +The **first element** of each inner array is always the primary +(containing) parent — the same value returned by +[sequenceNumParent](#sequencenumparent). + +```ts +const allParents = dggs.sequenceNumAllParents([256n], 3); +// allParents[0] = [65n, 66n] — 65 is the containing parent, +// 66 is a touching neighbor parent +``` + +#### Parameters + +##### sequenceNum + +`bigint`[] + +Array of `BigInt` cell IDs to query. + +##### resolution? + +`number` = `DEFAULT_RESOLUTION` + +Resolution at which the input IDs were generated + (must be > 0). Defaults to the instance's current [resolution](#sequencenumallparents). + +#### Returns + +`bigint`[][] + +A 2-D array: `result[i]` contains all parent cell IDs that + touch `sequenceNum[i]`, with the primary parent first. + +#### Throws + +If `resolution` is 0 or negative, or if an invalid cell ID is + provided. + +*** + ### sequenceNumChildren() > **sequenceNumChildren**(`sequenceNum`, `resolution?`): `bigint`[][] -Defined in: [webdggrid.ts:1085](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1085) +Defined in: [webdggrid.ts:1142](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1142) Returns all child cells at the next finer resolution (resolution + 1) for each input cell. @@ -992,7 +1195,7 @@ If an invalid cell ID is provided or if the maximum resolution > **sequenceNumNeighbors**(`sequenceNum`, `resolution?`): `bigint`[][] -Defined in: [webdggrid.ts:935](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L935) +Defined in: [webdggrid.ts:935](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L935) Returns all neighboring cells (sharing an edge) for each input cell. @@ -1045,7 +1248,7 @@ If Triangle topology is used or if an invalid cell ID is provided. > **sequenceNumParent**(`sequenceNum`, `resolution?`): `bigint`[] -Defined in: [webdggrid.ts:1014](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1014) +Defined in: [webdggrid.ts:1014](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1014) Returns the parent cell at the next coarser resolution (resolution - 1) for each input cell. @@ -1096,7 +1299,7 @@ If resolution is 0 or if an invalid cell ID is provided. > **sequenceNumToGeo**(`sequenceNum`, `resolution?`): `Position`[] -Defined in: [webdggrid.ts:655](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L655) +Defined in: [webdggrid.ts:655](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L655) Converts an array of DGGS cell sequence numbers to the geographic coordinates of their centroids. @@ -1137,7 +1340,7 @@ Array of `[lng, lat]` centroid positions, one per input ID, in > **sequenceNumToGrid**(`sequenceNum`, `resolution?`): `Position`[][] -Defined in: [webdggrid.ts:785](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L785) +Defined in: [webdggrid.ts:785](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L785) Returns the polygon boundary vertices for each cell in `sequenceNum`. @@ -1186,7 +1389,7 @@ If the WASM module encounters an invalid cell ID. > **sequenceNumToGridFeatureCollection**(`sequenceNum`, `resolution?`): `FeatureCollection`\<`Polygon`, `object` & `object`\> -Defined in: [webdggrid.ts:880](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L880) +Defined in: [webdggrid.ts:880](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L880) Converts an array of DGGS cell IDs into a GeoJSON `FeatureCollection` where each `Feature` is a `Polygon` representing the cell boundary. @@ -1242,7 +1445,7 @@ A GeoJSON `FeatureCollection` of `Polygon` features, one per > **sequenceNumToPlane**(`sequenceNum`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1644](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1644) +Defined in: [webdggrid.ts:1945](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1945) Converts sequence numbers to PLANE coordinates. @@ -1272,7 +1475,7 @@ Array of `{x, y}` plane coordinates > **sequenceNumToProjtri**(`sequenceNum`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1662](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1662) +Defined in: [webdggrid.ts:1963](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1963) Converts sequence numbers to PROJTRI coordinates. @@ -1302,7 +1505,7 @@ Array of `{tnum, x, y}` projection triangle coordinates > **sequenceNumToQ2dd**(`sequenceNum`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1684](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1684) +Defined in: [webdggrid.ts:1985](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1985) Converts sequence numbers to Q2DD coordinates. @@ -1332,7 +1535,7 @@ Array of `{quad, x, y}` quad 2D double coordinates > **sequenceNumToQ2di**(`sequenceNum`, `resolution?`): `object`[] -Defined in: [webdggrid.ts:1706](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1706) +Defined in: [webdggrid.ts:2007](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L2007) Converts sequence numbers to Q2DI coordinates. @@ -1362,7 +1565,7 @@ Array of `{quad, i, j}` quad 2D integer coordinates > **sequenceNumToVertex2DD**(`sequenceNum`, `resolution?`): [`Vertex2DDCoordinate`](../interfaces/Vertex2DDCoordinate.md) -Defined in: [webdggrid.ts:1157](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1157) +Defined in: [webdggrid.ts:1214](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1214) Convert a SEQNUM cell ID to VERTEX2DD (icosahedral vertex) coordinates. @@ -1402,7 +1605,7 @@ An object with `{keep, vertNum, triNum, x, y}` representing > **sequenceNumToZ3**(`sequenceNum`, `resolution?`): `bigint` -Defined in: [webdggrid.ts:1329](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1329) +Defined in: [webdggrid.ts:1386](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1386) Convert a SEQNUM cell ID to Z3 (base-3 Central Place Indexing) coordinate. @@ -1448,7 +1651,7 @@ If used with an incompatible aperture (not 3) or topology. > **sequenceNumToZ7**(`sequenceNum`, `resolution?`): `bigint` -Defined in: [webdggrid.ts:1424](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1424) +Defined in: [webdggrid.ts:1481](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1481) Convert a SEQNUM cell ID to Z7 (base-7 Central Place Indexing) coordinate. @@ -1495,7 +1698,7 @@ If used with an incompatible aperture (not 7) or topology. > **sequenceNumToZOrder**(`sequenceNum`, `resolution?`): `bigint` -Defined in: [webdggrid.ts:1234](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1234) +Defined in: [webdggrid.ts:1291](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1291) Convert a SEQNUM cell ID to ZORDER (Z-order curve) coordinate. @@ -1542,7 +1745,7 @@ If used with an incompatible aperture (7) or topology. > **setDggs**(`dggs?`, `resolution?`): `void` -Defined in: [webdggrid.ts:347](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L347) +Defined in: [webdggrid.ts:347](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L347) Sets both the DGGS configuration and the resolution in one call. @@ -1583,7 +1786,7 @@ The new resolution level. Defaults to `1`. > **setResolution**(`resolution`): `void` -Defined in: [webdggrid.ts:377](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L377) +Defined in: [webdggrid.ts:377](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L377) Sets the grid resolution used by default in all conversion and statistics methods. @@ -1611,7 +1814,7 @@ The new resolution level. Must be a positive integer. > **version**(): `string` -Defined in: [webdggrid.ts:324](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L324) +Defined in: [webdggrid.ts:324](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L324) Returns the version string of the underlying DGGRID C++ library. @@ -1631,7 +1834,7 @@ The DGGRID C++ library version string. > **vertex2DDToSequenceNum**(`keep`, `vertNum`, `triNum`, `x`, `y`, `resolution?`): `bigint` -Defined in: [webdggrid.ts:1190](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1190) +Defined in: [webdggrid.ts:1247](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1247) Convert VERTEX2DD (icosahedral vertex) coordinates to a SEQNUM cell ID. @@ -1687,11 +1890,159 @@ The sequence number (BigInt) of the cell containing this coordinate. *** +### z3ExtractDigits() + +> **z3ExtractDigits**(`z3Value`, `resolution`): `object` + +Defined in: [webdggrid.ts:1720](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1720) + +Extract all digits from a Z3 index up to a given resolution. + +```ts +const { quad, digits } = dggs.z3ExtractDigits(z3Value, 5); +// quad: 1, digits: [1, 0, 2, 1, 0] +``` + +#### Parameters + +##### z3Value + +`bigint` + +A Z3 packed index (BigInt). + +##### resolution + +`number` + +Number of digits to extract (1-based). + +#### Returns + +`object` + +Object with `quad` (number) and `digits` (number array). + +##### digits + +> **digits**: `number`[] + +##### quad + +> **quad**: `number` + +*** + +### z3GetDigit() + +> **z3GetDigit**(`z3Value`, `res`): `number` + +Defined in: [webdggrid.ts:1686](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1686) + +Get the digit at a specific resolution level from a Z3 index. + +Each digit is 2 bits wide. Valid digits are 0–2; the value 3 is the +invalid/padding marker. + +```ts +const digit = dggs.z3GetDigit(z3Value, 3); // 0–2 (or 3 = invalid) +``` + +#### Parameters + +##### z3Value + +`bigint` + +A Z3 packed index (BigInt). + +##### res + +`number` + +Resolution level (1-based, 1 to 30). + +#### Returns + +`number` + +The digit value (0–3). + +*** + +### z3GetQuad() + +> **z3GetQuad**(`z3Value`): `number` + +Defined in: [webdggrid.ts:1668](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1668) + +Get the quad (icosahedron face) number from a Z3 index. + +```ts +const quad = dggs.z3GetQuad(z3Value); // 0–11 +``` + +#### Parameters + +##### z3Value + +`bigint` + +A Z3 packed index (BigInt). + +#### Returns + +`number` + +The quad number (0–11). + +*** + +### z3SetDigit() + +> **z3SetDigit**(`z3Value`, `res`, `digit`): `bigint` + +Defined in: [webdggrid.ts:1703](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1703) + +Set the digit at a specific resolution level in a Z3 index. + +```ts +const child = dggs.z3SetDigit(z3Value, 6, 1); // set res-6 digit to 1 +``` + +#### Parameters + +##### z3Value + +`bigint` + +A Z3 packed index (BigInt). + +##### res + +`number` + +Resolution level (1-based, 1 to 30). + +##### digit + +`number` + +The digit value to set (0–2, or 3 for invalid). + +#### Returns + +`bigint` + +A new Z3 value with the digit replaced. + +*** + ### z3ToSequenceNum() > **z3ToSequenceNum**(`z3Value`, `resolution?`): `bigint` -Defined in: [webdggrid.ts:1373](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1373) +Defined in: [webdggrid.ts:1430](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1430) Convert a Z3 (base-3 Central Place Indexing) coordinate to a SEQNUM cell ID. @@ -1727,11 +2078,163 @@ If used with an incompatible aperture (not 3) or topology. *** +### z7ExtractDigits() + +> **z7ExtractDigits**(`z7Value`, `resolution`): `object` + +Defined in: [webdggrid.ts:1649](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1649) + +Extract all digits from a Z7 index up to a given resolution. + +```ts +const { quad, digits } = dggs.z7ExtractDigits(z7Value, 5); +// quad: 1, digits: [2, 0, 3, 4, 1] +``` + +#### Parameters + +##### z7Value + +`bigint` + +A Z7 packed index (BigInt). + +##### resolution + +`number` + +Number of digits to extract (1-based). + +#### Returns + +`object` + +Object with `quad` (number) and `digits` (number array). + +##### digits + +> **digits**: `number`[] + +##### quad + +> **quad**: `number` + +*** + +### z7GetDigit() + +> **z7GetDigit**(`z7Value`, `res`): `number` + +Defined in: [webdggrid.ts:1613](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1613) + +Get the digit at a specific resolution level from a Z7 index. + +Each digit is 3 bits wide and occupies a fixed position in the 64-bit value. +Valid digits are 0–6; the value 7 is the invalid/padding marker. + +```ts +const digit = dggs.z7GetDigit(z7Value, 3); // 0–6 (or 7 = invalid) +``` + +#### Parameters + +##### z7Value + +`bigint` + +A Z7 packed index (BigInt). + +##### res + +`number` + +Resolution level (1-based, 1 to 20). + +#### Returns + +`number` + +The digit value (0–7). + +*** + +### z7GetQuad() + +> **z7GetQuad**(`z7Value`): `number` + +Defined in: [webdggrid.ts:1595](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1595) + +Get the quad (icosahedron face) number from a Z7 index. + +The quad occupies bits 63–60 of the 64-bit packed value. + +```ts +const quad = dggs.z7GetQuad(z7Value); // 0–11 +``` + +#### Parameters + +##### z7Value + +`bigint` + +A Z7 packed index (BigInt). + +#### Returns + +`number` + +The quad number (0–11). + +*** + +### z7SetDigit() + +> **z7SetDigit**(`z7Value`, `res`, `digit`): `bigint` + +Defined in: [webdggrid.ts:1632](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1632) + +Set the digit at a specific resolution level in a Z7 index. + +Returns a new Z7 value with the digit at position `res` replaced. + +```ts +const child = dggs.z7SetDigit(z7Value, 6, 3); // set res-6 digit to 3 +``` + +#### Parameters + +##### z7Value + +`bigint` + +A Z7 packed index (BigInt). + +##### res + +`number` + +Resolution level (1-based, 1 to 20). + +##### digit + +`number` + +The digit value to set (0–6, or 7 for invalid). + +#### Returns + +`bigint` + +A new Z7 value with the digit replaced. + +*** + ### z7ToSequenceNum() > **z7ToSequenceNum**(`z7Value`, `resolution?`): `bigint` -Defined in: [webdggrid.ts:1468](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1468) +Defined in: [webdggrid.ts:1525](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1525) Convert a Z7 (base-7 Central Place Indexing) coordinate to a SEQNUM cell ID. @@ -1767,11 +2270,158 @@ If used with an incompatible aperture (not 7) or topology. *** +### zOrderExtractDigits() + +> **zOrderExtractDigits**(`zorderValue`, `resolution`): `object` + +Defined in: [webdggrid.ts:1790](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1790) + +Extract all digits from a ZORDER index up to a given resolution. + +```ts +const { quad, digits } = dggs.zOrderExtractDigits(zorderValue, 5); +// quad: 1, digits: [2, 0, 3, 1, 0] +``` + +#### Parameters + +##### zorderValue + +`bigint` + +A ZORDER packed index (BigInt). + +##### resolution + +`number` + +Number of digits to extract (1-based). + +#### Returns + +`object` + +Object with `quad` (number) and `digits` (number array). + +##### digits + +> **digits**: `number`[] + +##### quad + +> **quad**: `number` + +*** + +### zOrderGetDigit() + +> **zOrderGetDigit**(`zorderValue`, `res`): `number` + +Defined in: [webdggrid.ts:1756](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1756) + +Get the digit at a specific resolution level from a ZORDER index. + +Each digit is 2 bits wide (values 0–3). + +```ts +const digit = dggs.zOrderGetDigit(zorderValue, 3); // 0–3 +``` + +#### Parameters + +##### zorderValue + +`bigint` + +A ZORDER packed index (BigInt). + +##### res + +`number` + +Resolution level (1-based, 1 to 30). + +#### Returns + +`number` + +The digit value (0–3). + +*** + +### zOrderGetQuad() + +> **zOrderGetQuad**(`zorderValue`): `number` + +Defined in: [webdggrid.ts:1739](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1739) + +Get the quad (icosahedron face) number from a ZORDER index. + +```ts +const quad = dggs.zOrderGetQuad(zorderValue); // 0–11 +``` + +#### Parameters + +##### zorderValue + +`bigint` + +A ZORDER packed index (BigInt). + +#### Returns + +`number` + +The quad number (0–11). + +*** + +### zOrderSetDigit() + +> **zOrderSetDigit**(`zorderValue`, `res`, `digit`): `bigint` + +Defined in: [webdggrid.ts:1773](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1773) + +Set the digit at a specific resolution level in a ZORDER index. + +```ts +const modified = dggs.zOrderSetDigit(zorderValue, 3, 2); +``` + +#### Parameters + +##### zorderValue + +`bigint` + +A ZORDER packed index (BigInt). + +##### res + +`number` + +Resolution level (1-based, 1 to 30). + +##### digit + +`number` + +The digit value to set (0–3). + +#### Returns + +`bigint` + +A new ZORDER value with the digit replaced. + +*** + ### zOrderToSequenceNum() > **zOrderToSequenceNum**(`zorderValue`, `resolution?`): `bigint` -Defined in: [webdggrid.ts:1279](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L1279) +Defined in: [webdggrid.ts:1336](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L1336) Convert a ZORDER (Z-order curve) coordinate to a SEQNUM cell ID. @@ -1811,7 +2461,7 @@ If used with an incompatible aperture (7) or topology. > `static` **load**(): `Promise`\<*typeof* `Webdggrid`\> -Defined in: [webdggrid.ts:298](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L298) +Defined in: [webdggrid.ts:298](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L298) Compiles and instantiates the DGGRID WebAssembly module. @@ -1841,7 +2491,7 @@ A promise that resolves to a fully initialised `Webdggrid` instance. > `static` **unload**(): `void` -Defined in: [webdggrid.ts:311](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L311) +Defined in: [webdggrid.ts:311](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L311) Releases the compiled WASM instance and frees its memory. diff --git a/docs/api/enumerations/Projection.md b/docs/api/enumerations/Projection.md index 8201916..884dc51 100644 --- a/docs/api/enumerations/Projection.md +++ b/docs/api/enumerations/Projection.md @@ -2,7 +2,7 @@ # Enumeration: Projection -Defined in: [webdggrid.ts:49](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L49) +Defined in: [webdggrid.ts:49](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L49) The map projection used to place the polyhedron faces onto the sphere. @@ -27,7 +27,7 @@ dggs.setDggs({ projection: Projection.ISEA, ... }, 4); > **FULLER**: `"FULLER"` -Defined in: [webdggrid.ts:53](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L53) +Defined in: [webdggrid.ts:53](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L53) Fuller/Dymaxion projection — shape-preserving cells. @@ -37,6 +37,6 @@ Fuller/Dymaxion projection — shape-preserving cells. > **ISEA**: `"ISEA"` -Defined in: [webdggrid.ts:51](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L51) +Defined in: [webdggrid.ts:51](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L51) Icosahedral Snyder Equal Area projection — equal-area cells. diff --git a/docs/api/enumerations/Topology.md b/docs/api/enumerations/Topology.md index 6725844..9c6e0c4 100644 --- a/docs/api/enumerations/Topology.md +++ b/docs/api/enumerations/Topology.md @@ -2,7 +2,7 @@ # Enumeration: Topology -Defined in: [webdggrid.ts:22](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L22) +Defined in: [webdggrid.ts:22](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L22) The shape of each cell in the Discrete Global Grid System. @@ -26,7 +26,7 @@ dggs.setDggs({ topology: Topology.HEXAGON, ... }, 4); > **DIAMOND**: `"DIAMOND"` -Defined in: [webdggrid.ts:28](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L28) +Defined in: [webdggrid.ts:28](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L28) Four-sided diamond cells (squares rotated 45°). @@ -36,7 +36,7 @@ Four-sided diamond cells (squares rotated 45°). > **HEXAGON**: `"HEXAGON"` -Defined in: [webdggrid.ts:24](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L24) +Defined in: [webdggrid.ts:24](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L24) Six-sided cells — the default and most widely used topology. @@ -46,6 +46,6 @@ Six-sided cells — the default and most widely used topology. > **TRIANGLE**: `"TRIANGLE"` -Defined in: [webdggrid.ts:26](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L26) +Defined in: [webdggrid.ts:26](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L26) Three-sided cells. diff --git a/docs/api/functions/unwrapAntimeridianRing.md b/docs/api/functions/unwrapAntimeridianRing.md index 0c089ab..792de86 100644 --- a/docs/api/functions/unwrapAntimeridianRing.md +++ b/docs/api/functions/unwrapAntimeridianRing.md @@ -4,7 +4,7 @@ > **unwrapAntimeridianRing**(`ring`): `Position`[] -Defined in: [webdggrid.ts:195](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L195) +Defined in: [webdggrid.ts:195](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L195) Rewraps a polygon ring that crosses the antimeridian so that all longitudes are in a contiguous range (some may exceed 180°). This is the format diff --git a/docs/api/index.md b/docs/api/index.md index eb6c377..2e75f8e 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -56,10 +56,47 @@ const seqNum = dggs.geoToSequenceNum([[0, 0]]); ``` +## Live Demos + +- [Globe Demo](https://am2222.github.io/webDggrid/demo) — interactive MapLibre globe with topology switching, multi-aperture grids, and hierarchical cell selection +- [Hierarchical Operations Demo](https://am2222.github.io/webDggrid/hierarchical-operations#interactive-demo) — explore parent, children, and neighbor relationships +- [Address Types Demo](https://am2222.github.io/webDggrid/hierarchical-addresses#interactive-demo) — compare index types and see bitwise digit breakdowns +- [Index Arithmetic Demo](https://am2222.github.io/webDggrid/index-arithmetic#interactive-demo) — live demonstration of digit manipulation on Z3, Z7, and ZORDER indices + ## API -### Core Methods -`setDggs` · `getResolution` · `setResolution` · `geoToSequenceNum` · `sequenceNumToGeo` · `sequenceNumToGrid` · `sequenceNumToGridFeatureCollection` · `geoToGeo` · `cellAreaKM` · `cellDistKM` · `nCells` +### Lifecycle +`Webdggrid.load` · `Webdggrid.unload` + +### Configuration +`setDggs` · `getResolution` · `setResolution` · `version` + +### Coordinate Conversion +`geoToSequenceNum` · `sequenceNumToGeo` · `geoToGeo` · `sequenceNumToGrid` · `sequenceNumToGridFeatureCollection` + +### Grid Statistics +`nCells` · `cellAreaKM` · `cellDistKM` · `gridStatCLS` + +### Hierarchical Operations +`sequenceNumNeighbors` · `sequenceNumParent` · `sequenceNumAllParents` · `sequenceNumChildren` + +### Hierarchical Address Types +`sequenceNumToVertex2DD` · `vertex2DDToSequenceNum` · `sequenceNumToZOrder` · `zOrderToSequenceNum` · `sequenceNumToZ3` · `z3ToSequenceNum` · `sequenceNumToZ7` · `z7ToSequenceNum` + +### Index Digit Manipulation +`z7GetQuad` · `z7GetDigit` · `z7SetDigit` · `z7ExtractDigits` · `z3GetQuad` · `z3GetDigit` · `z3SetDigit` · `z3ExtractDigits` · `zOrderGetQuad` · `zOrderGetDigit` · `zOrderSetDigit` · `zOrderExtractDigits` + +### Low-Level Coordinate Systems +`geoToPlane` · `geoToProjtri` · `geoToQ2dd` · `geoToQ2di` · `sequenceNumToPlane` · `sequenceNumToProjtri` · `sequenceNumToQ2dd` · `sequenceNumToQ2di` + +### Q2DI Conversions +`q2diToGeo` · `q2diToSequenceNum` · `q2diToPlane` · `q2diToProjtri` · `q2diToQ2dd` + +### Q2DD Conversions +`q2ddToGeo` · `q2ddToSequenceNum` · `q2ddToPlane` · `q2ddToProjtri` · `q2ddToQ2di` + +### PROJTRI Conversions +`projtriToGeo` · `projtriToSequenceNum` · `projtriToPlane` · `projtriToQ2dd` · `projtriToQ2di` ### Multi-Aperture Support diff --git a/docs/api/interfaces/Coordinate.md b/docs/api/interfaces/Coordinate.md index 4c74861..4a67323 100644 --- a/docs/api/interfaces/Coordinate.md +++ b/docs/api/interfaces/Coordinate.md @@ -2,7 +2,7 @@ # Interface: Coordinate -Defined in: [webdggrid.ts:65](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L65) +Defined in: [webdggrid.ts:65](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L65) A simple geographic coordinate expressed as latitude and longitude in decimal degrees (WGS-84). @@ -19,7 +19,7 @@ const coord: Coordinate = { lat: 51.5, lng: -0.1 }; > **lat**: `number` -Defined in: [webdggrid.ts:67](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L67) +Defined in: [webdggrid.ts:67](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L67) Latitude in decimal degrees. Range: −90 to 90. @@ -29,6 +29,6 @@ Latitude in decimal degrees. Range: −90 to 90. > **lng**: `number` -Defined in: [webdggrid.ts:69](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L69) +Defined in: [webdggrid.ts:69](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L69) Longitude in decimal degrees. Range: −180 to 180. diff --git a/docs/api/interfaces/IDGGSProps.md b/docs/api/interfaces/IDGGSProps.md index b32540a..3190da4 100644 --- a/docs/api/interfaces/IDGGSProps.md +++ b/docs/api/interfaces/IDGGSProps.md @@ -2,7 +2,7 @@ # Interface: IDGGSProps -Defined in: [webdggrid.ts:136](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L136) +Defined in: [webdggrid.ts:136](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L136) Full configuration of a Discrete Global Grid System. @@ -32,7 +32,7 @@ dggs.setDggs(myDggs, 5); > `optional` **aperture?**: `7` \| `3` \| `4` \| `5` -Defined in: [webdggrid.ts:162](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L162) +Defined in: [webdggrid.ts:162](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L162) Subdivision aperture — the number of child cells each parent cell is divided into when moving to the next finer resolution. @@ -52,7 +52,7 @@ Ignored if `apertureSequence` is specified. > `optional` **apertureSequence?**: `string` -Defined in: [webdggrid.ts:181](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L181) +Defined in: [webdggrid.ts:181](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L181) Mixed aperture sequence (e.g., `"434747"`). @@ -78,7 +78,7 @@ apertureSequence: "434747" > **azimuth**: `number` -Defined in: [webdggrid.ts:148](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L148) +Defined in: [webdggrid.ts:148](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L148) Azimuth of the icosahedron pole in decimal degrees. Rotates the grid around the pole axis. Defaults to `0`. @@ -89,7 +89,7 @@ Rotates the grid around the pole axis. Defaults to `0`. > **poleCoordinates**: [`Coordinate`](Coordinate.md) -Defined in: [webdggrid.ts:143](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L143) +Defined in: [webdggrid.ts:143](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L143) Geographic location of the icosahedron pole used to orient the grid. Changing this rotates the entire grid on the globe, which can be used @@ -102,7 +102,7 @@ Defaults to `{ lat: 0, lng: 0 }`. > **projection**: [`Projection`](../enumerations/Projection.md) -Defined in: [webdggrid.ts:185](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L185) +Defined in: [webdggrid.ts:185](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L185) Projection used to map the polyhedron faces onto the sphere. See [Projection](../enumerations/Projection.md). @@ -112,6 +112,6 @@ Projection used to map the polyhedron faces onto the sphere. See [Projection](.. > **topology**: [`Topology`](../enumerations/Topology.md) -Defined in: [webdggrid.ts:183](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L183) +Defined in: [webdggrid.ts:183](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L183) Shape of each cell. See [Topology](../enumerations/Topology.md). diff --git a/docs/api/interfaces/Vertex2DDCoordinate.md b/docs/api/interfaces/Vertex2DDCoordinate.md index a04c75b..9ae1087 100644 --- a/docs/api/interfaces/Vertex2DDCoordinate.md +++ b/docs/api/interfaces/Vertex2DDCoordinate.md @@ -2,7 +2,7 @@ # Interface: Vertex2DDCoordinate -Defined in: [webdggrid.ts:78](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L78) +Defined in: [webdggrid.ts:78](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L78) VERTEX2DD coordinate representation. @@ -15,7 +15,7 @@ faces in DGGRID's coordinate system. > **keep**: `boolean` -Defined in: [webdggrid.ts:80](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L80) +Defined in: [webdggrid.ts:80](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L80) Whether to keep this vertex. @@ -25,7 +25,7 @@ Whether to keep this vertex. > **triNum**: `number` -Defined in: [webdggrid.ts:84](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L84) +Defined in: [webdggrid.ts:84](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L84) Triangle number on the icosahedron. @@ -35,7 +35,7 @@ Triangle number on the icosahedron. > **vertNum**: `number` -Defined in: [webdggrid.ts:82](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L82) +Defined in: [webdggrid.ts:82](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L82) Vertex number (0-11 for icosahedron). @@ -45,7 +45,7 @@ Vertex number (0-11 for icosahedron). > **x**: `number` -Defined in: [webdggrid.ts:86](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L86) +Defined in: [webdggrid.ts:86](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L86) X coordinate within the triangle. @@ -55,6 +55,6 @@ X coordinate within the triangle. > **y**: `number` -Defined in: [webdggrid.ts:88](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L88) +Defined in: [webdggrid.ts:88](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L88) Y coordinate within the triangle. diff --git a/docs/api/type-aliases/DGGSGeoJsonProperty.md b/docs/api/type-aliases/DGGSGeoJsonProperty.md index 51f19aa..54caf6a 100644 --- a/docs/api/type-aliases/DGGSGeoJsonProperty.md +++ b/docs/api/type-aliases/DGGSGeoJsonProperty.md @@ -4,7 +4,7 @@ > **DGGSGeoJsonProperty** = `GeoJsonProperties` & `object` -Defined in: [webdggrid.ts:102](https://github.com/am2222/webDggrid/blob/16f19ca15fe4f253b39e62ee2d6a6a107f5964b9/src-ts/webdggrid.ts#L102) +Defined in: [webdggrid.ts:102](https://github.com/am2222/webDggrid/blob/7917cb44f49dfd54c006cb0b682993cf9f954743/src-ts/webdggrid.ts#L102) GeoJSON `properties` object attached to every cell feature returned by [Webdggrid.sequenceNumToGridFeatureCollection](../classes/Webdggrid.md#sequencenumtogridfeaturecollection). diff --git a/docs/coordinate-transformations.md b/docs/coordinate-transformations.md index 2450b06..36ebe6f 100644 --- a/docs/coordinate-transformations.md +++ b/docs/coordinate-transformations.md @@ -206,6 +206,6 @@ All possible transformations: ## See Also -- [API Reference - Webdggrid class](classes/Webdggrid.md) +- [API Reference - Webdggrid class](api/classes/Webdggrid.md) - [examples/multi-aperture-example.mjs](../examples/multi-aperture-example.mjs) - [tests/unit/coordinate-transforms.test.ts](../tests/unit/coordinate-transforms.test.ts) diff --git a/docs/examples.md b/docs/examples.md index d2fbf74..48666dc 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -99,7 +99,6 @@ console.log('Features:', geojson.features.length); // 2 ## Additional Resources - [API Documentation](api/classes/Webdggrid.md) -- [Testing Guide](testing.md) - [Multi-Aperture Documentation](multi-aperture.md) - [Coordinate Transformations](coordinate-transformations.md) diff --git a/docs/getting-started.md b/docs/getting-started.md index 5f876fd..7ae0e90 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -130,7 +130,8 @@ const distkm = dggs.cellDistKM(3); // average cell spacing in km | Method | Description | |--------|-------------| | [`sequenceNumNeighbors()`](api/classes/Webdggrid.md#sequencenumneighbors) | Find edge-sharing neighbor cells | -| [`sequenceNumParent()`](api/classes/Webdggrid.md#sequencenumparent) | Get parent cell at coarser resolution | +| [`sequenceNumParent()`](api/classes/Webdggrid.md#sequencenumparent) | Get primary (containing) parent at coarser resolution | +| [`sequenceNumAllParents()`](api/classes/Webdggrid.md#sequencenumallparents) | Get all touching parent cells (primary first) | | [`sequenceNumChildren()`](api/classes/Webdggrid.md#sequencenumchildren) | Get child cells at finer resolution | ### Hierarchical Address Types diff --git a/docs/hierarchical-operations.md b/docs/hierarchical-operations.md index f977cd8..fe40dd9 100644 --- a/docs/hierarchical-operations.md +++ b/docs/hierarchical-operations.md @@ -362,10 +362,29 @@ try { } ``` +## Primary vs All Parents + +`sequenceNumParent()` returns the **primary (containing) parent** — the coarser-resolution cell whose center is closest to the child cell's center. This is determined by converting the child's center point to the parent resolution. + +For cells that lie on the **boundary** between two or more parent cells, `sequenceNumAllParents()` returns all touching parents. The primary parent is always first in the returned array. + +```ts +// Primary parent only (most common use case) +const parent = dggs.sequenceNumParent([cellId], 5)[0]; + +// All touching parents (boundary analysis) +const allParents = dggs.sequenceNumAllParents([cellId], 5)[0]; +// allParents[0] is the primary (containing) parent +// allParents[1..n] are additional touching parents (if any) +``` + +Interior cells typically have 1 parent. Boundary cells may have 2–3 parents depending on the aperture and topology. + ## API Reference | Method | Description | |--------|-------------| | [`sequenceNumNeighbors()`](api/classes/Webdggrid.md#sequencenumneighbors) | Find all cells sharing an edge with the input cells | -| [`sequenceNumParent()`](api/classes/Webdggrid.md#sequencenumparent) | Get parent cell at `resolution - 1` | +| [`sequenceNumParent()`](api/classes/Webdggrid.md#sequencenumparent) | Get the primary (containing) parent at `resolution - 1` | +| [`sequenceNumAllParents()`](api/classes/Webdggrid.md#sequencenumallparents) | Get all touching parent cells at `resolution - 1` (primary first) | | [`sequenceNumChildren()`](api/classes/Webdggrid.md#sequencenumchildren) | Get child cells at `resolution + 1` | diff --git a/readme.md b/readme.md index 323152f..8cb1f4f 100644 --- a/readme.md +++ b/readme.md @@ -81,7 +81,7 @@ const seqNum = dggs.geoToSequenceNum([[0, 0]]); `nCells` · `cellAreaKM` · `cellDistKM` · `gridStatCLS` ### Hierarchical Operations -`sequenceNumNeighbors` · `sequenceNumParent` · `sequenceNumChildren` +`sequenceNumNeighbors` · `sequenceNumParent` · `sequenceNumAllParents` · `sequenceNumChildren` ### Hierarchical Address Types `sequenceNumToVertex2DD` · `vertex2DDToSequenceNum` · `sequenceNumToZOrder` · `zOrderToSequenceNum` · `sequenceNumToZ3` · `z3ToSequenceNum` · `sequenceNumToZ7` · `z7ToSequenceNum` diff --git a/src-cpp/dggrid_transform.cpp b/src-cpp/dggrid_transform.cpp index 5145b38..b54ce20 100644 --- a/src-cpp/dggrid_transform.cpp +++ b/src-cpp/dggrid_transform.cpp @@ -64,9 +64,11 @@ #include // DgZ3RF, DgZ3Coord #include // DgZ7RF, DgZ7Coord +#include #include #include #include +#include #include #include #include @@ -1014,47 +1016,87 @@ SeqNum seqNumParent(const DggsParams &p, SeqNum seqnum) { if (p.res <= 0) { throw std::runtime_error("Cannot get parent: already at resolution 0"); } - + + // Strategy: convert the child cell's center point to the parent resolution. + // This correctly identifies the containing parent cell, unlike setParents() + // which returns all touching parents and may pick the wrong one for + // cells near parent boundaries. auto t = getTransformer(p); - - // Convert seqnum to Q2DI + + // Convert seqnum → GEO (cell center) + auto loc = t->inSEQNUM(seqnum); + double lon_deg = 0, lat_deg = 0; + t->outGEO(loc, lon_deg, lat_deg); + + // Convert GEO → SEQNUM at parent resolution (res - 1) + DggsParams parentParams = p; + parentParams.res = p.res - 1; + return geoToSeqNum(parentParams, lon_deg, lat_deg); +} + +std::vector seqNumsParents(const DggsParams &p, + const std::vector& seqnums) { + std::vector result; + result.reserve(seqnums.size()); + + for (const auto& seqnum : seqnums) { + result.push_back(seqNumParent(p, seqnum)); + } + + return result; +} + +std::vector seqNumAllParents(const DggsParams &p, SeqNum seqnum) { + if (p.res <= 0) { + throw std::runtime_error("Cannot get parents: already at resolution 0"); + } + + // Use DGGRID's setParents which finds all parent cells that touch the + // child cell (via edge midpoint sampling). For interior cells this + // typically returns 1 parent; for cells on a parent boundary it may + // return 2 or more. + auto t = getTransformer(p); + auto loc = t->inSEQNUM(seqnum); const DgQ2DICoord *q2di = t->dgg->getAddress(*loc); - - // Create resAdd for current resolution - DgResAdd resAdd(*q2di, p.res); - - // Get parent cells - use public API + DgLocVector parents(*(t->idggs)); t->idggs->setParents(p.res, *loc, parents); - - if (parents.size() == 0) { - throw std::runtime_error("No parent found"); - } - - // Get the parent at coarser resolution - // DgLocVector elements are already in the idggs frame - // Need to get the Q2DI address from the first parent + const DgIDGGBase &parent_dgg = t->idggs->idggBase(p.res - 1); - - // Create a new location to convert - DgLocation parent_loc(parents[0]); - parent_dgg.convert(&parent_loc); - const DgQ2DICoord *parent_q2di = parent_dgg.getAddress(parent_loc); - - uint64_t parent_seqnum = parent_dgg.bndRF().seqNumAddress(*parent_q2di); - return static_cast(parent_seqnum); -} -std::vector seqNumsParents(const DggsParams &p, - const std::vector& seqnums) { std::vector result; + // Deduplicate: setParents may return the same cell more than once + std::set seen; + for (int i = 0; i < parents.size(); i++) { + DgLocation parent_loc(parents[i]); + parent_dgg.convert(&parent_loc); + const DgQ2DICoord *parent_q2di = parent_dgg.getAddress(parent_loc); + uint64_t parent_seqnum = parent_dgg.bndRF().seqNumAddress(*parent_q2di); + if (seen.insert(parent_seqnum).second) { + result.push_back(static_cast(parent_seqnum)); + } + } + + // Ensure the primary (containing) parent is first + SeqNum primary = seqNumParent(p, seqnum); + auto it = std::find(result.begin(), result.end(), primary); + if (it != result.end() && it != result.begin()) { + std::iter_swap(result.begin(), it); + } else if (it == result.end()) { + result.insert(result.begin(), primary); + } + + return result; +} + +std::vector> seqNumsAllParents(const DggsParams &p, + const std::vector& seqnums) { + std::vector> result; result.reserve(seqnums.size()); - for (const auto& seqnum : seqnums) { - result.push_back(seqNumParent(p, seqnum)); + result.push_back(seqNumAllParents(p, seqnum)); } - return result; } diff --git a/src-cpp/dggrid_transform.hpp b/src-cpp/dggrid_transform.hpp index 24dc656..adf6973 100644 --- a/src-cpp/dggrid_transform.hpp +++ b/src-cpp/dggrid_transform.hpp @@ -180,11 +180,16 @@ std::vector seqNumsNeighbors (const DggsParams& p, // --------------------------------------------------------------------------- // PARENT/CHILD - Hierarchical relationships between resolutions // --------------------------------------------------------------------------- -// Get parent cell at the previous (coarser) resolution +// Get the primary (containing) parent cell at the previous (coarser) resolution SeqNum seqNumParent (const DggsParams& p, SeqNum seqnum); -std::vector seqNumsParents (const DggsParams& p, +std::vector seqNumsParents (const DggsParams& p, const std::vector& seqnums); +// Get ALL parent cells that touch a child cell (primary parent first) +std::vector seqNumAllParents (const DggsParams& p, SeqNum seqnum); +std::vector> seqNumsAllParents (const DggsParams& p, + const std::vector& seqnums); + // Get all child cells at the next (finer) resolution std::vector seqNumChildren (const DggsParams& p, SeqNum seqnum); std::vector> seqNumsChildren (const DggsParams& p, diff --git a/src-cpp/webdggrid.cpp b/src-cpp/webdggrid.cpp index 821c140..51cc0f0 100644 --- a/src-cpp/webdggrid.cpp +++ b/src-cpp/webdggrid.cpp @@ -905,6 +905,32 @@ val SEQNUMS_parents( return seqNumArray(parents); } +val SEQNUMS_all_parents( + double pole_lon_deg, double pole_lat_deg, double azimuth_deg, + unsigned int aperture, int res, + std::string topology, std::string projection, + bool is_aperture_sequence, std::string aperture_sequence, + val seqnums) +{ + auto p = makeParams(pole_lon_deg, pole_lat_deg, azimuth_deg, + aperture, res, topology, projection, + is_aperture_sequence, aperture_sequence); + + const auto sv = convertJSArrayToNumberVector(seqnums); + auto allParents = dggrid::seqNumsAllParents(p, sv); + + // Return as array of arrays + val result = val::array(); + for (const auto& parents : allParents) { + val inner = val::array(); + for (const auto& parent : parents) { + inner.call("push", static_cast(parent)); + } + result.call("push", inner); + } + return result; +} + val SEQNUM_children( double pole_lon_deg, double pole_lat_deg, double azimuth_deg, unsigned int aperture, int res, @@ -1180,8 +1206,9 @@ EMSCRIPTEN_BINDINGS(my_module) // PARENT/CHILD emscripten::function("SEQNUM_parent", &SEQNUM_parent); - emscripten::function("SEQNUMS_parents", &SEQNUMS_parents); - emscripten::function("SEQNUM_children", &SEQNUM_children); + emscripten::function("SEQNUMS_parents", &SEQNUMS_parents); + emscripten::function("SEQNUMS_all_parents", &SEQNUMS_all_parents); + emscripten::function("SEQNUM_children", &SEQNUM_children); emscripten::function("SEQNUMS_children", &SEQNUMS_children); // HIERARCHICAL ADDRESS TYPES diff --git a/src-ts/webdggrid.ts b/src-ts/webdggrid.ts index 0513530..4d95196 100644 --- a/src-ts/webdggrid.ts +++ b/src-ts/webdggrid.ts @@ -1052,6 +1052,63 @@ export class Webdggrid { } } + /** + * Returns **all** parent cells that touch each input cell at the coarser + * resolution (resolution - 1). + * + * Unlike {@link sequenceNumParent} which returns only the primary + * (containing) parent, this method returns every parent cell whose area + * overlaps with the child cell. For interior cells this is typically 1; + * for cells on a parent boundary it may be 2 or more. + * + * The **first element** of each inner array is always the primary + * (containing) parent — the same value returned by + * {@link sequenceNumParent}. + * + * ```ts + * const allParents = dggs.sequenceNumAllParents([256n], 3); + * // allParents[0] = [65n, 66n] — 65 is the containing parent, + * // 66 is a touching neighbor parent + * ``` + * + * @param sequenceNum - Array of `BigInt` cell IDs to query. + * @param resolution - Resolution at which the input IDs were generated + * (must be > 0). Defaults to the instance's current {@link resolution}. + * @returns A 2-D array: `result[i]` contains all parent cell IDs that + * touch `sequenceNum[i]`, with the primary parent first. + * @throws If `resolution` is 0 or negative, or if an invalid cell ID is + * provided. + */ + sequenceNumAllParents( + sequenceNum: bigint[], + resolution: number = DEFAULT_RESOLUTION + ): bigint[][] { + if (resolution <= 0) { + throw new Error('Cannot get parents at resolution 0 or below'); + } + + try { + const resultArray = this._module.SEQNUMS_all_parents( + ...this._getParams(resolution), + sequenceNum + ); + + // Convert from JS array of arrays to bigint[][] + const result: bigint[][] = []; + for (let i = 0; i < resultArray.length; i++) { + const inner: bigint[] = []; + for (let j = 0; j < resultArray[i].length; j++) { + inner.push(resultArray[i][j]); + } + result.push(inner); + } + return result; + } catch (e) { + console.error(this._module.getExceptionMessage(e).toString()); + throw e; + } + } + /** * Returns all child cells at the next finer resolution (resolution + 1) * for each input cell. diff --git a/tests/unit/hierarchy.test.ts b/tests/unit/hierarchy.test.ts index a50c934..10a05de 100644 --- a/tests/unit/hierarchy.test.ts +++ b/tests/unit/hierarchy.test.ts @@ -116,6 +116,59 @@ describe('sequenceNumParent', () => { }); }); +// ── All Parents ───────────────────────────────────────────────────────────── + +describe('sequenceNumAllParents', () => { + test('returns at least one parent with primary first', () => { + const allParents = dggs.sequenceNumAllParents([100n], 5); + + expect(allParents).toHaveLength(1); // one input cell + expect(allParents[0].length).toBeGreaterThanOrEqual(1); + + // Primary parent should match sequenceNumParent + const primary = dggs.sequenceNumParent([100n], 5)[0]; + expect(allParents[0][0]).toBe(primary); + }); + + test('primary parent contains the child in its children', () => { + const cellId = 256n; + const allParents = dggs.sequenceNumAllParents([cellId], 3); + const primary = allParents[0][0]; + + const children = dggs.sequenceNumChildren([primary], 2)[0]; + expect(children).toContain(cellId); + }); + + test('boundary cells may have multiple parents', () => { + // Test many cells — some should have >1 parent + let foundMultiple = false; + for (let i = 1n; i <= 300n; i++) { + const allParents = dggs.sequenceNumAllParents([i], 3); + if (allParents[0].length > 1) { + foundMultiple = true; + // Primary should still be first + const primary = dggs.sequenceNumParent([i], 3)[0]; + expect(allParents[0][0]).toBe(primary); + break; + } + } + expect(foundMultiple).toBe(true); + }); + + test('works for multiple cells at once', () => { + const allParents = dggs.sequenceNumAllParents([100n, 200n], 5); + expect(allParents).toHaveLength(2); + expect(allParents[0].length).toBeGreaterThanOrEqual(1); + expect(allParents[1].length).toBeGreaterThanOrEqual(1); + }); + + test('throws error when resolution is 0', () => { + expect(() => { + dggs.sequenceNumAllParents([1n], 0); + }).toThrow(); + }); +}); + // ── Children ───────────────────────────────────────────────────────────────── describe('sequenceNumChildren', () => {