landxml 0.6.6 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # landxml
 
+## 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,188 @@
-# 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 centre: "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>`;
 
-    // Retrieve geojson with raw LandXML coordinates
-    let { geojson, wktString } = geojsonSurfaces[0];
+const surfaces = await toGeojsonContours(
+  landXmlString,
+  2, // contour interval (metres)
+  true, // include surface outline as a z=0 feature
+);
 
-    // Reproject GeoJSON to a desired coordinate system (e.g., WGS84)
-    const targetCoordinateSystem = wktString || "WGS84";
-    const keepOriginalGeometryAsFeatureProperties = false;
-    return reprojectGeoJson(geojson, wktString, targetCoordinateSystem, keepOriginalGeometryAsFeatureProperties);
-}
+const { geojson, wktString } = surfaces[0];
+
+// Reproject from the LandXML coordinate system to WGS84 for web mapping
+const reprojected = reprojectGeoJson(geojson, wktString ?? "WGS84", "WGS84", false);
+
+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>`;
 
-    // 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 surfaces = await toGlb(
+  landXmlString,
+  "auto", // centre strategy: "auto" | "origin" | [x, y]
+);
 
-    let { download, glb } = glbSurfaces[0];
-    download()
+const { glb, center, download } = surfaces[0];
 
-    // Alternatively, process the raw binary data from the 'glb' variable (Uint8Array)
-}
+// 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";
+
+const landXmlString = `<?xml version="1.0"?>...<LandXML>...</LandXML>`;
+
+// By name
+const byName = await toGeojsonContours(landXmlString, 2, true, "ExistingGround");
+
+// 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.

package/dist/index.d.mts

@@ -59,4 +59,69 @@ 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;
+    /** XY center used to offset the GLB model 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.
+ *
+ * @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" (median XY), "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

@@ -59,4 +59,69 @@ 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;
+    /** XY center used to offset the GLB model 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.
+ *
+ * @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" (median XY), "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 };