landxml 0.6.6 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # landxml
 
+## 0.8.0
+
+### Minor Changes
+
+- 6a4a531: Modified "auto" behavior on LandXML files with multiple surfaces to create a combined center (rather than each surface its own cetner)
+
+## 0.7.1
+
+### Patch Changes
+
+- b200147: Updated publish workflow
+- eec1ceb: Struggling with CI/CD #2
+- b80d579: Struggling with CI/CD #1
+
+## 0.7.0
+
+### Minor Changes
+
+- 23cc669: Ai performance optimizations
+
 ## 0.6.6
 
 ### Patch Changes

package/README.md

@@ -1,48 +1,196 @@
-# LandXML Parser for Contour Geojson and 3D Models
+# LandXML Parser for Contour GeoJSON and 3D Models
 
-Easily transform LandXML surfaces into stunning GeoJSON contours or immersive GLB models to explore within threeJS or any popular 3D software.
+Easily transform LandXML surfaces into GeoJSON contours or GLB 3D models for use in ThreeJS, Cesium, QGIS, or any popular 3D/GIS software.
 
-### Features
+---
 
-- **toGlb:** Generate GLB models from LandXML surfaces.
-- **toGeojsonContours:** Convert LandXML data into detailed contour GeoJSON representations.
-- **reprojectGeojson:** Effortlessly reproject GeoJSON data to desired projection using `proj4`
+## Features
 
-### Example: Retrieve GeoJSON Contours
+- **`toGlbAndContours`** — Generate both a GLB model and GeoJSON contours in a single pass (fastest when you need both outputs).
+- **`toGlb`** — Generate a GLB 3D model from LandXML surfaces.
+- **`toGeojsonContours`** — Convert LandXML surfaces into contour line GeoJSON.
+- **`reprojectGeoJson`** — Reproject GeoJSON coordinates to any projection using `proj4`.
+
+---
+
+## Installation
+
+```bash
+npm install landxml
+```
+
+## Examples
+
+### Get contours and a GLB model together (recommended)
+
+When you need both outputs, use `toGlbAndContours` — it parses the XML once and shares computed data between both outputs, making it significantly faster than calling `toGlb` and `toGeojsonContours` separately.
+
+```typescript
+import { toGlbAndContours, reprojectGeoJson } from "landxml";
+
+const landXmlString = `<?xml version="1.0"?>...<LandXML>...</LandXML>`;
+
+const surfaces = await toGlbAndContours(
+  landXmlString,
+  2, // contour interval (LandXML units)
+  true, // generate outline
+  "auto", // GLB center: "auto" | "origin" | [x, y]
+);
+
+const { glb, center, geojson, wktString, download } = surfaces[0];
+
+// Download the GLB file in the browser
+download();
+
+// Reproject contours from the LandXML CRS to WGS84
+const reprojected = reprojectGeoJson(geojson, wktString, "WGS84", false);
+```
+
+---
+
+### Get GeoJSON contours only
 
 ```typescript
 import { toGeojsonContours, reprojectGeoJson } from "landxml";
 
-const loadGeojson = async () => {
-    const landXmlString = "<?xml version="1.0"?>...</LandXML>";
-    const contourInterval = 2;
-    const geojsonSurfaces = await toGeojsonContours(landXmlString, contourInterval);
+const landXmlString = `<?xml version="1.0"?>...<LandXML>...</LandXML>`;
+
+const surfaces = await toGeojsonContours(
+  landXmlString,
+  2, // contour interval (LandXML units)
+  true, // include surface outline as a z=0 feature
+);
+
+const { geojson, wktString } = surfaces[0];
 
-    // Retrieve geojson with raw LandXML coordinates
-    let { geojson, wktString } = geojsonSurfaces[0];
+// Reproject from the LandXML coordinate system to WGS84 for web mapping
+const reprojected = reprojectGeoJson(geojson, wktString ?? "WGS84", "WGS84", false);
 
-    // Reproject GeoJSON to a desired coordinate system (e.g., WGS84)
-    const targetCoordinateSystem = wktString || "WGS84";
-    const keepOriginalGeometryAsFeatureProperties = false;
-    return reprojectGeoJson(geojson, wktString, targetCoordinateSystem, keepOriginalGeometryAsFeatureProperties);
-}
+console.log(reprojected.features.length); // number of contour + outline features
 ```
 
