plebeiangraphlibrary 2.0.1 → 2.1.2

package/Examples/examples.html

@@ -36,8 +36,8 @@
       </a>
       <a href="5_Hierarchy_simple.html" class="example-card">
         <div class="num">Example 5</div>
-        <div class="title">Hierarchy</div>
-        <p class="desc">3D KD-tree clustering: nodes within a distance threshold are merged into super-nodes at centroids. Simplified graph with thick edges.</p>
+        <div class="title">Hierarchy (simplify by merging nearby nodes)</div>
+        <p class="desc">Merge nodes within a distance in 3D into super-nodes at cluster centers; edges between clusters are combined. Fewer nodes, same overall structure — good for LOD or flow-map style views.</p>
       </a>
       <a href="6_Flowmap_style.html" class="example-card">
         <div class="num">Example 6</div>
@@ -54,6 +54,31 @@
         <div class="title">ThreeWrapper variants</div>
         <p class="desc">Different draw styles: box nodes, simplified (cylinder-style) edges, and modularity-based node/edge groups by a node property.</p>
       </a>
+      <a href="9_Simulation_live.html" class="example-card">
+        <div class="num">Example 9</div>
+        <div class="title">Live 3D simulation</div>
+        <p class="desc">Time-based 3D Kamada–Kawai: layout evolves in real time. Uses createKamadaKawai3D, step(dt), and mutable vertices.</p>
+      </a>
+      <a href="10_Adjacency_matrix.html" class="example-card">
+        <div class="num">Example 10</div>
+        <div class="title">Adjacency matrix + power iteration</div>
+        <p class="desc">get_adjacency_matrix() and matrix math in the browser. Power iteration for leading eigenvector; node size reflects value.</p>
+      </a>
+      <a href="11_Custom_layout.html" class="example-card">
+        <div class="num">Example 11</div>
+        <div class="title">Custom layout from matrix math</div>
+        <p class="desc">Adjacency → power iteration for two coordinates → apply_position_map. Full pipeline: matrix math to 3D layout.</p>
+      </a>
+      <a href="12_StressSGD_simulation_live.html" class="example-card">
+        <div class="num">Example 12</div>
+        <div class="title">Stress SGD live simulation</div>
+        <p class="desc">Stress layout by s_gd2: epoch-based, Fisher-Yates shuffle. createStressSGD3D, step(dt).</p>
+      </a>
+      <a href="13_StressSGD_bunny_3d.html" class="example-card">
+        <div class="num">Example 13</div>
+        <div class="title">Stress SGD 3D (Stanford Bunny mesh)</div>
+        <p class="desc">3D stress layout from a mesh: OBJ → graph (vertices + edges), initial positions = mesh. Layout refines in 3D so the shape stays bunny-like.</p>
+      </a>
     </section>
   </main>
 </body>

package/README.md

@@ -1,20 +1,18 @@
 ## Introduction
 
-The Plebeian Graph Library (PGL) is a library designed to facilitate the visualization of large-scale network data (Network X line plotting in Javascript/Typescript). Leveraging the power of WebGL, PGL offers an efficient and interactive solution for visualizing network data in web browsers (Tested on Firefox, Edge and Chrome). Whether dealing with local datasets or data retrieved from APIs, PGL provides a versatile platform for conducting extensive network simulations, physical modeling, and immersive visualizations. With a rich set of features including graph condensation based on selected criteria, randomized edge pruning in highly connected graphs, and support for diverse visualization techniques like network diffusions and Kamada Kawai layouts, and edge bundling, PGL empowers users to gain valuable insights from complex network structures.
+The Plebeian Graph Library (PGL) is a library designed to facilitate the visualization of large-scale network data (NetworkX-style graph plotting in JavaScript/TypeScript). Leveraging the power of WebGL, PGL offers an efficient and interactive solution for visualizing network data in web browsers (Tested on Firefox, Edge and Chrome). Whether dealing with local datasets or data retrieved from APIs, PGL provides a versatile platform for conducting extensive network simulations, physical modeling, and immersive visualizations. With a rich set of features including graph condensation based on selected criteria, randomized edge pruning in highly connected graphs, and support for diverse visualization techniques like network diffusions and Kamada Kawai layouts, and edge bundling, PGL empowers users to gain valuable insights from complex network structures.
 
 ## Notes on terminology
 
