las-laz-js 0.4.0 → 0.5.0

package/src/ops/columns.js

@@ -0,0 +1,209 @@
+// src/ops/columns.js
+//==========================================================
+// Point columns and selections, the two shapes every operation in
+// src/ops takes. Columns are the object readPoints returns (or any
+// caller's object of the same shape): { count, <name>: TypedArray }.
+// A property is a column when it is a typed array of length
+// count * k, k a whole number >= 1 (k = 1 for x, classification;
+// k = 3 for an interleaved positions or rgb). A selection is a
+// Uint32Array of point indices, strictly ascending, each < count.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+
+var MAX_INDEX = 4294967295;
+
+function bad(message) { return new LasError(ERROR_CODES.INVALID_ARGUMENT, message); }
+
+function isTyped(v) { return ArrayBuffer.isView(v) && !(v instanceof DataView); }
+
+/**
+ * Check cols.count is a whole number >= 0 and return it.
+ * @param {object} cols - point columns.
+ * @returns {number}
+ */
+export function countOf(cols) {
+	if (cols === null || typeof cols !== "object") throw bad("columns must be an object { count, <name>: TypedArray }");
+	var n = cols.count;
+	if (typeof n !== "number" || !Number.isInteger(n) || n < 0) throw bad("count " + String(n) + " is not a whole number ≥ 0");
+	return n;
+}
+
+/**
+ * The columns of a point-column object: own typed-array properties of
+ * length count * k. With count 0, every typed array of length 0 is a
+ * k = 1 column. Everything else (numbers, bounds, a typed array of any
+ * other length) is skipped silently.
+ * @param {object} cols
+ * @returns {Array<{name: string, k: number}>}
+ */
+export function columnsOf(cols) {
+	var n = countOf(cols);
+	var out = [];
+	Object.keys(cols).forEach(function (name) {
+		var a = cols[name];
+		if (!isTyped(a)) return;
+		if (n === 0) {
+			if (a.length === 0) out.push({ name: name, k: 1 });
+			return;
+		}
+		var k = a.length / n;
+		if (Number.isInteger(k) && k >= 1) out.push({ name: name, k: k });
+	});
+	return out;
+}
+
+/**
+ * Validate a selection and return it as a Uint32Array. Accepts a
+ * Uint32Array or a plain Array of whole numbers; it must be strictly
+ * ascending with every index below count.
+ * @param {Uint32Array|number[]} sel
+ * @param {number} count - points in the columns (Infinity: no upper limit).
+ * @param {string} [name] - how the message names it (default "selection").
+ * @returns {Uint32Array}
+ */
+export function checkSelection(sel, count, name) {
+	name = name || "selection";
+	var isU32 = sel instanceof Uint32Array;
+	if (!isU32 && !Array.isArray(sel)) throw bad(name + " must be a Uint32Array or an Array of whole numbers");
+	var prev = -1;
+	for (var i = 0; i < sel.length; i++) {
+		var v = sel[i];
+		var at = name + "[" + i + "] = " + v;
+		if (typeof v !== "number" || !Number.isInteger(v) || v < 0) throw bad(at + " is not a whole number ≥ 0");
+		if (v > MAX_INDEX) throw bad(at + " is not below " + (MAX_INDEX + 1));
+		if (v <= prev) throw bad(at + " is not above " + name + "[" + (i - 1) + "] = " + prev);
+		if (v >= count) throw bad(at + " is not below count " + count);
+		prev = v;
+	}
+	return isU32 ? sel : Uint32Array.from(sel);
+}
+
+/**
+ * The k = 1 column called name, or an error naming the function.
+ * @param {object} cols
+ * @param {string} name
+ * @param {string} fn - the calling function, for the message.
+ * @returns {TypedArray}
+ */
+export function needColumn(cols, name, fn) {
+	var n = countOf(cols);
+	var a = cols[name];
+	if (!isTyped(a) || a.length !== n) throw bad(fn + " needs a " + name + " column");
+	return a;
+}
+
+/**
+ * A new typed array of the same type as a (a Node Buffer gives a Uint8Array).
+ * Internal; not exported from the package entry.
+ * @param {TypedArray} a
+ * @param {number} length
+ * @returns {TypedArray}
+ */
+export function sameType(a, length) {
+	var Ctor = globalThis[Object.prototype.toString.call(a).slice(8, -1)];
+	return new Ctor(length);
+}
+
+/**
+ * dst[i] = src[sel[i]] for each i (k values each; internal, not exported from the package entry).
+ * dst may be src: i <= sel[i], so ascending writes never overwrite a value still to be read.
+ * @param {TypedArray} src
+ * @param {TypedArray} dst
+ * @param {number} k
+ * @param {Uint32Array} sel - strictly ascending.
+ */
+export function gather(src, dst, k, sel) {
+	var n = sel.length;
+	if (k === 1) {
+		for (var i = 0; i < n; i++) dst[i] = src[sel[i]];
+		return;
+	}
+	for (var p = 0; p < n; p++) {
+		var from = sel[p] * k;
+		var to = p * k;
+		for (var j = 0; j < k; j++) dst[to + j] = src[from + j];
+	}
+}
+
+/**
+ * Throw INVALID_ARGUMENT when two of the named columns overlap in memory (internal; not exported
+ * from the package entry). In-place compaction writes into every column's buffer, so two columns
+ * whose byte ranges overlap would corrupt each other: refuse before any write.
+ * @param {object} cols
+ * @param {Array<{name: string}>} list - the columns to check, by name.
+ */
+export function checkNoSharedMemory(cols, list) {
+	for (var i = 0; i < list.length; i++) {
+		var a = cols[list[i].name];
+		if (a.byteLength === 0) continue;
+		for (var j = i + 1; j < list.length; j++) {
+			var b = cols[list[j].name];
+			if (b.byteLength === 0 || a.buffer !== b.buffer) continue;
+			if (a.byteOffset < b.byteOffset + b.byteLength && b.byteOffset < a.byteOffset + a.byteLength) {
+				throw bad("inPlace: columns \"" + list[i].name + "\" and \"" + list[j].name + "\" share memory");
+			}
+		}
+	}
+}
+
+var FLOATS = { Float64Array: 8, Float32Array: 4 };
+function has(o, k) { return Object.prototype.hasOwnProperty.call(o, k); }
+
+var INTS = {
+	Int8Array: [1, true], Int16Array: [2, true], Int32Array: [4, true],
+	Uint8Array: [1, false], Uint8ClampedArray: [1, false], Uint16Array: [2, false], Uint32Array: [4, false]
+};
+var BIGS = { BigInt64Array: true, BigUint64Array: true };
+
+/**
+ * The typed-array type a merge of columns of these types is stored in
+ * (internal; not exported from the package entry). Float64 beats Float32
+ * beats any integer type, except that Float32 with a 32-bit integer type
+ * (Int32, Uint32) gives Float64, since Float32 holds integers exactly only
+ * to 2^24. Among integers the widest wins, and mixed
+ * signedness is allowed only when the widest is signed and strictly
+ * wider than every unsigned one (Uint8 + Int16 gives Int16); Int16 +
+ * Uint16 and Int8 + Uint16 throw, because the unsigned values would wrap.
+ * Uint8ClampedArray counts as Uint8Array. A BigInt array only merges
+ * with its own type.
+ * @param {Function[]} types - typed-array constructors, at least one.
+ * @param {string} name - the column, for the message.
+ * @returns {Function}
+ */
+export function widestType(types, name) {
+	var label = "column \"" + name + "\"";
+	if (!Array.isArray(types) || types.length === 0) throw bad(label + " has no types to merge");
+	var names = types.map(function (t) {
+		var n = t && t.name;
+		if (typeof n !== "string" || (!has(FLOATS, n) && !has(INTS, n) && !has(BIGS, n))) throw bad(label + " has a type that is not a typed-array constructor");
+		return n === "Uint8ClampedArray" ? "Uint8Array" : n;
+	});
+	var first = names[0];
+	if (has(BIGS, first)) {
+		names.forEach(function (n) {
+			if (n !== first) throw bad(label + " cannot merge " + first + " with " + n);
+		});
+		return globalThis[first];
+	}
+	names.forEach(function (n) {
+		if (has(BIGS, n)) throw bad(label + " cannot merge " + n + " with " + first);
+	});
+	if (names.indexOf("Float64Array") >= 0) return Float64Array;
+	if (names.indexOf("Float32Array") >= 0) {
+		// Float32 holds integers exactly only to 2^24: 32-bit integers (an index column) go to Float64
+		if (names.indexOf("Int32Array") >= 0 || names.indexOf("Uint32Array") >= 0) return Float64Array;
+		return Float32Array;
+	}
+	var maxS = 0;
+	var maxU = 0;
+	names.forEach(function (n) {
+		var b = INTS[n][0];
+		if (INTS[n][1]) { if (b > maxS) maxS = b; } else if (b > maxU) maxU = b;
+	});
+	if (maxS > 0 && maxU > 0 && maxS <= maxU) {
+		throw bad(label + " cannot merge signed Int" + maxS * 8 + "Array with unsigned Uint" + maxU * 8 + "Array (values would wrap)");
+	}
+	if (maxS > 0) return globalThis["Int" + maxS * 8 + "Array"];
+	return globalThis["Uint" + maxU * 8 + "Array"];
+}

