las-laz-js 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.6.1 (2026-10-22)
+
+- Demo: a read bigger than the draw cap (20 M) is drawn as an even spread over the whole cloud,
+  not its first 20 M points; selections and edits still act on every point read, and the
+  selection line says how many selected points are on screen. `?drawCap=N` lowers the cap.
+
+## 0.6.0 (2026-10-22)
+
+Voxel neighbour index and the sparse-point (dust) filter.
+
+- `selectSparse(cols, { radius, minNeighbours = 1, xy })` selects the points with fewer than
+  `minNeighbours` other points within `radius` (inclusive), for `removePoints`. `minNeighbours: 1`
+  keeps thin sparse features such as scanned blastholes. Checked point for point against PDAL's
+  `filters.outlier` (`method=radius`; PDAL's `min_k` is `minNeighbours`, and PDAL does not count a
+  point exactly `radius` away).
+- `buildIndex(cols, { cellSize })`: a sorted voxel grid on flat typed arrays (6 to 8 bytes a point),
+  over x / y / z or a k = 3 `positions` column, with exact queries: `nearestPoint` (3D, or `xy` in
+  plan; `maxDistance`), `pointsInRadius` (a selection) and `pointsNearRay` (a cylinder or a cone,
+  with each point's `t` along the ray and `d` from its axis, for a caller's snap). Rebuild it after
+  any edit of the columns.
+- `dedupeSelection(cols, tolerance, { z })` returns `dedupe`'s kept points as a selection and a
+  `map` from every input point to the kept point it merged into (its nearest within the tolerance).
+- Speed (Node): a 34-million-point LAS (Float32 after a local origin) indexes in about 1.1 s at
+  about 8 bytes a point, and `selectSparse` at 2 m takes about 2.1 s.
+- Demo: a Sparse points selection on the Edit tab.
+
 ## 0.5.0 (2026-10-22)
 
 Point operations.

package/README.md

@@ -11,7 +11,8 @@ runs in the browser and in Node — and built for files far larger than memory.
   thinning, a polygon crop, a coordinate transform and the original point index; `colourize`
   colours points; `writeLas` and `createLasWriter` write LAS 1.0–1.4.
 - Point operations on columns: select by box, polygon, class or return; keep, remove, split and