-It can be a bit confusing especially when working with Nodes/Edges/Vertices/Lines in this library (Also in general in working with graphs). Hence the terminology that I've followed here is as following:
+It can be a bit confusing especially when working with Nodes/Edges/Vertices/Lines in this library (Also in general in working with graphs). Hence the terminology that I've followed here is as follows:
 
 - Nodes (The library and the class is called \_Node so as to not confuse with NodeJS ) and Edges make up a graph.
 - Vertices and Lines make up the 3d visualization side of a graph.
 - Nodes are the abstract idea, vertices are what's visualized
-- Edges are the abstract idea , lines are what's visualized. Lastly, there are a few helper classes like points and lines. Points are essentially vectors and are used for displacement and also for describing a place in relation to the global coordinate system. Line are an array of points that get translated into lines using one of the visualization methods. Points can have different visualizations like boxes, billboarded planes and cylinders etc.
+- Edges are the abstract idea , lines are what's visualized. 
 
-## Semantics of the Package
+Lastly, there are a few helper classes like points and lines. Points are essentially vectors and are used for displacement and also for describing a place in relation to the global coordinate system. Line are an array of points that get translated into lines using one of the visualization methods. Points can have different visualizations like boxes, billboarded planes and cylinders etc.
 
-Existing network visualization libraries like NetworkX dictated the semantics of the graph library and borrowed some of the semantic ideas from three JS. The process is to define a Graph Object made of nodes and edges. Then modify this graph based on some set of properties. Then update the relevant settings. And lastly, to visualize the nodes, either as point clouds, boxes or cylinders, and to draw out the edges (bundled or not) lines.
-Here is an illustrated walkthrough of a simple set-up given a predefined set of “nodes” and “edges”.
 
 ## Documentation
 