package/src/ops/interleave.js

@@ -0,0 +1,81 @@
+// src/ops/interleave.js
+//==========================================================
+// Interleaved positions for a renderer: x, y[, z] packed per point
+// into one typed array (Kirra uploads these to Three.js). Values
+// are written in Float64 and shifted by an optional origin before
+// they are stored, so large world coordinates keep their decimals
+// in a Float32 buffer.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+import { countOf, needColumn } from "./columns.js";
+
+function bad(message) { return new LasError(ERROR_CODES.INVALID_ARGUMENT, message); }
+
+// The origin axis as a number to subtract, or 0 when it is absent or not finite.
+function shiftOf(origin, axis) {
+	var v = origin[axis];
+	if (v === undefined || v === null) return 0;
+	if (typeof v !== "number") throw bad("origin." + axis + " must be a number");
+	return Number.isFinite(v) ? v : 0;
+}
+
+/**
+ * Pack point positions as interleaved values, x y z (stride 3) or x y
+ * (stride 2). Each value is shifted by the origin in Float64, then
+ * stored. An origin axis that is absent or not finite is not shifted,
+ * so { x, y } keeps world Z.
+ * @param {object} cols - point columns with x and y (and z for "xyz").
+ * @param {{layout?: "xyz"|"xy", into?: Float32Array|Float64Array, at?: number,
+ *   origin?: {x?: number, y?: number, z?: number}, float32?: boolean}} [options]
+ *   layout: default "xyz". into: a caller's buffer, written from element at × stride
+ *   (default: a new Float32Array when float32 is true or omitted, else a Float64Array).
+ *   at: whole number ≥ 0, default 0.
+ * @returns {Float32Array|Float64Array} into, or the new array.
+ * @throws {LasError} INVALID_ARGUMENT when an argument is wrong or into is too short.
+ */
+export function interleavePositions(cols, options) {
+	var opt = options === undefined ? {} : options;
+	if (opt === null || typeof opt !== "object") throw bad("options must be an object");
+	var n = countOf(cols);
+	var layout = opt.layout === undefined ? "xyz" : opt.layout;
+	if (layout !== "xyz" && layout !== "xy") throw bad("layout " + String(layout) + " is not \"xyz\" or \"xy\"");
+	var stride = layout === "xyz" ? 3 : 2;
+	var at = opt.at === undefined ? 0 : opt.at;
+	if (typeof at !== "number" || !Number.isInteger(at) || at < 0) throw bad("at " + String(at) + " is not a whole number ≥ 0");
+	var origin = opt.origin === undefined || opt.origin === null ? {} : opt.origin;
+	if (typeof origin !== "object") throw bad("origin must be an object { x, y, z }");
+	var sx = shiftOf(origin, "x");
+	var sy = shiftOf(origin, "y");
+	var sz = layout === "xyz" ? shiftOf(origin, "z") : 0;
+
+	var x = needColumn(cols, "x", "interleavePositions");
+	var y = needColumn(cols, "y", "interleavePositions");
+	var z = layout === "xyz" ? needColumn(cols, "z", "interleavePositions") : null;
+
+	var into = opt.into;
+	if (into === undefined) {
+		var f32 = opt.float32 === undefined ? true : opt.float32;
+		into = f32 ? new Float32Array(n * stride) : new Float64Array(n * stride);
+	} else if (!(into instanceof Float32Array) && !(into instanceof Float64Array)) {
+		throw bad("into must be a Float32Array or a Float64Array");
+	}
+	if ((at + n) * stride > into.length) throw bad("into is too short: needs " + (at + n) * stride + " elements from " + at * stride + ", has " + into.length);
+
+	var base = at * stride;
+	if (stride === 3) {
+		for (var i = 0; i < n; i++) {
+			var o = base + i * 3;
+			into[o] = x[i] - sx;
+			into[o + 1] = y[i] - sy;
+			into[o + 2] = z[i] - sz;
+		}
+	} else {
+		for (var j = 0; j < n; j++) {
+			var p = base + j * 2;
+			into[p] = x[j] - sx;
+			into[p + 1] = y[j] - sy;
+		}
+	}
+	return into;
+}

