Class CellIndex

Stores a collection of (CellID, label) pairs.

The CellIDs may be overlapping or contain duplicate values. For example, a CellIndex could store a collection of CellUnions, where each CellUnion gets its own non-negative int32 label.

Similar to ShapeIndex and PointIndex which map each stored element to an identifier, CellIndex stores a label that is typically used to map the results of queries back to client's specific data.

To build a CellIndex where each Cell has a distinct label, call add() for each (CellID, label) pair, and then build() the index. For example:

// contents is a mapping of an identifier in my system (restaurantID,
// vehicleID, etc) to a CellID
const contents = new Map<number, CellID>([...])

for (const [key, val] of contents) {
  index.add(val, key)
}

index.build()
Copy

There is also a helper method that adds all elements of CellUnion with the same label:

index.addCellUnion(cellUnion, label)
Copy

Note that the index is not dynamic; the contents of the index cannot be changed once it has been built. Adding more after calling build() results in undefined behavior of the index.

There are several options for retrieving data from the index. The simplest is to use a built-in method such as intersectingLabels (which returns the labels of all cells that intersect a given target CellUnion):

const labels = index.intersectingLabels(targetUnion)
Copy

Alternatively, you can use a ClosestCellQuery which computes the cell(s) that are closest to a given target geometry.

Internally, the index consists of a set of non-overlapping leaf cell ranges that subdivide the sphere and such that each range intersects a particular set of (cellID, label) pairs.

Most clients should use either the methods such as visitIntersectingCells and intersectingLabels, or a helper such as ClosestCellQuery.