@jbroll/jscad-modeling 2.12.7

package/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `@jscad/modeling`, a Constructive Solid Geometry (CSG) library for 2D and 3D geometric modeling. It implements boolean operations (union, intersect, subtract) using BSP trees on meshes. Part of the JSCAD monorepo at `/home/john/pkg/OpenJSCAD.org`.
+
+## Commands
+
+```bash
+# Run all tests (AVA framework)
+npm test
+
+# Run a single test file
+npx ava src/maths/vec2/add.test.js --verbose
+
+# Run tests matching a pattern
+npx ava 'src/primitives/*.test.js' --verbose
+
+# Generate coverage report
+npm run coverage
+
+# Build browser bundle
+npm run build
+
+# TypeScript definition tests
+npm run test:tsd
+
+# From monorepo root - run all package tests
+npm test
+
+# From monorepo root - lint all packages (StandardX)
+npm run lint
+```
+
+## Architecture
+
+### Module Organization
+- **Namespace-based**: Each directory is a namespace with a barrel `index.js`
+- **One function per file**: Each function lives in its own file with matching `.test.js` and `.d.ts`
+- **CommonJS exports**: `module.exports = functionName`
+
+### Core Namespaces
+- `geometries/` - Data types: geom2 (2D polygons), geom3 (3D meshes), path2, poly2, poly3
+- `maths/` - Vector (vec2/3/4), matrix (mat4), plane, line operations
+- `primitives/` - Basic shapes: cube, sphere, cylinder, torus, etc.
+- `operations/booleans/` - CSG operations: union, intersect, subtract, scission
+- `operations/transforms/` - translate, rotate, scale, mirror, align, center
+- `operations/extrusions/` - 2D to 3D: extrudeLinear, extrudeRotate, extrudeHelical
+- `operations/hulls/` - Convex hull operations
+- `measurements/` - Area, volume, bounding box calculations
+
+### Data Structures
+```javascript
+// geom3 - 3D geometry
+{ polygons: [poly3, ...], transforms: mat4 }
+
+// geom2 - 2D geometry
+{ sides: [[start, end], ...], transforms: mat4 }
+
+// poly3 - 3D polygon
+{ vertices: [[x,y,z], ...] }
+
+// Vectors are plain arrays: [x, y] or [x, y, z]
+```
+
+### Function Patterns
+
+**In-place math operations** (vec/mat): First param receives result
+```javascript
+const add = (out, a, b) => {
+  out[0] = a[0] + b[0]
+  out[1] = a[1] + b[1]
+  return out
+}
+```
+
+**Options pattern with defaults**:
+```javascript
+const cube = (options) => {
+  const defaults = { center: [0, 0, 0], size: 2 }
+  let { center, size } = Object.assign({}, defaults, options)
+  if (!isGTE(size, 0)) throw new Error('size must be positive')
+  return cuboid({ center, size: [size, size, size] })
+}
+```
+
+**Validation** via `commonChecks.js`: `isGTE`, `isGT`, `isNumberArray`
+
+## Code Style
+
+ESLint rules enforced (from root package.json):
+- `func-style: expression` - Use const arrow functions, not function declarations
+- `prefer-arrow-callback` - Arrow functions for callbacks
+- `no-var` - Use const/let only
+- `arrow-parens: always` - Always use parentheses: `(x) => x`
+
+## Test Conventions
+
+Tests use AVA with helpers from `test/helpers/`:
+```javascript
+const test = require('ava')
+const { compareVectors } = require('../../../test/helpers/index')
+
+test('vec2: add() should return correct values', (t) => {
+  const obs = fromValues(0, 0)
+  const ret = add(obs, [1, 2], [3, 4])
+  t.true(compareVectors(ret, [4, 6]))
+})
+```
+
+Helpers: `compareVectors`, `comparePoints`, `comparePolygons`, `comparePolygonLists`, `nearlyEqual`
+
+## JSDoc Requirements
+
+Every exported function needs:
+```javascript
+/**
+ * Brief description of what it does.
+ *
+ * @param {type} name - description
+ * @returns {type} description
+ * @alias module:modeling/namespace.functionName
+ * @example
+ * let result = functionName(args)
+ */
+```
+
+## Adding a New Function
+
+1. Create `src/namespace/functionName.js` with JSDoc and implementation
+2. Create `src/namespace/functionName.test.js` with AVA tests
+3. Create `src/namespace/functionName.d.ts` for TypeScript
+4. Export from `src/namespace/index.js` and `src/namespace/index.d.ts`