package/src/ops/polygon.js

@@ -0,0 +1,83 @@
+// src/ops/polygon.js
+//==========================================================
+// The point-in-polygon test behind selectPolygon and the reader's
+// polygon crop (filters.js). Internal: not exported from index.js.
+// The boundary decision comes first (a point within tolerance of an
+// edge or vertex, measured in Float64), so an edge point never
+// depends on crossing-test rounding; only a point clear of every
+// edge goes to the even-odd crossing test (W. Randolph Franklin's
+// PNPOLY).
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+
+function bad(message) { return new LasError(ERROR_CODES.INVALID_ARGUMENT, message); }
+
+// Validate a flat polygon [x0, y0, x1, y1, ...] and copy it to a Float64Array
+function checkPolygon(polygon) {
+	if (!Array.isArray(polygon) && !(ArrayBuffer.isView(polygon) && !(polygon instanceof DataView))) throw bad("polygon must be an Array or typed array [x0, y0, x1, y1, ...]");
+	var n = polygon.length;
+	if (n % 2 !== 0) throw bad("polygon has an odd length " + n + ": it holds x, y pairs");
+	if (n < 6) throw bad("polygon needs at least 3 vertices (6 values), got " + n);
+	var p = new Float64Array(n);
+	for (var i = 0; i < n; i++) {
+		var v = polygon[i];
+		if (typeof v !== "number" || !Number.isFinite(v)) throw bad("polygon[" + i + "] = " + String(v) + " is not a finite number");
+		p[i] = v;
+	}
+	return p;
+}
+
+/**
+ * Build a point-in-polygon test.
+ * @param {number[]|TypedArray} polygon - [x0, y0, x1, y1, ...], at least 3 vertices, implicitly closed.
+ * @param {{boundary?: string, tolerance?: number}} [opts] - boundary "touching" (default: points on the
+ *   boundary are in) or "inside" (they are out); tolerance (default 0): within this distance of an edge
+ *   or vertex is on the boundary.
+ * @returns {{test: function(number, number): boolean, minX: number, maxX: number, minY: number, maxY: number}}
+ *   test(x, y) decides a point (false outside the box at once); the box is the polygon's grown by tolerance.
+ */
+export function makePolygonTest(polygon, opts) {
+	if (opts === undefined || opts === null) opts = {};
+	if (typeof opts !== "object") throw bad("options must be an object { boundary, tolerance }");
+	var p = checkPolygon(polygon);
+	var boundary = opts.boundary === undefined ? "touching" : opts.boundary;
+	if (boundary !== "touching" && boundary !== "inside") throw bad("boundary must be \"touching\" or \"inside\", got " + String(boundary));
+	var tol = opts.tolerance === undefined ? 0 : opts.tolerance;
+	if (typeof tol !== "number" || !Number.isFinite(tol) || tol < 0) throw bad("tolerance must be a finite number ≥ 0, got " + String(tol));
+	var touching = boundary === "touching", tol2 = tol * tol;
+	var n = p.length / 2;
+	var minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+	for (var k = 0; k < n; k++) {
+		if (p[2 * k] < minX) minX = p[2 * k];
+		if (p[2 * k] > maxX) maxX = p[2 * k];
+		if (p[2 * k + 1] < minY) minY = p[2 * k + 1];
+		if (p[2 * k + 1] > maxY) maxY = p[2 * k + 1];
+	}
+	minX -= tol; maxX += tol; minY -= tol; maxY += tol;
+
+	// Squared distance from (px, py) to the segment (ax, ay)-(bx, by); 0 when the point is exactly on it
+	function dist2(px, py, ax, ay, bx, by) {
+		var ex = bx - ax, ey = by - ay;
+		var wx = px - ax, wy = py - ay;
+		var len2 = ex * ex + ey * ey;
+		if (len2 === 0) return wx * wx + wy * wy;
+		if (ex * wy - ey * wx === 0 && px >= Math.min(ax, bx) && px <= Math.max(ax, bx) && py >= Math.min(ay, by) && py <= Math.max(ay, by)) return 0;
+		var t = (wx * ex + wy * ey) / len2;
+		if (t < 0) t = 0; else if (t > 1) t = 1;
+		var dx = px - (ax + t * ex), dy = py - (ay + t * ey);
+		return dx * dx + dy * dy;
+	}
+
+	function test(px, py) {
+		if (!(px >= minX && px <= maxX && py >= minY && py <= maxY)) return false;
+		var inside = false;
+		for (var i = 0, j = n - 1; i < n; j = i++) {
+			var ax = p[2 * j], ay = p[2 * j + 1], bx = p[2 * i], by = p[2 * i + 1];
+			if (dist2(px, py, ax, ay, bx, by) <= tol2) return touching;
+			if ((by > py) !== (ay > py) && px < (ax - bx) * (py - by) / (ay - by) + bx) inside = !inside;
+		}
+		return inside;
+	}
+	return { test: test, minX: minX, maxX: maxX, minY: minY, maxY: maxY };
+}