-### Example: Convert to GLB 3D model
+---
+
+### Convert to a GLB 3D model
 
 ```typescript
 import { toGlb } from "landxml";
 
-const LandXml2GlbModel = async () => {
-    const landXmlString = "<?xml version="1.0"?>...</LandXML>";
+const landXmlString = `<?xml version="1.0"?>...<LandXML>...</LandXML>`;
+
+const surfaces = await toGlb(
+  landXmlString,
+  "auto", // centre strategy: "auto" | "origin" | [x, y]
+);
+
+const { glb, center, download } = surfaces[0];
+
+// Trigger a browser download of the .glb file
+download();
+
+// Or use the raw binary (Uint8Array) directly — e.g. load into Three.js
+const loader = new GLTFLoader();
+loader.parse(glb.buffer, "", (gltf) => {
+  scene.add(gltf.scene);
+});
+```
+
+---
+
+### Work with a specific surface in a multi-surface LandXML
+
+LandXML files can contain multiple surfaces. Use `surfaceId` to select one by name or by index.
+
+```typescript
+import { toGeojsonContours } from "landxml";
 
-    // Define how the model's origin should be positioned (options: "origin" | "auto" | [x: number, y: number])
-    const center = "auto";
-    const glbSurfaces = await toGlb(landXmlString, center);
+const landXmlString = `<?xml version="1.0"?>...<LandXML>...</LandXML>`;
 
-    let { download, glb } = glbSurfaces[0];
-    download()
+// By name
+const byName = await toGeojsonContours(landXmlString, 2, true, "ExistingGround");
 
-    // Alternatively, process the raw binary data from the 'glb' variable (Uint8Array)
-}
+// By index (0-based)
+const byIndex = await toGeojsonContours(landXmlString, 2, true, 1);
 ```
+
+---
+
+### Reproject GeoJSON
+
+`reprojectGeoJson` wraps `proj4` and works with both WKT strings (exported by Civil 3D when a drawing is geo-referenced) and standard proj4 definition strings.
+
+```typescript
+import { reprojectGeoJson } from "landxml";
+
+// wktString is available on every surface returned by toGeojsonContours / toGlbAndContours
+const reprojected = reprojectGeoJson(
+  geojson,
+  wktString, // source CRS — WKT or proj4 string
+  "WGS84", // target CRS (default)
+  true, // keep original geometry as feature property "_rawGeometry"
+);
+```
+
+---
+
+## API Reference
+
+### `toGlbAndContours(landXmlString, contourInterval?, generateOutline?, center?, surfaceId?)`
+
+| Parameter         | Type                           | Default  | Description                                        |
+| ----------------- | ------------------------------ | -------- | -------------------------------------------------- |
+| `landXmlString`   | `string`                       | —        | Raw LandXML XML string                             |
+| `contourInterval` | `number`                       | `2`      | Vertical interval between contour lines            |
+| `generateOutline` | `boolean`                      | `true`   | Append surface boundary as a `z=0` GeoJSON feature |
+| `center`          | `"auto" \| "origin" \| [x, y]` | `"auto"` | GLB model origin strategy                          |
+| `surfaceId`       | `string \| number`             | `-1`     | Surface name or index; `-1` returns all surfaces   |
+
+Returns `Promise<GlbAndContoursResult[]>` where each element contains `name`, `description`, `sourceFile`, `timeStamp`, `wktString`, `glb`, `center`, `download`, and `geojson`.
+
+---
+
+### `toGeojsonContours(landXmlString, contourInterval?, generateOutline?, surfaceId?)`
+
+| Parameter         | Type               | Default | Description                                        |
+| ----------------- | ------------------ | ------- | -------------------------------------------------- |
+| `landXmlString`   | `string`           | —       | Raw LandXML XML string                             |
+| `contourInterval` | `number`           | `2`     | Vertical interval between contour lines            |
+| `generateOutline` | `boolean`          | `true`  | Append surface boundary as a `z=0` GeoJSON feature |
+| `surfaceId`       | `string \| number` | `-1`    | Surface name or index; `-1` returns all surfaces   |
+
+Returns `Promise<{ name, description, sourceFile, timeStamp, wktString?, geojson }[]>`.
+
+---
+
+### `toGlb(landXmlString, center?, surfaceId?)`
+
+| Parameter       | Type                           | Default  | Description                                                                                                 |
+| --------------- | ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `landXmlString` | `string`                       | —        | Raw LandXML XML string                                                                                      |
+| `center`        | `"auto" \| "origin" \| [x, y]` | `"auto"` | GLB model origin strategy. 3D models are sensitive to large coordinates — `"auto"` offsets to the XY median |
+| `surfaceId`     | `string \| number`             | `-1`     | Surface name or index; `-1` returns all surfaces                                                            |
+
+Returns `Promise<{ name, description, sourceFile, timeStamp, glb, center, download }[]>`.
+
+---
+
+### `reprojectGeoJson(geojson, sourceProjection, targetProjection?, keepOriginalGeometry?)`
+
+| Parameter              | Type                | Default   | Description                                                        |
+| ---------------------- | ------------------- | --------- | ------------------------------------------------------------------ |
+| `geojson`              | `FeatureCollection` | —         | GeoJSON to reproject                                               |
+| `sourceProjection`     | `string`            | —         | Proj4 or WKT string of the source CRS                              |
+| `targetProjection`     | `string`            | `"WGS84"` | Proj4 or WKT string of the target CRS                              |
+| `keepOriginalGeometry` | `boolean`           | `true`    | Store original coordinates under `feature.properties._rawGeometry` |
+
+Returns the mutated `FeatureCollection` with updated coordinates.
+
+---
+
+## Multi-surface center behaviour
+
+When a LandXML file contains multiple surfaces and `center` is set to `"auto"` (the default), the package computes a **single shared median center** across all surfaces' points. Every GLB produced in that call is offset by the same origin, so the surfaces remain correctly positioned relative to each other in your 3D scene. This happens automatically — no extra configuration is needed.
+
+If you need each surface to be individually centered (e.g. you are processing them in isolation), pass an explicit `[x, y]` pair instead.
+
+---

