@jgphilpott/polytree 0.0.7 → 0.0.9

package/README.md

@@ -1,34 +1,262 @@
 <p align="center">
-    <img width="320" height="320" src="https://raw.githubusercontent.com/jgphilpott/polytree/polytree/icon.png" alt="Polytree Logo">
+    <img width="321" height="321" src="https://raw.githubusercontent.com/jgphilpott/polytree/polytree/icon.png" alt="Polytree Icon">
 </p>
 
-# Intro
+# Polytree
 
-**Polytree** is a modern, modular Constructive Solid Geometry (CSG) library for JavaScript and Node.js, built to utilize the efficiencies of Octree data structure. It is designed for robust 3D modeling, spatial queries, and seamless integration with [three.js](https://github.com/mrdoob/three.js).
+<details open>
 
-## Getting Started
+<summary><h2 style="display:inline">Intro</h2></summary><br>
+
+**Polytree** is a modern, high-performance Constructive Solid Geometry (CSG) library for JavaScript and Node.js, built to utilize the efficiencies of Octree data structure. It is designed for robust 3D modeling, spatial queries, and seamless integration with [three.js](https://github.com/mrdoob/three.js).
+
+### Features
+
+- **Complete CSG Operations**: Union, subtraction, and intersection with full test coverage.
+- **High Performance**: Optimized Octree-based spatial partitioning for fast operations.
+- **Dual API**: Both synchronous and asynchronous operation modes.
+- **Lightweight**: Minimal dependencies with efficient memory usage.
+- **Three.js Integration**: Direct mesh-to-mesh operations with material preservation.
+- **Well Documented**: Comprehensive API documentation and examples.
+- **Robust Testing**: 450+ tests ensuring reliability across edge cases.
+
+</details><br>
+
+<details open>
+
+<summary><h2 style="display:inline">Getting Started</h2></summary>
+
+### Node.js
+
+#### Install
 
 ```bash
 npm install polytree
 ```
 
+#### Import
+
 ```js
 import * as THREE from 'three';
 import { Polytree } from 'polytree';
+```
+
+### Browser
+
+For browser usage, use the ES module-compatible bundle:
 
-// Example usage coming soon!
+```html
+<script type="importmap">
+{
+    "imports": {
+        "three": "./path/to/three.module.min.js",
+        "polytree": "./path/to/polytree.bundle.browser.js"
+    }
+}
+</script>
+
+<script type="module">
+import * as THREE from 'three';
+import Polytree from 'polytree';
+</script>
 ```
 
-## Applications
+The browser bundle (`polytree.bundle.browser.js`) is specifically designed for ES module imports in browsers, while the main bundle (`polytree.bundle.js`) is for Node.js environments.
+
+</details><br>
+
+<details open>
+
+<summary><h2 style="display:inline">Usage</h2></summary><br>
+
+<details open>
 
-- 3D modeling and design for 3D printing.
-- Integration with [Polyslice](https://github.com/jgphilpott/polyslice) FDM slicer.
-- General-purpose spatial querying and mesh manipulation.
+<summary><h3 style="display:inline">Basic CSG Operations</h3></summary><br>
+
+Polytree provides three core CSG operations that work directly with Three.js meshes:
+
+#### Unite (Join)
+
+Join two 3D objects into a single merged object:
+
+```js
+// Create two identical boxes.
+const geometry1 = new THREE.BoxGeometry(2, 2, 2);
+const geometry2 = new THREE.BoxGeometry(2, 2, 2);
+
+const mesh1 = new THREE.Mesh(geometry1, new THREE.MeshBasicMaterial());
+const mesh2 = new THREE.Mesh(geometry2, new THREE.MeshBasicMaterial());
+
+// Offset the position of one box.
+mesh1.position.set(1, 1, 1);
+
+// Join the boxes together.
+const result = await Polytree.unite(mesh1, mesh2);
+
+scene.add(result);
+```
+
+#### Subtract (Remove)
+
+Remove one object's volume from another:
+
+```js
+// Create a box and a sphere.
+const boxGeometry = new THREE.BoxGeometry(2, 2, 2);
+const sphereGeometry = new THREE.SphereGeometry(1.5);
+
+const boxMesh = new THREE.Mesh(boxGeometry, new THREE.MeshBasicMaterial());
+const sphereMesh = new THREE.Mesh(sphereGeometry, new THREE.MeshBasicMaterial());
+
+// Remove the sphere from the box (creates a cavity).
+const result = await Polytree.subtract(boxMesh, sphereMesh);
+
+scene.add(result);
+```
+
+#### Intersect (Overlap)
+
+Keep only the overlapping volume of two objects:
+
+```js
+// Create two overlapping spheres.
+const sphere1 = new THREE.Mesh(
+    new THREE.SphereGeometry(1),
+    new THREE.MeshBasicMaterial()
+);
+
+const sphere2 = new THREE.Mesh(
+    new THREE.SphereGeometry(1),
+    new THREE.MeshBasicMaterial()
+);
+
+// Offset the position of one sphere.
+sphere1.position.set(1, 0, 0);
+
+// Keep only the overlapping volume.
+const result = await Polytree.intersect(sphere1, sphere2);
+
+scene.add(result);
+```
 
-## Contributing
+</details><br>
+
+<details>
+
+<summary><h3 style="display:inline">Asynchronous Operations</h3></summary><br>
+
+For better performance in web applications, use async operations to prevent UI blocking:
+
+```js
+// Async union with Promise.
+const unionPromise = Polytree.unite(mesh1, mesh2);
+unionPromise.then(result => {
+    scene.add(result);
+});
+
+// Async with await.
+const unionResult = await Polytree.unite(mesh1, mesh2);
+scene.add(unionResult);
+```
+
+</details><br>
+
+<details>
+
+<summary><h3 style="display:inline">Advanced: Polytree-to-Polytree Operations</h3></summary><br>
+
+For maximum performance when chaining operations, work directly with Polytree objects:
+
+```js
+// Convert meshes to polytrees once.
+const polytree1 = Polytree.fromMesh(mesh1);
+const polytree2 = Polytree.fromMesh(mesh2);
+const polytree3 = Polytree.fromMesh(mesh3);
+
+// Chain operations efficiently.
+const intermediate = await Polytree.unite(polytree1, polytree2);
+const final = await Polytree.subtract(intermediate, polytree3);
+
+// Convert back to mesh for rendering.
+const finalMesh = Polytree.toMesh(final);
+
+scene.add(finalMesh);
+
+// Clean up resources.
+polytree1.delete();
+polytree2.delete();
+polytree3.delete();
+intermediate.delete();
+final.delete();
+```
+
+</details><br>
+
+<details>
+
+<summary><h3 style="display:inline">Async Array Operations</h3></summary><br>
+
+Process multiple objects efficiently:
+
+```js
+// Unite multiple objects asynchronously.
+const meshArray = [mesh1, mesh2, mesh3, mesh4 ... meshX];
+const polytreeArray = meshArray.map(mesh => Polytree.fromMesh(mesh));
+
+Polytree.async.uniteArray(polytreeArray).then(result => {
+
+    const finalMesh = Polytree.toMesh(result);
+    scene.add(finalMesh);
+
+    // Clean up.
+    polytreeArray.forEach(polytree => {
+        polytree.delete()
+    });
+
+    result.delete();
+
+});
+```
+
+</details>
+
+</details><br>
+
+<details open>
+
+<summary><h2 style="display:inline">Performance</h2></summary><br>
+
+Polytree is designed for high-performance CSG operations:
+
+- **Octree Optimization**: Spatial partitioning reduces computational complexity.
+- **Memory Efficient**: Smart resource management with cleanup methods.
+- **Comprehensive Testing**: 450+ test cases ensuring reliability and performance.
+- **Async Support**: Non-blocking operations for smooth user experiences.
+- **Minimal Dependencies**: Only Three.js as a dependency for lightweight integration.
+
+</details><br>
+
+<details open>
+
+<summary><h2 style="display:inline">Applications</h2></summary><br>
+
+- **3D Modeling**: Professional-grade boolean operations for CAD applications.
+- **Game Development**: Runtime mesh manipulation and procedural geometry.
+- **3D Printing**: Solid geometry preparation and mesh optimization.
+- **Architectural Visualization**: Complex building geometry operations.
+- **Educational Tools**: Interactive 3D geometry learning applications.
+- **Integration with [Polyslice](https://github.com/jgphilpott/polyslice)**: Advanced FDM slicing workflows.
+
+</details><br>
+
+<details open>
+
+<summary><h2 style="display:inline">Contributing</h2></summary><br>
 
 Contributions, issues, and feature requests are welcome! Please [open an issue](https://github.com/jgphilpott/polytree/issues) or submit a [pull request](https://github.com/jgphilpott/polytree/pulls).
 
+</details>
+
 ---
 
 **Polytree** is developed and maintained by [@jgphilpott](https://github.com/jgphilpott).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgphilpott/polytree",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "A Constructive Solid Geometry (CSG) library using Octree data structure.",
   "funding": "https://github.com/sponsors/jgphilpott",
   "main": "polytree.bundle.js",
@@ -10,19 +10,27 @@
     }
   },
   "files": [
-    "polytree.bundle.js",
+    "LICENSE",
     "README.md",
-    "LICENSE"
+    "polytree.bundle.js",
+    "polytree.bundle.min.js",
+    "polytree.bundle.browser.js",
+    "polytree.bundle.browser.min.js"
   ],
   "directories": {
     "example": "examples"
   },
   "scripts": {
     "test": "jest",
-    "pretest": "npm run compile",
+    "pretest": "npm run build",
     "compile": "coffee -cb .",
     "compile:watch": "coffee -cbw . &",
-    "build": "npm run compile && cat app/polytree.js app/triangle.intersection.js > polytree.bundle.js",
+    "build": "npm run compile && npm run build:node && npm run build:browser && npm run minify",
+    "build:node": "./scripts/bundle.sh",
+    "build:browser": "node scripts/browserify.cjs",
+    "minify": "npm run minify:node && npm run minify:browser",
+    "minify:node": "uglifyjs polytree.bundle.js -cmo polytree.bundle.min.js",
+    "minify:browser": "uglifyjs polytree.bundle.browser.js -cmo polytree.bundle.browser.min.js",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build"
   },
@@ -30,14 +38,15 @@
     "type": "git",
     "url": "https://github.com/jgphilpott/polytree"
   },
-  "keywords": ["Polytree","Octree","CSG","BVH"],
+  "keywords": ["Polytree", "Octree", "CSG", "BVH"],
   "author": { "name": "Jacob Philpott", "email": "jacob.philpott@gmx.com" },
   "license": "MIT",
   "bugs": { "url": "https://github.com/jgphilpott/polytree/issues" },
   "homepage": "https://github.com/jgphilpott/polytree#readme",
   "devDependencies": {
     "coffeescript": "^2.7.0",
-    "jest": "^30.1.3"
+    "jest": "^30.1.3",
+    "uglify-js": "^3.19.3"
   },
   "dependencies": {
     "three": "^0.180.0"