package/src/ops/select.js

@@ -0,0 +1,245 @@
+// src/ops/select.js
+//==========================================================
+// Making selections: a Uint32Array of point indices, strictly
+// ascending, from point columns (see columns.js). Box, class and
+// return selections mean what the reader's filters mean; thinSelection
+// is the reader's maxPoints rule, exported, and thinStep is the one
+// place that rule lives (decodeRecords calls it per passing record).
+// Set operations are linear merges of two ascending selections.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+import { countOf, checkSelection, needColumn } from "./columns.js";
+import { makePolygonTest } from "./polygon.js";
+
+function bad(message) { return new LasError(ERROR_CODES.INVALID_ARGUMENT, message); }
+
+function whole(v) { return typeof v === "number" && Number.isInteger(v) && v >= 0; }
+
+// out[0..n) as a copy that does not pin the full-size buffer.
+function trim(out, n) { return n === out.length ? out : out.slice(0, n); }
+
+// A lookup table of 256 flags for a list of whole numbers 0..255.
+function table(list, name) {
+	if (!Array.isArray(list)) throw bad(name + " must be an Array of whole numbers");
+	var t = new Uint8Array(256);
+	list.forEach(function (v, i) {
+		if (!whole(v) || v > 255) throw bad(name + "[" + i + "] = " + v + " is not a whole number 0 to 255");
+		t[v] = 1;
+	});
+	return t;
+}
+
+function bound(box, key) {
+	var v = box[key];
+	if (v === undefined || v === null) return undefined;
+	if (typeof v !== "number" || v !== v) throw bad(key + " must be a number");
+	return v;
+}
+
+/**
+ * Indices of the points inside a box, bounds inclusive. An omitted
+ * (undefined) or null bound is no limit, as in the reader's bounds. Needs x and y; z only when minZ or
+ * maxZ is given.
+ * @param {object} cols - point columns.
+ * @param {{minX?:number, maxX?:number, minY?:number, maxY?:number, minZ?:number, maxZ?:number}} box
+ * @returns {Uint32Array}
+ */
+export function selectBox(cols, box) {
+	var n = countOf(cols);
+	if (box === null || typeof box !== "object") throw bad("box must be an object { minX, maxX, minY, maxY, minZ, maxZ }");
+	var minX = bound(box, "minX"), maxX = bound(box, "maxX");
+	var minY = bound(box, "minY"), maxY = bound(box, "maxY");
+	var minZ = bound(box, "minZ"), maxZ = bound(box, "maxZ");
+	var x = needColumn(cols, "x", "selectBox"), y = needColumn(cols, "y", "selectBox");
+	var useZ = minZ !== undefined || maxZ !== undefined;
+	var z = useZ ? needColumn(cols, "z", "selectBox") : null;
+	if (minX === undefined) minX = -Infinity;
+	if (maxX === undefined) maxX = Infinity;
+	if (minY === undefined) minY = -Infinity;
+	if (maxY === undefined) maxY = Infinity;
+	if (minZ === undefined) minZ = -Infinity;
+	if (maxZ === undefined) maxZ = Infinity;
+	var out = new Uint32Array(n), m = 0;
+	for (var i = 0; i < n; i++) {
+		var vx = x[i];
+		if (!(vx >= minX && vx <= maxX)) continue;
+		var vy = y[i];
+		if (!(vy >= minY && vy <= maxY)) continue;
+		if (useZ) {
+			var vz = z[i];
+			if (!(vz >= minZ && vz <= maxZ)) continue;
+		}
+		out[m++] = i;
+	}
+	return trim(out, m);
+}
+
+/**
+ * Indices of the points inside a polygon (even-odd rule), in the columns' own frame. A point on the
+ * boundary (within tolerance of an edge or vertex, as the 2D distance to the segment in Float64) is
+ * kept by boundary "touching" (default) and dropped by "inside", so the two differ by exactly the
+ * boundary points. The boundary is decided before the crossing test. Needs x and y; z only when a Z
+ * limit is given.
+ * @param {object} cols - point columns.
+ * @param {number[]|TypedArray} polygon - [x0, y0, x1, y1, ...], at least 3 vertices, implicitly closed.
+ * @param {{boundary?: "touching"|"inside", tolerance?: number, minZ?: number, maxZ?: number}} [opts]
+ * @returns {Uint32Array}
+ */
+export function selectPolygon(cols, polygon, opts) {
+	var n = countOf(cols);
+	if (opts === undefined || opts === null) opts = {};
+	if (typeof opts !== "object") throw bad("options must be an object { boundary, tolerance, minZ, maxZ }");
+	var poly = makePolygonTest(polygon, opts);
+	var minZ = bound(opts, "minZ"), maxZ = bound(opts, "maxZ");
+	var x = needColumn(cols, "x", "selectPolygon"), y = needColumn(cols, "y", "selectPolygon");
+	var useZ = minZ !== undefined || maxZ !== undefined;
+	var z = useZ ? needColumn(cols, "z", "selectPolygon") : null;
+	if (minZ === undefined) minZ = -Infinity;
+	if (maxZ === undefined) maxZ = Infinity;
+	var test = poly.test;
+	var out = new Uint32Array(n), m = 0;
+	for (var i = 0; i < n; i++) {
+		if (useZ) {
+			var vz = z[i];
+			if (!(vz >= minZ && vz <= maxZ)) continue;
+		}
+		if (test(x[i], y[i])) out[m++] = i;
+	}
+	return trim(out, m);
+}
+
+/**
+ * Indices of the points whose classification is in the list.
+ * @param {object} cols - point columns (needs classification).
+ * @param {number[]} classes
+ * @returns {Uint32Array}
+ */
+export function selectClasses(cols, classes) {
+	var n = countOf(cols);
+	var cls = needColumn(cols, "classification", "selectClasses");
+	var t = table(classes, "classes");
+	var out = new Uint32Array(n), m = 0;
+	for (var i = 0; i < n; i++) if (cls[i] < 256 && t[cls[i]] === 1) out[m++] = i;
+	return trim(out, m);
+}
+
+/**
+ * Indices of the points matching any of the return criteria given:
+ * returns (returnNumber in the list), first (returnNumber 1), last
+ * (returnNumber equals numberOfReturns), single (numberOfReturns 1).
+ * @param {object} cols - point columns (returnNumber; numberOfReturns for last / single).
+ * @param {{returns?:number[], first?:boolean, last?:boolean, single?:boolean}} criteria
+ * @returns {Uint32Array}
+ */
+export function selectReturns(cols, criteria) {
+	var n = countOf(cols);
+	if (criteria === null || typeof criteria !== "object") throw bad("criteria must be an object { returns, first, last, single }");
+	var hasList = criteria.returns !== undefined;
+	var first = !!criteria.first, last = !!criteria.last, single = !!criteria.single;
+	if (!hasList && !first && !last && !single) throw bad("selectReturns needs returns, first, last or single");
+	var t = hasList ? table(criteria.returns, "returns") : null;
+	var rn = needColumn(cols, "returnNumber", "selectReturns");
+	var nr = (last || single) ? needColumn(cols, "numberOfReturns", "selectReturns") : null;
+	var out = new Uint32Array(n), m = 0;
+	for (var i = 0; i < n; i++) {
+		var r = rn[i];
+		var hit = (hasList && r < 256 && t[r] === 1) || (first && r === 1) || (last && r === nr[i]) || (single && nr[i] === 1);
+		if (hit) out[m++] = i;
+	}
+	return trim(out, m);
+}
+
+/**
+ * One step of the reader's even-thinning rule. thin is
+ * { total, target, acc }: acc gains target per record and the record
+ * is kept each time acc reaches total (then acc -= total). The j-th
+ * kept record is number ceil(j * total / target) - 1.
+ * @param {{total:number, target:number, acc:number}} thin - updated in place.
+ * @returns {boolean} true when this record is kept.
+ */
+export function thinStep(thin) {
+	thin.acc += thin.target;
+	if (thin.acc < thin.total) return false;
+	thin.acc -= thin.total;
+	return true;
+}
+
+/**
+ * The reader's maxPoints rule as a selection: exactly min(count, target)
+ * indices spread evenly over 0..count-1. readPoints({ maxPoints: target })
+ * keeps the same points.
+ * @param {number} count - points to choose from.
+ * @param {number} target - points to keep.
+ * @returns {Uint32Array}
+ */
+export function thinSelection(count, target) {
+	if (!whole(count)) throw bad("count " + String(count) + " is not a whole number ≥ 0");
+	if (!whole(target)) throw bad("target " + String(target) + " is not a whole number ≥ 0");
+	var out, i;
+	if (target >= count) {
+		out = new Uint32Array(count);
+		for (i = 0; i < count; i++) out[i] = i;
+		return out;
+	}
+	out = new Uint32Array(target);
+	var thin = { total: count, target: target, acc: 0 }, m = 0;
+	for (i = 0; i < count && m < target; i++) if (thinStep(thin)) out[m++] = i;
+	return out;
+}
+
+/**
+ * Indices in a or in b.
+ * @param {Uint32Array|number[]} a - ascending selection.
+ * @param {Uint32Array|number[]} b - ascending selection.
+ * @returns {Uint32Array}
+ */
+export function unionSelections(a, b) {
+	a = checkSelection(a, Infinity, "a");
+	b = checkSelection(b, Infinity, "b");
+	var out = new Uint32Array(a.length + b.length), i = 0, j = 0, m = 0;
+	while (i < a.length && j < b.length) {
+		if (a[i] < b[j]) out[m++] = a[i++];
+		else if (a[i] > b[j]) out[m++] = b[j++];
+		else { out[m++] = a[i++]; j++; }
+	}
+	while (i < a.length) out[m++] = a[i++];
+	while (j < b.length) out[m++] = b[j++];
+	return trim(out, m);
+}
+
+/**
+ * Indices in both a and b.
+ * @param {Uint32Array|number[]} a - ascending selection.
+ * @param {Uint32Array|number[]} b - ascending selection.
+ * @returns {Uint32Array}
+ */
+export function intersectSelections(a, b) {
+	a = checkSelection(a, Infinity, "a");
+	b = checkSelection(b, Infinity, "b");
+	var out = new Uint32Array(Math.min(a.length, b.length)), i = 0, j = 0, m = 0;
+	while (i < a.length && j < b.length) {
+		if (a[i] < b[j]) i++;
+		else if (a[i] > b[j]) j++;
+		else { out[m++] = a[i++]; j++; }
+	}
+	return trim(out, m);
+}
+
+/**
+ * Indices in a that are not in b.
+ * @param {Uint32Array|number[]} a - ascending selection.
+ * @param {Uint32Array|number[]} b - ascending selection.
+ * @returns {Uint32Array}
+ */
+export function subtractSelections(a, b) {
+	a = checkSelection(a, Infinity, "a");
+	b = checkSelection(b, Infinity, "b");
+	var out = new Uint32Array(a.length), i = 0, j = 0, m = 0;
+	while (i < a.length) {
+		while (j < b.length && b[j] < a[i]) j++;
+		if (j < b.length && b[j] === a[i]) { i++; continue; }
+		out[m++] = a[i++];
+	}
+	return trim(out, m);
+}