package/dist/index.d.mts

@@ -3,7 +3,9 @@ import { FeatureCollection, LineString } from 'geojson';
 
 /**
  * @param landXmlString
- * @param center 3D models don't work well when they're far from origin (coordinate `[0,0,0]`), therefore by default your center is moved to the median of x and y axis of your surface
+ * @param center 3D models don't work well when they're far from origin (coordinate `[0,0,0]`), therefore by default your center is moved to the median of x and y axis of your surface.
+ *   When processing multiple surfaces with `"auto"`, a **single shared center** is computed
+ *   from all surfaces combined so they remain correctly positioned relative to each other.
  * @param surfaceId Surface name or index if your LandXML contains multiple surfaces. By default all surfaces are converted and returns an array of glb Uint8Array
  * @returns {Object[]} glbs - Array of processed glbs (will also return an array when just one surface has been processed)
  * @returns {string} glbs[].name - Name of surface as defined in LandXML
@@ -11,7 +13,7 @@ import { FeatureCollection, LineString } from 'geojson';
  * @returns {string} glbs[].sourceFile - Source file of where the LandXML was generated from.
  * @returns {string} glbs[].timeStamp - Timestamp of when the surface was exported into LandXML
  * @returns {Uint8Array} glbs[].glb - Uint8Array binary data of glb
- * @returns {[number, number]} glbs[].center - Offset center of the processed glb
+ * @returns {[number, number]} glbs[].center - Shared offset center applied to all GLBs
  * @returns {function(): void} glbs[].download - Convenient way to download the GLB, within the filename the new center will be appended.
  */
 declare const toGlb: (landXmlString: string, center?: "auto" | "origin" | [
@@ -59,4 +61,73 @@ declare const toGeojsonContours: (landXmlString: string, contourInterval?: numbe
  */
 declare const reprojectGeoJson: (geojson: FeatureCollection, sourceProjection: string, targetProjection?: string, keepOriginalGeometryAsFeatureProperty?: boolean) => FeatureCollection<geojson.Geometry, geojson.GeoJsonProperties>;
 
-export { reprojectGeoJson, toGeojsonContours, toGlb };
+type GlbAndContoursResult = {
+    name: string;
+    description: string;
+    sourceFile: string;
+    timeStamp: string;
+    wktString?: string;
+    /** Binary GLB data */
+    glb: Uint8Array;
+    /** Shared XY center used to offset all GLB models from origin */
+    center: [x: number, y: number];
+    /** Convenience download trigger (browser only) */
+    download: () => void;
+    /** Contour lines + optional outline as a GeoJSON FeatureCollection */
+    geojson: FeatureCollection<LineString, {
+        z: number;
+    }>;
+};
+/**
+ * Converts a LandXML string into **both** a GLB 3-D model and GeoJSON contour
+ * lines in a single pass — the XML is parsed once and the triangle/elevation
+ * data computed once and shared between both outputs.
+ *
+ * Use this instead of calling `toGlb` + `toGeojsonContours` separately when
+ * you need both outputs, as it eliminates all redundant work.
+ *
+ * When processing multiple surfaces with `center: "auto"`, a **single shared
+ * center** is computed from all surfaces combined, so every GLB is offset by
+ * the same origin and surfaces remain correctly positioned relative to each other.
+ *
+ * @param landXmlString   Raw LandXML string
+ * @param contourInterval Vertical interval between contour lines (default 2)
+ * @param generateOutline When true, the outline of each surface is appended to
+ *                        the GeoJSON as a z=0 feature (default true)
+ * @param center          GLB origin strategy: "auto" (combined median XY of all surfaces),
+ *                        "origin" ([0,0]), or an explicit [x, y] pair (default "auto")
+ * @param surfaceId       Surface name or 0-based index to process a single
+ *                        surface; -1 processes all surfaces (default -1)
+ */
+declare const toGlbAndContours: (landXmlString: string, contourInterval?: number, generateOutline?: boolean, center?: "auto" | "origin" | [
+    x: number,
+    y: number
+], surfaceId?: string | number) => Promise<GlbAndContoursResult[]>;
+
+type ParsedSurface = {
+    sourceFile: string;
+    timeStamp: string;
+    name: string;
+    description: string;
+    wktString?: string;
+    surfaceDefinition: {
+        points: [x: number, y: number, z: number][];
+        faces: [vertIndexA: number, vertIndexB: number, vertIndexC: number][];
+        faceNeighbors: [faceIndex: number, faceIndex: number, faceIndex: number][];
+    };
+};
+
+/**
+ * Derives the triangle list and elevation range from a ParsedSurface.
+ * Call this once and pass the result to both getContours() and getGlb() when
+ * you need both outputs for the same surface — avoids double-traversal of the
+ * (potentially large) faces/points arrays.
+ */
+type PrecomputedSurfaceData = {
+    triangles: [x: number, y: number, z: number][][];
+    minElevation: number;
+    maxElevation: number;
+};
+declare const precomputeSurfaceData: (data: ParsedSurface) => PrecomputedSurfaceData;
+
+export { type GlbAndContoursResult, type PrecomputedSurfaceData, precomputeSurfaceData, reprojectGeoJson, toGeojsonContours, toGlb, toGlbAndContours };

package/dist/index.d.ts

@@ -3,7 +3,9 @@ import { FeatureCollection, LineString } from 'geojson';
 
 /**
  * @param landXmlString
- * @param center 3D models don't work well when they're far from origin (coordinate `[0,0,0]`), therefore by default your center is moved to the median of x and y axis of your surface
+ * @param center 3D models don't work well when they're far from origin (coordinate `[0,0,0]`), therefore by default your center is moved to the median of x and y axis of your surface.
+ *   When processing multiple surfaces with `"auto"`, a **single shared center** is computed
+ *   from all surfaces combined so they remain correctly positioned relative to each other.
  * @param surfaceId Surface name or index if your LandXML contains multiple surfaces. By default all surfaces are converted and returns an array of glb Uint8Array
  * @returns {Object[]} glbs - Array of processed glbs (will also return an array when just one surface has been processed)
  * @returns {string} glbs[].name - Name of surface as defined in LandXML
@@ -11,7 +13,7 @@ import { FeatureCollection, LineString } from 'geojson';
  * @returns {string} glbs[].sourceFile - Source file of where the LandXML was generated from.
  * @returns {string} glbs[].timeStamp - Timestamp of when the surface was exported into LandXML
  * @returns {Uint8Array} glbs[].glb - Uint8Array binary data of glb
- * @returns {[number, number]} glbs[].center - Offset center of the processed glb
+ * @returns {[number, number]} glbs[].center - Shared offset center applied to all GLBs
  * @returns {function(): void} glbs[].download - Convenient way to download the GLB, within the filename the new center will be appended.
  */
 declare const toGlb: (landXmlString: string, center?: "auto" | "origin" | [
@@ -59,4 +61,73 @@ declare const toGeojsonContours: (landXmlString: string, contourInterval?: numbe
  */
 declare const reprojectGeoJson: (geojson: FeatureCollection, sourceProjection: string, targetProjection?: string, keepOriginalGeometryAsFeatureProperty?: boolean) => FeatureCollection<geojson.Geometry, geojson.GeoJsonProperties>;
 
-export { reprojectGeoJson, toGeojsonContours, toGlb };
+type GlbAndContoursResult = {
+    name: string;
+    description: string;
+    sourceFile: string;
+    timeStamp: string;
+    wktString?: string;
+    /** Binary GLB data */
+    glb: Uint8Array;
+    /** Shared XY center used to offset all GLB models from origin */
+    center: [x: number, y: number];
+    /** Convenience download trigger (browser only) */
+    download: () => void;
+    /** Contour lines + optional outline as a GeoJSON FeatureCollection */
+    geojson: FeatureCollection<LineString, {
+        z: number;
+    }>;
+};
+/**
+ * Converts a LandXML string into **both** a GLB 3-D model and GeoJSON contour
+ * lines in a single pass — the XML is parsed once and the triangle/elevation
+ * data computed once and shared between both outputs.
+ *
+ * Use this instead of calling `toGlb` + `toGeojsonContours` separately when
+ * you need both outputs, as it eliminates all redundant work.
+ *
+ * When processing multiple surfaces with `center: "auto"`, a **single shared
+ * center** is computed from all surfaces combined, so every GLB is offset by
+ * the same origin and surfaces remain correctly positioned relative to each other.
+ *
+ * @param landXmlString   Raw LandXML string
+ * @param contourInterval Vertical interval between contour lines (default 2)
+ * @param generateOutline When true, the outline of each surface is appended to
+ *                        the GeoJSON as a z=0 feature (default true)
+ * @param center          GLB origin strategy: "auto" (combined median XY of all surfaces),
+ *                        "origin" ([0,0]), or an explicit [x, y] pair (default "auto")
+ * @param surfaceId       Surface name or 0-based index to process a single
+ *                        surface; -1 processes all surfaces (default -1)
+ */
+declare const toGlbAndContours: (landXmlString: string, contourInterval?: number, generateOutline?: boolean, center?: "auto" | "origin" | [
+    x: number,
+    y: number
+], surfaceId?: string | number) => Promise<GlbAndContoursResult[]>;
+
+type ParsedSurface = {
+    sourceFile: string;
+    timeStamp: string;
+    name: string;
+    description: string;
+    wktString?: string;
+    surfaceDefinition: {
+        points: [x: number, y: number, z: number][];
+        faces: [vertIndexA: number, vertIndexB: number, vertIndexC: number][];
+        faceNeighbors: [faceIndex: number, faceIndex: number, faceIndex: number][];
+    };
+};
+
+/**
+ * Derives the triangle list and elevation range from a ParsedSurface.
+ * Call this once and pass the result to both getContours() and getGlb() when
+ * you need both outputs for the same surface — avoids double-traversal of the
+ * (potentially large) faces/points arrays.
+ */
+type PrecomputedSurfaceData = {
+    triangles: [x: number, y: number, z: number][][];
+    minElevation: number;
+    maxElevation: number;
+};
+declare const precomputeSurfaceData: (data: ParsedSurface) => PrecomputedSurfaceData;
+
+export { type GlbAndContoursResult, type PrecomputedSurfaceData, precomputeSurfaceData, reprojectGeoJson, toGeojsonContours, toGlb, toGlbAndContours };