las-laz-js 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.5.0 (2026-10-22)
+
+Point operations.
+
+- Operations on point columns (the object `readPoints` returns, or any `{ count, <name>: TypedArray }`
+  whose arrays are `count × k` long), with no dependencies. A selection is a `Uint32Array` of
+  strictly ascending point indices, checked on use (`INVALID_ARGUMENT` names the bad position).
+- Select: `selectBox`, `selectPolygon` (even-odd; `boundary: "touching"` keeps points on the edge,
+  `"inside"` drops them; `tolerance`; `minZ` / `maxZ`), `selectClasses`, `selectReturns` (`returns`,
+  `first`, `last`, `single`, any one matches), `thinSelection` (the reader's `maxPoints` rule,
+  exported), and `unionSelections`, `intersectSelections`, `subtractSelections`.
+- Apply: `keepPoints`, `removePoints`, `splitPoints`, `mergePoints`. Copies by default; `inPlace: true`
+  on keep and remove compacts each column inside its own buffer and returns views of it (columns that
+  share memory are refused). `mergePoints` takes the union of the columns, lists zero-filled ones
+  in `filled`, widens types (Float64 over Float32 over integers; Int32 or Uint32 with Float32 gives
+  Float64), and refuses a `k` mismatch, a column named `count` or `filled`, and signed with unsigned
+  integers unless the signed type is strictly wider.
+- Transform: `makeTransform({ shift, rotateZ, rotate, scale, about })` builds a row-major `{ m, t }`;
+  `transformPoints(cols, T, { inPlace })` applies it in Float64 and returns a new `{ count, columns }`
+  object (a copy has new x, y, z and shares the rest; `inPlace` returns the input's arrays, overwritten).
+- `interleavePositions(cols, { layout, into, at, origin, float32 })` packs x y (z) into a caller's
+  Float32 / Float64 buffer, shifting by `origin` in Float64 first.
+- Reads: `index` field (each point's record number; Uint32, Float64 above 4,294,967,295 points);
+  `polygon` / `boundary` / `tolerance` crop while reading, so only the region is decoded and held;
+  `transform` applies in the fixed order record → world → T → minus `localOrigin` → Float32.
+  Filters apply in file coordinates; the result's bounds and `dedupe` are in output coordinates,
+  and the worker's elevation colour range follows the transform.
+- Changed: an omitted (or `null`) `bounds` limit is now open. Before, a missing limit kept nothing.
+  `polygon: null` means no polygon. `selectBox` and the `minZ` / `maxZ` of `selectPolygon` read a
+  `null` bound as open too.
+- `dedupe` moves every column (k values per point, such as an interleaved `positions` or `rgb`) with
+  the kept points; other properties pass through. `transformPoints` with `inPlace` refuses x, y or z
+  that share memory. `mergePoints` ignores a zero-point input when widening types.
+- Demo: an Edit tab (polygon, box and class selections; keep, delete, split, transform, crop on
+  read) and LAZ export.
+- Docs: README "Point operations".
+
+## 0.4.0 (2026-10-22)
+
+Writes LAZ.
+
+- `writeLas(points, { compress: true })` and `createLasWriter(sink, { compress: true })` write LAZ:
+  point formats 0–3 (point-wise) and 6–8 (layered), with a LASzip VLR, 50,000-point chunks and a
+  chunk table, as PDAL (LAZperf) lays it out. Plain JavaScript, translated from laz-rs
+  (Apache-2.0), like the decoders. Formats 4, 5, 9, 10 cannot be compressed (`UNSUPPORTED`).
+- `chunkSize`: points per chunk, a whole number 1 to 4294967294 (default 50,000); ignored without
+  `compress`.
+- `threads`: chunks compress on the worker pool the LAZ reader uses, written in chunk order, so the
+  bytes are the same for any thread count. Automatic by default: from 4 chunks up, with at most 4
+  workers, as gains flatten after about 4 (explicit `threads` are honoured); `1` is the calling
+  thread. A 10 M-point LAZ (format 3) rewritten: `writeLas` 7166 ms on one thread, 1708 ms
+  automatic (4 workers, 4.2×), 1624 ms with 16; `createLasWriter` 7109 ms, 2033–2246 ms, 1657 ms.
+- With workers, up to about 2 tasks of 4 chunks per worker of records are in flight: about 55 MB
+  at the automatic 4 workers with 50,000-point format 3 chunks. That holds across awaited
+  `writePoints` calls; unawaited calls, or one huge batch, submit at once. An abandoned writer
+  keeps its workers until `close()`.
+- A streaming LAZ writer stops at its first error (a chunk, a sink write, `close()`):
+  `writePoints` and `close` keep rejecting. Start a new writer. After `close()`, both reject
+  (`ABORTED`).
+- The compressed bytes are PDAL's (LAZperf's) with one lossless exception: in formats 6–8 a GPS
+  time of −0 following +0 is coded as a change (LAZperf finds the doubles equal).
+- Extra bytes are not written yet (as for LAS); they arrive with 0.7.0.
+- Checked against PDAL 2.10: the committed fixtures' chunks, chunk tables and LASzip VLRs are
+  PDAL's bytes; PDAL reads what we write (`pdal info`, `pdal translate`) and finds the same points
+  field by field. Real files compress and read back to the same points: a 1.1 GB, 34-million-point
+  LAS streams to a 155 MB LAZ (0.14 of its size) in 6.4 s; a 10-million-point LAZ recompresses to
+  the same size in 2.7 s. That file, written by PDAL 1.6 in 2019, comes back as LAS 1.2 format 3 with
+  the original's point data byte for byte, and opens in CloudCompare as LAS 1.2 format 3 and as
+  LAS 1.4 format 7.
+- Docs: README "Writing LAZ"; the demo says LAZ is read and written.
+
 ## 0.3.1 (2026-10-21)
 
 Worker fixes.

package/NOTICE

@@ -1,7 +1,7 @@
 las-laz-js
 Copyright (c) 2026 Brent Buffham (https://kirra-design.com). MIT licence (see LICENSE).
 
-The LAZ decoder in src/laz/ is a JavaScript translation of laz-rs
+The LAZ decoder and encoder in src/laz/ are a JavaScript translation of laz-rs
 (https://github.com/laz-rs/laz-rs), which is itself a Rust port of LASzip
 (https://laszip.org) by rapidlasso. Those files are licensed under the
 Apache License, Version 2.0 (see LICENSE-APACHE), not the MIT licence:

package/README.md

@@ -1,22 +1,26 @@
 # las-laz-js
 
-A JavaScript reader and writer for ASPRS **LAS** point clouds, and a reader for **LAZ**
+A JavaScript reader and writer for ASPRS **LAS** point clouds and **LAZ**
 (LASzip-compressed LAS), 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.
-- LAZ: point formats 0–3 and 6–8, with extra bytes, read exactly like LAS — the same calls, the
-  same options, decoded chunk by chunk in plain JavaScript (no WebAssembly).
+  `readPoints` and `chunks` decode every point format (0–10) a window at a time, with filters,
+  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.
+- 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
+  Writing LAZ), compressed in parallel.
 - Big files: a 1.1 GB, 34-million-point LAS reads in under a second in Node, and a 10-million-point
   LAZ decodes on every core (a 10-million-point file in about 0.6 s); neither is held in memory
   whole (see LAZ below for the one exception).
 - Also: a ready-made module Worker (`las-laz-js/worker`) and a
   [Three.js demo](https://brentbuffham.github.io/las-laz-js/).
-- Not yet: writing LAZ (0.3.0).
 
 ## Install
 
@@ -34,8 +38,9 @@ Drop a LAS or LAZ file onto the page. It is read locally (never uploaded), decod
 library's Worker (LAZ on every core) behind a progress bar, then shown once in a Three.js viewer;
 colour changes recolour the points already read, without reading the file again. The side panel shows the header, VLRs, coordinate
 system and LAZ compression; reads with class, return, bounds, thinning and dedupe filters;
-colours by RGB, intensity, elevation or class; lists point statistics; and saves the points back
-out as LAS. To run it locally: `npm run demo`, then open http://localhost:8080/.
+colours by RGB, intensity, elevation or class; lists point statistics; selects points by polygon,
+box or class and keeps, deletes, splits, transforms or crops them (the Edit tab); and saves the
+points back out as LAS or LAZ. To run it locally: `npm run demo`, then open http://localhost:8080/.
 
 ## Reading
 
@@ -55,7 +60,11 @@ 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 },
+	bounds: { minX, maxX, minY, maxY, minZ, maxZ },   // any limit may be left out: an omitted limit is open
+	polygon: [x0, y0, x1, y1, x2, y2],   // crop: keep points inside it (file coordinates, XY, even-odd); null is none
+	boundary: "touching",    // polygon edge: "touching" keeps points on it (default), "inside" drops them
+	tolerance: 0,            // file units: within this of a polygon edge counts as on it
+	transform: T,            // { m, t } from makeTransform, applied to world coordinates (see Point operations)
 	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
@@ -63,7 +72,7 @@ var pts = await las.readPoints({
 	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
+pts.bounds; pts.stats;            // world bounds (after any transform), per-class counts
 ```
 
 Fields: `x y z intensity returnNumber numberOfReturns scanDirection edgeOfFlightLine
@@ -71,10 +80,141 @@ classification classificationFlags scannerChannel scanAngle userData pointSource
 red green blue nir`. Fields a point format does not hold are left out. `scanAngle` is in
 degrees for every format.
 
+`index` is one more field, for every format: the column is present for the points the filters and
+`maxPoints` keep, and each value is that record's position in the file (0-based; it is not
+renumbered after filtering). It is a `Uint32Array`, or a `Float64Array` for a file of more than
+4,294,967,295 points. It is an ordinary column, so keep, remove, split and merge carry it, and it
+tells you which records of the file are left.
+
 Filters run on the raw record before it is decoded, so a filtered-out point costs a byte read.
+`polygon` is a crop on read: only the points inside it are decoded and held, so a site region of
+a large file never costs the whole file in memory. It needs at least 3 vertices (a flat list of
+x, y pairs, implicitly closed) and combines with the other filters and `maxPoints`. A LAZ crop
+saves memory and field decoding but still decompresses every chunk (there is no spatial index), so
+its time is close to a full read.
 `maxPoints` keeps exactly that many of the points that pass the filters, spread evenly over
 the whole file; with filters set it first counts the passing points, which reads the file twice.
 
+In `bounds`, a limit that is left out (or `null`) is open; before 0.5.0 a missing limit kept
+nothing. `polygon: null` means no polygon. `boundary` and `tolerance` belong to `polygon`: a point
+within `tolerance` of an edge or vertex is on the boundary, kept by `"touching"` and dropped by
+`"inside"`. They are not `dedupe`'s tolerance, which is the value of the `dedupe` option.
+
+`transform` moves the points while they are decoded, in a fixed order: record → world (scale and
+offset) → `transform` (Float64) → minus `localOrigin` → Float32 (when `float32` and `localOrigin`
+are set). Raw scanner coordinates never pass through Float32 at full magnitude. The filters
+(`classes`, `returns`, `bounds`, `polygon`) apply in **file** coordinates, before the transform;
+the result's `bounds`, its stats and `dedupe` are in the output coordinates. To crop a scan in
+site coordinates, read it transformed and use `selectPolygon`. The Worker's elevation colour
+range follows the transform.
+
+## Point operations
+
+Zero-dependency operations on **point columns**: the object `readPoints` returns, or any object
+of the same shape, `{ count, <name>: TypedArray, ... }`. A property is a column when it is a typed
+array whose length is `count × k` for a whole number `k` of 1 or more (`k` is 1 for `x` or
+`classification`, 3 for an interleaved `positions` or `rgb`). Operations carry every column, `k`
+values per point, and nothing else: `bounds`, `stats` and the like are not copied, so rebuild them
+from the result. A **selection** is a `Uint32Array` of point indices, strictly ascending, each
+below `count`. Everything that takes one checks it in one pass and throws `INVALID_ARGUMENT`
+naming the first bad position; everything that makes one returns a valid one.
+
+### Select
+
+```js
+import { selectBox, selectPolygon, selectClasses, selectReturns, thinSelection,
+         unionSelections, intersectSelections, subtractSelections } from "las-laz-js";
+
+var inBox  = selectBox(pts, { minX: 477010, maxX: 477050, minZ: 295 });   // inclusive; a limit left out is open
+var inSite = selectPolygon(pts, poly, { boundary: "inside", tolerance: 0.001 });   // poly: [x0, y0, x1, y1, ...]
+var ground = selectClasses(pts, [2]);
+var last   = selectReturns(pts, { last: true, single: true });   // returns: [..], first, last, single; any one matches
+var thin   = thinSelection(pts.count, 1000);                     // exactly min(count, 1000) indices, spread evenly
+var wanted = intersectSelections(inSite, ground);                // also unionSelections, subtractSelections
+```
+
+`selectPolygon` takes a flat `[x0, y0, x1, y1, ...]` list of at least 3 vertices, closed for you,
+in the columns' own coordinates; the interior is the even-odd rule, so a concave polygon works.
+Points on the boundary are kept by `boundary: "touching"` (the default) and dropped by `"inside"`,
+so the two differ by exactly the boundary points, and `splitPoints` by one polygon loses and
+duplicates nothing. Coordinates are not exact in binary, so a point mathematically on an edge may not
+count as on it at `tolerance: 0`; use a small tolerance (for example 1e-6 of the units) to catch
+boundary points. `minZ` / `maxZ` add a height limit. `thinSelection` is the reader's
+`maxPoints` rule: `keepPoints(all, thinSelection(n, t))` gives the points
+`readPoints({ maxPoints: t })` does.
+
+### Keep, remove, split, merge
+
+```js
+import { keepPoints, removePoints, splitPoints, mergePoints } from "las-laz-js";
+
+var kept    = keepPoints(pts, wanted);              // new columns of the same types
+var without = removePoints(pts, wanted);
+var [inside, outside] = splitPoints(pts, inSite);   // always copies; every point lands in one result
+var both    = mergePoints([inside, outside]);       // concatenated in order; both.filled is []
+
+var crop = keepPoints(big, selectPolygon(big, poly), { inPlace: true });   // no second copy
+```
+
+`inPlace: true` (for `keepPoints` and `removePoints`) slides the kept values down inside each
+column's own buffer and returns views of that memory: the input is overwritten, and a big cloud is
+cropped without a second copy. Columns that share memory (the same array twice, or overlapping
+views) are refused, since compacting one would corrupt the other.
+
+`mergePoints` takes the union of the column names; a column missing from an input is zero for
+that input's points, and its name is listed in `result.filled`. A column named `count` or
+`filled` is refused. A column's `k` must agree across inputs. The result's type is the widest:
+Float64 over Float32 over the integer types; an Int32 or Uint32 with a Float32 gives Float64
+(Float32 holds integers exactly only to 2^24). Signed with unsigned integers merge only when the
+signed type is strictly wider (Int16 with Uint8 is Int16; Int8 with Uint8, or Int32 with Uint32,
+is `INVALID_ARGUMENT`). An input with no points is ignored when the type is chosen, so an empty
+Int8 column does not block a Uint16 one; a column only an empty input has keeps its type.
+Coordinates must already share one frame.
+
+### Transform
+
+```js
+import { makeTransform, transformPoints } from "las-laz-js";
+
+// p' = scale · R · (p − about) + about + shift; rotateZ is degrees anticlockwise about +Z
+var T = makeTransform({ rotateZ: 90, about: [477050, 6770015, 0], shift: [10, 0, 0] });
+// T = { m: [0, -1, 0, 1, 0, 0, 0, 0, 1], t: [7247075, 6292965, 0] }   row-major: p' = m·p + t
+
+var moved = transformPoints(pts, T);                     // { count, columns }: new x, y, z; the rest shared
+var same  = transformPoints(pts, T, { inPlace: true });  // the same x, y, z arrays, overwritten
+
+var local = await las.readPoints({                       // or while reading
+	fields: ["x", "y", "z"], transform: T,
+	localOrigin: { x: 477050, y: 6770015 }, float32: true
+});
+```
+
+A transform is a plain object, `{ m, t }`, with `m` nine numbers (a row-major 3×3) and `t` three.
+Any affine map fits, so a fitted registration can be passed the same way; it is not Three.js's
+column-major `Matrix4`. `makeTransform` takes `shift`, `about`, `scale` and either `rotateZ` or
+`rotate` (a row-major 3×3; not both). `transformPoints` needs `x`, `y` and `z`, computes in
+Float64 and stores in the columns' own types. It returns a new `{ count, columns }` object either
+way: with `inPlace` the arrays in it are the input's, overwritten (and `x`, `y` and `z` must not
+share memory, or it throws `INVALID_ARGUMENT`). On read, the order is the one
+above.
+
+### Interleave for a renderer
+
+```js
+import { interleavePositions } from "las-laz-js";
+
+var positions = interleavePositions(pts, { origin: { x: 477000, y: 6770000 } });   // Float32Array, x y z per point
+geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+
+// or into a buffer you own, starting at point 'at'; layout "xy" writes two values per point
+interleavePositions(pts, { into: buffer, at: 50000, layout: "xyz", origin: { x: 477000, y: 6770000, z: 300 } });
+```
+
+The origin is subtracted in Float64 before storing, so world coordinates keep their decimals in a
+Float32 buffer; an axis left out of `origin` is not shifted ({ x, y } keeps world Z). `float32`
+defaults to true and picks the type of a new array; `into` must be a Float32Array or Float64Array
+long enough, else `INVALID_ARGUMENT`.
+
 ## LAZ
 
 A LAZ file is opened and read with the same calls as LAS. Each LASzip chunk (50,000 points in
@@ -135,6 +275,7 @@ import { writeLas, createLasWriter } from "las-laz-js";
 
 var bytes = await writeLas(pts, { version: "1.2", pointFormat: 3, crs: { epsg: 28350 } });
 var v14 = await writeLas(pts, { version: "1.4", pointFormat: 7, crs: { wkt: las.crs.wkt } });
+var laz = await writeLas(pts, { compress: true, pointFormat: 3 });   // LAZ
 
 var w = await createLasWriter(sink, { version: "1.2", pointFormat: 3, scale, offset });
 // sink: an OPFS writer from openScratchSyncWriter, a Node FileHandle, or any { write(bytes, position) }
@@ -146,7 +287,44 @@ A version and point format that do not go together (format 6 in LAS 1.2) are ref
 silently changed. Scale and offset are chosen from the bounds when not given. `crs.epsg`
 writes a GeoKey record; `crs.wkt` a WKT record. Point formats 6–10 must carry WKT (LAS 1.4), so
 an EPSG code alone is refused for them — the library has no projection database to turn a code
-into WKT. Writing LAZ arrives in 0.3.0.
+into WKT.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `compress` | `false` | write LAZ (LASzip) instead of LAS: point formats 0–3 and 6–8; formats 4, 5, 9, 10 are refused (`UNSUPPORTED`) |
+| `chunkSize` | `50000` | points per LAZ chunk, a whole number from 1 to 4294967294; ignored without `compress` |
+| `threads` | automatic | workers that compress chunks: automatic by default (from 4 chunks up, at most 4 workers), `1` compresses on the calling thread, `n` asks for n workers; only with `compress` |
+
+### Writing LAZ
+
+`writeLas(pts, { compress: true })` and `createLasWriter(sink, { compress: true, ... })` write the
+same records as the LAS writers, compressed `chunkSize` points at a time (LASzip's 50,000 by
+default) behind a LASzip VLR, with the chunk table at the end of the point data. The layout and
+the compressed bytes are those PDAL (LAZperf) writes: for the same points, version, format, scale
+and offset, the point data is identical to PDAL's — with one exception: in formats 6–8 a GPS time
+of −0 following +0 is coded as a change, so it reads back as −0 (lossless), where LAZperf compares
+the doubles, finds them equal and writes no change. Point formats 0–3 are written point-wise
+(LASzip item version 2), 6–8 layered (item version 3).
+
+- **Speed.** Chunks are independent, so they compress on the same pool of workers that decode
+  LAZ, and are written strictly in chunk order: the bytes are the same for any `threads`. Gains
+  flatten after about four workers, so with `threads` automatic the writers use at most four (one
+  fewer than the cores, if that is less): a 10-million-point format 3 file writes in about 1.7 s
+  that way on a 24-core machine, 1.6 s with `threads: 16`, about 7 s on one thread. A write of
+  under four chunks (200,000 points) stays on one thread, where workers would cost more than they
+  save. If workers cannot start, it falls back to one thread.
+- **Memory.** With workers, up to about 2 tasks of 4 chunks per worker are in flight at once —
+  about 55 MB of records at the automatic four workers with 50,000-point format 3 chunks (about
+  220 MB at `threads: 16`). That bound holds across awaited `writePoints` calls; calls made
+  without waiting, or one huge batch, submit all at once. Pass a smaller `threads` or `chunkSize`
+  to bound it further. A writer that is abandoned without `close()` keeps its workers in a
+  browser until it is closed.
+- **Errors.** A streaming LAZ writer stops for good at its first error — in a chunk, in a sink
+  write or in `close()` — and `writePoints` and `close` keep rejecting with it. Start a new
+  writer. After a successful `close()`, both reject (`ABORTED`, "the LAZ writer is closed").
+- **Extra bytes** are not written (the writers have never written them): a file read with
+  extra bytes is written without them. They arrive with 0.7.0.
+- The streaming writer needs `scale` and `offset` up front, as for LAS.
 
 ## In a Worker
 
@@ -160,7 +338,7 @@ worker.postMessage({ id: 2, type: "chunks", payload: { fields: ["x", "y", "z"],
 The protocol is documented in `src/workers/workerProtocol.js` and can be driven directly with
 `createWorkerHandler(post)`.
 
-**Bundlers.** The worker entry and the LAZ decode workers are found through
+**Bundlers.** The worker entry and the LAZ decode and encode workers are found through
 `new Worker(new URL(..., import.meta.url))`, which Vite and webpack 5 follow. With Vite, keep the
 package out of dependency pre-bundling (`optimizeDeps: { exclude: ["las-laz-js"] }`), so the
 worker files stay next to the module that loads them.
@@ -182,11 +360,12 @@ 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 decoder in
-`src/laz/` is a JavaScript translation of [laz-rs](https://github.com/laz-rs/laz-rs) by Thomas
+Brent Buffham's blast-design app, rewritten as a standalone library. The LAZ decoder and encoder in
+`src/laz/` are a JavaScript translation of [laz-rs](https://github.com/laz-rs/laz-rs) by Thomas
 Montaigu, itself a Rust port of [LASzip](https://laszip.org) by Martin Isenburg (rapidlasso).
-It is checked against an independent encoder: the test fixtures were compressed by
-[PDAL](https://pdal.io), and every record must equal PDAL's own decompression.
+It is checked against an independent implementation: the test fixtures were compressed by
+[PDAL](https://pdal.io), every record must equal PDAL's own decompression, and what this
+library compresses must equal PDAL's bytes and be read by PDAL.
 Formats are written to the ASPRS LAS 1.4 R15 specification; see `docs/LAS_FORMAT_NOTES.md`.
 
 ## Development
@@ -200,12 +379,14 @@ node _dev/makeLazFixtures.mjs   # remake test/fixtures/laz with PDAL (needs PDAL
 ```
 
 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, and each LAZ with a
-LAS twin (same count and bounds) field by field.
+`samples/paths.txt`; the sample tests compare each file with its own header, each LAZ with a
+LAS twin (same count and bounds) field by field, and compress each file to LAZ and read it back.
+Set `LAS_PDAL=<path to pdal>` to also have PDAL read what this library writes
+(`test/laz/pdalWrite.test.js` and the sample tests).
 
 ## Licence
 
-`MIT AND Apache-2.0`. The library is MIT © Brent Buffham (`LICENSE`). The LAZ decoder in
+`MIT AND Apache-2.0`. The library is MIT © Brent Buffham (`LICENSE`). The LAZ decoder and encoder in
 `src/laz/`, translated from laz-rs / LASzip, is under the Apache License 2.0 (`LICENSE-APACHE`,
 `NOTICE`). Both are permissive: use, change and ship it in open or closed software, keeping the
 notices.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "las-laz-js",
-	"version": "0.3.1",
-	"description": "Zero-dependency JavaScript reader and writer for ASPRS LAS point clouds, and reader for LAZ (LASzip), for the browser and Node, built for files larger than memory.",
+	"version": "0.5.0",
+	"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": {
 		".": "./src/index.js",

package/src/LasReader.js

@@ -25,6 +25,7 @@ import { createChunkDecoder } from "./laz/decompressChunk.js";
 import { createLazPool, defaultThreads } from "./laz/pool.js";
 import { makeKeep, countKept } from "./filter/filters.js";
 import { dedupe } from "./filter/dedupe.js";
+import { checkTransform } from "./ops/transform.js";
 import { openScratchSyncWriter } from "./io/ScratchBinaryFile.js";
 
 var DEFAULT_WINDOW = 64 * 1024 * 1024;
@@ -179,7 +180,7 @@ LasReader.prototype._plan = async function () {
 
 /**
  * Iterate the selected points window by window.
- * @param {object} [opts] - fields, classes, returns, bounds, maxPoints, localOrigin, float32, onProgress, signal
+ * @param {object} [opts] - fields, classes, returns, bounds, polygon (crop; with boundary "touching" | "inside" and tolerance), maxPoints, transform ({ m, t } from makeTransform: world coordinates are transformed in Float64 before localOrigin is subtracted; filters apply in file coordinates), localOrigin, float32, onProgress, signal
  * @returns {AsyncGenerator<object>} PointColumns per window
  */
 LasReader.prototype.chunks = async function* (opts) {
@@ -192,6 +193,7 @@ LasReader.prototype.chunks = async function* (opts) {
 // makes decodeRecords write straight into readPoints' result columns.
 LasReader.prototype._scan = async function* (opts, into) {
 	var h = this.header;
+	if (opts.transform) checkTransform(opts.transform, "transform");
 	var plan = await this._plan();
 	var keep = makeKeep(opts, h);
 	var fields = resolveFields(h, opts.fields);
@@ -208,7 +210,7 @@ LasReader.prototype._scan = async function* (opts, into) {
 		var kept = 0, w = 0;
 		for await (var bytes of windowBytes(plan, pool, buf, opts.signal)) {
 			var win = list[w];
-			var cols = decodeRecords(bytes, h, { fields: fields, keep: keep, thin: thin, localOrigin: opts.localOrigin, float32: opts.float32, into: into ? into(win) : null });
+			var cols = decodeRecords(bytes, h, { fields: fields, keep: keep, thin: thin, localOrigin: opts.localOrigin, float32: opts.float32, transform: opts.transform, firstIndex: win.firstRecord, into: into ? into(win) : null });
 			kept += cols.count;
 			w++;
 			if (typeof opts.onProgress === "function") opts.onProgress(w / list.length, "read " + kept + " points");
@@ -257,7 +259,7 @@ LasReader.prototype._countPassing = async function (plan, pool, buf, keep, signa
 
 /**
  * Read the selected points into one set of columns.
- * @param {object} [opts] - chunks() options plus dedupe (tolerance) and dedupeZ
+ * @param {object} [opts] - chunks() options plus dedupe (tolerance) and dedupeZ; dedupe runs on the output coordinates (after transform and localOrigin)
  * @returns {Promise<object>} PointColumns plus bounds and stats
  */
 LasReader.prototype.readPoints = async function (opts) {
@@ -273,7 +275,7 @@ LasReader.prototype.readPoints = async function (opts) {
 	var cap = !filtered ? (opts.maxPoints > 0 ? Math.min(opts.maxPoints, h.pointCount) : h.pointCount)
 		: (opts.maxPoints > 0 ? Math.min(opts.maxPoints, h.pointCount) : 0);
 	var acc = {}, n = 0;
-	fields.forEach(function (f) { acc[f] = new (columnType(f, opts))(cap || 1024); });
+	fields.forEach(function (f) { acc[f] = new (columnType(f, opts, h))(cap || 1024); });
 	function into(win) {
 		// A known cap is never exceeded, so it never grows; filters alone grow by doubling
 		if (!cap && n + win.count > acc[fields[0]].length) {

package/src/filter/dedupe.js

@@ -5,10 +5,11 @@
 // tolerance-sized cells, neighbours checked), ported from point
 // 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.
+// Every column follows the kept points (k values per point).
 //==========================================================
 
 import { LasError, ERROR_CODES } from "../errors.js";
+import { columnsOf, gather, sameType } from "../ops/columns.js";
 
 /**
  * @param {object} cols - PointColumns ({ count, x, y, z?, ... }).
@@ -69,13 +70,21 @@ export function dedupe(cols, tolerance, opts) {
 		kept[nKept++] = i;
 	}
 
+	// 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 };
 	Object.keys(cols).forEach(function (name) {
+		if (name === "count") return;
 		var col = cols[name];
-		if (!ArrayBuffer.isView(col) || col.length !== cols.count) { if (name !== "count") out[name] = col; return; }
-		var c = new col.constructor(nKept);
-		for (var q = 0; q < nKept; q++) c[q] = col[kept[q]];
-		out[name] = c;
+		var v = col;
+		if (Object.prototype.hasOwnProperty.call(ks, name)) {
+			v = sameType(col, nKept * ks[name]);
+			gather(col, v, ks[name], sel);
+		}
+		// defineProperty so a column named "__proto__" stays a column
+		Object.defineProperty(out, name, { value: v, enumerable: true, writable: true, configurable: true });
 	});
 	return out;
 }

package/src/filter/filters.js

@@ -2,8 +2,8 @@
 //==========================================================
 // Record filters that run on the RAW record, before decoding, so
 // rejected points cost one or two byte reads (Kirra's classFilter
-// trick, generalised): classification codes, return numbers and a
-// 3D box. Filters combine with AND.
+// trick, generalised): classification codes, return numbers, a
+// 3D box and a polygon (crop on read). Filters combine with AND.
 // maxPoints thinning is NOT Kirra's floor-stride-and-cap rule, which
 // kept only the start of the file and, run before the filters,
 // could leave nothing: decodeRecords thins the records that PASS,
@@ -11,12 +11,16 @@
 //==========================================================
 
 import { POINT_FORMATS } from "../format/PointFormats.js";
+import { makePolygonTest } from "../ops/polygon.js";
 
 var LE = true;
 
+function limit(v, open) { return v === undefined || v === null ? open : v; }
+
 /**
  * Build a keep(view, recordOffset) test for decodeRecords.
- * @param {object} [filter] - { classes?: number[], returns?: number[], bounds?: {minX,maxX,minY,maxY,minZ,maxZ} }
+ * @param {object} [filter] - { classes?: number[], returns?: number[], bounds?: {minX,maxX,minY,maxY,minZ,maxZ} (an omitted or null limit is open),
+ *   polygon?: number[] (null or omitted: no crop) [x0, y0, x1, y1, ...] with boundary ("touching" | "inside") and tolerance as selectPolygon, in the file's world coordinates }
  * @param {object} header - from parseHeader.
  * @returns {function(DataView, number): boolean|null} null when there is nothing to filter
  */
@@ -38,15 +42,32 @@ export function makeKeep(filter, header) {
 			? function (v, at) { return ret[v.getUint8(at + 14) & 15] === 1; } // bits-ok
 			: function (v, at) { return ret[v.getUint8(at + 14) & 7] === 1; }); // bits-ok
 	}
+	var sc = header.scale, of = header.offset;
 	if (filter.bounds) {
-		var b = filter.bounds, s = header.scale, o = header.offset;
+		// an omitted limit is open
+		var b = filter.bounds;
+		var minX = limit(b.minX, -Infinity), maxX = limit(b.maxX, Infinity);
+		var minY = limit(b.minY, -Infinity), maxY = limit(b.maxY, Infinity);
+		var minZ = limit(b.minZ, -Infinity), maxZ = limit(b.maxZ, Infinity);
+		tests.push(function (v, at) {
+			var x = v.getInt32(at, LE) * sc.x + of.x;
+			if (x < minX || x > maxX) return false;
+			var y = v.getInt32(at + 4, LE) * sc.y + of.y;
+			if (y < minY || y > maxY) return false;
+			var z = v.getInt32(at + 8, LE) * sc.z + of.z;
+			return z >= minZ && z <= maxZ;
+		});
+	}
+	if (filter.polygon !== undefined && filter.polygon !== null) {
+		// the file's world x, y of the raw record, as the bounds test computes them; boundary and tolerance as selectPolygon
+		var poly = makePolygonTest(filter.polygon, { boundary: filter.boundary, tolerance: filter.tolerance });
+		var inPoly = poly.test, pminX = poly.minX, pmaxX = poly.maxX, pminY = poly.minY, pmaxY = poly.maxY;
 		tests.push(function (v, at) {
-			var x = v.getInt32(at, LE) * s.x + o.x;
-			if (x < b.minX || x > b.maxX) return false;
-			var y = v.getInt32(at + 4, LE) * s.y + o.y;
-			if (y < b.minY || y > b.maxY) return false;
-			var z = v.getInt32(at + 8, LE) * s.z + o.z;
-			return z >= b.minZ && z <= b.maxZ;
+			var x = v.getInt32(at, LE) * sc.x + of.x;
+			if (x < pminX || x > pmaxX) return false;   // y is not decoded for a point outside the box in x
+			var y = v.getInt32(at + 4, LE) * sc.y + of.y;
+			if (y < pminY || y > pmaxY) return false;
+			return inPoly(x, y);
 		});
 	}
 	if (!tests.length) return null;

package/src/index.js

@@ -6,7 +6,7 @@
 //==========================================================
 
 /** Library version, matches package.json. */
-export var VERSION = "0.3.1";
+export var VERSION = "0.5.0";
 
 export { LasError, ERROR_CODES } from "./errors.js";
 export { openLas, LasReader } from "./LasReader.js";
@@ -17,6 +17,10 @@ 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 { 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 { MemorySource } from "./io/MemorySource.js";
 export { BlobSource } from "./io/BlobSource.js";
 export { NodeFileSource } from "./io/NodeFileSource.js";