@team-geospan/struct3d 1.0.0

package/.github/workflows/deploy.yml

@@ -0,0 +1,50 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+  
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Website
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build Docs
+        run: npm run build
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,17 @@
+# Struct3D
+
+The 3D Viewer component for StructuresJSON collections.
+
+## Installation
+
+```
+npm install @team-geospan/struct3d
+```
+
+## Usage
+
+The docs contain a [great example](./docs/src/pages/demo.jsx).
+
+## License
+
+Apache 2.0. Availabe in [LICENSE](./LICENSE).

package/docs/astro.config.mjs

@@ -0,0 +1,8 @@
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://team-geospan.github.io',
+  base: '/struct3d/',
+  integrations: [react()]
+});

package/docs/src/pages/demo.jsx

@@ -0,0 +1,205 @@
+import React, { useRef, useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import StructureThreeD from "../../../lib/index.js";
+
+// This is a nice default with two structures
+const DEMO_URL =
+  "https://raw.githubusercontent.com/team-geospan/structures-json/refs/heads/main/versions/examples/V1.0-draft/two-structure-collection.json";
+
+// Demo changing the edge colors using different palettes
+const PALETTES = {
+  hicontrast: {
+    eave: "#000000", // Black
+    hip: "#FFFFFF", // White
+    valley: "#FFD700", // Bright Yellow
+    flash: "#FF0000", // Bright Red
+    ridge: "#00FFFF", // Cyan
+    rake: "#FF00FF", // Magenta
+    stepflash: "#00FF00", // Neon Green
+    parapet: "#0000FF", // Pure Blue
+    fance: "#FFA500", // Orange
+    chimney: "#808080", // Gray for balance
+  },
+  hotdog: {
+    eave: "#FF0000", // Bright Red
+    hip: "#FFFF00", // Bright Yellow
+    valley: "#00FFFF", // Cyan
+    flash: "#FF00FF", // Magenta
+    ridge: "#0000FF", // Blue
+    rake: "#FFA500", // Orange
+    stepflash: "#00FF00", // Bright Green
+    parapet: "#FF4500", // Red-Orange
+    fance: "#FFD700", // Gold
+    chimney: "#800000", // Dark Red
+  },
+};
+
+// Somewhat bad practice to put all the components into one file but this
+//  puts everything into a singular grokable view.
+function SelectedInfo({ structureCollection, selectedId }) {
+  const [structureIndex, elementId] = selectedId.split("-");
+  const structure = structureCollection.structures[parseInt(structureIndex)];
+
+  let unitLabel = "sq. m.";
+  let value = 0.0;
+  if (structure.edges[elementId]) {
+    // use as edge
+    unitLabel = "m.";
+    value = structure.edges[elementId].properties.length;
+  } else {
+    // assume a surface
+    value = structure.surfaces[elementId].properties.area;
+  }
+
+  return (
+    <div>
+      {elementId}: {value} {unitLabel}
+    </div>
+  );
+}
+
+SelectedInfo.propTypes = {
+  structureCollection: PropTypes.object,
+  selectedId: PropTypes.string,
+};
+
+function Demo() {
+  const [isLoading, setLoading] = useState(true);
+  const [structureCollection, setStructureCollection] = useState(null);
+  const [selectedIds, setSelectedIds] = useState([]);
+  const [url, setUrl] = useState(DEMO_URL);
+  const [palette, setPalette] = useState("");
+  const inputRef = useRef();
+
+  useEffect(() => {
+    fetch(url)
+      .then((r) => r.json())
+      .then((stc) => {
+        if (stc.kind === "structurecollection") {
+          setStructureCollection(stc);
+        } else if (stc.kind === "structure") {
+          setStructureCollection({
+            kind: "structurecollection",
+            structures: [stc],
+          });
+        }
+        setLoading(false);
+      });
+  }, [url]);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        flex: 1,
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+      }}
+    >
+      <div
+        style={{
+          padding: "6px",
+          display: "flex",
+          flexDirection: "column",
+          gap: 6,
+        }}
+      >
+        <div
+          style={{
+            display: "flex",
+            gap: 1,
+          }}
+        >
+          <input ref={inputRef} defaultValue={url} style={{ flex: 1 }} />
+          <button
+            onClick={() => {
+              setUrl(inputRef.current.value);
+            }}
+          >
+            Load
+          </button>
+        </div>
+        <div>
+          <label>Color palette:</label>
+          <select
+            value={palette}
+            onChange={(evt) => {
+              setPalette(evt.target.value);
+            }}
+          >
+            <option value="">Default</option>
+            <option value="hicontrast">High Contrast</option>
+            <option value="hotdog">Hot Dog Stand</option>
+          </select>
+        </div>
+      </div>
+      <div
+        style={{
+          position: "relative",
+          flex: 1,
+        }}
+      >
+        {selectedIds && selectedIds.length > 0 && (
+          <div
+            style={{
+              position: "absolute",
+              zIndex: 10,
+              left: 12,
+              top: 12,
+              padding: 12,
+              borderRadius: 6,
+              border: "solid 2px #d4af38",
+              backgroundColor: "#333",
+              color: "white",
+            }}
+          >
+            {selectedIds.map((selectedId) => (
+              <SelectedInfo
+                key={selectedId}
+                selectedId={selectedId}
+                structureCollection={structureCollection}
+              />
+            ))}
+          </div>
+        )}
+        {isLoading && (
+          <div
+            style={{
+              display: "flex",
+              position: "absolute",
+              left: 0,
+              top: 0,
+              width: "100%",
+              height: "100%",
+              alignItems: "center",
+              justifyContent: "center",
+            }}
+          >
+            Loading...
+          </div>
+        )}
+        {!isLoading && structureCollection && (
+          <StructureThreeD
+            key={url + palette}
+            structureCollection={structureCollection}
+            onClick={(ids) => {
+              setSelectedIds(ids);
+            }}
+            selectedIds={selectedIds}
+            edgeColors={PALETTES[palette]}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+Demo.propTypes = {
+  url: PropTypes.string,
+};
+
+export default Demo;

package/docs/src/pages/index.astro

@@ -0,0 +1,60 @@
+---
+import Demo from "./demo.jsx";
+---
+
+<html>
+  <head>
+    <title>Struct3D: Renderer for StructuresJSON</title>
+  <style>
+body {
+  font-family: sans-serif;
+  display: flex;
+  flex-direction: column;
+}
+
+html, body {
+  height: 100%;
+  padding: 0;
+  margin: 0;
+}
+
+header {
+  margin: 24px;
+  margin-bottom: 0px;
+}
+
+footer {
+  margin: 24px;
+  margin-top: 0px;
+}
+
+h1 {
+  margin: 0;
+  padding: 0;
+}
+
+#viewer {
+  flex: 1;
+  position: relative;
+  margin: 24px;
+  border: solid 1px black;
+  border-radius: 12px;
+  overflow: hidden;
+}
+  </style>
+  </head>
+  <body>
+    <header>
+      <h1>Struct3D</h1>
+      <p>
+        3D Renderer for <a href="https://github.com/team-geospan/structures-json">StructuresJSON</a> files.
+      </p>
+    </header>
+    <div id="viewer">
+      <Demo client:only="react" />
+    </div>
+    <footer>
+      &copy; 2025 GEOSPAN Corp. Apache-2 License
+    </footer>
+  </body>
+</html>

package/docs/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "astro/tsconfigs/base",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react"
+  }
+}