-  merge; transform coordinates; interleave positions for a renderer. See Point operations.
+  merge; transform coordinates; interleave positions for a renderer; find sparse points (dust);
+  a voxel neighbour index with nearest, radius and near-ray queries. See Point operations.
 - LAZ: point formats 0–3 and 6–8, read exactly like LAS — the same calls, the same options,
   decoded chunk by chunk in plain JavaScript (no WebAssembly) — and written with
   `compress: true`, byte for byte what PDAL (LAZperf) writes (bar one lossless exception, see
@@ -215,6 +216,57 @@ Float32 buffer; an axis left out of `origin` is not shifted ({ x, y } keeps worl
 defaults to true and picks the type of a new array; `into` must be a Float32Array or Float64Array
 long enough, else `INVALID_ARGUMENT`.
 
+### Sparse points (dust)
+
+```js
+import { selectSparse, removePoints } from "las-laz-js";
+
+var dust  = selectSparse(pts, { radius: 2 });   // fewer than 1 other point within 2 m
+var clean = removePoints(pts, dust);
+var lone  = selectSparse(pts, { radius: 0.5, minNeighbours: 4, xy: true });   // counted in 2D
+```
+
+A point is sparse when fewer than `minNeighbours` (default 1) **other** points lie within
+`radius` of it, inclusive; `radius` is required, in the columns' units. The result is a selection,
+so it can be shown before anything is deleted. `minNeighbours: 1` keeps any point with a single
+neighbour inside the radius, so thin sparse features — a line of points down a scanned blasthole —
+survive; dust that clumps survives too. A higher `minNeighbours` removes small clumps, at the
+cost of thin features. It works on columns in memory (x / y / z, or a k = 3 `positions`): 34 million
+points take about 2 s in Node. With PDAL's `filters.outlier` (`method=radius`), `min_k` is the same
+as `minNeighbours`, but PDAL does not count a point exactly `radius` away.
+
+### Neighbour index
+
+```js
+import { buildIndex, nearestPoint, pointsInRadius, pointsNearRay } from "las-laz-js";
+
+var index = buildIndex(pts);                              // or { cellSize: 0.5 }; omitted: ~16 points a cell
+var i     = nearestPoint(index, [x, y, z]);               // point number, or -1
+var j     = nearestPoint(index, [x, y], { xy: true, maxDistance: 0.3 });   // nearest in plan, within 0.3
+var near  = pointsInRadius(index, [x, y, z], 5);          // a selection
+var hit   = pointsNearRay(index, origin, direction, { radius: 0.2, growth: 0 });
+// hit = { points, t, d }: every point within radius + growth · t of the ray, t along it, d from its axis
+```
+
+A sorted voxel grid on flat typed arrays, 6 to 8 bytes a point (34 million points build in about
+1 s). Results are exact — every candidate is distance-checked in Float64 — "within" is inclusive,
+and ties go to the lowest point number. `pointsNearRay` is a cylinder for `growth: 0` (an
+orthographic camera's pick ray) and a cone for `growth > 0` (a perspective camera's, `growth` the
+tangent of the half-angle); points behind `origin` are left out, and choosing a snap point from `t`
+and `d` is the caller's. The index refers to the coordinate arrays, it does not copy them: rebuild
+it after any keep, remove, merge or transform — after an `inPlace` edit an old index would read
+overwritten memory, and queries cannot tell.
+
+### Dedupe with an index map
+
+```js
+import { dedupeSelection } from "las-laz-js";
+
+var { keep, map } = dedupeSelection(pts, 0.01);   // { z: true } for 3D
+var unique = keepPoints(pts, keep);               // what dedupe(pts, 0.01) returns
+// map[i]: where input point i went in unique — a dropped point maps to its nearest kept point
+```
+
 ## LAZ
 
 A LAZ file is opened and read with the same calls as LAS. Each LASzip chunk (50,000 points in

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "las-laz-js",
-	"version": "0.5.0",
+	"version": "0.6.1",
 	"description": "Zero-dependency JavaScript reader and writer for ASPRS LAS point clouds, and reader and writer for LAZ (LASzip), for the browser and Node, built for files larger than memory.",
 	"type": "module",
 	"exports": {

package/src/filter/dedupe.js

@@ -6,18 +6,24 @@
 // objects to columns. XY by default (one Z per XY location, as a
 // 2.5D surface wants); { z: true } compares in 3D.
 // Every column follows the kept points (k values per point).
+// dedupeSelection gives the same keep as a selection, plus a map from
+// every input point to the output point it merged into.
 //==========================================================
 
 import { LasError, ERROR_CODES } from "../errors.js";
 import { columnsOf, gather, sameType } from "../ops/columns.js";
 
 /**
+ * The points dedupe keeps, and where every input point went.
+ * map[i] is the output number (position in keep) of the kept point that point i
+ * merged into: for a dropped point, the nearest kept point within tolerance
+ * (lowest number on a tie); a kept point maps to itself.
  * @param {object} cols - PointColumns ({ count, x, y, z?, ... }).
  * @param {number} tolerance - distance below which points merge (> 0).
- * @param {{z?: boolean}} [opts]
- * @returns {object} PointColumns with only the kept points
+ * @param {{z?: boolean}} [opts] - z: compare in 3D.
+ * @returns {{keep: Uint32Array, map: Uint32Array}}
  */
-export function dedupe(cols, tolerance, opts) {
+export function dedupeSelection(cols, tolerance, opts) {
 	if (!(tolerance > 0)) throw new LasError(ERROR_CODES.INVALID_ARGUMENT, "dedupe tolerance must be > 0");
 	var use3d = !!(opts && opts.z && cols.z);
 	var tol2 = tolerance * tolerance;
@@ -44,6 +50,8 @@ export function dedupe(cols, tolerance, opts) {
 	var head = new Map();
 	var next = new Int32Array(n);
 	var kept = new Uint32Array(n);
+	var map = new Uint32Array(n);
+	var dropped = [];
 	var nKept = 0;
 	for (var i = 0; i < n; i++) {
 		var cx = Math.floor(x[i] / tolerance) - lo[0] + 1, cy = Math.floor(y[i] / tolerance) - lo[1] + 1;
@@ -62,16 +70,49 @@ export function dedupe(cols, tolerance, opts) {
 				}
 			}
 		}
-		if (dup) continue;
+		if (dup) { dropped.push(i); continue; }
 		var own = key(cx, cy, cz);
 		var prev = head.get(own);
 		next[i] = prev === undefined ? -1 : prev;
 		head.set(own, i);
+		map[i] = nKept;
 		kept[nKept++] = i;
 	}
 
+	// Each dropped point maps to its nearest kept point (the cell lists hold kept points only)
+	dropped.forEach(function (i) {
+		var cx = Math.floor(x[i] / tolerance) - lo[0] + 1, cy = Math.floor(y[i] / tolerance) - lo[1] + 1;
+		var cz = use3d ? Math.floor(z[i] / tolerance) - lo[2] + 1 : 1;
+		var best = -1, bd = Infinity;
+		for (var dx = -1; dx <= 1; dx++) {
+			for (var dy = -1; dy <= 1; dy++) {
+				for (var dz = -dzRange; dz <= dzRange; dz++) {
+					var k = head.get(key(cx + dx, cy + dy, cz + dz));
+					while (k !== undefined && k >= 0) {
+						var ex = x[k] - x[i], ey = y[k] - y[i];
+						var ez = use3d ? z[k] - z[i] : 0;
+						var d = ex * ex + ey * ey + ez * ez;
+						if (d <= tol2 && (d < bd || (d === bd && k < best))) { bd = d; best = k; }
+						k = next[k];
+					}
+				}
+			}
+		}
+		map[i] = map[best];
+	});
+	return { keep: kept.slice(0, nKept), map: map };
+}
+
+/**
+ * @param {object} cols - PointColumns ({ count, x, y, z?, ... }).
+ * @param {number} tolerance - distance below which points merge (> 0).
+ * @param {{z?: boolean}} [opts]
+ * @returns {object} PointColumns with only the kept points
+ */
+export function dedupe(cols, tolerance, opts) {
+	var sel = dedupeSelection(cols, tolerance, opts).keep, nKept = sel.length;
+
 	// Every column (k values per point) follows the kept points; anything else passes through
-	var sel = kept.subarray(0, nKept);
 	var ks = Object.create(null);   // a column may be named like an Object.prototype member
 	columnsOf(cols).forEach(function (c) { ks[c.name] = c.k; });
 	var out = { count: nKept };

package/src/index/grid.js

@@ -0,0 +1,198 @@
+// src/index/grid.js
+//==========================================================
+// The voxel neighbour index: a sorted voxel grid on flat typed
+// arrays. Point numbers are counting-sorted by cell into `order`
+// (stable, so a cell's points stay ascending); an open-addressing
+// hash table (linear probing, power-of-two capacity) maps each
+// occupied cell's key to its `start` and `length` in `order`.
+// Coordinates are referenced, not copied: x / y / z columns, or a
+// k = 3 positions column (Kirra's kadCloud layout) read with a
+// stride of 3. About 6 bytes per point at 16 points per cell.
+// The grid only prunes: queries (query.js) distance-check every
+// candidate in Float64, so their results are exact.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+import { columnsOf, countOf } from "../ops/columns.js";
+
+var MAX_POINTS = 4294967295;
+var MAX_CELLS = 9007199254740992;   // 2^53: keys stay exact integers
+var EMPTY = -1;
+
+function bad(message) { return new LasError(ERROR_CODES.INVALID_ARGUMENT, message); }
+
+/**
+ * The coordinates of point columns: x / y / z (stride 1), else a k = 3
+ * positions column (stride 3, y and z as offset views of it).
+ * Point i's x is coords.x[i * coords.stride].
+ * @param {object} cols - point columns.
+ * @param {string} fn - the calling function's name, for the message.
+ * @returns {{x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number>, stride: number}}
+ */
+export function coordsOf(cols, fn) {
+	var count = countOf(cols);
+	var k = Object.create(null);
+	columnsOf(cols).forEach(function (c) { k[c.name] = c.k; });
+	if (k.x === 1 && k.y === 1 && k.z === 1) return { x: cols.x, y: cols.y, z: cols.z, stride: 1 };
+	if (k.positions === 3 || (count === 0 && k.positions === 1)) {
+		var p = cols.positions;
+		return { x: p, y: p.subarray(1), z: p.subarray(2), stride: 3 };
+	}
+	throw bad(fn + " needs x, y, z columns or a k = 3 positions column");
+}
+
+/**
+ * Refuse a point count the index cannot number (order is a Uint32Array).
+ * @param {number} n
+ */
+export function checkPointCount(n) {
+	if (n > MAX_POINTS) throw new LasError(ERROR_CODES.TOO_MANY_POINTS, "the neighbour index takes at most 4,294,967,295 points, not " + n);
+}
+
+// murmur3's 32-bit finaliser: every input bit reaches the low bits the mask keeps
+function fmix32(h) {
+	h ^= h >>> 16; h = Math.imul(h, 0x85EBCA6B);
+	h ^= h >>> 13; h = Math.imul(h, 0xC2B2AE35);
+	return (h ^ (h >>> 16)) >>> 0;
+}
+
+/**
+ * The home slot of a cell key (an integer below 2^53) in a table of mask + 1 slots.
+ * @param {number} key
+ * @param {number} mask
+ * @returns {number}
+ */
+export function hashKey(key, mask) {
+	var lo = key % 4294967296, hi = (key - lo) / 4294967296;
+	return fmix32(lo ^ fmix32(hi)) & mask;
+}
+
+function nextPow2(n) {
+	var p = 16;
+	while (p < n) p *= 2;
+	return p;
+}
+
+/**
+ * Build the grid over coordinates.
+ * @param {{x, y, z, stride}} coords - from coordsOf.
+ * @param {number} count - points.
+ * @param {number} [cellSize] - cell edge; omitted: about 16 points per cell.
+ * @param {boolean} [xy] - ignore Z (nz = 1).
+ * @returns {object} PointIndex
+ */
+export function buildGrid(coords, count, cellSize, xy) {
+	if (cellSize !== undefined && !(typeof cellSize === "number" && cellSize > 0 && isFinite(cellSize))) throw bad("cellSize must be a positive finite number, not " + String(cellSize));
+	var X = coords.x, Y = coords.y, Z = coords.z, st = coords.stride;
+
+	// 1. Bounds
+	var lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+	for (var i = 0, o = 0; i < count; i++, o += st) {
+		var a = X[o], b = Y[o], c = xy ? 0 : Z[o];
+		if (a - a !== 0 || b - b !== 0 || c - c !== 0) throw bad("point " + i + " has a non-finite " + (a - a !== 0 ? "x" : b - b !== 0 ? "y" : "z") + " coordinate");
+		if (a < lo[0]) lo[0] = a; if (a > hi[0]) hi[0] = a;
+		if (b < lo[1]) lo[1] = b; if (b > hi[1]) hi[1] = b;
+		if (c < lo[2]) lo[2] = c; if (c > hi[2]) hi[2] = c;
+	}
+	if (count === 0) { lo = [0, 0, 0]; hi = [0, 0, 0]; }
+	var ext = [hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]];
+	if (cellSize === undefined) {
+		var prod = 1, d = 0;
+		ext.forEach(function (e) { if (e > 0) { prod *= e; d++; } });
+		cellSize = d === 0 ? 1 : Math.pow(16 * prod / count, 1 / d);
+	}
+	var nx = Math.floor(ext[0] / cellSize) + 1, ny = Math.floor(ext[1] / cellSize) + 1, nz = Math.floor(ext[2] / cellSize) + 1;
+	if (nx * ny * nz > MAX_CELLS) throw bad("cellSize too small for this extent: " + nx + " × " + ny + " × " + nz + " cells is more than 2^53");
+	var inv = 1 / cellSize, x0 = lo[0], y0 = lo[1], z0 = lo[2];
+	function keyOf(o) {
+		var cx = Math.floor((X[o] - x0) * inv); if (cx >= nx) cx = nx - 1;
+		var cy = Math.floor((Y[o] - y0) * inv); if (cy >= ny) cy = ny - 1;
+		var cz = 0;
+		if (!xy) { cz = Math.floor((Z[o] - z0) * inv); if (cz >= nz) cz = nz - 1; }
+		return (cx * ny + cy) * nz + cz;
+	}
+
+	// 2. Count points per cell into the hash table
+	var cap = nextPow2(2 * Math.min(nx * ny * nz, Math.ceil(count / 16)));
+	var mask = cap - 1, used = 0;
+	var keys = new Float64Array(cap).fill(EMPTY), length = new Uint32Array(cap);
+	function grow() {
+		var oldK = keys, oldL = length;
+		cap *= 2; mask = cap - 1;
+		keys = new Float64Array(cap).fill(EMPTY); length = new Uint32Array(cap);
+		for (var s = 0; s < oldK.length; s++) {
+			if (oldK[s] === EMPTY) continue;
+			var h = hashKey(oldK[s], mask);
+			while (keys[h] !== EMPTY) h = (h + 1) & mask;
+			keys[h] = oldK[s]; length[h] = oldL[s];
+		}
+	}
+	for (i = 0, o = 0; i < count; i++, o += st) {
+		var key = keyOf(o), h = hashKey(key, mask);
+		while (keys[h] !== EMPTY && keys[h] !== key) h = (h + 1) & mask;
+		if (keys[h] === EMPTY) {
+			if (2 * (used + 1) > cap) {
+				grow();
+				h = hashKey(key, mask);
+				while (keys[h] !== EMPTY) h = (h + 1) & mask;
+			}
+			keys[h] = key; used++;
+		}
+		length[h]++;
+	}
+
+	// 3. Prefix sums give each cell's start; place point numbers (stable)
+	var start = new Uint32Array(cap), run = 0;
+	for (var s = 0; s < cap; s++) { start[s] = run; run += length[s]; }
+	var order = new Uint32Array(count);
+	for (i = 0, o = 0; i < count; i++, o += st) {
+		var k2 = keyOf(o), h2 = hashKey(k2, mask);
+		while (keys[h2] !== k2) h2 = (h2 + 1) & mask;
+		order[start[h2]++] = i;
+	}
+	for (s = 0; s < cap; s++) start[s] -= length[s];
+
+	return { count: count, cellSize: cellSize, min: [x0, y0, z0], nx: nx, ny: ny, nz: nz, order: order, keys: keys, start: start, length: length, mask: mask, coords: coords };
+}
+
+/**
+ * Build a neighbour index over point columns.
+ * @param {object} cols - point columns with x, y, z, or a k = 3 positions column.
+ * @param {{cellSize?: number}} [opts] - cellSize omitted: about 16 points per cell.
+ * @returns {object} PointIndex { count, cellSize, min, nx, ny, nz, order, keys, start, length, mask, coords }
+ */
+export function buildIndex(cols, opts) {
+	var coords = coordsOf(cols, "buildIndex");
+	checkPointCount(cols.count);
+	return buildGrid(coords, cols.count, opts ? opts.cellSize : undefined, false);
+}
+
+/**
+ * The hash-table slot of cell (ix, iy, iz), or -1 when the cell is empty or outside the grid.
+ * @param {object} index - PointIndex.
+ * @returns {number}
+ */
+export function lookup(index, ix, iy, iz) {
+	if (ix < 0 || iy < 0 || iz < 0 || ix >= index.nx || iy >= index.ny || iz >= index.nz) return -1;
+	var key = (ix * index.ny + iy) * index.nz + iz, keys = index.keys, mask = index.mask;
+	var h = hashKey(key, mask);
+	while (keys[h] !== EMPTY) {
+		if (keys[h] === key) return h;
+		h = (h + 1) & mask;
+	}
+	return -1;
+}
+
+/**
+ * Refuse an index that is not self-consistent.
+ * @param {object} index - PointIndex.
+ * @param {string} fn - the calling function's name, for the message.
+ */
+export function checkIndex(index, fn) {
+	var ok = index !== null && typeof index === "object" && index.order instanceof Uint32Array && index.order.length === index.count && index.coords;
+	if (ok && index.count > 0) {
+		var need = (index.count - 1) * index.coords.stride + 1;
+		ok = index.coords.x.length >= need && index.coords.y.length >= need && index.coords.z.length >= need;
+	}
+	if (!ok) throw bad(fn + ": index is not self-consistent (rebuild it with buildIndex)");
+}

package/src/index/query.js

@@ -0,0 +1,329 @@
+// src/index/query.js
+//==========================================================
+// Queries on a PointIndex (grid.js). The grid only prunes: every
+// candidate is distance-checked in Float64 against the stored
+// coordinates, "within" is inclusive (<=) and ties go to the lowest
+// point number, so each answer equals a plain scan of the points.
+// Cell ranges and cell distances are widened by a millionth of a
+// cell so float rounding can never skip a cell holding an answer.
+// When a query would visit more cells than the hash table has
+// slots (a cell size far below the query's reach, or a query far
+// outside the cloud), it walks the occupied slots instead.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+import { checkIndex, lookup as lookupCell } from "./grid.js";
+
+var EPS = 1e-6;   // in cells
+
+function bad(message) { return new LasError(ERROR_CODES.INVALID_ARGUMENT, message); }
+
+function fin(v) { return typeof v === "number" && isFinite(v); }
+
+// [x, y, z] as Numbers; with xy, [x, y] or [x, y, anything]
+function checkPoint(p, xy, name) {
+	var ok = Array.isArray(p) && (p.length === 3 || (xy && p.length === 2)) && fin(p[0]) && fin(p[1]) && (xy || fin(p[2]));
+	if (!ok) throw bad(name + " must be [x, y, z]" + (xy ? " or [x, y]" : "") + " of finite numbers");
+	return [p[0], p[1], xy ? 0 : p[2]];
+}
+
+function checkPositive(v, name, optional) {
+	if (optional && v === undefined) return;
+	if (!(fin(v) && v > 0)) throw bad(name + " must be a positive finite number, not " + String(v));
+}
+
+function dims(index) { return [index.nx, index.ny, index.nz]; }
+
+// Inclusive cell range on one axis covering [a, b], clamped; lo > hi when empty
+function cellRange(index, axis, a, b) {
+	var n = dims(index)[axis], inv = 1 / index.cellSize, m = index.min[axis];
+	var lo = Math.floor((a - m) * inv - EPS), hi = Math.floor((b - m) * inv + EPS);
+	return [Math.max(0, lo), Math.min(n - 1, hi)];
+}
+
+// Squared distance from q to the box of cell (ix, iy, iz), the box widened by EPS cells
+function cellDist2(index, ix, iy, iz, q, xy) {
+	var cs = index.cellSize, g = cs * EPS, m = index.min, c = [ix, iy, iz], s = 0;
+	for (var a = 0; a < (xy ? 2 : 3); a++) {
+		var lo = m[a] + c[a] * cs - g, hi = m[a] + (c[a] + 1) * cs + g;
+		var d = lo - q[a] > 0 ? lo - q[a] : (q[a] - hi > 0 ? q[a] - hi : 0);
+		s += d * d;
+	}
+	return s;
+}
+
+function decode(index, key) {
+	var iz = key % index.nz, t = (key - iz) / index.nz, iy = t % index.ny;
+	return [(t - iy) / index.ny, iy, iz];
+}
+
+/**
+ * Call fn(slot, ix, iy, iz) for every occupied cell in an inclusive cell box.
+ * Walks the table instead when the box has more cells than the table has slots.
+ * @param {object} index - PointIndex.
+ * @param {number[]} lo - [ix, iy, iz] low corner.
+ * @param {number[]} hi - [ix, iy, iz] high corner.
+ * @param {function} fn
+ */
+export function visitBox(index, lo, hi, fn) {
+	if (lo[0] > hi[0] || lo[1] > hi[1] || lo[2] > hi[2]) return;
+	var cells = (hi[0] - lo[0] + 1) * (hi[1] - lo[1] + 1) * (hi[2] - lo[2] + 1), keys = index.keys;
+	if (cells > keys.length) {
+		for (var s = 0; s < keys.length; s++) {
+			if (keys[s] < 0) continue;
+			var c = decode(index, keys[s]);
+			if (c[0] >= lo[0] && c[0] <= hi[0] && c[1] >= lo[1] && c[1] <= hi[1] && c[2] >= lo[2] && c[2] <= hi[2]) fn(s, c[0], c[1], c[2]);
+		}
+		return;
+	}
+	for (var ix = lo[0]; ix <= hi[0]; ix++) {
+		for (var iy = lo[1]; iy <= hi[1]; iy++) {
+			for (var iz = lo[2]; iz <= hi[2]; iz++) {
+				var slot = lookupCell(index, ix, iy, iz);
+				if (slot >= 0) fn(slot, ix, iy, iz);
+			}
+		}
+	}
+}
+
+/**
+ * Every point within `radius` of a point (inclusive), as a selection.
+ * @param {object} index - PointIndex from buildIndex.
+ * @param {number[]} point - [x, y, z]; with xy, [x, y] is enough.
+ * @param {number} radius - > 0.
+ * @param {{xy?: boolean}} [opts] - xy: measure in XY only.
+ * @returns {Uint32Array} ascending point numbers
+ */
+export function pointsInRadius(index, point, radius, opts) {
+	checkIndex(index, "pointsInRadius");
+	var xy = !!(opts && opts.xy);
+	var q = checkPoint(point, xy, "point");
+	checkPositive(radius, "radius");
+	if (index.count === 0) return new Uint32Array(0);
+	var rx = cellRange(index, 0, q[0] - radius, q[0] + radius), ry = cellRange(index, 1, q[1] - radius, q[1] + radius);
+	var rz = xy ? [0, index.nz - 1] : cellRange(index, 2, q[2] - radius, q[2] + radius);
+	var r2 = radius * radius, co = index.coords, X = co.x, Y = co.y, Z = co.z, st = co.stride, order = index.order;
+	var hits = [];
+	visitBox(index, [rx[0], ry[0], rz[0]], [rx[1], ry[1], rz[1]], function (s, ix, iy, iz) {
+		if (cellDist2(index, ix, iy, iz, q, xy) > r2) return;
+		for (var j = index.start[s], e = j + index.length[s]; j < e; j++) {
+			var p = order[j], o = p * st;
+			var dx = X[o] - q[0], dy = Y[o] - q[1], dz = xy ? 0 : Z[o] - q[2];
+			if (dx * dx + dy * dy + dz * dz <= r2) hits.push(p);
+		}
+	});
+	return Uint32Array.from(hits).sort();
+}
+
+/**
+ * The nearest point (lowest number on a tie), or -1 when none is within maxDistance.
+ * @param {object} index - PointIndex from buildIndex.
+ * @param {number[]} point - [x, y, z]; with xy, [x, y] is enough.
+ * @param {{maxDistance?: number, xy?: boolean}} [opts] - maxDistance omitted: unlimited.
+ * @returns {number}
+ */
+export function nearestPoint(index, point, opts) {
+	checkIndex(index, "nearestPoint");
+	var xy = !!(opts && opts.xy);
+	var q = checkPoint(point, xy, "point");
+	var maxD = opts ? opts.maxDistance : undefined;
+	checkPositive(maxD, "maxDistance", true);
+	if (index.count === 0) return -1;
+	var maxD2 = maxD === undefined ? Infinity : maxD * maxD;
+	var n = dims(index), cs = index.cellSize, inv = 1 / cs, m = index.min, axes = xy ? 2 : 3;
+	var c = [0, 0, 0];
+	for (var a = 0; a < axes; a++) c[a] = Math.min(n[a] - 1, Math.max(0, Math.floor((q[a] - m[a]) * inv)));
+	var co = index.coords, X = co.x, Y = co.y, Z = co.z, st = co.stride, order = index.order;
+	var best = -1, bd = Infinity, visited = 0, budget = index.keys.length;
+	// How far the query lies outside the grid on each axis (0 inside)
+	var out = [0, 0, 0];
+	for (a = 0; a < axes; a++) {
+		var gl = m[a], gh = m[a] + n[a] * cs;
+		out[a] = Math.max(0, (q[a] < gl ? gl - q[a] : q[a] > gh ? q[a] - gh : 0) - cs * EPS);
+	}
+
+	function cell(ix, iy, iz) {
+		visited++;
+		var s = lookupCell(index, ix, iy, iz);
+		if (s < 0 || cellDist2(index, ix, iy, iz, q, xy) > Math.min(bd, maxD2)) return;
+		for (var j = index.start[s], e = j + index.length[s]; j < e; j++) {
+			var p = order[j], o = p * st;
+			var dx = X[o] - q[0], dy = Y[o] - q[1], dz = xy ? 0 : Z[o] - q[2];
+			var d = dx * dx + dy * dy + dz * dz;
+			if (d <= maxD2 && (d < bd || (d === bd && p < best))) { bd = d; best = p; }
+		}
+	}
+	// Every grid cell at Chebyshev distance r (in the axes used) from c
+	function ring(r) {
+		var x0 = Math.max(0, c[0] - r), x1 = Math.min(n[0] - 1, c[0] + r);
+		var y0 = Math.max(0, c[1] - r), y1 = Math.min(n[1] - 1, c[1] + r);
+		var z0 = xy ? 0 : Math.max(0, c[2] - r), z1 = xy ? n[2] - 1 : Math.min(n[2] - 1, c[2] + r);
+		function column(ix, iy) { for (var iz = z0; iz <= z1; iz++) cell(ix, iy, iz); }
+		for (var ix = x0; ix <= x1; ix++) {
+			if (ix === c[0] - r || ix === c[0] + r) {
+				for (var iy = y0; iy <= y1; iy++) column(ix, iy);
+				continue;
+			}
+			if (c[1] - r >= 0) column(ix, c[1] - r);
+			if (c[1] + r < n[1]) column(ix, c[1] + r);
+			if (xy) continue;
+			// interior columns: only the two z faces
+			for (iy = Math.max(y0, c[1] - r + 1); iy <= Math.min(y1, c[1] + r - 1); iy++) {
+				if (c[2] - r >= 0) cell(ix, iy, c[2] - r);
+				if (c[2] + r < n[2]) cell(ix, iy, c[2] + r);
+			}
+		}
+	}
+
+	function gap(g) { g = Math.max(0, g - cs * EPS); return g * g; }
+
+	for (var r = 0; ; r++) {
+		ring(r);
+		if (visited > budget) return nearestByScan(index, q, xy, maxD2, best, bd);
+		// Unvisited points lie beyond a face of the cells c - r .. c + r on some axis a, and
+		// inside the grid on the others: a lower bound on their squared distance
+		var bound2 = Infinity;
+		for (a = 0; a < axes; a++) {
+			var rest = 0;
+			for (var b = 0; b < axes; b++) if (b !== a) rest += out[b] * out[b];
+			if (c[a] - r > 0) bound2 = Math.min(bound2, gap(q[a] - (m[a] + (c[a] - r) * cs)) + rest);
+			if (c[a] + r < n[a] - 1) bound2 = Math.min(bound2, gap(m[a] + (c[a] + r + 1) * cs - q[a]) + rest);
+		}
+		if (bound2 === Infinity) break;
+		if (best >= 0 && bd < bound2) break;
+		if (bound2 > maxD2) break;
+	}
+	return best;
+}
+
+// The occupied cells in order of distance, for queries a ring search would make slow
+function nearestByScan(index, q, xy, maxD2, best, bd) {
+	var keys = index.keys, cand = [];
+	for (var s = 0; s < keys.length; s++) {
+		if (keys[s] < 0) continue;
+		var c = decode(index, keys[s]), cd = cellDist2(index, c[0], c[1], c[2], q, xy);
+		if (cd <= maxD2 && cd <= bd) cand.push([cd, s]);
+	}
+	cand.sort(function (u, v) { return u[0] - v[0]; });
+	var co = index.coords, X = co.x, Y = co.y, Z = co.z, st = co.stride, order = index.order;
+	for (var i = 0; i < cand.length; i++) {
+		if (cand[i][0] > bd) break;
+		s = cand[i][1];
+		for (var j = index.start[s], e = j + index.length[s]; j < e; j++) {
+			var p = order[j], o = p * st;
+			var dx = X[o] - q[0], dy = Y[o] - q[1], dz = xy ? 0 : Z[o] - q[2];
+			var d = dx * dx + dy * dy + dz * dz;
+			if (d <= maxD2 && (d < bd || (d === bd && p < best))) { bd = d; best = p; }
+		}
+	}
+	return best;
+}
+
+/**
+ * Every point near a ray: within radius + growth · t of its axis, where t >= 0 is the
+ * point's distance along it (growth 0: a cylinder, as an orthographic view's pick ray;
+ * growth > 0: a cone, as a perspective camera's, growth = tan of the half-angle).
+ * The snap rules (front-most, priorities) are the caller's: pick from t and d.
+ * @param {object} index - PointIndex from buildIndex.
+ * @param {number[]} origin - [x, y, z].
+ * @param {number[]} direction - [x, y, z], any length > 0.
+ * @param {{radius: number, growth?: number, maxT?: number}} opts - maxT omitted: unlimited.
+ * @returns {{points: Uint32Array, t: Float64Array, d: Float64Array}} points ascending; t, d parallel
+ */
+export function pointsNearRay(index, origin, direction, opts) {
+	checkIndex(index, "pointsNearRay");
+	var o = checkPoint(origin, false, "origin");
+	var dir = checkPoint(direction, false, "direction");
+	var len = Math.sqrt(dir[0] * dir[0] + dir[1] * dir[1] + dir[2] * dir[2]);
+	if (!(len > 0 && isFinite(len))) throw bad("direction must not be zero");
+	var u = [dir[0] / len, dir[1] / len, dir[2] / len];
+	opts = opts || {};
+	checkPositive(opts.radius, "radius");
+	var growth = opts.growth === undefined ? 0 : opts.growth;
+	if (!(fin(growth) && growth >= 0)) throw bad("growth must be a finite number >= 0, not " + String(growth));
+	checkPositive(opts.maxT, "maxT", true);
+	var radius = opts.radius, maxT = opts.maxT;
+	var points = [], ts = [], ds = [];
+	var co = index.coords, X = co.x, Y = co.y, Z = co.z, st = co.stride, order = index.order;
+
+	function check(s) {
+		for (var j = index.start[s], e = j + index.length[s]; j < e; j++) {
+			var p = order[j], q = p * st;
+			var vx = X[q] - o[0], vy = Y[q] - o[1], vz = Z[q] - o[2];
+			var t = vx * u[0] + vy * u[1] + vz * u[2];
+			if (t < 0 || (maxT !== undefined && t > maxT)) continue;
+			var cx = vy * u[2] - vz * u[1], cy = vz * u[0] - vx * u[2], cz = vx * u[1] - vy * u[0];
+			var d = Math.sqrt(cx * cx + cy * cy + cz * cz);
+			if (d <= radius + growth * t) { points.push(p); ts.push(t); ds.push(d); }
+		}
+	}
+
+	if (index.count > 0) walk();
+	var idx = points.map(function (_, i) { return i; }).sort(function (a, b) { return points[a] - points[b]; });
+	return {
+		points: Uint32Array.from(idx, function (i) { return points[i]; }),
+		t: Float64Array.from(idx, function (i) { return ts[i]; }),
+		d: Float64Array.from(idx, function (i) { return ds[i]; })
+	};
+
+	function walk() {
+		var cs = index.cellSize, m = index.min, n = dims(index);
+		var lo = [m[0], m[1], m[2]], hi = [m[0] + n[0] * cs, m[1] + n[1] * cs, m[2] + n[2] * cs];
+		// No point has a t beyond the far side of the grid's bounding sphere
+		var half = 0, dc = 0;
+		for (var a = 0; a < 3; a++) { var e = (hi[a] - lo[a]) / 2, w = (lo[a] + hi[a]) / 2 - o[a]; half += e * e; dc += w * w; }
+		var T = Math.sqrt(dc) + Math.sqrt(half);
+		if (maxT !== undefined && maxT < T) T = maxT;
+		var R = radius + growth * T + cs * EPS;
+		// Clip [0, T] to where the ray is within R of the grid's box (slab method)
+		var t0 = 0, t1 = T;
+		for (a = 0; a < 3; a++) {
+			if (u[a] === 0) {
+				if (o[a] < lo[a] - R || o[a] > hi[a] + R) return;
+				continue;
+			}
+			var ta = (lo[a] - R - o[a]) / u[a], tb = (hi[a] + R - o[a]) / u[a];
+			if (ta > tb) { var sw = ta; ta = tb; tb = sw; }
+			if (ta > t0) t0 = ta;
+			if (tb < t1) t1 = tb;
+		}
+		if (t0 > t1) return;
+		// Many more cells along the way than occupied cells: test each occupied cell once
+		var across = 2 * R / cs + 1;
+		if (((t1 - t0) / cs + 1) * across * across > index.keys.length) return scanCells();
+		var seen = new Set();
+		for (var t = t0; t <= t1; t += cs) {
+			var t2 = Math.min(t + cs, t1), rr = radius + growth * t2;
+			var bl = [0, 0, 0], bh = [0, 0, 0];
+			for (a = 0; a < 3; a++) {
+				var pa = o[a] + t * u[a], pb = o[a] + t2 * u[a];
+				var r = cellRange(index, a, Math.min(pa, pb) - rr, Math.max(pa, pb) + rr);
+				bl[a] = r[0]; bh[a] = r[1];
+			}
+			visitBox(index, bl, bh, function (s) {
+				if (seen.has(s)) return;
+				seen.add(s);
+				check(s);
+			});
+			if (t2 >= t1) break;
+		}
+	}
+
+	// A cell can hold an answer only if its centre is near enough: every point is
+	// within hd of the centre, so its t and d differ from the centre's by at most hd
+	function scanCells() {
+		var cs = index.cellSize, m = index.min, keys = index.keys, hd = cs * Math.sqrt(3) / 2 + cs * EPS;
+		for (var s = 0; s < keys.length; s++) {
+			if (keys[s] < 0) continue;
+			var c = decode(index, keys[s]);
+			var vx = m[0] + (c[0] + 0.5) * cs - o[0], vy = m[1] + (c[1] + 0.5) * cs - o[1], vz = m[2] + (c[2] + 0.5) * cs - o[2];
+			var tc = vx * u[0] + vy * u[1] + vz * u[2];
+			if (tc + hd < 0 || (maxT !== undefined && tc - hd > maxT)) continue;
+			var cx = vy * u[2] - vz * u[1], cy = vz * u[0] - vx * u[2], cz = vx * u[1] - vy * u[0];
+			if (Math.sqrt(cx * cx + cy * cy + cz * cz) - hd > radius + growth * Math.max(0, tc + hd)) continue;
+			check(s);
+		}
+	}
+}
+
+export { checkPoint, checkPositive, cellRange, cellDist2, decode };

package/src/index.js

@@ -6,7 +6,7 @@
 //==========================================================
 
 /** Library version, matches package.json. */
-export var VERSION = "0.5.0";
+export var VERSION = "0.6.1";
 
 export { LasError, ERROR_CODES } from "./errors.js";
 export { openLas, LasReader } from "./LasReader.js";
@@ -16,11 +16,14 @@ export { parseCrs } from "./format/LasCrs.js";
 export { POINT_FORMATS, formatHasRgb } from "./format/PointFormats.js";
 export { decodeRecords, DEFAULT_FIELDS, FIELD_TYPES } from "./read/decodeRecords.js";
 export { makeKeep, countKept } from "./filter/filters.js";
-export { dedupe } from "./filter/dedupe.js";
+export { dedupe, dedupeSelection } from "./filter/dedupe.js";
+export { buildIndex } from "./index/grid.js";
+export { pointsInRadius, nearestPoint, pointsNearRay } from "./index/query.js";
 export { selectBox, selectPolygon, selectClasses, selectReturns, thinSelection, unionSelections, intersectSelections, subtractSelections } from "./ops/select.js";
 export { keepPoints, removePoints, splitPoints, mergePoints } from "./ops/apply.js";
 export { makeTransform, transformPoints } from "./ops/transform.js";
 export { interleavePositions } from "./ops/interleave.js";
+export { selectSparse } from "./ops/sparse.js";
 export { MemorySource } from "./io/MemorySource.js";
 export { BlobSource } from "./io/BlobSource.js";
 export { NodeFileSource } from "./io/NodeFileSource.js";

package/src/ops/sparse.js

@@ -0,0 +1,97 @@
+// src/ops/sparse.js
+//==========================================================
+// The sparse-point (dust) filter: select the points that have fewer
+// than minNeighbours other points within radius (inclusive), for
+// removePoints. A private grid with cells one radius wide is built
+// and dropped. Each cell looks up its 27 neighbour cells once (9 in
+// 2D); a point near enough to a cell face that rounding could reach
+// two cells away gets its own lookup instead, so the count is exact.
+// Counting stops at minNeighbours: a point on a dense surface
+// usually gets there inside its own cell.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+import { coordsOf, buildGrid, lookup, checkPointCount } from "../index/grid.js";
+import { cellRange, visitBox, decode } from "../index/query.js";
+
+var FACE = 2e-6;   // in cells: nearer a face than this, a point gets its own cell lookup
+
+function bad(message) { return new LasError(ERROR_CODES.INVALID_ARGUMENT, message); }
+
+/**
+ * The points with fewer than minNeighbours other points within radius.
+ * minNeighbours 1 keeps any point with one neighbour inside the radius, so thin
+ * sparse features (a line of points down a scanned blasthole) survive; clumped
+ * dust survives too, and a higher minNeighbours removes small clumps at the
+ * cost of thin features.
+ * @param {object} cols - point columns with x, y, z, or a k = 3 positions column.
+ * @param {{radius: number, minNeighbours?: number, xy?: boolean}} opts - radius in the columns' units (required); minNeighbours default 1; xy: count in 2D.
+ * @returns {Uint32Array} selection of the sparse points
+ */
+export function selectSparse(cols, opts) {
+	var radius = opts ? opts.radius : undefined;
+	if (!(typeof radius === "number" && radius > 0 && isFinite(radius))) throw bad("selectSparse radius must be a positive finite number, not " + String(radius));
+	var minN = opts.minNeighbours === undefined ? 1 : opts.minNeighbours;
+	if (!(Number.isInteger(minN) && minN >= 1)) throw bad("selectSparse minNeighbours must be a whole number >= 1, not " + String(minN));
+	var xy = !!opts.xy;
+	var coords = coordsOf(cols, "selectSparse"), n = cols.count;
+	checkPointCount(n);
+	if (n === 0) return new Uint32Array(0);
+
+	var g = buildGrid(coords, n, radius, xy);
+	var X = coords.x, Y = coords.y, Z = coords.z, st = coords.stride, order = g.order, start = g.start, length = g.length;
+	var r2 = radius * radius, sparse = new Uint8Array(n), nSparse = 0;
+	var dz = xy ? 0 : 1;
+
+	// Count p's other points within radius over a list of slots, stopping at minN
+	function enough(p, slots) {
+		var o = p * st, px = X[o], py = Y[o], pz = xy ? 0 : Z[o], k = 0;
+		for (var a = 0; a < slots.length; a++) {
+			var s = slots[a];
+			for (var j = start[s], e = j + length[s]; j < e; j++) {
+				var q = order[j];
+				if (q === p) continue;
+				var w = q * st, ex = X[w] - px, ey = Y[w] - py, ez = xy ? 0 : Z[w] - pz;
+				if (ex * ex + ey * ey + ez * ez <= r2 && ++k >= minN) return true;
+			}
+		}
+		return false;
+	}
+
+	// A point on a cell face: the cells its own radius box covers, its own cell first
+	function slotsAround(o, own) {
+		var rx = cellRange(g, 0, X[o] - radius, X[o] + radius), ry = cellRange(g, 1, Y[o] - radius, Y[o] + radius);
+		var rz = xy ? [0, 0] : cellRange(g, 2, Z[o] - radius, Z[o] + radius), out = [own];
+		visitBox(g, [rx[0], ry[0], rz[0]], [rx[1], ry[1], rz[1]], function (u) { if (u !== own) out.push(u); });
+		return out;
+	}
+
+	var keys = g.keys, inv = 1 / g.cellSize, x0 = g.min[0], y0 = g.min[1], z0 = g.min[2];
+	for (var s = 0; s < keys.length; s++) {
+		if (keys[s] < 0) continue;
+		var c = decode(g, keys[s]);
+		var near = [s];   // own cell first
+		for (var ix = c[0] - 1; ix <= c[0] + 1; ix++) {
+			for (var iy = c[1] - 1; iy <= c[1] + 1; iy++) {
+				for (var iz = c[2] - dz; iz <= c[2] + dz; iz++) {
+					if (ix === c[0] && iy === c[1] && iz === c[2]) continue;
+					var t = lookup(g, ix, iy, iz);
+					if (t >= 0) near.push(t);
+				}
+			}
+		}
+		for (var j = start[s], e = j + length[s]; j < e; j++) {
+			var p = order[j], o = p * st;
+			// Where p sits in its cell (0 to 1 per axis): away from the faces, every point
+			// within one radius (= one cell) is in the 27 cells around
+			var fx = (X[o] - x0) * inv - c[0], fy = (Y[o] - y0) * inv - c[1], fz = xy ? 0.5 : (Z[o] - z0) * inv - c[2];
+			var slots = near;
+			if (fx < FACE || fx > 1 - FACE || fy < FACE || fy > 1 - FACE || fz < FACE || fz > 1 - FACE) slots = slotsAround(o, s);
+			if (!enough(p, slots)) { sparse[p] = 1; nSparse++; }
+		}
+	}
+
+	var out = new Uint32Array(nSparse);
+	for (var i = 0, w = 0; i < n; i++) if (sparse[i]) out[w++] = i;
+	return out;
+}