package/README.md

@@ -0,0 +1,99 @@
+# @jscad/modeling
+
+> Solid Modelling Library for 2D and 3D Geometries
+
+[![NPM version](https://badge.fury.io/js/%40jscad%2Fmodeling.svg)](https://www.npmjs.com/package/@jscad/modeling)
+[![NPM downloads](https://img.shields.io/npm/dw/@jscad/modeling)](https://www.npmjs.com/package/@jscad/modeling)
+[![Build Status](https://travis-ci.org/jscad/OpenJSCAD.org.svg?branch=master)](https://travis-ci.org/jscad/OpenJSCAD.org)
+[![Stability](https://img.shields.io/badge/stability-stable-success)](https://github.com/emersion/stability-badges#stable)
+[![License](https://img.shields.io/github/license/jscad/OpenJSCAD.org)](https://github.com/jscad/OpenJSCAD.org/blob/master/LICENSE)
+
+[![User Group](https://img.shields.io/badge/maintained%20by-user%20group-blue)](https://openjscad.nodebb.com/)
+[![Lerna](https://img.shields.io/badge/maintained%20with-lerna-blue)](https://lerna.js.org/)
+[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-blue)](https://standardjs.com)
+
+[![Backers](https://img.shields.io/opencollective/backers/openjscad)](https://opencollective.com/openjscad)
+[![Sponsors](https://img.shields.io/opencollective/sponsors/openjscad)](https://opencollective.com/openjscad)
+
+<a href="https://opencollective.com/openjscad"><img src="https://opencollective.com/openjscad/donate/button.png?color=blue" alt="Open Collective"></a>
+
+## Overview
+
+This library contains boolean operations based on Constructive Solid Geometry (CSG). CSG is a modelling technique that uses boolean operations like union and intersection to combine 3D solids. This library implements CSG operations on meshes elegantly and concisely using BSP trees, and is meant to serve as an easily understandable implementation of the algorithm.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [Community](#community)
+- [Copyrights](#copyrights)
+- [License](#license)
+
+## Installation
+
+This package is published and available for download via [NPM](https://www.npmjs.com/org/jscad)
+```
+npm install @jscad/modeling
+```
+
+In addition this package is hosted at [UNPKG](https://unpkg.com/), and can be imported directly into webpages.
+
+```
+<script language="javascript" src="https://unpkg.com/@jscad/modeling" id="MODELING"></script>
+```
+
+## Usage
+
+As a Node module:
+
+```
+const {color, connectors, geometry, math, primitives, text, utils} = require('@jscad/modeling')
+const {booleans, expansions, extrusions, hulls, measurements, transforms} = require('@jscad/modeling')
+```
+
+## Documentation
+
+- [API Reference](https://openjscad.xyz/docs/).
+- [JSCAD User Guide](https://openjscad.xyz/guide.html)
+
+## Contributing
+
+The various JSCAD packages and all source code are part of the JSCAD Organization, and maintained by a group of volunteers.
+We welcome and encourage anyone to pitch in but please take a moment to read the following guidelines.
+
+* If you want to submit a bug report please make sure to follow the [Reporting Issues](https://github.com/jscad/OpenJSCAD.org/wiki/Reporting-Issues) guide. Bug reports are accepted as [Issues](https://github.com/jscad/OpenJSCAD.org/issues/) via GitHub.
+
+* If you want to submit a change or a patch, please read the [Contributing Guide](../../CONTRIBUTING.md). New contributions are accepted as [Pull Requests](https://github.com/jscad/OpenJSCAD.org/pulls/) via GitHub.
+
+* We only accept bug reports and pull requests on **GitHub**.
+
+* If you have a question about how to use JSCAD, then please start a conversation at the [JSCAD User Group](https://openjscad.xyz/forum.html). You might find the answer in the [JSCAD User Guide](https://openjscad.xyz/guide.html).
+
+* If you have a change or new feature in mind, please start a conversation with the [Core Developers](https://openjscad.xyz/forum.html) and start contributing changes.
+
+Small Note: If editing this README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+
+## Community
+
+Discuss designs or issues
+* [JSCAD User Group](https://openjscad.xyz/forum.html)
+
+Or chat with other users
+* [Discord Community](https://openjscad.xyz/discord.html)
+
+## Copyrights
+
+Some copyrights apply from integration of original libraries.
+
+CSG Library : Copyright (c) 2012 Joost Nieuwenhuijse, under the MIT license. Copyright (c) 2011 Evan Wallace, under MIT license.
+
+Portions of glMatrix Library: Copyright (c) 2015-2020, Brandon Jones, Colin MacKenzie IV, under MIT license.
+
+Quickhull Library: Copyright (c) 2015 Mauricio Poppe, under the MIT license.
+
+## License
+
+[The MIT License (MIT)](../../LICENSE)
+(unless specified otherwise)

package/benchmarks/booleans.bench.js

@@ -0,0 +1,100 @@
+/**
+ * Boolean operation benchmarks
+ *
+ * Tests union, subtract, intersect at varying complexity levels.
+ * These benchmarks target issue #1421 (splitPolygonByPlane splice).
+ */
+
+const { primitives, booleans, transforms } = require('../src')
+const { cube, sphere, cylinder } = primitives
+const { union, subtract, intersect } = booleans
+const { translate } = transforms
+
+const name = 'Booleans'
+
+const benchmarks = [
+  // Simple operations - baseline
+  {
+    name: 'union-sphere-8-segments',
+    fn: () => union(cube({ size: 2 }), sphere({ radius: 1.2, segments: 8 }))
+  },
+  {
+    name: 'union-sphere-16-segments',
+    fn: () => union(cube({ size: 2 }), sphere({ radius: 1.2, segments: 16 }))
+  },
+  {
+    name: 'union-sphere-32-segments',
+    fn: () => union(cube({ size: 2 }), sphere({ radius: 1.2, segments: 32 }))
+  },
+  // Higher complexity - should reveal O(n²) behavior
+  {
+    name: 'union-sphere-64-segments',
+    fn: () => union(cube({ size: 2 }), sphere({ radius: 1.2, segments: 64 }))
+  },
+
+  // Subtract operations
+  {
+    name: 'subtract-sphere-16-segments',
+    fn: () => subtract(cube({ size: 2 }), sphere({ radius: 1.2, segments: 16 }))
+  },
+  {
+    name: 'subtract-sphere-32-segments',
+    fn: () => subtract(cube({ size: 2 }), sphere({ radius: 1.2, segments: 32 }))
+  },
+  {
+    name: 'subtract-sphere-64-segments',
+    fn: () => subtract(cube({ size: 2 }), sphere({ radius: 1.2, segments: 64 }))
+  },
+
+  // Intersect operations
+  {
+    name: 'intersect-sphere-32-segments',
+    fn: () => intersect(cube({ size: 2 }), sphere({ radius: 1.2, segments: 32 }))
+  },
+
+  // Chain of unions (tests repeated boolean operations)
+  {
+    name: 'union-chain-5-cubes',
+    fn: () => {
+      let result = cube({ size: 1 })
+      for (let i = 1; i < 5; i++) {
+        result = union(result, translate([i * 0.8, 0, 0], cube({ size: 1 })))
+      }
+      return result
+    }
+  },
+  {
+    name: 'union-chain-10-cubes',
+    fn: () => {
+      let result = cube({ size: 1 })
+      for (let i = 1; i < 10; i++) {
+        result = union(result, translate([i * 0.8, 0, 0], cube({ size: 1 })))
+      }
+      return result
+    }
+  },
+
+  // Union of array (tests flatten utility - issue #1422)
+  {
+    name: 'union-array-10-cubes',
+    fn: () => {
+      const cubes = []
+      for (let i = 0; i < 10; i++) {
+        cubes.push(translate([i * 1.5, 0, 0], cube({ size: 1 })))
+      }
+      return union(cubes)
+    }
+  },
+  {
+    name: 'union-array-25-cubes',
+    fn: () => {
+      const cubes = []
+      for (let i = 0; i < 25; i++) {
+        cubes.push(translate([i * 1.5, 0, 0], cube({ size: 1 })))
+      }
+      return union(cubes)
+    }
+  }
+]
+
+module.exports = { name, benchmarks }

package/benchmarks/extrusions.bench.js

@@ -0,0 +1,124 @@
+/**
+ * Extrusion operation benchmarks
+ *
+ * Tests extrudeLinear, extrudeRotate at varying slice counts.
+ * These benchmarks target:
+ * - Issue #1419 (extrudeFromSlices concat in loop)
+ * - Issue #1424 (extrudeWalls vec3.create allocations)
+ */
+
+const { primitives, extrusions } = require('../src')
+const { circle, rectangle, star } = primitives
+const { extrudeLinear, extrudeRotate, extrudeHelical } = extrusions
+
+const name = 'Extrusions'
+
+const benchmarks = [
+  // ExtrudeLinear with varying heights (affects slice count internally)
+  {
+    name: 'extrudeLinear-circle-16-segments',
+    fn: () => extrudeLinear({ height: 10 }, circle({ radius: 5, segments: 16 }))
+  },
+  {
+    name: 'extrudeLinear-circle-32-segments',
+    fn: () => extrudeLinear({ height: 10 }, circle({ radius: 5, segments: 32 }))
+  },
+  {
+    name: 'extrudeLinear-circle-64-segments',
+    fn: () => extrudeLinear({ height: 10 }, circle({ radius: 5, segments: 64 }))
+  },
+
+  // ExtrudeLinear with twist (creates multiple slices - tests #1419)
+  {
+    name: 'extrudeLinear-twist-10-slices',
+    fn: () => extrudeLinear(
+      { height: 10, twistAngle: Math.PI / 4, twistSteps: 10 },
+      rectangle({ size: [4, 4] })
+    )
+  },
+  {
+    name: 'extrudeLinear-twist-50-slices',
+    fn: () => extrudeLinear(
+      { height: 10, twistAngle: Math.PI / 4, twistSteps: 50 },
+      rectangle({ size: [4, 4] })
+    )
+  },
+  {
+    name: 'extrudeLinear-twist-100-slices',
+    fn: () => extrudeLinear(
+      { height: 10, twistAngle: Math.PI / 4, twistSteps: 100 },
+      rectangle({ size: [4, 4] })
+    )
+  },
+  {
+    name: 'extrudeLinear-twist-200-slices',
+    fn: () => extrudeLinear(
+      { height: 10, twistAngle: Math.PI / 4, twistSteps: 200 },
+      rectangle({ size: [4, 4] })
+    )
+  },
+
+  // ExtrudeRotate (creates many slices)
+  {
+    name: 'extrudeRotate-16-segments',
+    fn: () => extrudeRotate(
+      { segments: 16 },
+      rectangle({ size: [1, 2], center: [3, 0] })
+    )
+  },
+  {
+    name: 'extrudeRotate-32-segments',
+    fn: () => extrudeRotate(
+      { segments: 32 },
+      rectangle({ size: [1, 2], center: [3, 0] })
+    )
+  },
+  {
+    name: 'extrudeRotate-64-segments',
+    fn: () => extrudeRotate(
+      { segments: 64 },
+      rectangle({ size: [1, 2], center: [3, 0] })
+    )
+  },
+  {
+    name: 'extrudeRotate-128-segments',
+    fn: () => extrudeRotate(
+      { segments: 128 },
+      rectangle({ size: [1, 2], center: [3, 0] })
+    )
+  },
+
+  // ExtrudeHelical (complex extrusion)
+  {
+    name: 'extrudeHelical-32-segments',
+    fn: () => extrudeHelical(
+      { height: 10, angle: Math.PI * 4, segments: 32 },
+      circle({ radius: 0.5, segments: 8, center: [2, 0] })
+    )
+  },
+  {
+    name: 'extrudeHelical-64-segments',
+    fn: () => extrudeHelical(
+      { height: 10, angle: Math.PI * 4, segments: 64 },
+      circle({ radius: 0.5, segments: 8, center: [2, 0] })
+    )
+  },
+
+  // Complex 2D shape extrusion (star has many vertices)
+  {
+    name: 'extrudeLinear-star-10-points',
+    fn: () => extrudeLinear(
+      { height: 5 },
+      star({ vertices: 10, innerRadius: 2, outerRadius: 4 })
+    )
+  },
+  {
+    name: 'extrudeLinear-star-20-points',
+    fn: () => extrudeLinear(
+      { height: 5 },
+      star({ vertices: 20, innerRadius: 2, outerRadius: 4 })
+    )
+  }
+]
+
+module.exports = { name, benchmarks }

package/benchmarks/measurements.bench.js

@@ -0,0 +1,123 @@
+/**
+ * Measurement operation benchmarks
+ *
+ * Tests measureBoundingBox, measureVolume, etc at varying complexity.
+ * These benchmarks target issue #1427 (toPoints in measureBoundingBox).
+ */
+
+const { primitives, booleans, transforms, measurements } = require('../src')
+const { sphere, cube, cylinder } = primitives
+const { union } = booleans
+const { translate } = transforms
+const { measureBoundingBox, measureVolume, measureArea, measureCenter } = measurements
+
+const name = 'Measurements'
+
+// Pre-create geometries of varying complexity for benchmarking
+const createComplexGeometry = (polygonTarget) => {
+  // sphere segments² ≈ polygon count
+  // segments=16 → ~512 polygons
+  // segments=32 → ~2048 polygons
+  // segments=64 → ~8192 polygons
+  const segments = Math.ceil(Math.sqrt(polygonTarget))
+  return sphere({ radius: 5, segments })
+}
+
+// Create a mesh with many polygons by unioning multiple spheres
+const createMultiPartGeometry = (parts) => {
+  const shapes = []
+  for (let i = 0; i < parts; i++) {
+    shapes.push(translate([i * 3, 0, 0], sphere({ radius: 1, segments: 16 })))
+  }
+  return union(shapes)
+}
+
+const benchmarks = [
+  // measureBoundingBox at varying polygon counts
+  {
+    name: 'boundingBox-sphere-512-polys',
+    fn: () => {
+      const geom = createComplexGeometry(512)
+      return measureBoundingBox(geom)
+    }
+  },
+  {
+    name: 'boundingBox-sphere-2048-polys',
+    fn: () => {
+      const geom = createComplexGeometry(2048)
+      return measureBoundingBox(geom)
+    }
+  },
+  {
+    name: 'boundingBox-sphere-8192-polys',
+    fn: () => {
+      const geom = createComplexGeometry(8192)
+      return measureBoundingBox(geom)
+    }
+  },
+
+  // measureVolume
+  {
+    name: 'volume-sphere-512-polys',
+    fn: () => {
+      const geom = createComplexGeometry(512)
+      return measureVolume(geom)
+    }
+  },
+  {
+    name: 'volume-sphere-2048-polys',
+    fn: () => {
+      const geom = createComplexGeometry(2048)
+      return measureVolume(geom)
+    }
+  },
+
+  // measureArea
+  {
+    name: 'area-sphere-512-polys',
+    fn: () => {
+      const geom = createComplexGeometry(512)
+      return measureArea(geom)
+    }
+  },
+  {
+    name: 'area-sphere-2048-polys',
+    fn: () => {
+      const geom = createComplexGeometry(2048)
+      return measureArea(geom)
+    }
+  },
+
+  // measureCenter
+  {
+    name: 'center-sphere-2048-polys',
+    fn: () => {
+      const geom = createComplexGeometry(2048)
+      return measureCenter(geom)
+    }
+  },
+
+  // Measure multiple geometries (tests flatten - issue #1422)
+  {
+    name: 'boundingBox-10-cubes',
+    fn: () => {
+      const cubes = []
+      for (let i = 0; i < 10; i++) {
+        cubes.push(translate([i * 2, 0, 0], cube({ size: 1 })))
+      }
+      return measureBoundingBox(cubes)
+    }
+  },
+  {
+    name: 'boundingBox-50-cubes',
+    fn: () => {
+      const cubes = []
+      for (let i = 0; i < 50; i++) {
+        cubes.push(translate([i * 2, 0, 0], cube({ size: 1 })))
+      }
+      return measureBoundingBox(cubes)
+    }
+  }
+]
+
+module.exports = { name, benchmarks }