package/lib/defaults.js

@@ -0,0 +1,22 @@
+export const DEFAULT_FACET_COLORS = {
+  asphalt: "#ecc696",
+  wood: "#ffdbb7",
+  tile: "#a4e6ff",
+  metal: "#ceffe3",
+  slate: "#95be8f",
+  membrane: "#c39fcc",
+  solar: "#c6a2ab",
+};
+
+export const DEFAULT_EDGE_COLORS = {
+  eave: "#9f476d",
+  hip: "#83b936",
+  valley: "#7663cf",
+  flash: "#bbb047",
+  ridge: "#5b8acc",
+  rake: "#d05330",
+  stepflash: "#40bbc1",
+  parapet: "#62be89",
+  fance: "#a97bc2",
+  chimney: "#6f903e",
+};

package/lib/draw.js

@@ -0,0 +1,234 @@
+/**
+ * Copyright GEOSPAN Corp
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import earcut, { flatten } from "earcut";
+import * as THREE from "three";
+import { Line2 } from "three/addons/lines/Line2.js";
+import { LineGeometry } from "three/addons/lines/LineGeometry.js";
+import { LineMaterial } from "three/addons/lines/LineMaterial.js";
+
+function calcCollectionBounds(collection) {
+  let [minx, miny, minz, maxx, maxy, maxz] = [
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+  ];
+
+  collection.structures.forEach((st) => {
+    Object.values(st.points).map((pt) => {
+      const [x, y, z] = pt.coordinates;
+      if (minx === null || x < minx) {
+        minx = x;
+      }
+      if (maxx === null || x > maxx) {
+        maxx = x;
+      }
+      if (miny === null || y < miny) {
+        miny = y;
+      }
+      if (maxy === null || y > maxy) {
+        maxy = y;
+      }
+      if (minz === null || z < minz) {
+        minz = z;
+      }
+      if (maxz === null || z > maxz) {
+        maxz = z;
+      }
+    });
+  });
+
+  // make this compatible with 2d representation
+  return [minx, miny, maxx, maxy, minz, maxz];
+}
+
+function getAnchor(collection) {
+  const bounds = calcCollectionBounds(collection);
+  const x0 = bounds[0] + (bounds[2] - bounds[0]) / 2;
+  const y0 = bounds[1] + (bounds[3] - bounds[1]) / 2;
+  return [x0, y0, bounds[4]];
+}
+
+export function createLines(
+  collection,
+  baseElevation,
+  edgeColors,
+  width,
+  height,
+) {
+  const [x0, y0, minz] = getAnchor(collection);
+  const lines = collection.structures.flatMap((structure, stIdx) => {
+    const { edges, points } = structure;
+    return Object.keys(edges).map((edgeId) => {
+      const edge = edges[edgeId];
+      // offset and swap coordinates
+      const linePoints = edge.points.map((pointId) => {
+        const pt = points[pointId].coordinates;
+        return [pt[0] - x0, pt[2] - minz + baseElevation, y0 - pt[1]];
+      });
+
+      const geometry = new LineGeometry();
+      geometry.setPositions(linePoints.flatMap((p) => p));
+
+      const material = new LineMaterial({
+        color: edgeColors[edge.kind] || "#000000",
+        linewidth: edge.kind ? 3 : 1,
+      });
+      material.resolution.set(width, height);
+
+      const line = new Line2(geometry, material);
+      line.userData = {
+        ...edge.properties,
+        kind: edge.kind,
+        id: `${stIdx}-${edgeId}`,
+        layer: "edges",
+      };
+      return line;
+    });
+  });
+
+  return lines;
+}
+
+/**
+ * Convert the edge into a list of point IDs,
+ * edges are not directional! The ends need to be checked for
+ * continuity
+ */
+function simplifyRing(edges) {
+  if (!edges || edges.length === 0) {
+    return [];
+  }
+
+  const sortedList = [edges.shift()];
+
+  while (edges.length > 0) {
+    for (let i = 0; i < edges.length; i++) {
+      const edge = edges[i];
+      if (sortedList[sortedList.length - 1][1] === edge[0]) {
+        sortedList.push(edges.splice(i, 1)[0]);
+        break;
+      } else if (sortedList[sortedList.length - 1][1] === edge[1]) {
+        sortedList.push(edges.splice(i, 1)[0].reverse());
+        break;
+      }
+    }
+  }
+
+  const asPoints = sortedList.map((e) => e[0]);
+  asPoints.push(sortedList[0][0]);
+  return asPoints;
+}
+
+export function createFacets(structureCollection, baseElevation, facetColors) {
+  const [x0, y0, minz] = getAnchor(structureCollection);
+
+  const meshes = structureCollection.structures.flatMap((structure, stIdx) => {
+    const { edges, points } = structure;
+
+    return Object.keys(structure.surfaces).map((surfaceId) => {
+      const surface = structure.surfaces[surfaceId];
+
+      const coords = surface.edges.map((ring) => {
+        return simplifyRing(
+          structuredClone(ring.map((edgeId) => edges[edgeId].points)),
+        )
+          .map((ptId) => points[ptId].coordinates)
+          .map((pt) => [pt[0] - x0, y0 - pt[1], pt[2] - minz + baseElevation]);
+      });
+
+      // make all the triangles, thank you earcut!
+      const data = flatten(coords);
+      const triangles = earcut(data.vertices, data.holes, data.dimensions);
+
+      // swap the y and z coordinates
+      for (let i = 0, len = data.vertices.length; i < len; i += 3) {
+        const y = data.vertices[i + 1];
+        const z = data.vertices[i + 2];
+        data.vertices[i + 1] = z;
+        data.vertices[i + 2] = y;
+      }
+
+      const bufferGeometry = new THREE.BufferGeometry();
+      bufferGeometry.setIndex(triangles);
+      bufferGeometry.setAttribute(
+        "position",
+        new THREE.BufferAttribute(new Float32Array(data.vertices), 3),
+      );
+      // Normally, the normals would be used to calculate the normal
+      //  for each vertex and apply the material, *however* we use flatShading
+      //  so do not want to compute the normals
+      // bufferGeometry.computeVertexNormals();
+
+      const material = new THREE.MeshPhongMaterial({
+        side: THREE.DoubleSide,
+        color: facetColors[surface.properties.material || "asphalt"],
+        flatShading: true,
+        shininess: 30,
+      });
+
+      const polygon = new THREE.Mesh(bufferGeometry, material);
+      polygon.userData = {
+        ...surface.properties,
+        id: `${stIdx}-${surfaceId}`,
+        layer: "facets",
+      };
+      return polygon;
+    });
+  });
+  return meshes;
+}
+
+export function createReferences(scene) {
+  const floorGeom = new THREE.PlaneGeometry(1000, 1000);
+  const floorMaterial = new THREE.MeshPhongMaterial({
+    color: 0x315d0a,
+    side: THREE.DoubleSide,
+  });
+  const floorMesh = new THREE.Mesh(floorGeom, floorMaterial);
+  floorMesh.rotation.x = -Math.PI / 2;
+  floorMesh.receiveShadow = true;
+  scene.add(floorMesh);
+
+  // TODO: Size is set to "1" which is one meter in this projection,
+  //       we should do something for US measurements
+  const gridHelper = new THREE.GridHelper(100, 100, 0x888888, 0x888888);
+  gridHelper.receiveShadow = true;
+  gridHelper.position.set(0, 0.1, 0);
+  scene.add(gridHelper);
+}
+
+export function addLights(scene, center, bounds) {
+  const intensity = 5000;
+  const ambient = new THREE.AmbientLight(0xffffff);
+  ambient.intensity = 1.5;
+  scene.add(ambient);
+
+  const spotLight = new THREE.SpotLight(0xffffff, intensity);
+  spotLight.position.set(bounds.x / 2, bounds.y + 50, bounds.z / 2);
+  spotLight.castShadow = true;
+  spotLight.angle = 5.0;
+  spotLight.lookAt(center);
+
+  scene.add(spotLight);
+}
+
+export function clearScene(scene) {
+  scene.clear();
+}

