Maps coordinates to H3 cell identifiers a block at a time, so that peak memory is set by the block size rather than by the number of points.
Arguments
- xy
Two-column numeric matrix of longitude and latitude, in that order. Every row must be a valid position; blocking does not make
h3jsr::point_to_cell()any more tolerant of one that is not.- res
Integer (0–15). H3 resolution.
- chunk
Integer. Maximum points per call. Default
100000.
Details
h3jsr::point_to_cell() is a bridge to a JavaScript H3 build, not compiled
code: it pushes the whole coordinate set into a V8 heap as one object per
point, loops over them in JavaScript, and ships the strings back. The heap
that requires grows with the input and is not returned to the operating
system, so a single call over a full backfill is an out-of-memory kill rather
than a slow run.
Splitting the call costs nothing. Measured at H3 resolution 9 on 4M points, peak resident memory falls monotonically with block size — 2.69 GB in one call, 1.75 GB at 100,000, 1.68 GB at 50,000 — while wall time stays flat (21.7s against 20.5s), because the work per point is unchanged and only the number of round trips differs. The default of 100,000 sits at the point where the memory curve has flattened but the round trips are still few.
Blocking does not change the result: each point's cell depends only on its
own coordinates, so the concatenated output is identical to the single call
(verified byte-for-byte up to 4M points). The one deliberate departure is the
empty input, which h3jsr::point_to_cell() errors on rather than answering;
here it returns character(0).
Coordinates are assumed to have been checked already — see
valid_coordinates() for what happens if they have not been.