chore(all): syncing changes from V2 to V3

jscad · Jan 3, 2025 · 9e5123d · 9e5123d
2 parents a6565a3 + dbb7d33
commit 9e5123d
Show file tree

Hide file tree

Showing 44 changed files with 1,850 additions and 1,510 deletions.
diff --git a/.github/workflows/node.yml b/.github/workflows/node.yml
@@ -4,7 +4,6 @@ on:
   push:
   pull_request:
     branches:
-      - master
       - V3
 
 jobs:
@@ -16,7 +15,7 @@ jobs:
     name: Node ${{ matrix.node }} test
     steps:
       - uses: actions/checkout@v2
-      - uses: pnpm/action-setup@v2.2.2
+      - uses: pnpm/action-setup@v4
         with:
           version: 7
       - name: Setup Node ${{ matrix.node }}

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,7 @@
 # Change Log
 
+## CHANGE LOGS ARE NOW FOUND IN EACH PACKAGE
+
 All notable changes to this project will be documented in this file.
 
 ## 0.6.0 (2017-05-xx)

diff --git a/LICENSE b/LICENSE
@@ -1,7 +1,7 @@
 
 The MIT License (MIT)
 
-Copyright (c) 2017-2021 JSCAD Organization
+Copyright (c) 2017-2025 JSCAD Organization
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/jsdoc/assets/README.md b/jsdoc/assets/README.md
@@ -16,10 +16,10 @@ Check out the Tutorials section for tips on getting started, and best practises.
 
 There are different 'flavors' of JSCAD that you can use based on your needs
 - For browser-based modelling (no install) simply go to [https://openjscad.xyz/](https://openjscad.xyz/)
+- For the command line interface, install as part of a project using NPM. See [JSCAD Command Line Interface](https://www.npmjs.com/package/@jscad/cli) at NPM
 - For other usage options, the first step is to visit [JSCAD on GitHub](https://github.com/jscad/OpenJSCAD.org/)
-  * Command line interface : can be found in ./packages/cli
-  * Desktop app : pre-pre-alpha work in progress can be found  at ./packages/desktop
-  * For custom mix and match of packages, all the packages are available [on NPM](https://www.npmjs.com/search?q=%40jscad) under the '@jscad' name
+  * Review the available [list of packages](https://github.com/jscad/OpenJSCAD.org/tree/master/packages) at GitHub
+  * Packages are also available [on NPM](https://www.npmjs.com/search?q=%40jscad) under the '@jscad' name
 
 ## Documentation
 
@@ -29,9 +29,14 @@ There are different 'flavors' of JSCAD that you can use based on your needs
 
 ## 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)
 
+HUGE THANKS and SHOUTOUT to [nodeBB](https://nodebb.org/) for hosting our (awesome) forum for free ! Thanks a lot !
+
 ## Contributing
 
 The various JSCAD packages and all source code are part of the JSCAD Organization, and maintained by a group of volunteers.
@@ -47,9 +52,20 @@ We welcome and encourage anyone to pitch in but please take a moment to read the
 
 * 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.
 
-A BIG THANKS to all the people who have already contributed to the JSCAD project!
+A BIG THANKS to all the people who have already contributed changes to the JSCAD project!
 <a href="https://github.com/jscad/OpenJSCAD.org/graphs/contributors"><img src="https://opencollective.com/openjscad/contributors.svg?width=890" alt="Open Collective"></a>
 
+## Backers
+Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/openjscad#backer)]
+
+<a href="https://opencollective.com/openjscad#backers" target="_blank"><img src="https://opencollective.com/openjscad/backers.svg?width=890"></a>
+
+## Sponsors
+This project has some awesome sponsors! [[Become a sponsor](https://opencollective.com/openjscad#sponsor)]
+Your logo will show up here with a link to your website.
+
+<a href="https://opencollective.com/openjscad#backers" target="_blank"><object type="image/svg+xml" data="https://opencollective.com/openjscad/tiers/sponsors.svg?avatarHeight=36&width=600"></object></a>
+
 ## License
 
 [The MIT License (MIT)](https://github.com/jscad/OpenJSCAD.org/blob/master/LICENSE)

diff --git a/package.json b/package.json
@@ -13,7 +13,6 @@
     "changed": "lerna changed",
     "graph": "lerna list --graph",
     "list": "lerna ls",
-    "web": "cd ./packages/web && pnpm run dev",
     "preversion": "pnpm run test && pnpm run test:tsd && pnpm run docs",
     "publish": "lerna publish premajor --include-merged-tags --no-private --no-push --conventional-prerelease --dist-tag alpha --pre-dist-tag alpha",
     "publish-dryrun": "lerna version premajor --include-merged-tags --no-push --conventional-prerelease"
@@ -35,15 +34,15 @@
   "license": "MIT",
   "devDependencies": {
     "@jscad/sample-files": "github:jscad/sample-files#master",
-    "@lerna-lite/changed": "^2.5.1",
-    "@lerna-lite/cli": "^2.5.1",
-    "@lerna-lite/publish": "^2.5.1",
-    "@lerna-lite/run": "^2.5.1",
-    "@lerna-lite/version": "^2.5.1",
-    "ava": "4.3.3",
-    "docdash": "2.0.1",
-    "jsdoc": "4.0.2",
-    "c8": "8.0.0",
+    "@lerna-lite/changed": "^2.7.2",
+    "@lerna-lite/cli": "^2.7.2",
+    "@lerna-lite/publish": "^2.7.2",
+    "@lerna-lite/run": "^2.7.2",
+    "@lerna-lite/version": "^2.7.2",
+    "ava": "^4.3.3",
+    "c8": "^8.0.0",
+    "docdash": "^2.0.1",
+    "jsdoc": "^4.0.2",
     "standardx": "7.0.0",
     "tsd": "^0.28.1"
   },

diff --git a/packages/core/src/io/registerExtensions.js b/packages/core/src/io/registerExtensions.js
@@ -17,7 +17,13 @@ const registerDeserializer = (extension, fs, _require) => {
   const deserializer = deserializers[extension]
   const fileExtension = '.' + extension
   _require.extensions[fileExtension] = (module, filename) => {
-    const content = fs.readFileSync(filename, 'utf8')
+    const fileReadResult = fs.readFileSync(filename) // read into buffer
+    // NOTE: https://nodejs.org/api/buffer.html#bufbuffer: Buffer.buffer is not
+    // guaranteed to correspond exactly to the original Buffer.
+    const content = fileReadResult.buffer
+      ? fileReadResult.buffer.slice(fileReadResult.byteOffset, fileReadResult.byteOffset + fileReadResult.length)
+      : fileReadResult;
+
     const parsed = deserializer({ filename, output: 'geometry' }, content)
     module.exports = parsed
   }

diff --git a/packages/io/dxf-deserializer/package.json b/packages/io/dxf-deserializer/package.json
@@ -33,7 +33,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@jscad/modeling": "workspace:3.0.0-alpha.0"
+    "@jscad/modeling": "workspace:3.0.0-alpha.0",
+    "@jscad/io-utils": "workspace:3.0.0-alpha.0"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.2.1",

diff --git a/packages/io/dxf-deserializer/src/index.js b/packages/io/dxf-deserializer/src/index.js
@@ -1,3 +1,5 @@
+import { ensureString } from '@jscad/io-utils'
+
 import { BYLAYER, getTLA } from './autocad.js'
 import { colorIndex } from './colorindex2017.js'
 import { DxfReader } from './DxfReader.js'
@@ -593,6 +595,8 @@ const deserialize = (options, src) => {
     }
   }
   options = Object.assign({}, defaults, options)
+
+  src = ensureString(src);
   return options.output === 'script' ? translate(src, options) : instantiate(src, options)
 }
 

diff --git a/packages/io/io-utils/src/ensureString.js b/packages/io/io-utils/src/ensureString.js
@@ -0,0 +1,12 @@
+/**
+ * Ensure the give buffer is a string, or decode the buffer contents into a string.
+ * @return {string} contents of the given buffer as a string
+ * @alias module:io/utils.ensureString
+ */
+export const ensureString = (stringOrArrayBuffer, defaultBinaryEncoding = 'utf-8') => {
+  if (typeof (stringOrArrayBuffer) === 'string') {
+    return stringOrArrayBuffer;
+  }
+
+  return new TextDecoder(defaultBinaryEncoding).decode(new Uint8Array(stringOrArrayBuffer));
+}
diff --git a/packages/io/io-utils/src/index.js b/packages/io/io-utils/src/index.js
@@ -9,3 +9,4 @@ export { makeBlob } from './makeBlob.js'
 export { BinaryReader } from './BinaryReader.js'
 export { Blob } from './Blob.js'
 export { stringify } from './stringify.js'
+export { ensureString } from './ensureString.js'
diff --git a/packages/io/json-deserializer/package.json b/packages/io/json-deserializer/package.json
@@ -33,7 +33,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@jscad/array-utils": "workspace:3.0.0-alpha.0"
+    "@jscad/array-utils": "workspace:3.0.0-alpha.0",
+    "@jscad/io-utils": "workspace:3.0.0-alpha.0"
   },
   "devDependencies": {
     "@jscad/modeling": "workspace:3.0.0-alpha.0",

diff --git a/packages/io/json-deserializer/src/index.js b/packages/io/json-deserializer/src/index.js
@@ -14,6 +14,7 @@
  */
 
 import { flatten, toArray } from '@jscad/array-utils'
+import { ensureString } from '@jscad/io-utils'
 
 const version = '[VI]{version}[/VI]' // version is injected by rollup
 
@@ -38,6 +39,7 @@ const deserialize = (options, input) => {
   options = Object.assign({}, defaults, options)
 
   // convert the JSON notation into anonymous object(s)
+  input = ensureString(input);
   let objects = JSON.parse(input)
 
   // cleanup the objects

diff --git a/packages/io/obj-deserializer/README.md b/packages/io/obj-deserializer/README.md
@@ -54,7 +54,7 @@ npm install @jscad/obj-deserializer
 const objDeserializer = require('@jscad/obj-deserializer')
 
 const rawData = fs.readFileSync('PATH/TO/file.obj')
-const geometries = objDeserializer.deserialize(rawData, 'file.obj', {output: 'geometry'})
+const geometries = objDeserializer.deserialize({output: 'geometry'}, rawData.toString())
 
 ```
 

diff --git a/packages/io/obj-deserializer/package.json b/packages/io/obj-deserializer/package.json
@@ -37,7 +37,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@jscad/modeling": "workspace:3.0.0-alpha.0"
+    "@jscad/modeling": "workspace:3.0.0-alpha.0",
+    "@jscad/io-utils": "workspace:3.0.0-alpha.0"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.2.1",

diff --git a/packages/io/obj-deserializer/src/index.js b/packages/io/obj-deserializer/src/index.js
@@ -1,3 +1,4 @@
+import { ensureString } from '@jscad/io-utils'
 import { colorNameToRgb, polyhedron } from '@jscad/modeling'
 
 const version = '[VI]{version}[/VI]' // version is injected by rollup
@@ -34,6 +35,7 @@ const deserialize = (options, input) => {
 
   options && options.statusCallback && options.statusCallback({ progress: 0 })
 
+  input = ensureString(input)
   const { positions, groups } = getGroups(input, options)
 
   const result = output === 'script' ? stringify(positions, groups, options) : objectify(positions, groups, options)

diff --git a/packages/io/svg-deserializer/package.json b/packages/io/svg-deserializer/package.json
@@ -38,6 +38,7 @@
   "license": "MIT",
   "dependencies": {
     "@jscad/array-utils": "workspace:3.0.0-alpha.0",
+    "@jscad/io-utils": "workspace:3.0.0-alpha.0",
     "@jscad/modeling": "workspace:3.0.0-alpha.0",
     "saxes": "6.0.0"
   },

diff --git a/packages/io/svg-deserializer/src/index.js b/packages/io/svg-deserializer/src/index.js
@@ -2,6 +2,7 @@ import saxes from 'saxes'
 
 import { colorize, mirrorX, mirrorY, rotateZ, translate, scale } from '@jscad/modeling'
 import { toArray } from '@jscad/array-utils'
+import { ensureString } from '@jscad/io-utils'
 
 import { pxPmm } from './constants.js'
 import { cagLengthX, cagLengthY, svgColorForTarget } from './helpers.js'
@@ -47,6 +48,8 @@ const deserialize = (options, input) => {
     version
   }
   options = Object.assign({}, defaults, options)
+
+  input = ensureString(input)
   return options.output === 'script' ? translateScript(input, options) : instantiate(input, options)
 }
 

diff --git a/packages/io/x3d-deserializer/package.json b/packages/io/x3d-deserializer/package.json
@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "@jscad/array-utils": "workspace:3.0.0-alpha.0",
+    "@jscad/io-utils": "workspace:3.0.0-alpha.0",
     "@jscad/modeling": "workspace:3.0.0-alpha.0",
     "saxes": "^6.0.0"
   },

diff --git a/packages/io/x3d-deserializer/src/index.js b/packages/io/x3d-deserializer/src/index.js
@@ -12,6 +12,7 @@
  * @example
  * const { deserializer, extension } = require('@jscad/x3d-deserializer')
  */
+import { ensureString } from '@jscad/io-utils'
 
 import { translate } from './translate.js'
 import { instantiate } from './instantiate.js'
@@ -41,6 +42,7 @@ const deserialize = (options, input) => {
   }
   options = Object.assign({}, defaults, options)
 
+  input = ensureString(input)
   return options.output === 'script' ? translate(options, input) : instantiate(options, input)
 }
 

diff --git a/packages/modeling/src/geometries/index.js b/packages/modeling/src/geometries/index.js
@@ -5,14 +5,13 @@
  * @see {@link geom2} - 2D geometry consisting of 2D outlines
  * @see {@link geom3} - 3D geometry consisting of polygons
  * @see {@link path2} - 2D geometry consisting of ordered points
- * @see {@link poly2} - 2D polygon consisting of ordered vertices
+ * @see {@link poly2} - 2D polygon consisting of ordered points
  * @see {@link poly3} - 3D polygon consisting of ordered vertices
- * @see {@link slice} - 3D geometry consisting of 3D outlines
+ * @see {@link slice} - 3D geometry consisting of 3D contours
  *
  * @module modeling/geometries
  * @example
- * import { geometries } from '@jscad/modeling'
- * const { geom2, geom3, path2, poly2, poly3 } = geometries
+ * import { geom2, geom3, path2, poly2, poly3, slice } from '@jscad/modeling'
  */
 export * as geom2 from './geom2/index.js'
 export * as geom3 from './geom3/index.js'

diff --git a/packages/modeling/src/geometries/poly3/type.d.ts b/packages/modeling/src/geometries/poly3/type.d.ts
@@ -6,6 +6,6 @@ export interface Poly3 {
   vertices: Array<Vec3>
   color?: Color
 
-  // used internally for caching:
+  // used internally for calculations
   plane?: Plane
 }
diff --git a/packages/modeling/src/operations/booleans/intersect.js b/packages/modeling/src/operations/booleans/intersect.js
@@ -17,7 +17,7 @@ import { intersectGeom3 } from './intersectGeom3.js'
  * @alias module:modeling/booleans.intersect
  *
  * @example
- * let myshape = intersect(cube({size: [5,5,5]}), cube({size: [5,5,5], center: [5,5,5]}))
+ * let myshape = intersect(cube({size: 5}), cube({size: 5, center: [3,3,3]}))
  *
  * @example
  * +-------+

diff --git a/packages/modeling/src/operations/booleans/scission.d.ts b/packages/modeling/src/operations/booleans/scission.d.ts
@@ -1,6 +1,5 @@
-import type { Geom2 } from '../../geometries/geom2/type.d.ts'
 import type { Geom3 } from '../../geometries/geom3/type.d.ts'
 import type { RecursiveArray } from '../../utils/recursiveArray.d.ts'
 
-export function scission(...geometries: RecursiveArray<Geom2>): Geom2
 export function scission(...geometries: RecursiveArray<Geom3>): Geom3
+export function scission(...geometries: RecursiveArray<Geom3>): Array<Geom3>
diff --git a/packages/modeling/src/operations/booleans/scission.js b/packages/modeling/src/operations/booleans/scission.js
@@ -5,6 +5,8 @@ import { scissionGeom3 } from './scissionGeom3.js'
 /**
  * Scission (divide) the given geometry into the component pieces.
  *
+ * NOTE: Currently only 3D geometries are supported.
+ *
  * @param {...Object} objects - list of geometries
  * @returns {Array} list of pieces from each geometry
  * @alias module:modeling/booleans.scission

diff --git a/packages/modeling/src/operations/booleans/subtract.js b/packages/modeling/src/operations/booleans/subtract.js
@@ -17,7 +17,7 @@ import { subtractGeom3 } from './subtractGeom3.js'
  * @alias module:modeling/booleans.subtract
  *
  * @example
- * let myshape = subtract(cuboid({size: [5,5,5]}), cuboid({size: [5,5,5], center: [5,5,5]}))
+ * let myshape = subtract(cuboid({size: 5}), cuboid({size: 5, center: [3,3,3]}))
  *
  * @example
  * +-------+            +-------+

diff --git a/packages/modeling/src/operations/booleans/union.js b/packages/modeling/src/operations/booleans/union.js
@@ -16,7 +16,7 @@ import { unionGeom3 } from './unionGeom3.js'
  * @alias module:modeling/booleans.union
  *
  * @example
- * let myshape = union(cube({size: [5,5,5]}), cube({size: [5,5,5], center: [5,5,5]}))
+ * let myshape = union(cube({size: 5}), cube({size: 5, center: [3,3,3]}))
  *
  * @example
  * +-------+            +-------+

diff --git a/packages/modeling/src/operations/extrusions/extrudeHelical.js b/packages/modeling/src/operations/extrusions/extrudeHelical.js
@@ -19,14 +19,8 @@ import { extrudeFromSlices } from './extrudeFromSlices.js'
  * @alias module:modeling/extrusions.extrudeHelical
  *
  * @example
- * const myshape = extrudeHelical(
- *  {
- *      angle: Math.PI * 4,
- *      pitch: 10,
- *      segmentsPerRotation: 64
- *  },
- *  circle({size: 3, center: [10, 0]})
- * )
+ * const myshape = circle({size: 3, center: [10, 0]}) // position for extrusion about Z
+ * const mycoil = extrudeHelical({angle: TAU*2, pitch: 10, segmentsPerRotation: 64}, myshape))
  */
 export const extrudeHelical = (options, geometry) => {
   const defaults = {