package/lib/index.js

@@ -0,0 +1,313 @@
+/**
+ * Copyright GEOSPAN Corp
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createElement, useCallback, useEffect, useMemo, useRef } from "react";
+import { useResizeDetector } from "react-resize-detector";
+import { DEFAULT_EDGE_COLORS, DEFAULT_FACET_COLORS } from "./defaults";
+import { toMercator } from "@turf/projection";
+import PropTypes from "prop-types";
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls";
+
+import {
+  addLights,
+  clearScene,
+  createFacets,
+  createLines,
+  createReferences,
+} from "./draw";
+
+const THREED_SKY_COLOR = "#CDEBF7";
+
+const setupScene = (
+  divRef,
+  sceneRef,
+  cameraRef,
+  rendererRef,
+  orbitRef,
+  fieldOfView,
+) => {
+  const [width, height] = [
+    divRef.current.offsetWidth,
+    divRef.current.offsetHeight,
+  ];
+
+  // create the scene
+  const scene = new THREE.Scene();
+  sceneRef.current = scene;
+
+  scene.background = new THREE.Color(THREED_SKY_COLOR);
+  scene.fog = new THREE.Fog(scene.background, 1, 5000);
+
+  const camera = new THREE.PerspectiveCamera(
+    fieldOfView,
+    width / height,
+    0.1,
+    1000.0,
+  );
+  cameraRef.current = camera;
+  const renderer = new THREE.WebGLRenderer({
+    preserveDrawingBuffer: true,
+    antialias: true,
+  });
+
+  const orbitControl = new OrbitControls(camera, renderer.domElement);
+  orbitControl.minPolarAngle = 0;
+  orbitControl.maxPolarAngle = Math.PI * 0.5;
+  orbitRef.current = orbitControl;
+
+  renderer.setSize(width, height);
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+  rendererRef.current = renderer;
+  renderer.setAnimationLoop(() => {
+    renderer.render(scene, camera);
+  });
+  divRef.current.appendChild(renderer.domElement);
+};
+
+const renderModel = (
+  divRef,
+  collection,
+  baseElevation,
+  facetColors,
+  edgeColors,
+  sceneRef,
+  cameraRef,
+  orbitRef,
+  fieldOfView,
+) => {
+  // calculate the spatial extents of the meshes
+  const boundingBox = new THREE.Box3();
+  const [width, height] = [
+    divRef.current.offsetWidth,
+    divRef.current.offsetHeight,
+  ];
+  const scene = sceneRef.current;
+  const camera = cameraRef.current;
+  const orbitControl = orbitRef.current;
+
+  // convert the polygons to meshes
+  const meshes = createFacets(collection, baseElevation, facetColors);
+
+  meshes.forEach((mesh) => {
+    mesh.receiveShadow = true;
+    mesh.castShadow = true;
+    scene.add(mesh);
+    boundingBox.expandByObject(mesh);
+  });
+
+  const lines = createLines(
+    collection,
+    baseElevation + 0.01,
+    edgeColors,
+    width,
+    height,
+  );
+  lines.forEach((line) => {
+    scene.add(line);
+  });
+
+  const center = new THREE.Vector3();
+  boundingBox.getCenter(center);
+
+  const bounds = new THREE.Vector3();
+  boundingBox.getSize(bounds);
+
+  createReferences(scene, center, bounds);
+
+  addLights(scene, center, bounds);
+
+  orbitControl.target = center;
+
+  // calculate the distance to zoom out in order to fit the entire model
+  const h = bounds.x / 2 / Math.tan(((fieldOfView / 2.0) * Math.PI) / 180);
+  const d = bounds.z / 2 / Math.tan(((fieldOfView / 2.0) * Math.PI) / 180);
+
+  camera.position.x = center.x / 1.25;
+  camera.position.y = Math.max(h, d) + bounds.y;
+  camera.position.z = bounds.z / 1.25;
+  camera.lookAt(center);
+};
+
+export default function StructureThreeD({
+  structureCollection,
+  selectedIds,
+  onClick,
+  selectionColor = "#d4af38",
+  facetColors = DEFAULT_FACET_COLORS,
+  edgeColors = DEFAULT_EDGE_COLORS,
+}) {
+  const baseElevation = 10;
+  const fieldOfView = 70;
+  const divRef = useRef(null);
+  const sceneRef = useRef(null);
+  const cameraRef = useRef(null);
+  const orbitRef = useRef(null);
+  const rendererRef = useRef(null);
+
+  const collection = useMemo(() => {
+    // check the projection of the structures and put them into webmerc
+    const cleanCollection = structuredClone(structureCollection);
+    cleanCollection.structures.forEach((structure) => {
+      if (structure.projection === "crs84") {
+        // convert the points to mercator
+        Object.keys(structure.points).forEach((pointId) => {
+          // this looks messier than it is, get the coordinates from the point,
+          //  shim toMercator to use a GeoJSON style point, then pull the coordinates
+          //  out in order to reproject the stucture.
+          const coordinates = structure.points[pointId].coordinates;
+          structure.points[pointId].coordinates = toMercator({
+            type: "Point",
+            coordinates,
+          }).coordinates;
+        });
+        structure.projection = "webmerc";
+      } else if (structure.projection === "webmerc") {
+        return structure;
+      } else {
+        // yikes this is unsupported right now!
+        console.error(
+          `Structure with projection "${structure.projection}" is not currently supported.`,
+        );
+      }
+    });
+
+    return cleanCollection;
+  }, [structureCollection]);
+
+  // handle resizing of the div!
+  const { width, height, ref } = useResizeDetector();
+
+  useEffect(() => {
+    if (divRef.current) {
+      if (sceneRef.current === null) {
+        setupScene(
+          divRef,
+          sceneRef,
+          cameraRef,
+          rendererRef,
+          orbitRef,
+          fieldOfView,
+        );
+      }
+
+      clearScene(sceneRef.current);
+      renderModel(
+        divRef,
+        collection,
+        baseElevation,
+        facetColors,
+        edgeColors,
+        sceneRef,
+        cameraRef,
+        orbitRef,
+        fieldOfView,
+      );
+    }
+  }, [collection, selectionColor]);
+
+  const handleClick = useCallback(
+    (evt) => {
+      const [x, y] = [evt.nativeEvent.offsetX, evt.nativeEvent.offsetY];
+      const [width, height] = [
+        divRef.current.offsetWidth,
+        divRef.current.offsetHeight,
+      ];
+      const raycaster = new THREE.Raycaster();
+      const mouse = new THREE.Vector2();
+      mouse.set((x / width) * 2 - 1, -(y / height) * 2 + 1);
+      raycaster.setFromCamera(mouse, cameraRef.current);
+      const intersects = raycaster.intersectObjects(
+        sceneRef.current.children,
+        true,
+      );
+      const ids = intersects
+        .map((f) => f.object.userData)
+        .map((f) => f.id)
+        // ensure the object has an ID
+        .filter((id) => !!id);
+      if (onClick) {
+        onClick(ids);
+      }
+    },
+    [onClick],
+  );
+
+  useEffect(() => {
+    if (sceneRef.current) {
+      sceneRef.current.traverse((object) => {
+        // ensure the object has a material set and the userData has our layer specified
+        if (object.material && Boolean(object.userData?.layer)) {
+          let color =
+            object.userData.layer === "facets"
+              ? facetColors[object.userData?.material || "asphalt"]
+              : edgeColors[object.userData.kind] || "#00000000";
+          if (selectedIds.includes(object.userData?.id)) {
+            color = selectionColor;
+          }
+          object.material.color.set(color);
+        }
+      });
+    }
+  }, [selectedIds, selectionColor]);
+
+  useEffect(() => {
+    if (rendererRef.current && cameraRef.current && !!width && !!height) {
+      cameraRef.current.aspect = width / height;
+      cameraRef.current.updateProjectionMatrix();
+      rendererRef.current.setSize(width, height);
+    }
+  }, [width, height]);
+
+  return createElement(
+    "div",
+    {
+      ref,
+      style: {
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+        backgroundColor: "#eee",
+      },
+    },
+    [
+      createElement("div", {
+        ref: divRef,
+        onClick: handleClick,
+        className: "struct-3d",
+        style: {
+          position: "absolute",
+          top: 0,
+          left: 0,
+          width: "100%",
+          height: "100%",
+        },
+      }),
+    ],
+  );
+}
+
+StructureThreeD.propTypes = {
+  structureCollection: PropTypes.object,
+  selectedIds: PropTypes.array,
+  onClick: PropTypes.func,
+  selectionColor: PropTypes.string,
+  facetColors: PropTypes.object,
+  edgeColors: PropTypes.object,
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@team-geospan/struct3d",
+  "version": "1.0.0",
+  "description": "The 3D Viewer component for StructuresJSON models.",
+  "license": "Apache-2.0",
+  "author": "GEOSPAN Corp and Contributors",
+  "type": "module",
+  "scripts": {
+    "build:copy-files": "node ./scripts/bundle.js",
+    "lint": "eslint --report-unused-disable-directives --max-warnings 0 ./lib ./docs --ext .js,.jsx",
+    "lint:fix": "npm run lint -- --fix",
+    "start": "astro dev --root ./docs",
+    "build": "astro build --root ./docs",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "eslintConfig": {
+    "env": {
+      "browser": true,
+      "es2021": true
+    },
+    "parserOptions": {
+      "ecmaVersion": "latest",
+      "sourceType": "module"
+    },
+    "settings": {
+      "react": {
+        "version": "detect"
+      }
+    },
+    "extends": [
+      "eslint:recommended",
+      "plugin:react/recommended",
+      "plugin:prettier/recommended"
+    ],
+    "rules": {
+      "prettier/prettier": "error"
+    }
+  },
+  "dependencies": {
+    "@turf/projection": "^6.5.0",
+    "earcut": "^3.0.1",
+    "react-resize-detector": "^12.0.2",
+    "three": "^0.167.1"
+  },
+  "devDependencies": {
+    "@astrojs/react": "^4.2.0",
+    "@swc/cli": "^0.3.12",
+    "@swc/core": "^1.5.25",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "astro": "^5.3.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.3",
+    "eslint-plugin-react": "^7.37.4",
+    "prop-types": "^15.8.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}