las-laz-js 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-10-21)
+
+First release: read and write ASPRS LAS.
+
+- `openLas` reads the header, VLRs, EVLRs and coordinate system (GeoKeys / WKT) of LAS 1.0–1.4,
+  from a File / Blob, ArrayBuffer, Uint8Array, Node path or any `{ size, read }` source.
+- `readPoints` and `chunks` decode every point format (0–10) in windows of whole records, never
+  holding the file whole; filters (classes, returns, bounds), even thinning (`maxPoints`),
+  `dedupe`, `localOrigin` + `float32`, progress and abort.
+- `readPointsToScratch` streams columns into OPFS scratch files.
+- `colourize` by RGB (with 8-bit files detected), intensity, elevation or classification.
+- `writeLas` and the streaming `createLasWriter` write LAS 1.0–1.4, formats 0–10, with EPSG or
+  WKT coordinate systems.
+- `las-laz-js/worker`: a module Worker with a documented message protocol.
+- A Three.js demo.
+- LAZ files open and report `compressed`; reading their points arrives in 0.2.0.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brent Buffham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# las-laz-js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A JavaScript reader and writer for ASPRS **LAS** point clouds (LAZ to follow), published on npm
+as `las-laz-js`. Plain ES modules, no dependencies, runs in the browser and in Node — and built
+for files far larger than memory.
+
+**Status: early (0.x).** It works and is tested, but the API may still change before 1.0.
+
+- Working: `openLas` reads the header, VLRs / EVLRs and coordinate system of LAS 1.0–1.4;
+  `readPoints` and `chunks` decode every point format (0–10) a window at a time, with filters
+  and thinning; `colourize` colours points; `writeLas` writes LAS 1.0–1.4.
+- Big files: a 1.1 GB, 34-million-point cloud reads in about 2 seconds in Node, and is never held
+  in memory whole.
+- Also: a ready-made module Worker (`las-laz-js/worker`) and a Three.js demo.
+- Not yet: reading LAZ (0.2.0) and writing LAZ (0.3.0).
+
+## Install
+
+```sh
+npm install las-laz-js
+```
+
+Node 22 or newer, or any current browser. No dependencies.
+
+## Demo
+
+Drop a LAS file onto the page and it is read locally (never uploaded), in the library's Worker,
+and streamed into a Three.js viewer. The side panel runs every library function.
+Run it locally with `npm run demo`, then open http://localhost:8080/.
+
+## Reading
+
+```js
+import { openLas } from "las-laz-js";
+
+var las = await openLas(file);           // File / Blob, ArrayBuffer, Uint8Array, a Node path, or { size, read }
+las.header;   // { versionMajor, versionMinor, pointFormat, pointCount, bounds, scale, offset,
+              //   software, systemId, creationDay, creationYear, pointsByReturn, compressed, ... }
+las.crs;      // { kind: "geokeys" | "wkt" | null, epsg, wkt?, keys? } — parsed, never reprojected
+las.vlrs;     // [{ userId, recordId, description, bytes }]
+
+var pts = await las.readPoints({
+	fields: ["x", "y", "z", "classification", "red", "green", "blue"],
+	classes: [2],            // keep only these classification codes
+	returns: [1],            // keep only these return numbers
+	bounds: { minX, maxX, minY, maxY, minZ, maxZ },
+	maxPoints: 5000000,      // even thinning; 0 keeps every point
+	dedupe: 0.01,            // drop points within 1 cm (XY; dedupeZ: true for 3D)
+	localOrigin: { x: 478000, y: 6772000 }, float32: true,   // small Float32 coordinates for the GPU
+	onProgress: function (fraction, label) {},
+	signal: abortController.signal
+});
+pts.count; pts.x; pts.y; pts.z;   // one typed array per field
+pts.bounds; pts.stats;            // world bounds, per-class counts
+```
+
+Fields: `x y z intensity returnNumber numberOfReturns scanDirection edgeOfFlightLine
+classification classificationFlags scannerChannel scanAngle userData pointSourceId gpsTime
+red green blue nir`. Fields a point format does not hold are left out. `scanAngle` is in
+degrees for every format.
+
+Filters run on the raw record before it is decoded, so a filtered-out point costs a byte read.
+
+## Files bigger than memory
+
+`openLas` reads only the header and the VLRs. Points are read in windows of whole records
+(64 MiB by default, `openLas(file, { windowSize })`), so memory holds one window plus what you
+keep.
+
+```js
+for await (var chunk of las.chunks({ fields: ["x", "y", "z"] })) {
+	draw(chunk);          // one window's points
+}
+```
+
+In the browser, `readPointsToScratch` streams the selected columns into OPFS scratch files (one
+per field) instead of memory; run it in a Worker, which OPFS sync access needs.
+
+## Colour
+
+```js
+import { colourize } from "las-laz-js";
+var rgb = colourize(pts, { by: "elevation" });   // "rgb" | "intensity" | "elevation" | "classification"
+```
+
+Returns a `Uint8Array`, three bytes per point. LAS colour is 16-bit and is scaled to 8 bits —
+except in files that store 8-bit values in the 16-bit fields (a common writer bug), which are
+detected and used as they are instead of turning almost black. Elevation uses a blue → cyan →
+green → yellow → red ramp; intensity a greyscale over the 2nd–98th percentile; classification
+the usual LiDAR-viewer colours (ASPRS defines the codes, not colours).
+
+## Writing
+
+```js
+import { writeLas, createLasWriter } from "las-laz-js";
+
+var bytes = await writeLas(pts, { version: "1.4", pointFormat: 7, crs: { epsg: 28350 } });
+
+var w = await createLasWriter(sink, { version: "1.2", pointFormat: 3, scale, offset });  // sink: { write(bytes, position) }
+await w.writePoints(batch1); await w.writePoints(batch2);
+await w.close();   // patches the header totals
+```
+
+A version and point format that do not go together (format 6 in LAS 1.2) are refused, never
+silently changed. Scale and offset are chosen from the bounds when not given. `crs.epsg`
+writes a GeoKey record; `crs.wkt` a WKT record.
+
+## In a Worker
+
+```js
+var worker = new Worker(new URL("las-laz-js/worker", import.meta.url), { type: "module" });
+worker.postMessage({ id: 1, type: "open", payload: { blob: file } });
+worker.postMessage({ id: 2, type: "chunks", payload: { fields: ["x", "y", "z"], colour: { by: "rgb" } } });
+// replies: { id, type: "progress" | "chunk" | "result" | "error", ... }; buffers are transferred
+```
+
+The protocol is documented in `src/workers/workerProtocol.js` and can be driven directly with
+`createWorkerHandler(post)`.
+
+## Errors
+
+Every failure is a `LasError` with a stable `code` (`ERROR_CODES`) and, for byte-level problems,
+the file `offset`: `NOT_LAS`, `UNSUPPORTED_VERSION`, `UNSUPPORTED`, `COMPRESSED_LAZ`,
+`TRUNCATED`, `BAD_HEADER`, `BAD_VLR`, `INVALID_ARGUMENT`, `ABORTED`, `TOO_MANY_POINTS`.
+A file shorter than its header promises is `TRUNCATED`, never garbage points.
+
+## Scope
+
+Reprojection is out of scope (the coordinate system is reported, not changed). Waveform
+formats 4, 5, 9 and 10 have their point fields read; the waveform data itself is not. COPC,
+EPT and E57 are not read.
+
+## Provenance
+
+The LAS reader, writer and big-file handling come from [Kirra](https://kirra-design.com),
+Brent Buffham's blast-design app, rewritten as a standalone library. The LAZ codec (0.2.0) is
+being ported from [laz-rs](https://github.com/laz-rs/laz-rs), used under its MIT licence.
+Formats are written to the ASPRS LAS 1.4 R15 specification; see `docs/LAS_FORMAT_NOTES.md`.
+
+## Development
+
+```sh
+npm test               # node --test, every test
+npm run test:coverage  # with the coverage gate
+npm run demo           # the demo on http://localhost:8080/
+npm run check:private  # before every push: no private sample details in the repo
+```
+
+Private sample files go in the gitignored `samples/` folder, or are listed by path in
+`samples/paths.txt`; the sample tests compare each file with its own header.
+
+## Licence
+
+MIT © Brent Buffham

package/package.json

@@ -1,6 +1,48 @@
 {
-  "name": "las-laz-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "las-laz-js",
+	"version": "0.1.0",
+	"description": "Zero-dependency JavaScript reader and writer for ASPRS LAS point clouds (LAZ to follow), for the browser and Node, built for files larger than memory.",
+	"type": "module",
+	"exports": {
+		".": "./src/index.js",
+		"./worker": "./src/workers/lasWorker.js"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"engines": {
+		"node": ">=22"
+	},
+	"scripts": {
+		"test": "node --test \"test/**/*.test.js\"",
+		"test:coverage": "node --test --experimental-test-coverage --test-coverage-include=\"src/**\" --test-coverage-lines=97 --test-coverage-branches=88 --test-coverage-functions=97 \"test/**/*.test.js\"",
+		"demo": "node _dev/serve.mjs",
+		"check:private": "node _dev/checkPrivate.mjs"
+	},
+	"keywords": [
+		"las",
+		"laz",
+		"lidar",
+		"point-cloud",
+		"pointcloud",
+		"asprs",
+		"gis",
+		"survey",
+		"opfs",
+		"threejs"
+	],
+	"author": "Brent Buffham (https://kirra-design.com)",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/brentbuffham/las-laz-js.git"
+	},
+	"bugs": {
+		"url": "https://github.com/brentbuffham/las-laz-js/issues"
+	},
+	"homepage": "https://github.com/brentbuffham/las-laz-js#readme"
+}

package/src/LasReader.js

@@ -0,0 +1,242 @@
+// src/LasReader.js
+//==========================================================
+// openLas(source) -> LasReader. Opening reads only the header and
+// the VLRs; points are read later in windows of whole records
+// (default 64 MiB), so a file far larger than memory streams
+// through and is never held whole — Kirra's current import reads
+// the whole file into one ArrayBuffer; this does not.
+//
+// Sources: a File / Blob, an ArrayBuffer / Uint8Array, a Node file
+// path, or any async source { size, read(start, end) }.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "./errors.js";
+import { BlobSource } from "./io/BlobSource.js";
+import { MemorySource } from "./io/MemorySource.js";
+import { NodeFileSource } from "./io/NodeFileSource.js";
+import { parseHeader } from "./format/LasHeader.js";
+import { parseVlrs, parseEvlrs } from "./format/LasVlr.js";
+import { parseCrs } from "./format/LasCrs.js";
+import { decodeRecords, resolveFields } from "./read/decodeRecords.js";
+import { windows } from "./read/windows.js";
+import { makeKeep, strideFor } from "./filter/filters.js";
+import { dedupe } from "./filter/dedupe.js";
+import { openScratchSyncWriter } from "./io/ScratchBinaryFile.js";
+
+var DEFAULT_WINDOW = 64 * 1024 * 1024;
+
+function memorySource(bytes) {
+	return { size: bytes.length, read: async function (a, b) {
+		if (b > bytes.length) throw new LasError(ERROR_CODES.TRUNCATED, "read past end of " + bytes.length + "-byte buffer", b);
+		return bytes.subarray(a, b);
+	} };
+}
+
+async function toSource(source) {
+	if (source instanceof Uint8Array) return memorySource(source);
+	if (source instanceof ArrayBuffer) return memorySource(new Uint8Array(source));
+	if (typeof source === "string") return NodeFileSource.open(source);
+	if (source && typeof source.slice === "function" && typeof source.size === "number" && typeof source.read !== "function") return new BlobSource(source);
+	if (source && typeof source.size === "number" && typeof source.read === "function") return source;
+	throw new LasError(ERROR_CODES.INVALID_ARGUMENT, "openLas needs a File / Blob, ArrayBuffer, Uint8Array, file path or { size, read } source");
+}
+
+/**
+ * Open a LAS (or LAZ) file and read its header and VLRs.
+ * @param {*} source
+ * @param {{windowSize?: number}} [opts]
+ * @returns {Promise<LasReader>}
+ */
+export async function openLas(source, opts) {
+	var src = await toSource(source);
+	var headBytes = await src.read(0, Math.min(src.size, 375));
+	var header = parseHeader(new MemorySource(headBytes));
+	var vlrs = [];
+	if (header.numberOfVlrs > 0) {
+		var vlrEnd = Math.min(header.offsetToPointData, src.size);
+		var vlrBytes = await src.read(0, vlrEnd);
+		vlrs = parseVlrs(new MemorySource(vlrBytes), header.headerSize, header.numberOfVlrs, vlrEnd);
+	}
+	var evlrs = [];
+	if (header.numberOfEvlrs > 0 && header.evlrStart > 0 && header.evlrStart < src.size) {
+		var evBytes = await src.read(header.evlrStart, src.size);
+		evlrs = parseEvlrs(new MemorySource(evBytes), 0, header.numberOfEvlrs).map(function (e) {
+			return Object.assign({}, e, { start: e.start + header.evlrStart });
+		});
+	}
+	return new LasReader(src, header, vlrs, evlrs, (opts && opts.windowSize) || DEFAULT_WINDOW);
+}
+
+/**
+ * A LAS file opened for reading. Create with openLas().
+ */
+export function LasReader(src, header, vlrs, evlrs, windowSize) {
+	this._src = src;
+	this._windowSize = windowSize;
+	/** Public header. */
+	this.header = header;
+	/** Variable length records. */
+	this.vlrs = vlrs;
+	/** Extended variable length records (LAS 1.4). */
+	this.evlrs = evlrs;
+	/** Declared coordinate system (never reprojected). */
+	this.crs = parseCrs(vlrs.concat(evlrs));
+	/** True for LAZ (compressed points). */
+	this.compressed = header.compressed;
+}
+
+LasReader.prototype._check = function () {
+	var h = this.header;
+	if (h.compressed) {
+		throw new LasError(ERROR_CODES.COMPRESSED_LAZ, "this file is LAZ (compressed); reading LAZ points is supported from las-laz-js 0.2.0");
+	}
+	var end = h.offsetToPointData + h.pointCount * h.recordLength;
+	if (end > this._src.size) {
+		throw new LasError(ERROR_CODES.TRUNCATED, "the header promises " + h.pointCount + " points ending at byte " + end + " but the file is " + this._src.size + " bytes", this._src.size);
+	}
+};
+
+/**
+ * Iterate the selected points window by window.
+ * @param {object} [opts] - fields, classes, returns, bounds, maxPoints, localOrigin, float32, onProgress, signal
+ * @returns {AsyncGenerator<object>} PointColumns per window
+ */
+LasReader.prototype.chunks = async function* (opts) {
+	opts = opts || {};
+	if (opts.dedupe) throw new LasError(ERROR_CODES.INVALID_ARGUMENT, "dedupe needs every point at once: use readPoints, not chunks");
+	this._check();
+	var h = this.header;
+	var keep = makeKeep(opts, h);
+	var stride = strideFor(h.pointCount, opts.maxPoints);
+	var cap = opts.maxPoints > 0 ? opts.maxPoints : Infinity;
+	var fields = resolveFields(h, opts.fields);
+	var list = windows(h, this._windowSize);
+	var kept = 0;
+	for (var w = 0; w < list.length && kept < cap; w++) {
+		if (opts.signal && opts.signal.aborted) throw new LasError(ERROR_CODES.ABORTED, "read aborted");
+		var win = list[w];
+		var bytes = await this._src.read(win.start, win.end);
+		var cols = decodeRecords(bytes, h, { fields: fields, keep: keep, stride: stride, firstIndex: win.firstRecord, localOrigin: opts.localOrigin, float32: opts.float32 });
+		if (kept + cols.count > cap) cols = trim(cols, fields, cap - kept);
+		kept += cols.count;
+		if (typeof opts.onProgress === "function") opts.onProgress(kept >= cap ? 1 : (w + 1) / list.length, "read " + kept + " points");
+		yield cols;
+	}
+	if (opts.signal && opts.signal.aborted) throw new LasError(ERROR_CODES.ABORTED, "read aborted");
+};
+
+function trim(cols, fields, n) {
+	var out = { count: n };
+	fields.forEach(function (f) { out[f] = cols[f].slice(0, n); });
+	return out;
+}
+
+/**
+ * Read the selected points into one set of columns.
+ * @param {object} [opts] - chunks() options plus dedupe (tolerance) and dedupeZ
+ * @returns {Promise<object>} PointColumns plus bounds and stats
+ */
+LasReader.prototype.readPoints = async function (opts) {
+	opts = opts || {};
+	var h = this.header;
+	var chunkOpts = Object.assign({}, opts);
+	delete chunkOpts.dedupe;
+	var fields = resolveFields(h, opts.fields);
+	var acc = null, n = 0;
+	for await (var c of this.chunks(chunkOpts)) {
+		if (!acc) {
+			acc = {};
+			var guess = Math.max(c.count, 1024);
+			fields.forEach(function (f) { acc[f] = new c[f].constructor(guess); });
+		}
+		if (n + c.count > acc[fields[0]].length) {
+			var size = Math.max(n + c.count, acc[fields[0]].length * 2);
+			fields.forEach(function (f) { var g = new acc[f].constructor(size); g.set(acc[f].subarray(0, n)); acc[f] = g; });
+		}
+		for (var i = 0; i < fields.length; i++) acc[fields[i]].set(c[fields[i]], n);
+		n += c.count;
+	}
+	var out = { count: n };
+	fields.forEach(function (f) { out[f] = acc ? acc[f].slice(0, n) : new Float64Array(0); });
+	if (opts.dedupe) out = dedupe(out, opts.dedupe, { z: !!opts.dedupeZ });
+	out.bounds = boundsOf(out, opts.localOrigin);
+	out.stats = statsOf(out);
+	return out;
+};
+
+function emptyBounds() { return { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity, minZ: Infinity, maxZ: -Infinity }; }
+
+// Grow raw (stored-value) bounds over one set of columns
+function extendBounds(b, c) {
+	for (var i = 0; i < c.count; i++) {
+		var x = c.x[i], y = c.y ? c.y[i] : 0, z = c.z ? c.z[i] : 0;
+		if (x < b.minX) b.minX = x; if (x > b.maxX) b.maxX = x;
+		if (y < b.minY) b.minY = y; if (y > b.maxY) b.maxY = y;
+		if (z < b.minZ) b.minZ = z; if (z > b.maxZ) b.maxZ = z;
+	}
+	return b;
+}
+
+// Raw bounds -> world bounds (origin added back), to the stored precision
+function worldBounds(b, origin) {
+	if (!(b.minX <= b.maxX)) return null;
+	var ox = origin && isFinite(origin.x) ? origin.x : 0;
+	var oy = origin && isFinite(origin.y) ? origin.y : 0;
+	var oz = origin && isFinite(origin.z) ? origin.z : 0;
+	var r = function (v) { return Math.round(v * 1e6) / 1e6; };
+	return { minX: r(b.minX + ox), maxX: r(b.maxX + ox), minY: r(b.minY + oy), maxY: r(b.maxY + oy), minZ: r(b.minZ + oz), maxZ: r(b.maxZ + oz) };
+}
+
+function boundsOf(c, origin) {
+	if (!c.x || !c.count) return null;
+	return worldBounds(extendBounds(emptyBounds(), c), origin);
+}
+
+function statsOf(c) {
+	var s = { count: c.count };
+	if (c.classification) {
+		var counts = {};
+		for (var i = 0; i < c.count; i++) { var k = c.classification[i]; counts[k] = (counts[k] || 0) + 1; }
+		s.classCounts = counts;
+	}
+	return s;
+}
+
+/**
+ * Read the selected points straight into OPFS scratch files — one per
+ * field, raw little-endian typed-array bytes — for selections too big
+ * for memory (browser, in a worker: OPFS sync handles are worker-only).
+ * @param {object} [opts] - chunks() options plus root / dir (OPFS) and prefix (file names)
+ * @returns {Promise<{count:number, fields:Object<string,string>, types:Object<string,string>, bounds:object}>}
+ */
+LasReader.prototype.readPointsToScratch = async function (opts) {
+	opts = opts || {};
+	var fields = resolveFields(this.header, opts.fields);
+	var prefix = opts.prefix || ("las-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8));
+	var where = { root: opts.root, dir: opts.dir };
+	var writers = {}, ids = {}, types = {};
+	for (var f = 0; f < fields.length; f++) {
+		ids[fields[f]] = prefix + "-" + fields[f];
+		writers[fields[f]] = await openScratchSyncWriter(ids[fields[f]], where);
+	}
+	var count = 0, b = emptyBounds();
+	try {
+		for await (var c of this.chunks(opts)) {
+			fields.forEach(function (name) {
+				var col = c[name];
+				types[name] = col.constructor.name;
+				writers[name].write(new Uint8Array(col.buffer, col.byteOffset, col.byteLength));
+			});
+			if (c.x) extendBounds(b, c);
+			count += c.count;
+		}
+	} finally {
+		fields.forEach(function (name) { writers[name].close(); });
+	}
+	return { count: count, fields: ids, types: types, bounds: worldBounds(b, opts.localOrigin) };
+};
+
+/** Close the underlying file (Node). */
+LasReader.prototype.close = async function () {
+	if (this._src && typeof this._src.close === "function") await this._src.close();
+};

package/src/colour/colourize.js

@@ -0,0 +1,129 @@
+// src/colour/colourize.js
+//==========================================================
+// Colour points: { by: "rgb" | "intensity" | "elevation" |
+// "classification" } -> Uint8Array, three bytes per point.
+//
+// rgb: LAS stores 16-bit colour; it is scaled with round(v / 256)
+//   (Kirra's rule). Files that wrongly store 8-bit values in the
+//   16-bit fields (every value <= 255 — a common writer bug) are
+//   used as-is instead of being divided down to almost black. This
+//   detection is new in the library; Kirra divides unconditionally.
+// elevation: Kirra's spectrum ramp, blue -> cyan -> green -> yellow
+//   -> red, over opts.range or the data's Z range.
+// intensity: greyscale over opts.range, or the 2nd-98th percentile
+//   so one hot return does not wash the rest out.
+// classification: conventional viewer colours. ASPRS defines the
+//   codes, not colours; these follow common LiDAR-viewer practice.
+//==========================================================
+
+import { LasError, ERROR_CODES } from "../errors.js";
+
+function spectrum(t) {
+	if (t < 0.25) return [0, Math.floor(t * 4 * 255), 255];
+	if (t < 0.5) return [0, 255, Math.floor(255 - (t - 0.25) * 4 * 255)];
+	if (t < 0.75) return [Math.floor((t - 0.5) * 4 * 255), 255, 0];
+	return [255, Math.floor(255 - (t - 0.75) * 4 * 255), 0];
+}
+function greyscale(t) { var g = Math.round(t * 255); return [g, g, g]; }
+
+/** Colour ramps: t in [0, 1] -> [r, g, b]. */
+export var RAMPS = Object.freeze({ spectrum: spectrum, greyscale: greyscale });
+
+/** Classification code -> [r, g, b] (common LiDAR viewer colours). */
+export var CLASS_COLOURS = Object.freeze({
+	0: [128, 128, 128],  // created, never classified
+	1: [170, 170, 170],  // unclassified
+	2: [165, 113, 78],   // ground
+	3: [144, 238, 144],  // low vegetation
+	4: [34, 139, 34],    // medium vegetation
+	5: [0, 100, 0],      // high vegetation
+	6: [220, 60, 40],    // building
+	7: [255, 0, 255],    // low point (noise)
+	8: [255, 215, 0],    // model key point (LAS 1.2) / reserved
+	9: [30, 144, 255],   // water
+	10: [139, 69, 19],   // rail
+	11: [90, 90, 90],    // road surface
+	12: [255, 255, 0],   // overlap (1.2) / reserved
+	13: [0, 255, 255],   // wire - guard
+	14: [0, 206, 209],   // wire - conductor
+	15: [148, 0, 211],   // transmission tower
+	16: [186, 85, 211],  // wire-structure connector
+	17: [205, 133, 63],  // bridge deck
+	18: [255, 20, 147]   // high noise
+});
+var UNKNOWN = [128, 128, 128];
+
+function need(points, name) {
+	if (!points[name]) throw new LasError(ERROR_CODES.INVALID_ARGUMENT, "colourize by this mode needs the \"" + name + "\" field; read it with fields: [..., \"" + name + "\"]");
+	return points[name];
+}
+
+function rangeOf(values, n) {
+	var lo = Infinity, hi = -Infinity;
+	for (var i = 0; i < n; i++) { var v = values[i]; if (v < lo) lo = v; if (v > hi) hi = v; }
+	return [lo, hi];
+}
+
+function percentiles(values, n) {
+	var copy = Array.prototype.slice.call(values, 0, n).sort(function (a, b) { return a - b; });
+	return [copy[Math.floor(0.02 * (n - 1))], copy[Math.floor(0.98 * (n - 1))]];
+}
+
+function rampColours(values, n, range, ramp) {
+	var out = new Uint8Array(n * 3);
+	var lo = range[0], span = range[1] - range[0];
+	for (var i = 0; i < n; i++) {
+		var t = span > 1e-12 ? (values[i] - lo) / span : 0.5;
+		if (!(t >= 0)) t = 0; else if (t > 1) t = 1;
+		var c = ramp(t);
+		out[i * 3] = c[0]; out[i * 3 + 1] = c[1]; out[i * 3 + 2] = c[2];
+	}
+	return out;
+}
+
+/**
+ * @param {object} points - PointColumns.
+ * @param {{by:string, ramp?:string, range?:number[]}} opts
+ * @returns {Uint8Array} r, g, b per point
+ */
+export function colourize(points, opts) {
+	opts = opts || {};
+	var n = points.count;
+	var rampName = opts.ramp || (opts.by === "intensity" ? "greyscale" : "spectrum");
+	var ramp = RAMPS[rampName];
+	if (!ramp) throw new LasError(ERROR_CODES.INVALID_ARGUMENT, "unknown ramp \"" + rampName + "\"");
+	var out, i;
+	switch (opts.by) {
+		case "rgb": {
+			var r = need(points, "red"), g = need(points, "green"), b = need(points, "blue");
+			var max = Math.max(rangeOf(r, n)[1], rangeOf(g, n)[1], rangeOf(b, n)[1]);
+			var eightBit = max <= 255;
+			out = new Uint8Array(n * 3);
+			for (i = 0; i < n; i++) {
+				out[i * 3] = eightBit ? r[i] : Math.min(255, Math.round(r[i] / 256));
+				out[i * 3 + 1] = eightBit ? g[i] : Math.min(255, Math.round(g[i] / 256));
+				out[i * 3 + 2] = eightBit ? b[i] : Math.min(255, Math.round(b[i] / 256));
+			}
+			return out;
+		}
+		case "elevation": {
+			var z = need(points, "z");
+			return rampColours(z, n, opts.range || rangeOf(z, n), ramp);
+		}
+		case "intensity": {
+			var v = need(points, "intensity");
+			return rampColours(v, n, opts.range || percentiles(v, n), ramp);
+		}
+		case "classification": {
+			var cls = need(points, "classification");
+			out = new Uint8Array(n * 3);
+			for (i = 0; i < n; i++) {
+				var c = CLASS_COLOURS[cls[i]] || UNKNOWN;
+				out[i * 3] = c[0]; out[i * 3 + 1] = c[1]; out[i * 3 + 2] = c[2];
+			}
+			return out;
+		}
+		default:
+			throw new LasError(ERROR_CODES.INVALID_ARGUMENT, "colourize by \"" + opts.by + "\" is not a mode (rgb, intensity, elevation, classification)");
+	}
+}

package/src/errors.js

@@ -0,0 +1,38 @@
+// src/errors.js
+//==========================================================
+// LasError: every failure the library raises carries a stable
+// `code` (see ERROR_CODES) and, for byte-level problems, the
+// file `offset` where it was detected. Callers branch on `code`;
+// the offset is appended to the message for humans.
+// Same shape as ecw-js's EcwError.
+//==========================================================
+
+/** Stable error codes. Each value equals its key. */
+export var ERROR_CODES = Object.freeze({
+	NOT_LAS: "NOT_LAS",
+	UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION",
+	UNSUPPORTED: "UNSUPPORTED",
+	COMPRESSED_LAZ: "COMPRESSED_LAZ",
+	TRUNCATED: "TRUNCATED",
+	BAD_HEADER: "BAD_HEADER",
+	BAD_VLR: "BAD_VLR",
+	INVALID_ARGUMENT: "INVALID_ARGUMENT",
+	ABORTED: "ABORTED",
+	TOO_MANY_POINTS: "TOO_MANY_POINTS"
+});
+
+/**
+ * Error raised by las-laz-js.
+ * @param {string} code - One of ERROR_CODES.
+ * @param {string} message - Human-readable description.
+ * @param {number} [offset] - Byte offset in the file, when relevant.
+ */
+export class LasError extends Error {
+	constructor(code, message, offset) {
+		var text = typeof offset === "number" ? message + " (at 0x" + offset.toString(16) + ")" : message;
+		super(text);
+		this.name = "LasError";
+		this.code = code;
+		this.offset = offset;
+	}
+}