@@ -24,11 +22,38 @@ The documentation for the package is available at [documentation](https://www.pl
 npm run document
 ```
 
-This writes TypeDoc output to the `docs/` folder. **API overview:** the library exposes the following namespaces: `Graph`, `GraphMethods` (BFS, Dijkstra, GraphDiameter, SelectSubgraph), `SampleData` (LoadZKC, LoadZKCSimulated), `Constructors` (ConstructGraphNodeEdgesList), `Drawing` (SimulateKamadaKawai, DrawEdgeLines, DrawEdgeBundling, DisplaceEdgeInY, etc.), `Geometry`, `Utilities`, `ThreeWrapper`, `GraphDrawer`, `Models` (Erdos–Renyi), and `Hierarchy` (clusterByDistance, clusterByStrategy for flow-map style clustering).
+This writes TypeDoc output to the `docs/` folder. **API overview:** the library exposes the following namespaces: `Graph`, `GraphMethods` (BFS, Dijkstra, GraphDiameter, SelectSubgraph — note: `Dijkstra` returns hop-count distances via BFS for unweighted graphs), `SampleData` (LoadZKC, LoadZKCSimulated, LoadGraphFromEdgeListText for (sgd)²-style edge lists, LoadGraphFromObjText for OBJ meshes → graph + positions), `Constructors` (ConstructGraphNodeEdgesList), `Drawing` (SimulateKamadaKawai, DrawEdgeLines, DrawEdgeBundling, DisplaceEdgeInY, etc.), `Geometry`, `Utilities`, `ThreeWrapper`, `GraphDrawer`, `Models` (Erdos–Renyi), `Hierarchy` (clusterByDistance, clusterByStrategy for flow-map style clustering), **Simulation** (createKamadaKawai3D, createStressSGD3D — stress layout methods from (sgd)², Imperial), **MatrixHelpers** (matrixVectorMultiply, normalizeVector), and **glMatrix** (re-exported [gl-matrix](https://github.com/toji/gl-matrix) for vector/matrix math in the browser).
+
+### Graph simulations
+
+For time-based layout updates (e.g. in a `requestAnimationFrame` loop), use **createKamadaKawai3D(graph, options)** or **createStressSGD3D(graph, options)** (async). Both return an object with **step(deltaTime)**, **getPositions()** (Float32Array), and **getPositionMap()**. The Stress SGD layout follows the (sgd)² reference implementation from Imperial ([arXiv:1710.04626](https://arxiv.org/abs/1710.04626), [IEEE TVCG](https://www.computer.org/csdl/journal/tg/2019/09/08419285/13rRUyYBlgE), [github.com/jxz12/s_gd2](https://github.com/jxz12/s_gd2)). Use **DrawTHREEGraphVerticesMutable** so you can call **updatePositions(simulation.getPositions())** each frame without recreating geometry. For 3D layout that does not collapse to a line, pass **initialPositions** (e.g. from **LoadGraphFromObjText**) and use **dimensions: 3**. See Examples 9 (Kamada–Kawai live simulation), 11 (custom layout), 12 (Stress SGD live simulation), and 13 (Stress SGD 3D with Stanford Bunny mesh).
+
+### Types (Point, PointLike)
+
+The library exports **Point** (class with `x`, `y`, `z` and `translate()`) and **PointLike** (`{ x: number; y: number; z: number }`) for typing position maps and custom layout results. Use `PointLike` for plain objects; use `new PGL.Point(x, y, z)` when you need the class.
+
+### Drawing API: static vs mutable
+
+- **Static** (one-shot layout): `DrawTHREEGraphVertices`, `DrawTHREEGraphEdgesThin` — create geometry once from the graph.
+- **Mutable** (animation loops): `DrawTHREEGraphVerticesMutable` (and `updatePositions()`), `DrawTHREEGraphEdgesThinMutable` (and `updateEdges()`) — update geometry each frame for time-based simulation.
+
+### LOD and flow-map style
+
+**Hierarchy** (clusterByDistance, clusterByStrategy) and Example 6 provide FlowmapBlue-style level-of-detail: cluster nodes by distance (e.g. KD-tree), merge nearby nodes into super-nodes, and simplify the graph for zoom-dependent detail. See Examples 5 (Hierarchy) and 6 (Flow map).
+
+### Matrix math in the browser
+
+**get_node_ids_order()** returns a stable array of node IDs. **get_adjacency_matrix()** returns `{ matrix: Float32Array (row-major n×n), nodeIds }`. Use **matrixVectorMultiply(A, n, x, out)** and **normalizeVector(x)** for power iteration or diffusion in the browser. The library re-exports **glMatrix** (vec3, mat4, etc.) so you can do full vector/matrix math without adding another dependency. Dense adjacency matrix is for small/medium graphs; for very large graphs use **get_adjacency()** (sparse). See Examples 10 and 11.
 
 ## General setup of the package
 
-Apart from the graph class all the methods are stored in variables. These variables (For example SampleData) would have a function attached to it that returns a value, or in some cases you can pass in values to do stuff (like displacing the graph etc). I mostly did this for the sake of speed to develop - at some point shall be wrapping them up as classes.
+Apart from the graph class all the methods are stored in variables. These variables (For example SampleData) would have a function attached to it that returns a value, or in some cases you can pass in values to do stuff (like displacing the graph etc). I mostly did this for the sake of speed to develop — they will eventually be wrapped up as classes.
+
+## Semantics of the Package
+
+Existing network visualization libraries like NetworkX dictated the semantics of the graph library and borrowed some of the semantic ideas from three JS. The process is to define a Graph Object made of nodes and edges. Then modify this graph based on some set of properties. Then update the relevant settings. And lastly, to visualize the nodes, either as point clouds, boxes or cylinders, and to draw out the edges (bundled or not) lines.
+Here is an illustrated walkthrough of a simple set-up given a predefined set of “nodes” and “edges”.
+
 
 ## An example of rendering a basic graph
 
@@ -94,6 +119,11 @@ async function createVisualization() {
 createVisualization();
 ```
 
+## Testing
+
+- **Unit tests:** `npm run test:unit` (Vitest; tests Utilities, Graph, Simulation, matrix helpers).
+- **Visual regression:** `npm test` (Puppeteer + pixelmatch against a baseline screenshot).
+
 ## Usage / Installation
 
 Install it from the npm repository. Note that this method needs a npm folder to be set up with a build tool like parcel to package the visualizations
@@ -139,6 +169,8 @@ Also remember to check out the contributions file where there are more details o
 
 Remember to follow our Code of Conduct to ensure a welcoming and inclusive environment for everyone
 
-## Acknowledgements
+## References and acknowledgements
+
+**Stress-based layout (createStressSGD3D):** The stress-minimization-by-SGD algorithm and schedule used in PGL are taken from the **(sgd)²** reference implementation ([jxz12/s_gd2](https://github.com/jxz12/s_gd2)) from Imperial College London. The underlying method is from the paper: J. X. Zheng, S. Pawar, D. F. M. Goodman, *Graph Drawing by Stochastic Gradient Descent*, IEEE Transactions on Visualization and Computer Graphics, [arXiv:1710.04626](https://arxiv.org/abs/1710.04626). Example graph data (e.g. football.txt) in the Stress SGD demo are from the same s_gd2 repository.
 
-This library was sponsored by the Geometry Lab under the Laboratory for Design Technologies at the Graduate School of Design, Harvard University. Many thanks to Andrew Witt for guiding this project. This project was developed by : [Indrajeet Haldar](https://www.indrajeethaldar.com/)
+**PGL:** This library was sponsored by the Geometry Lab under the Laboratory for Design Technologies at the Graduate School of Design, Harvard University. Many thanks to Andrew Witt for guiding this project. This project was developed by [Indrajeet Haldar](https://www.indrajeethaldar.com/).

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "plebeiangraphlibrary",
-  "version": "2.0.1",
+  "version": "2.1.2",
   "description": "A NetworkX like package for graphs in javascript",
   "source": "./Src/index.ts",
   "main": "./Build/pgl.js",
-  "types": "./Build/pgl.d.ts",
+  "types": "./Build/index.d.ts",
   "module": "./Build/pgl_module.js",
   "scripts": {
-    "watch": "parcel watch",
-    "build": "parcel build",
+    "watch": "vite build --watch",
+    "build": "rm -rf Build && vite build",
     "build:all": "npm run build && npm run document",
     "test": "node ./test/test_1.js",
-    "document": "npx typedoc --out docs Src",
-    "document:public": "npm run document && cp -R docs/. public/",
-    "examples:public": "cp -R Examples/. public/",
-    "deploy:public": "npm run build && npm run document && cp -R Build/. public/Build/ && cp -R Examples/. public/ && cp -R docs/. public/",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "document": "rm -rf docs && npx typedoc --options typedoc.json",
+    "document:public": "npm run document && rm -rf public && mkdir -p public && cp -R docs/. public/",
+    "examples:public": "rm -rf public && mkdir -p public && cp -R Examples/. public/",
+    "deploy:public": "npm run build && npm run document && rm -rf public && mkdir -p public && mkdir -p public/Build && cp -R Build/. public/Build/ && cp -R Examples/. public/ && cp -R docs/. public/",
     "serve": "python3 -m http.server 3000"
   },
   "repository": {
@@ -41,32 +43,22 @@
     "url": "https://github.com/range-et/PGL/issues"
   },
   "homepage": "https://www.plebeiangraphlibrary.com/",
-  "targets": {
-    "main": {
-      "includeNodeModules": false
-    },
-    "module": {
-      "includeNodeModules": true
-    }
-  },
   "dependencies": {
+    "gl-matrix": "^3.4.3",
     "three": "^0.170.0"
   },
   "devDependencies": {
-    "@parcel/packager-ts": "^2.9.1",
-    "@parcel/transformer-typescript-tsc": "^2.9.1",
-    "@parcel/transformer-typescript-types": "^2.9.1",
     "@types/three": "^0.170.0",
     "express": "^4.18.2",
-    "jest": "^29.7.0",
-    "jest-image-snapshot": "^6.4.0",
     "jsdoc": "^4.0.2",
-    "parcel": "^2.9.1",
     "pixelmatch": "^5.3.0",
     "pngjs": "^7.0.0",
     "puppeteer": "^21.7.0",
     "shelljs": "^0.8.5",
     "typedoc": "^0.24.8",
-    "typescript": "^5.1.3"
+    "typescript": "^5.1.3",
+    "vite": "^6.0.1",
+    "vite-plugin-dts": "^4.3.4",
+    "vitest": "^2.1.6"
   }
 }