From 503f4acb273cd65a6c0c5c14352d523ed0ec6e5b Mon Sep 17 00:00:00 2001 From: z3dev Date: Sat, 4 Apr 2026 09:46:00 +0900 Subject: [PATCH 1/8] docs(all): added missing IO deserializer/serializer docs --- jsdoc.json | 22 ++++++++++++------- packages/io/3mf-deserializer/src/index.js | 1 - packages/io/3mf-serializer/src/index.js | 3 ++- packages/io/dxf-deserializer/src/DxfReader.js | 2 +- packages/io/dxf-deserializer/src/index.js | 6 ++--- packages/io/dxf-serializer/src/index.js | 7 +++--- packages/io/json-deserializer/src/index.js | 6 ++--- packages/io/json-serializer/src/index.js | 3 +-- packages/io/obj-deserializer/src/index.js | 6 ++--- packages/io/obj-serializer/src/index.js | 7 +++--- packages/io/stl-deserializer/src/index.js | 6 ++--- packages/io/stl-serializer/src/index.js | 3 +-- packages/io/svg-deserializer/src/index.js | 3 +-- packages/io/svg-serializer/src/index.js | 3 +-- packages/io/x3d-deserializer/src/index.js | 3 +-- packages/io/x3d-serializer/src/index.js | 4 ++-- 16 files changed, 43 insertions(+), 42 deletions(-) diff --git a/jsdoc.json b/jsdoc.json index bac871f31..46051db94 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -36,14 +36,20 @@ "packages/modeling/src/utils", "packages/io/io-utils", - "packages/io/amf-deserializer/src", - "packages/io/amf-serializer", + "packages/io/3mf-deserializer/src", + "packages/io/3mf-serializer/src", + "packages/io/dxf-deserializer/src", + "packages/io/dxf-serializer/src", + "packages/io/json-deserializer/src", + "packages/io/json-serializer/src", + "packages/io/obj-deserializer/src", + "packages/io/obj-serializer/src", + "packages/io/stl-deserializer/src", + "packages/io/stl-serializer/src", "packages/io/svg-deserializer/src", - "packages/io/svg-serializer", + "packages/io/svg-serializer/src", "packages/io/x3d-deserializer/src", - "packages/io/x3d-serializer/src", - "packages/io/3mf-deserializer/src", - "packages/io/3mf-serializer/src" + "packages/io/x3d-serializer/src" ], "includePattern": ".+\\.js(doc|x)?$", "excludePattern": ".+test.js$" @@ -86,8 +92,8 @@ "url": "" }, "meta": { - "title": "JSCAD API Documentation", - "description": "JSCAD API Documentation", + "title": "JSCAD V3 API Documentation", + "description": "JSCAD V3 API Documentation", "keyword": "JSCAD OpenJSCAD" }, "search": [true], diff --git a/packages/io/3mf-deserializer/src/index.js b/packages/io/3mf-deserializer/src/index.js index 71c9abc4a..421f8e785 100644 --- a/packages/io/3mf-deserializer/src/index.js +++ b/packages/io/3mf-deserializer/src/index.js @@ -42,7 +42,6 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup * @param {String} [options.includedType] - type of 3MF objects to include, default is 'all' * @param {String} input - 3MF source data (OPC or XML) * @returns {(Array|String)} either an array of objects (geometry) or a string (script) - * @alias module:io/3mf-deserializer.deserialize */ const deserialize = (options, input) => { const defaults = { diff --git a/packages/io/3mf-serializer/src/index.js b/packages/io/3mf-serializer/src/index.js index efcb3ffc9..ce371f7f3 100644 --- a/packages/io/3mf-serializer/src/index.js +++ b/packages/io/3mf-serializer/src/index.js @@ -9,7 +9,7 @@ * * @module io/3mf-serializer * @example - * const { serializer, mimeType } = require('@jscad/3mf-serializer') + * import { serializer, mimeType } from '@jscad/3mf-serializer' */ import { zipSync, strToU8 } from 'fflate' @@ -24,6 +24,7 @@ const mimeType = 'model/3mf' /** * Serialize the give objects to 3MF contents (XML) or 3MF packaging (OPC). * @see https://3mf.io/specification/ + * * @param {Object} [options] - options for serialization * @param {String} [options.unit='millimeter'] - unit of design; micron, millimeter, inch, feet, meter or micrometer * @param {Boolean} [options.metadata=true] - add metadata to 3MF contents, such at CreationDate diff --git a/packages/io/dxf-deserializer/src/DxfReader.js b/packages/io/dxf-deserializer/src/DxfReader.js index 29da344f9..6ff334b5b 100644 --- a/packages/io/dxf-deserializer/src/DxfReader.js +++ b/packages/io/dxf-deserializer/src/DxfReader.js @@ -6,7 +6,7 @@ const STATES = [ 'error' ] -/** +/* * Class DxfReader * A class to hold state while reading DXF formatted data. * @param {Object} [options] - options for parsing diff --git a/packages/io/dxf-deserializer/src/index.js b/packages/io/dxf-deserializer/src/index.js index b00116435..6cb56cf78 100644 --- a/packages/io/dxf-deserializer/src/index.js +++ b/packages/io/dxf-deserializer/src/index.js @@ -18,7 +18,7 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup * Deserializer of DXF data to JSCAD geometries. * @module io/dxf-deserializer * @example - * const { deserialize, extension } = require('@jscad/dxf-deserializer') + * import { deserialize, mimeType } from '@jscad/dxf-deserializer' */ const handleError = (reader, error) => { @@ -571,6 +571,7 @@ const translate = (src, options) => { /** * Deserialize the given DXF source into either a script or an array of geometry + * * @param {Object} options - options used during deserializing, REQUIRED * @param {string} [options.filename='dxf'] - filename of original DXF data stream * @param {String} [options.version] - version added to the script metadata, default is package version @@ -578,8 +579,7 @@ const translate = (src, options) => { * @param {boolean} [options.strict=true] - obey strict DXF specifications * @param {array} [options.colorindex=[]] - list of colors (256) for use during rendering * @param {string} src - DXF data stream - * @return {string|[objects]} a string (script) or array of objects (geometry) - * @alias module:io/dxf-deserializer.deserialize + * @returns {(Array|String)} either an array of objects (geometry) or a string (script) */ const deserialize = (options, src) => { const defaults = { diff --git a/packages/io/dxf-serializer/src/index.js b/packages/io/dxf-serializer/src/index.js index ad08aef92..ca95ed368 100644 --- a/packages/io/dxf-serializer/src/index.js +++ b/packages/io/dxf-serializer/src/index.js @@ -8,19 +8,20 @@ const mimeType = 'image/vnd.dxf' /** * Serializer of JSCAD geometries to DXF entities. + * * @module io/dxf-serializer * @example - * const { serializer, mimeType } = require('@jscad/dxf-serializer') + * import { serializer, mimeType } from '@jscad/dxf-serializer' */ /** * Serialize the give objects to AutoCad DXF format. + * * @param {Object} options - options for serialization, REQUIRED * @param {String} [options.geom2To='lypolyline'] - target entity for 2D geometries, 'lwpolyline' or 'polyline' * @param {String} [options.geom3To='3dface'] - target entity for 3D geometries, '3dface' or 'polyline' * @param {Object|Array} objects - objects to serialize as DXF * @returns {Array} serialized contents, DXF format - * @alias module:io/dxf-serializer.serialize * @example * const geometry = primitives.cube() * const dxfData = serializer({geom3To: '3dface'}, geometry) @@ -60,7 +61,7 @@ EOF return [dxfContent] } -/** +/* * Serialize the given objects as a DXF entity section * @param {Array} objects - objects to serialize as DXF * @param {Object} options - options for serialization diff --git a/packages/io/json-deserializer/src/index.js b/packages/io/json-deserializer/src/index.js index 53bdb778a..559fb2b55 100644 --- a/packages/io/json-deserializer/src/index.js +++ b/packages/io/json-deserializer/src/index.js @@ -10,7 +10,7 @@ * @see https://www.json.org * @module io/json-deserializer * @example - * const { deserializer, extension } = require('@jscad/json-deserializer') + * import { deserializer, mimeType } from '@jscad/json-deserializer' */ import { flatten, toArray } from '@jscad/array-utils' @@ -20,14 +20,14 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup /** * Deserialize the given JSON notation (string) into either a script or an array of geometry. + * * @param {Object} options - options used during deserializing, REQUIRED * @param {String} [options.filename='json'] - filename of original JSON source * @param {String} [options.output='script'] - either 'script' or 'geometry' to set desired output * @param {String} [options.version='0.0.0'] - version number to add to the metadata * @param {Boolean} [options.addMetadata=true] - toggle injection of metadata at the start of the script * @param {String} input - JSON source data - * @return {[geometry]/String} either an array of objects (geometry) or a string (script) - * @alias module:io/json-deserializer.deserialize + * @return {(Array|String)} either an array of objects (geometry) or a string (script) */ const deserialize = (options, input) => { const defaults = { diff --git a/packages/io/json-serializer/src/index.js b/packages/io/json-serializer/src/index.js index dde0caa95..ad8b4ea04 100644 --- a/packages/io/json-serializer/src/index.js +++ b/packages/io/json-serializer/src/index.js @@ -2,7 +2,7 @@ * Serializer of JSCAD geometries to JSON strings. * @module io/json-serializer * @example - * const { serializer, mimeType } = require('@jscad/json-serializer') + * import { serializer, mimeType } from '@jscad/json-serializer' */ import { flatten } from '@jscad/array-utils' @@ -32,7 +32,6 @@ const replacer = (key, value) => { * @param {Object} options - options for serialization, REQUIRED * @param {Object|Array} objects - objects to serialize as JSON * @returns {Array} serialized contents as JSON string - * @alias module:io/json-serializer.serialize * @example * const geometry = cube() * const jsonData = serializer({}, geometry) diff --git a/packages/io/obj-deserializer/src/index.js b/packages/io/obj-deserializer/src/index.js index f892ba5d7..061909a15 100644 --- a/packages/io/obj-deserializer/src/index.js +++ b/packages/io/obj-deserializer/src/index.js @@ -7,20 +7,20 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup * Deserializer of OBJ data to JSCAD geometries. * @module io/obj-deserializer * @example - * const { deserializer, extension } = require('@jscad/obj-deserializer') + * import { deserializer, mimeType } from '@jscad/obj-deserializer' */ /** * Parse the given OBJ data and return either a JSCAD script or a set of geometry * @see http://en.wikipedia.org/wiki/Wavefront_.obj_file + * * @param {Object} options - options used during deserializing, REQUIRED * @param {string} [options.filename='obj'] - filename of the original obj data * @param {string} [options.version='0.0.0'] - version number to add to the metadata * @param {boolean} [options.addMetadata=true] - toggle injection of metadata at the start of the script * @param {string} [options.output='script'] - either 'script' or 'geometry' to set desired output * @param {string} input - obj data - * @return {[object]/string} either a script (script) or a set of objects (geometry) - * @alias module:io/obj-deserializer.deserialize + * @return {(Array|string)} either a script (script) or a set of objects (geometry) */ const deserialize = (options, input) => { const defaults = { diff --git a/packages/io/obj-serializer/src/index.js b/packages/io/obj-serializer/src/index.js index 099be70d2..5d967cedd 100644 --- a/packages/io/obj-serializer/src/index.js +++ b/packages/io/obj-serializer/src/index.js @@ -6,7 +6,7 @@ * * @module io/obj-serializer * @example - * const { serializer, mimeType } = require('@jscad/obj-serializer') + * import { serializer, mimeType } from '@jscad/obj-serializer' */ import { cssColors, generalize, geom3 } from '@jscad/modeling' @@ -22,7 +22,6 @@ const mimeType = 'model/obj' * @param {Function} [options.statusCallback] - call back function for progress ({ progress: 0-100 }) * @param {...Object} objects - objects to serialize into OBJ source data * @returns {Array} serialized contents, OBJ source data - * @alias module:io/obj-serializer.serialize * @example * const geometry = cube() * const objData = serializer({}, geometry) @@ -96,12 +95,12 @@ const serialize = (options, ...objects) => { return [body] } -/** +/* * Convert a vertex to an obj "v" string */ const convertVertex = (vertex) => `v ${vertex[0]} ${vertex[1]} ${vertex[2]}` -/** +/* * Get the closest css color name */ const getColorName = (object) => { diff --git a/packages/io/stl-deserializer/src/index.js b/packages/io/stl-deserializer/src/index.js index ab5da12a9..ca4eb43fc 100644 --- a/packages/io/stl-deserializer/src/index.js +++ b/packages/io/stl-deserializer/src/index.js @@ -16,19 +16,19 @@ const pkgversion = '[VI]{version}[/VI]' // version is injected by rollup * Deserializer of STL data to JSCAD geometries. * @module io/stl-deserializer * @example - * const { deserializer, extension } = require('@jscad/stl-deserializer') + * import { deserializer, extension } from '@jscad/stl-deserializer' */ /** * Parse the given STL data and return either a JSCAD script or a list of geometries + * * @param {Object} options - options used during deserializing, REQUIRED * @param {string} [options.filename='stl'] - filename of original STL source * @param {string} [options.version='0.0.0'] - version number to add to the metadata * @param {boolean} [options.addMetadata=true] - toggle injection of metadata at the start of the script * @param {string} [options.output='script'] - either 'script' or 'geometry' to set desired output * @param {string} input - stl data - * @return {[objects]|string} a list of objects (geometry) or a string (script) - * @alias module:io/stl-deserializer.deserialize + * @return {(Array|string)} a list of objects (geometry) or a string (script) */ const deserialize = (options, stl) => { const defaults = { diff --git a/packages/io/stl-serializer/src/index.js b/packages/io/stl-serializer/src/index.js index c38eebefd..5104d2546 100644 --- a/packages/io/stl-serializer/src/index.js +++ b/packages/io/stl-serializer/src/index.js @@ -2,7 +2,7 @@ * Serializer of JSCAD geometries to STL mesh. * @module io/stl-serializer * @example - * const { serializer, mimeType } = require('@jscad/stl-serializer') + * import { serializer, mimeType } from '@jscad/stl-serializer' */ import { generalize, geom3 } from '@jscad/modeling' @@ -22,7 +22,6 @@ const mimeType = 'model/stl' * @param {Function} [options.statusCallback] - call back function for progress ({ progress: 0-100 }) * @param {...Object} objects - objects to serialize as STL * @returns {Array} serialized contents with one STL mesh (either string or binary data) - * @alias module:io/stl-serializer.serialize * @example * const geometry = cube() * const stlData = serializer({binary: false}, geometry) diff --git a/packages/io/svg-deserializer/src/index.js b/packages/io/svg-deserializer/src/index.js index fe0a4184d..7bb74268c 100644 --- a/packages/io/svg-deserializer/src/index.js +++ b/packages/io/svg-deserializer/src/index.js @@ -17,7 +17,7 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup * @see {@link https://github.com/jscad/OpenJSCAD.org/blob/master/packages/io/svg-deserializer/README.md|README} for supported conversion of SVG elements. * @module io/svg-deserializer * @example - * const { deserializer, extension } = require('@jscad/svg-deserializer') + * import { deserializer, mimeType } from '@jscad/svg-deserializer' */ /** @@ -34,7 +34,6 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup * @param {string} [options.pathSelfClosed='error'] - [error||trim||split] if path self-closes with one of commands without stop command right after * @param {string} input - SVG source data * @returns {(Array|String)} either an array of objects (geometry) or a string (script) - * @alias module:io/svg-deserializer.deserialize */ const deserialize = (options, input) => { const defaults = { diff --git a/packages/io/svg-serializer/src/index.js b/packages/io/svg-serializer/src/index.js index cef31a1f9..ab4e2a3f3 100644 --- a/packages/io/svg-serializer/src/index.js +++ b/packages/io/svg-serializer/src/index.js @@ -10,7 +10,7 @@ * * @module io/svg-serializer * @example - * const { serializer, mimeType } = require('@jscad/svg-serializer') + * import { serializer, mimeType } from '@jscad/svg-serializer' */ import { geom2, flatten, measureBoundingBox, path2, vec3 } from '@jscad/modeling' @@ -29,7 +29,6 @@ const mimeType = 'image/svg+xml' * @param {Function} [options.statusCallback] - call back function for progress ({ progress: 0-100 }) * @param {Object|Array} objects - objects to serialize as SVG * @returns {Array} serialized contents, SVG code (XML string) - * @alias module:io/svg-serializer.serialize * @example * const geometry = primitives.square() * const svgData = serializer({unit: 'mm'}, geometry) diff --git a/packages/io/x3d-deserializer/src/index.js b/packages/io/x3d-deserializer/src/index.js index b2f76f506..b0741a39b 100644 --- a/packages/io/x3d-deserializer/src/index.js +++ b/packages/io/x3d-deserializer/src/index.js @@ -10,7 +10,7 @@ * @see {@link https://github.com/jscad/OpenJSCAD.org/blob/master/packages/io/x3d-deserializer/README.md|README} for supported conversion of X3D entities. * @module io/x3d-deserializer * @example - * const { deserializer, extension } = require('@jscad/x3d-deserializer') + * import { deserializer, mimeType } from '@jscad/x3d-deserializer' */ import { ensureString } from '@jscad/io-utils' @@ -30,7 +30,6 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup * @param {Boolean} [options.addMetadata=true] - toggle injection of metadata at the start of the script * @param {String} input - X3D source data (XML) * @returns {(Array|String)} either an array of objects (geometry) or a string (script) - * @alias module:io/x3d-deserializer.deserialize */ const deserialize = (options, input) => { const defaults = { diff --git a/packages/io/x3d-serializer/src/index.js b/packages/io/x3d-serializer/src/index.js index b7c2b8a67..fa29c7d46 100644 --- a/packages/io/x3d-serializer/src/index.js +++ b/packages/io/x3d-serializer/src/index.js @@ -16,7 +16,7 @@ import { stringify } from '@jscad/io-utils' * * @module io/x3d-serializer * @example - * const { serializer, mimeType } = require('@jscad/x3d-serializer') + * import { serializer, mimeType } from '@jscad/x3d-serializer' */ const mimeType = 'model/x3d+xml' @@ -24,6 +24,7 @@ const defNames = new Map() /** * Serialize the give objects to X3D elements (XML). + * * @param {Object} options - options for serialization, REQUIRED * @param {Array} [options.color=[0,0,1,1]] - default color for objects * @param {Number} [options.shininess=8/256] - x3d shininess for specular highlights @@ -34,7 +35,6 @@ const defNames = new Map() * @param {Function} [options.statusCallback] - call back function for progress ({ progress: 0-100 }) * @param {Object|Array} objects - objects to serialize as X3D * @returns {Array} serialized contents, X3D format (XML) - * @alias module:io/x3d-serializer.serialize * @example * const geometry = primitives.cube() * const x3dData = serializer({unit: 'meter'}, geometry) From 7f89de12402303b9f7054444be675a2773b44c22 Mon Sep 17 00:00:00 2001 From: z3dev Date: Sun, 5 Apr 2026 09:12:05 +0900 Subject: [PATCH 2/8] docs(all): updated tutorial docs to use V3 imports --- jsdoc/assets/README.md | 4 ++-- jsdoc/tutorials/01_gettingStarted.md | 31 +++++-------------------- jsdoc/tutorials/02_modelingBasics.md | 4 +--- jsdoc/tutorials/03_usingParameters.md | 4 +--- jsdoc/tutorials/04_multifileProjects.md | 7 +++--- jsdoc/tutorials/05_importingFiles.md | 5 ++-- 6 files changed, 16 insertions(+), 39 deletions(-) diff --git a/jsdoc/assets/README.md b/jsdoc/assets/README.md index 1499d281f..6a14a05fa 100644 --- a/jsdoc/assets/README.md +++ b/jsdoc/assets/README.md @@ -23,8 +23,8 @@ There are different 'flavors' of JSCAD that you can use based on your needs ## Documentation -* [JSCAD User Guide](https://openjscad.xyz/guide.html) -* [API Reference](https://openjscad.xyz/docs/) +* [JSCAD User Guide](https://openjscad.xyz/v3/guide.html) +* [API Reference](https://openjscad.xyz/v3/docs/) * [Open Issues](https://openjscad.xyz/issues.html) ## Community diff --git a/jsdoc/tutorials/01_gettingStarted.md b/jsdoc/tutorials/01_gettingStarted.md index f9162aadd..97c57b0a1 100644 --- a/jsdoc/tutorials/01_gettingStarted.md +++ b/jsdoc/tutorials/01_gettingStarted.md @@ -23,34 +23,17 @@ it with the "Load a JSCAD Project" file dialog. The simplest file that will render a cube in JSCAD looks like this: ```javascript // the import statement allows your code to use JSCAD functions. -import { primitives } from '@jscad/modeling' +import { cube } from '@jscad/modeling' // the export statement defines the entry point of the design. export const main = () => { - return primitives.cube() + return cube() } ``` -JSCAD functions must be imported, but there are several different syntaxes for using the functions: -```javascript -// import one or more functional areas from JSCAD: -import { primitives, booleans } from '@jscad/modeling' - -// use functions directly -let aCube = primitives.cube() - -// or - -// use the functions by name -const { cube, sphere } = primitives - -let aCube = cube() -let aSphere = sphere() -``` ## Adding Methods Clean, readable code is one of the most important aspects of a useful design. In that respect, it can often be useful to break your code into simple function that do part of the work for your design: ```javascript -import { primitives } from '@jscad/modeling' -const { cylinder } = primitives +import { cylinder } from '@jscad/modeling' const hex = (radius, height) => { return cylinder({radius, height, segments: 6}) @@ -63,8 +46,7 @@ export const main = () => { ## Re-usable Designs A valuable practise when creating models is to store all but the most trivial values as parameters in the code, rather than using the numerical values directly. This can be done by storing them in constants in your file... ```javascript -import { primitives } from '@jscad/modeling' -const { cylinder } = primitives +import { cylinder } from '@jscad/modeling' const options = { height: 5.1, @@ -78,10 +60,10 @@ export const main = () => { ... or, even better, to include runtime parameters in your design. This is done using the getParameterDefinitions function: ```javascript -import { primitives } from '@jscad/modeling' -const { cylinder } = primitives +import { cylinder } from '@jscad/modeling' // Declare a function named "getParameterDefinitions". It will return an array of parameter definitions. +// You must also export the getParameterDefinitions function. export const getParameterDefinitions = () => { return [ { name: 'height', type: 'number', initial: 2.0, min: 1.0, max: 10.0, step: 0.1, caption: 'Hex Height:' }, @@ -93,7 +75,6 @@ export const getParameterDefinitions = () => { export const main = (params) => { return cylinder({radius: params.radius, height: params.height, segments: 6}) } -// You must also export the getParameterDefinitions function. ``` JSCAD Parameters Example diff --git a/jsdoc/tutorials/02_modelingBasics.md b/jsdoc/tutorials/02_modelingBasics.md index cda892fc0..5366cc922 100644 --- a/jsdoc/tutorials/02_modelingBasics.md +++ b/jsdoc/tutorials/02_modelingBasics.md @@ -38,9 +38,7 @@ Another valuable way of building shapes is to start with 2D shapes. These can b specifying points, starting with basic primitive 2D shapes, or importing SVG files. The 2D shapes can then be extruded to produce a wide variety of different geometries. ```javascript -import { primitives, extrusions } from '@jscad/modeling' -const { polygon } = primitives -const { extrudeLinear } = extrusions +import { polygon, extrudeLinear } from '@jscad/modeling' export const main = () => { const poly = polygon({ points: [[-1, -1], [3, -1], [3.5, 2], [2, 1], [1, 2], [0, 1], [-1, 2]] }) diff --git a/jsdoc/tutorials/03_usingParameters.md b/jsdoc/tutorials/03_usingParameters.md index 6806b4d18..8c7a85ed9 100644 --- a/jsdoc/tutorials/03_usingParameters.md +++ b/jsdoc/tutorials/03_usingParameters.md @@ -3,9 +3,7 @@ your designs, so that they can easily adapt to different situations. ## ParametricBox.js ```javascript -import { primitives, booleans } from '@jscad/modeling' -const { cuboid, roundedCuboid } = primitives -const { subtract } = booleans +import { cuboid, roundedCuboid, subtract } from '@jscad/modeling' export const getParameterDefinitions = () => { return [ diff --git a/jsdoc/tutorials/04_multifileProjects.md b/jsdoc/tutorials/04_multifileProjects.md index dd8312c08..de14f7e25 100644 --- a/jsdoc/tutorials/04_multifileProjects.md +++ b/jsdoc/tutorials/04_multifileProjects.md @@ -21,14 +21,13 @@ contain your design. Your project can also contain: ``` ## hexcap/index.js ```javascript -import { primtives } from '@jscad/modeling' -const { cylinder } = primitives +import { cylinder } from '@jscad/modeling' import { hexWidthToRadius } from './lib/utils.js' export const main = () => { - let hexRadius = utils.hexWidthToRadius(12) - return cylinder({radius: hexRadius, height: 4, segments: 6}) + let radius = hexWidthToRadius(12) + return cylinder({radius, height: 4, segments: 6}) } ``` ## hexcap/lib/utils.js diff --git a/jsdoc/tutorials/05_importingFiles.md b/jsdoc/tutorials/05_importingFiles.md index e6fd3141e..c5b5526e3 100644 --- a/jsdoc/tutorials/05_importingFiles.md +++ b/jsdoc/tutorials/05_importingFiles.md @@ -1,10 +1,11 @@ Importing files in JSCAD is a simple case of loading them using the same import statement used to load javascript modules. The files you load need to be part of a multifile project, so that JSCAD can access them: ```javascript +// import all functions and global constants import * as jscad from '@jscad/modeling' -const { translate, scale, rotateZ } = jscad.transforms -const { union } = jscad.booleans +// import specific functions and global constants by name +const { translate, scale, rotateZ, union, TAU } = '@jscad/modeling' // Load the STL files using require const sculpture = require('./3d_sculpture-VernonBussler.stl') From db38de0a346c3239eda4e929c26828a0d5919d4b Mon Sep 17 00:00:00 2001 From: z3dev Date: Sun, 5 Apr 2026 09:13:07 +0900 Subject: [PATCH 3/8] docs(modeling): adjusted docs to use imports, added more examples --- .../src/geometries/geom2/applyTransforms.js | 4 ++- .../modeling/src/geometries/geom2/clone.js | 6 +++- .../modeling/src/geometries/geom2/create.js | 18 +++--------- .../src/geometries/geom2/fromSides.js | 6 ++-- .../modeling/src/geometries/geom2/index.js | 26 +++++++++++++---- packages/modeling/src/geometries/geom2/isA.js | 6 +++- .../modeling/src/geometries/geom2/reverse.js | 6 ++-- .../src/geometries/geom2/toOutlines.js | 3 +- .../modeling/src/geometries/geom2/toPoints.js | 7 +++-- .../modeling/src/geometries/geom2/toSides.js | 7 +++-- .../modeling/src/geometries/geom2/toString.js | 5 ++-- .../src/geometries/geom2/transform.js | 6 ++-- .../modeling/src/geometries/geom2/validate.js | 8 +++-- .../modeling/src/geometries/geom3/clone.js | 6 +++- .../modeling/src/geometries/geom3/create.js | 24 ++++----------- .../src/geometries/geom3/fromVertices.js | 14 ++++++++- .../geometries/geom3/fromVerticesConvex.js | 2 +- .../modeling/src/geometries/geom3/index.js | 29 ++++++++++++++++--- .../modeling/src/geometries/geom3/invert.js | 6 +++- packages/modeling/src/geometries/geom3/isA.js | 6 +++- .../modeling/src/geometries/geom3/isConvex.js | 5 ++-- .../src/geometries/geom3/toPolygons.js | 6 ++-- .../modeling/src/geometries/geom3/toString.js | 5 ++-- .../src/geometries/geom3/toVertices.js | 12 +++++--- .../src/geometries/geom3/transform.js | 7 +++-- .../modeling/src/geometries/geom3/validate.js | 8 +++-- packages/modeling/src/geometries/index.js | 14 +++++---- .../src/geometries/path2/appendArc.js | 10 ++++--- .../src/geometries/path2/appendBezier.js | 10 ++++--- .../src/geometries/path2/appendPoints.js | 6 ++-- .../src/geometries/path2/applyTransforms.js | 3 ++ .../modeling/src/geometries/path2/clone.js | 6 +++- .../modeling/src/geometries/path2/close.js | 6 +++- .../modeling/src/geometries/path2/concat.js | 5 ++-- .../modeling/src/geometries/path2/create.js | 18 ++---------- .../modeling/src/geometries/path2/equals.js | 19 +++++++----- .../src/geometries/path2/fromPoints.js | 8 +++-- .../modeling/src/geometries/path2/index.js | 25 +++++++++++++--- packages/modeling/src/geometries/path2/isA.js | 6 +++- .../modeling/src/geometries/path2/reverse.js | 6 ++-- .../modeling/src/geometries/path2/toPoints.js | 8 +++-- .../modeling/src/geometries/path2/toString.js | 5 ++-- .../src/geometries/path2/transform.js | 6 ++-- .../modeling/src/geometries/path2/validate.js | 6 +++- .../src/geometries/path3/applyTransforms.js | 2 +- .../modeling/src/geometries/path3/close.js | 6 ++-- .../modeling/src/geometries/path3/concat.js | 5 ++-- .../modeling/src/geometries/path3/create.js | 23 ++------------- .../modeling/src/geometries/path3/equals.js | 6 ++-- .../src/geometries/path3/fromVertices.js | 5 ++-- .../modeling/src/geometries/path3/index.js | 18 +++++++++++- packages/modeling/src/geometries/path3/isA.js | 6 ++-- .../modeling/src/geometries/path3/reverse.js | 5 ++-- .../modeling/src/geometries/path3/toString.js | 5 ++-- .../src/geometries/path3/toVertices.js | 5 ++-- .../src/geometries/path3/transform.js | 5 ++-- .../modeling/src/geometries/path3/validate.js | 9 ++++-- .../src/geometries/poly2/arePointsInside.js | 5 +++- .../modeling/src/geometries/poly2/clone.js | 5 +++- .../modeling/src/geometries/poly2/create.js | 11 ++----- .../modeling/src/geometries/poly2/index.js | 20 ++++++++++--- packages/modeling/src/geometries/poly2/isA.js | 6 +++- .../modeling/src/geometries/poly2/isConvex.js | 6 +++- .../modeling/src/geometries/poly2/isSimple.js | 6 +++- .../src/geometries/poly2/measureArea.js | 5 +++- .../geometries/poly2/measureBoundingBox.js | 7 ++++- .../modeling/src/geometries/poly2/reverse.js | 5 +++- .../modeling/src/geometries/poly2/toPoints.js | 7 ++++- .../modeling/src/geometries/poly2/toString.js | 6 +++- .../src/geometries/poly2/transform.js | 6 +++- .../modeling/src/geometries/poly2/validate.js | 8 +++-- .../modeling/src/geometries/poly3/clone.js | 5 +++- .../modeling/src/geometries/poly3/create.js | 14 ++------- .../geometries/poly3/fromVerticesAndPlane.js | 4 ++- .../modeling/src/geometries/poly3/index.js | 23 ++++++++++++--- .../modeling/src/geometries/poly3/invert.js | 5 +++- packages/modeling/src/geometries/poly3/isA.js | 6 +++- .../modeling/src/geometries/poly3/isConvex.js | 6 +++- .../src/geometries/poly3/measureArea.js | 6 +++- .../geometries/poly3/measureBoundingBox.js | 5 +++- .../geometries/poly3/measureBoundingSphere.js | 5 +++- .../geometries/poly3/measureSignedVolume.js | 7 ++++- .../modeling/src/geometries/poly3/plane.js | 3 ++ .../modeling/src/geometries/poly3/toString.js | 6 +++- .../src/geometries/poly3/toVertices.js | 7 ++++- .../src/geometries/poly3/transform.js | 6 +++- .../modeling/src/geometries/poly3/validate.js | 8 +++-- .../src/geometries/slice/calculatePlane.js | 6 ++-- .../modeling/src/geometries/slice/clone.js | 5 +++- .../modeling/src/geometries/slice/create.js | 15 ++++------ .../modeling/src/geometries/slice/equals.js | 6 +++- .../src/geometries/slice/fromGeom2.js | 2 +- .../src/geometries/slice/fromVertices.js | 6 ++-- .../modeling/src/geometries/slice/index.js | 23 ++++++++++++--- packages/modeling/src/geometries/slice/isA.js | 6 +++- .../modeling/src/geometries/slice/reverse.js | 7 +++-- .../modeling/src/geometries/slice/toEdges.js | 8 +++-- .../src/geometries/slice/toPolygons.js | 6 +++- .../modeling/src/geometries/slice/toString.js | 6 +++- .../src/geometries/slice/toVertices.js | 8 +++-- .../src/geometries/slice/transform.js | 7 +++-- .../modeling/src/geometries/slice/validate.js | 5 ++-- packages/modeling/src/index.js | 3 ++ packages/modeling/src/maths/constants.js | 18 +++++++----- packages/modeling/src/maths/index.js | 3 +- .../modeling/src/operations/booleans/index.js | 2 +- .../src/operations/booleans/intersect.js | 3 +- .../src/operations/booleans/scission.js | 3 +- .../src/operations/booleans/subtract.js | 2 +- .../modeling/src/operations/booleans/union.js | 2 +- 110 files changed, 577 insertions(+), 299 deletions(-) diff --git a/packages/modeling/src/geometries/geom2/applyTransforms.js b/packages/modeling/src/geometries/geom2/applyTransforms.js index 99300d96c..1b1084d67 100644 --- a/packages/modeling/src/geometries/geom2/applyTransforms.js +++ b/packages/modeling/src/geometries/geom2/applyTransforms.js @@ -3,12 +3,14 @@ import * as vec2 from '../../maths/vec2/index.js' /* * Apply the transforms of the given geometry. + * * NOTE: This function must be called BEFORE exposing any data. See toOutlines(). + * * @param {Geom2} geometry - the geometry to transform * @returns {Geom2} the given geometry * * @example - * geometry = applyTransforms(geometry) + * const geometry = geom2.applyTransforms(geometry) */ export const applyTransforms = (geometry) => { if (mat4.isIdentity(geometry.transforms)) return geometry diff --git a/packages/modeling/src/geometries/geom2/clone.js b/packages/modeling/src/geometries/geom2/clone.js index 81b41093c..1669518f6 100644 --- a/packages/modeling/src/geometries/geom2/clone.js +++ b/packages/modeling/src/geometries/geom2/clone.js @@ -1,7 +1,11 @@ /** * Performs a shallow clone of the given geometry. + * * @param {Geom2} geometry - the geometry to clone * @returns {Geom2} new geometry - * @alias module:modeling/geometries/geom2.clone + * @alias module:modeling/geom2.clone + * + * @example + * const geometry = geom2.clone(geometry) */ export const clone = (geometry) => Object.assign({}, geometry) diff --git a/packages/modeling/src/geometries/geom2/create.js b/packages/modeling/src/geometries/geom2/create.js index d3e599065..247978d30 100644 --- a/packages/modeling/src/geometries/geom2/create.js +++ b/packages/modeling/src/geometries/geom2/create.js @@ -1,24 +1,14 @@ import * as mat4 from '../../maths/mat4/index.js' -/** - * Represents a 2D geometry consisting of outlines, where each outline is an ordered list of points. - * @property {Array} outlines - list of polygon outlines - * @property {Mat4} transforms - transforms to apply to the geometry, see transform() - * @example - * // data structure - * { - * "outlines": [[[-1,-1],[1,-1],[1,1],[-1,1]]], - * "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1] - * } - */ - /** * Create a new 2D geometry composed of polygon outlines. + * * @param {Array} [outlines] - list of outlines where each outline is an array of points * @returns {Geom2} a new geometry - * @alias module:modeling/geometries/geom2.create + * @alias module:modeling/geom2.create + * * @example - * let myShape = create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ]) + * let myShape = geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ]) */ export const create = (outlines = []) => ({ outlines, diff --git a/packages/modeling/src/geometries/geom2/fromSides.js b/packages/modeling/src/geometries/geom2/fromSides.js index dbaec36ba..9096ede92 100644 --- a/packages/modeling/src/geometries/geom2/fromSides.js +++ b/packages/modeling/src/geometries/geom2/fromSides.js @@ -26,7 +26,7 @@ const toSharedPoints = (sides) => { */ const toPointMap = (sides) => { const pointMap = new Map() - // first map to edges with shared vertices + // first map to edges with shared points const edges = toSharedPoints(sides) // construct adjacent edges map edges.forEach((edge) => { @@ -41,11 +41,13 @@ const toPointMap = (sides) => { /** * Create a new 2D geometry from a list of sides. + * * @param {Array} sides - list of sides to create outlines from * @returns {Geom2} a new geometry + * @alias module:modeling/geom2.fromSides * * @example - * let geometry = fromSides([[[0, 0], [1, 0]], [[1, 0], [1, 1]], [[1, 1], [0, 0]]]) + * let geometry = geom2.fromSides([[[0, 0], [1, 0]], [[1, 0], [1, 1]], [[1, 1], [0, 0]]]) */ export const fromSides = (sides) => { const pointMap = toPointMap(sides) // {point: [edges]} diff --git a/packages/modeling/src/geometries/geom2/index.js b/packages/modeling/src/geometries/geom2/index.js index d13fbe3d8..7f120cd87 100644 --- a/packages/modeling/src/geometries/geom2/index.js +++ b/packages/modeling/src/geometries/geom2/index.js @@ -1,12 +1,28 @@ /** * Represents a 2D geometry consisting of outlines, where each outline is an ordered list of points. - * The outline is always closed between the first and last points. - * @see {@link geom2} for data structure information. - * @module modeling/geometries/geom2 + * + * Each outline is always closed between the first and last points. + * + * @see {@link Geom2} for data structure information. + * @module modeling/geom2 + * + * @example + * import { geom2 } from '@jscad/modeling' + * let myShape = geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ]) + */ + +/** + * @typedef Geom2 + * @type {Object} + * @property {Array} outlines - list of outlines, each outline is an ordered list of points + * @property {Mat4} transforms - transforms to apply to the polygons, see transform() * * @example - * import { geometries } from '@jscad/modeling' - * let myShape = geometries.geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ]) + * // data structure + * { + * "outlines": [[[-1,-1],[1,-1],[1,1],[-1,1]]], + * "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1] + * } */ export { clone } from './clone.js' export { create } from './create.js' diff --git a/packages/modeling/src/geometries/geom2/isA.js b/packages/modeling/src/geometries/geom2/isA.js index 2cb2d04da..1f9a5a267 100644 --- a/packages/modeling/src/geometries/geom2/isA.js +++ b/packages/modeling/src/geometries/geom2/isA.js @@ -1,8 +1,12 @@ /** * Determine if the given object is a 2D geometry. + * * @param {object} object - the object to interrogate * @returns {Boolean} true, if the object matches a geom2 based object - * @alias module:modeling/geometries/geom2.isA + * @alias module:modeling/geom2.isA + * + * @example + * const geometry = geom2.isA(geometry) */ export const isA = (object) => { if (object && typeof object === 'object') { diff --git a/packages/modeling/src/geometries/geom2/reverse.js b/packages/modeling/src/geometries/geom2/reverse.js index 6b73633c5..2698b458c 100644 --- a/packages/modeling/src/geometries/geom2/reverse.js +++ b/packages/modeling/src/geometries/geom2/reverse.js @@ -3,13 +3,15 @@ import { toOutlines } from './toOutlines.js' /** * Reverses the given geometry so that the outline points are flipped in the opposite order. + * * This swaps the left (interior) and right (exterior) edges. + * * @param {Geom2} geometry - the geometry to reverse * @returns {Geom2} the new reversed geometry - * @alias module:modeling/geometries/geom2.reverse + * @alias module:modeling/geom2.reverse * * @example - * let newGeometry = reverse(geometry) + * let newGeometry = geom2.reverse(geometry) */ export const reverse = (geometry) => { const outlines = toOutlines(geometry) diff --git a/packages/modeling/src/geometries/geom2/toOutlines.js b/packages/modeling/src/geometries/geom2/toOutlines.js index 68cd0ddd1..33742ef82 100644 --- a/packages/modeling/src/geometries/geom2/toOutlines.js +++ b/packages/modeling/src/geometries/geom2/toOutlines.js @@ -2,9 +2,10 @@ import { applyTransforms } from './applyTransforms.js' /** * Create the outline(s) of the given geometry. + * * @param {Geom2} geometry - geometry to create outlines from * @returns {Array} an array of outlines, where each outline is an array of ordered points - * @alias module:modeling/geometries/geom2.toOutlines + * @alias module:modeling/geom2.toOutlines * * @example * let geometry = subtract(rectangle({size: [5, 5]}), rectangle({size: [3, 3]})) diff --git a/packages/modeling/src/geometries/geom2/toPoints.js b/packages/modeling/src/geometries/geom2/toPoints.js index 1d80867ac..665c11a9a 100644 --- a/packages/modeling/src/geometries/geom2/toPoints.js +++ b/packages/modeling/src/geometries/geom2/toPoints.js @@ -2,14 +2,17 @@ import { toOutlines } from './toOutlines.js' /** * Produces an array of points from the given geometry. + * * The returned array should not be modified as the points are shared with the geometry. + * * NOTE: The points returned do NOT define an order. Use toOutlines() for ordered points. + * * @param {Geom2} geometry - the geometry * @returns {Array} an array of points - * @alias module:modeling/geometries/geom2.toPoints + * @alias module:modeling/geom2.toPoints * * @example - * let sharedPoints = toPoints(geometry) + * let sharedPoints = geom2.toPoints(geometry) */ export const toPoints = (geometry) => { const points = [] diff --git a/packages/modeling/src/geometries/geom2/toSides.js b/packages/modeling/src/geometries/geom2/toSides.js index dc091d937..e2fd7b598 100644 --- a/packages/modeling/src/geometries/geom2/toSides.js +++ b/packages/modeling/src/geometries/geom2/toSides.js @@ -2,14 +2,15 @@ import { toOutlines } from './toOutlines.js' /** * Produces an array of sides from the given geometry. - * The returned array should not be modified as the data is shared with the geometry. + * * NOTE: The sides returned do NOT define an order. Use toOutlines() for ordered points. + * * @param {Geom2} geometry - the geometry * @returns {Array} an array of sides - * @alias module:modeling/geometries/geom2.toSides + * @alias module:modeling/geom2.toSides * * @example - * let sharedSides = toSides(geometry) + * let sharedSides = geom2.toSides(geometry) */ export const toSides = (geometry) => { const sides = [] diff --git a/packages/modeling/src/geometries/geom2/toString.js b/packages/modeling/src/geometries/geom2/toString.js index 98fc4bcd2..53ab3ea88 100644 --- a/packages/modeling/src/geometries/geom2/toString.js +++ b/packages/modeling/src/geometries/geom2/toString.js @@ -4,12 +4,13 @@ import { toOutlines } from './toOutlines.js' /** * Create a string representing the contents of the given geometry. + * * @param {Geom2} geometry - the geometry * @returns {string} a representative string - * @alias module:modeling/geometries/geom2.toString + * @alias module:modeling/geom2.toString * * @example - * console.out(toString(geometry)) + * console.out(geom2.toString(geometry)) */ export const toString = (geometry) => { const outlines = toOutlines(geometry) diff --git a/packages/modeling/src/geometries/geom2/transform.js b/packages/modeling/src/geometries/geom2/transform.js index 562a05db4..fe5323807 100644 --- a/packages/modeling/src/geometries/geom2/transform.js +++ b/packages/modeling/src/geometries/geom2/transform.js @@ -4,15 +4,17 @@ import { reverse } from './reverse.js' /** * Transform the given geometry using the given matrix. + * * This is a lazy transform of the outlines, as this function only adjusts the transforms. * The transforms are applied when accessing the outlines via toOutlines(). + * * @param {Mat4} matrix - the matrix to transform with * @param {Geom2} geometry - the geometry to transform * @returns {Geom2} a new geometry - * @alias module:modeling/geometries/geom2.transform + * @alias module:modeling/geom2.transform * * @example - * let newGeometry = transform(fromZRotation(TAU / 4), geometry) + * let newGeometry = geom2.transform(fromZRotation(TAU / 4), geometry) */ export const transform = (matrix, geometry) => { const transforms = mat4.multiply(mat4.create(), matrix, geometry.transforms) diff --git a/packages/modeling/src/geometries/geom2/validate.js b/packages/modeling/src/geometries/geom2/validate.js index 33623d33b..6847cb146 100644 --- a/packages/modeling/src/geometries/geom2/validate.js +++ b/packages/modeling/src/geometries/geom2/validate.js @@ -7,13 +7,17 @@ import { toOutlines } from './toOutlines.js' /** * Determine if the given object is a valid geom2. + * * Checks for closedness, self-edges, and valid data points. * - * **If the geometry is not valid, an exception will be thrown with details of the geometry error.** + * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.** * * @param {object} object - the object to interrogate * @throws {Error} error if the geometry is not valid - * @alias module:modeling/geometries/geom2.validate + * @alias module:modeling/geom2.validate + * + * @example + * const geometry = geom2.validate(geometry) */ export const validate = (object) => { if (!isA(object)) { diff --git a/packages/modeling/src/geometries/geom3/clone.js b/packages/modeling/src/geometries/geom3/clone.js index 960d6bf60..0920a6a97 100644 --- a/packages/modeling/src/geometries/geom3/clone.js +++ b/packages/modeling/src/geometries/geom3/clone.js @@ -1,7 +1,11 @@ /** * Performs a shallow clone of the given geometry. + * * @param {Geom3} geometry - the geometry to clone * @returns {Geom3} a new geometry - * @alias module:modeling/geometries/geom3.clone + * @alias module:modeling/geom3.clone + * + * @example + * let clone = geom3.clone(geometry) */ export const clone = (geometry) => Object.assign({}, geometry) diff --git a/packages/modeling/src/geometries/geom3/create.js b/packages/modeling/src/geometries/geom3/create.js index 94cdb2e59..6170c6c60 100644 --- a/packages/modeling/src/geometries/geom3/create.js +++ b/packages/modeling/src/geometries/geom3/create.js @@ -1,27 +1,13 @@ import * as mat4 from '../../maths/mat4/index.js' -/** - * Represents a 3D geometry consisting of a list of polygons. - * @property {Array} polygons - list of polygons, each polygon containing three or more vertices - * @property {Mat4} transforms - transforms to apply to the polygons, see transform() - * @example - * { - * "polygons": [ - * {"vertices": [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]]}, - * {"vertices": [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]]}, - * {"vertices": [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]]}, - * {"vertices": [[-1,1,-1], [-1,1,1], [1,1,1], [1,1,-1]]}, - * {"vertices": [[-1,-1,-1], [-1,1,-1], [1,1,-1], [1,-1,-1]]}, - * {"vertices": [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]]} - * ], - * "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1], - * } - */ - /** * Create a new 3D geometry composed of the given polygons. + * * @param {Array} [polygons] - list of polygons, or undefined * @returns {Geom3} a new geometry - * @alias module:modeling/geometries/geom3.create + * @alias module:modeling/geom3.create + * + * @example + * let geometry = geom3.create() */ export const create = (polygons = []) => ({ polygons, transforms: mat4.create() }) diff --git a/packages/modeling/src/geometries/geom3/fromVertices.js b/packages/modeling/src/geometries/geom3/fromVertices.js index 03962169e..a209650d1 100644 --- a/packages/modeling/src/geometries/geom3/fromVertices.js +++ b/packages/modeling/src/geometries/geom3/fromVertices.js @@ -8,9 +8,21 @@ import { create } from './create.js' * The list of vertices should contain sub-arrays, each defining a single polygon of vertices. * In addition, the vertices should follow the right-hand rule for rotation in order to * define an external facing polygon. + * * @param {Array} listOfLists - list of lists, where each list is a set of vertices to construct a polygon * @returns {Geom3} a new geometry - * @alias module:modeling/geometries/geom3.fromVertices + * @alias module:modeling/geom3.fromVertices + * + * @example + * let vertices = [ + * [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]], + * [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]], + * [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]] + * [[-1,1,-1], [-1,1,1], [1,1,1], [1,1,-1]], + * [[-1,-1,-1], [-1,1,-1], [1,1,-1], [1,-1,-1]], + * [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]] + * ] + * let geometry = geom3.fromVertices(vertices) */ export const fromVertices = (listOfLists) => { if (!Array.isArray(listOfLists)) { diff --git a/packages/modeling/src/geometries/geom3/fromVerticesConvex.js b/packages/modeling/src/geometries/geom3/fromVerticesConvex.js index c2eff16ee..38d74bc68 100644 --- a/packages/modeling/src/geometries/geom3/fromVerticesConvex.js +++ b/packages/modeling/src/geometries/geom3/fromVerticesConvex.js @@ -7,7 +7,7 @@ import * as poly3 from '../poly3/index.js' * * @param {Array} uniqueVertices - list of vertices to construct convex 3D geometry * @returns {geom3} a new geometry - * @alias module:modeling/geometries/geom3.fromVerticesConvex + * @alias module:modeling/geom3.fromVerticesConvex */ export const fromVerticesConvex = (uniqueVertices) => { if (!Array.isArray(uniqueVertices)) { diff --git a/packages/modeling/src/geometries/geom3/index.js b/packages/modeling/src/geometries/geom3/index.js index 871c9c1ae..72fb5b1ad 100644 --- a/packages/modeling/src/geometries/geom3/index.js +++ b/packages/modeling/src/geometries/geom3/index.js @@ -1,11 +1,12 @@ /** * Represents a 3D geometry consisting of a list of polygons. - * @see {@link geom3} for data structure information. - * @module modeling/geometries/geom3 + * + * @see {@link Geom3} for data structure information + * @module modeling/geom3 * * @example - * import { geometries } from '@jscad/modeling' - * const myShape = geometries.geom3.fromVertices([ + * import { geom3 } from '@jscad/modeling' + * const myShape = geom3.fromVertices([ * [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]], * [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]], * [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]] @@ -14,6 +15,26 @@ * [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]] * ]) */ + +/** + * @typedef Geom3 + * @type {Object} + * @property {Array} polygons - list of polygons, each polygon containing three or more vertices + * @property {Mat4} transforms - transforms to apply to the polygons, see transform() + * + * @example + * { + * "polygons": [ + * {"vertices": [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]]}, + * {"vertices": [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]]}, + * {"vertices": [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]]}, + * {"vertices": [[-1,1,-1], [-1,1,1], [1,1,1], [1,1,-1]]}, + * {"vertices": [[-1,-1,-1], [-1,1,-1], [1,1,-1], [1,-1,-1]]}, + * {"vertices": [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]]} + * ], + * "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1], + * } + */ export { clone } from './clone.js' export { create } from './create.js' export { fromVertices } from './fromVertices.js' diff --git a/packages/modeling/src/geometries/geom3/invert.js b/packages/modeling/src/geometries/geom3/invert.js index 94ca72ff8..bc6187a76 100644 --- a/packages/modeling/src/geometries/geom3/invert.js +++ b/packages/modeling/src/geometries/geom3/invert.js @@ -5,9 +5,13 @@ import { toPolygons } from './toPolygons.js' /** * Invert the given geometry, transposing solid and empty space. + * * @param {Geom3} geometry - the geometry to invert * @returns {Geom3} a new geometry - * @alias module:modeling/geometries/geom3.invert + * @alias module:modeling/geom3.invert + * + * @example + * let inverted = geom3.invert(geometry) */ export const invert = (geometry) => { const polygons = toPolygons(geometry) diff --git a/packages/modeling/src/geometries/geom3/isA.js b/packages/modeling/src/geometries/geom3/isA.js index c0fdd063c..c6befd69a 100644 --- a/packages/modeling/src/geometries/geom3/isA.js +++ b/packages/modeling/src/geometries/geom3/isA.js @@ -1,8 +1,12 @@ /** * Determine if the given object is a 3D geometry. + * * @param {object} object - the object to interrogate * @returns {Boolean} true if the object matches a geom3 - * @alias module:modeling/geometries/geom3.isA + * @alias module:modeling/geom3.isA + * + * @example + * if (geom3.isA(geometry)) { ... } */ export const isA = (object) => { if (object && typeof object === 'object') { diff --git a/packages/modeling/src/geometries/geom3/isConvex.js b/packages/modeling/src/geometries/geom3/isConvex.js index 3dbf61d11..1ec339517 100644 --- a/packages/modeling/src/geometries/geom3/isConvex.js +++ b/packages/modeling/src/geometries/geom3/isConvex.js @@ -13,11 +13,10 @@ import { toPolygons } from './toPolygons.js' * * @param {geom3} geometry - the geometry to test * @returns {boolean} true if the geometry is convex - * @alias module:modeling/geometries/geom3.isConvex + * @alias module:modeling/geom3.isConvex * * @example - * const { geom3, primitives } = require('@jscad/modeling') - * const cube = primitives.cuboid({ size: [10, 10, 10] }) + * const cube = cuboid() * console.log(geom3.isConvex(cube)) // true */ export const isConvex = (geometry) => { diff --git a/packages/modeling/src/geometries/geom3/toPolygons.js b/packages/modeling/src/geometries/geom3/toPolygons.js index f1e795c22..d285ba45e 100644 --- a/packages/modeling/src/geometries/geom3/toPolygons.js +++ b/packages/modeling/src/geometries/geom3/toPolygons.js @@ -2,12 +2,14 @@ import { applyTransforms } from './applyTransforms.js' /** * Produces an array of polygons from the given geometry, after applying transforms. + * * The returned array should not be modified as the polygons are shared with the geometry. + * * @param {Geom3} geometry - the geometry * @returns {Array} an array of polygons - * @alias module:modeling/geometries/geom3.toPolygons + * @alias module:modeling/geom3.toPolygons * * @example - * let sharedPolygons = toPolygons(geometry) + * let sharedPolygons = geom3.toPolygons(geometry) */ export const toPolygons = (geometry) => applyTransforms(geometry).polygons diff --git a/packages/modeling/src/geometries/geom3/toString.js b/packages/modeling/src/geometries/geom3/toString.js index 11e321e9e..3b518a703 100644 --- a/packages/modeling/src/geometries/geom3/toString.js +++ b/packages/modeling/src/geometries/geom3/toString.js @@ -4,12 +4,13 @@ import { toPolygons } from './toPolygons.js' /** * Create a string representing the contents of the given geometry. + * * @param {Geom3} geometry - the geometry * @returns {string} a representative string - * @alias module:modeling/geometries/geom3.toString + * @alias module:modeling/geom3.toString * * @example - * console.out(toString(geometry)) + * console.out(geom3.toString(geometry)) */ export const toString = (geometry) => { const polygons = toPolygons(geometry) diff --git a/packages/modeling/src/geometries/geom3/toVertices.js b/packages/modeling/src/geometries/geom3/toVertices.js index f038ff16b..09dbd27cb 100644 --- a/packages/modeling/src/geometries/geom3/toVertices.js +++ b/packages/modeling/src/geometries/geom3/toVertices.js @@ -3,12 +3,16 @@ import * as poly3 from '../poly3/index.js' import { toPolygons } from './toPolygons.js' /** - * Return the given geometry as a list of points, after applying transforms. + * Return the given geometry as a list of vertices, after applying transforms. + * + * The returned array should not be modified as the vertices are shared with the geometry. * - * The returned array should not be modified as the points are shared with the geometry. * @param {Geom3} geometry - the geometry - * @return {Array} list of points, where each sub-array represents a polygon - * @alias module:modeling/geometries/geom3.toVertices + * @return {Array} list of vertices, where each sub-array represents a polygon + * @alias module:modeling/geom3.toVertices + * + * @example + * let sharedVertices = geom3.toVertices(geometry) */ export const toVertices = (geometry) => { const polygons = toPolygons(geometry) diff --git a/packages/modeling/src/geometries/geom3/transform.js b/packages/modeling/src/geometries/geom3/transform.js index 8a975735f..60d86393d 100644 --- a/packages/modeling/src/geometries/geom3/transform.js +++ b/packages/modeling/src/geometries/geom3/transform.js @@ -2,15 +2,18 @@ import * as mat4 from '../../maths/mat4/index.js' /** * Transform the given geometry using the given matrix. + * * This is a lazy transform of the polygons, as this function only adjusts the transforms. + * * See applyTransforms() for the actual application of the transforms to the polygons. + * * @param {Mat4} matrix - the matrix to transform with * @param {Geom3} geometry - the geometry to transform * @returns {Geom3} a new geometry - * @alias module:modeling/geometries/geom3.transform + * @alias module:modeling/geom3.transform * * @example - * let newGeometry = transform(fromXRotation(TAU / 4), geometry) + * let newGeometry = geom3.transform(fromXRotation(TAU / 4), geometry) */ export const transform = (matrix, geometry) => { const transforms = mat4.multiply(mat4.create(), matrix, geometry.transforms) diff --git a/packages/modeling/src/geometries/geom3/validate.js b/packages/modeling/src/geometries/geom3/validate.js index 6e751d37f..297944701 100644 --- a/packages/modeling/src/geometries/geom3/validate.js +++ b/packages/modeling/src/geometries/geom3/validate.js @@ -4,13 +4,17 @@ import { isA } from './isA.js' /** * Determine if the given object is a valid 3D geometry. + * * Checks for valid data structure, convex polygon faces, and manifold edges. * - * **If the geometry is not valid, an exception will be thrown with details of the geometry error.** + * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.** * * @param {object} object - the object to interrogate * @throws {Error} error if the geometry is not valid - * @alias module:modeling/geometries/geom3.validate + * @alias module:modeling/geom3.validate + * + * @example + * if (geom3.validate(geometry)) { ... } */ export const validate = (object) => { if (!isA(object)) { diff --git a/packages/modeling/src/geometries/index.js b/packages/modeling/src/geometries/index.js index 1df95c7cd..6d16e8ba5 100644 --- a/packages/modeling/src/geometries/index.js +++ b/packages/modeling/src/geometries/index.js @@ -1,13 +1,15 @@ /** * Geometries are objects that represent the contents of primitives or the results of operations. + * * Note: Geometries are considered immutable, so never change the contents directly. * - * @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 points - * @see {@link poly3} - 3D polygon consisting of ordered vertices - * @see {@link slice} - 3D geometry consisting of 3D contours + * @see [Geom2]{@link module:modeling/geom2} - 2D geometry consisting of 2D outlines + * @see [Geom3]{@link module:modeling/geom3} - 3D geometry consisting of polygons + * @see [Path2]{@link module:modeling/path2} - 2D geometry consisting of ordered points + * @see [Path3]{@link module:modeling/path3} - 3D geometry consisting of ordered vertices + * @see [Poly2]{@link module:modeling/poly2} - 2D polygon consisting of points + * @see [Poly3]{@link module:modeling/poly3} - 3D polygon consisting of vertices + * @see [Slice]{@link module:modeling/slice} - 3D geometry consisting of 3D contours * * @module modeling/geometries * @example diff --git a/packages/modeling/src/geometries/path2/appendArc.js b/packages/modeling/src/geometries/path2/appendArc.js index 8fcd0730b..ceffea1f9 100644 --- a/packages/modeling/src/geometries/path2/appendArc.js +++ b/packages/modeling/src/geometries/path2/appendArc.js @@ -6,8 +6,10 @@ import { toPoints } from './toPoints.js' /** * Append a series of points to the given geometry that represent an arc. + * * This implementation follows the SVG specifications. * @see http://www.w3.org/TR/SVG/paths.html#PathDataEllipticalArcCommands + * * @param {object} options - options for construction * @param {Vec2} options.endpoint - end point of arc (REQUIRED) * @param {Vec2} [options.radius=[0,0]] - radius of arc (X and Y) @@ -17,12 +19,12 @@ import { toPoints } from './toPoints.js' * @param {number} [options.segments=16] - number of segments per full rotation * @param {Path2} geometry - the path of which to append the arc * @returns {Path2} a new path with the appended points - * @alias module:modeling/geometries/path2.appendArc + * @alias module:modeling/path2.appendArc * * @example - * let myShape = fromPoints({}, [[27.5,-22.96875]]); - * myShape = appendPoints([[27.5,-3.28125]], myShape); - * myShape = appendArc({endpoint: [12.5, -22.96875], radius: [15, -19.6875]}, myShape); + * let myShape = path2.fromPoints({}, [[27.5,-22.96875]]); + * myShape = path2.appendPoints([[27.5,-3.28125]], myShape); + * myShape = path2.appendArc({endpoint: [12.5, -22.96875], radius: [15, -19.6875]}, myShape); */ export const appendArc = (options, geometry) => { const defaults = { diff --git a/packages/modeling/src/geometries/path2/appendBezier.js b/packages/modeling/src/geometries/path2/appendBezier.js index ef7e516b1..58677d7f7 100644 --- a/packages/modeling/src/geometries/path2/appendBezier.js +++ b/packages/modeling/src/geometries/path2/appendBezier.js @@ -7,22 +7,24 @@ import { toPoints } from './toPoints.js' /** * Append a series of points to the given geometry that represent a Bézier curve. + * * The Bézier curve starts at the last point in the given geometry, and ends at the last control point. * The other control points are intermediate control points to transition the curve from start to end points. * The first control point may be null to ensure a smooth transition occurs. In this case, * the second to last point of the given geometry is mirrored into the control points of the Bézier curve. * In other words, the trailing gradient of the geometry matches the new gradient of the curve. + * * @param {object} options - options for construction * @param {Array} options.controlPoints - list of control points (2D) for the Bézier curve * @param {number} [options.segments=16] - number of segments per 360 rotation * @param {Path2} geometry - the path of which to append points * @returns {Path2} a new path with the appended points - * @alias module:modeling/geometries/path2.appendBezier + * @alias module:modeling/path2.appendBezier * * @example - * let myShape = fromPoints({}, [[10,-20]]) - * myShape = appendBezier({controlPoints: [[10,-10],[25,-10],[25,-20]]}, myShape); - * myShape = appendBezier({controlPoints: [null, [25,-30],[40,-30],[40,-20]]}, myShape) + * let myShape = path2.fromPoints({}, [[10,-20]]) + * myShape = path2.appendBezier({controlPoints: [[10,-10],[25,-10],[25,-20]]}, myShape); + * myShape = path2.appendBezier({controlPoints: [null, [25,-30],[40,-30],[40,-20]]}, myShape) */ export const appendBezier = (options, geometry) => { const defaults = { diff --git a/packages/modeling/src/geometries/path2/appendPoints.js b/packages/modeling/src/geometries/path2/appendPoints.js index 5a2e8c635..a4efb9e2c 100644 --- a/packages/modeling/src/geometries/path2/appendPoints.js +++ b/packages/modeling/src/geometries/path2/appendPoints.js @@ -3,11 +3,13 @@ import { create } from './create.js' /** * Append the given list of points to the end of the given geometry. + * * @param {Array} points - the points (2D) to append to the given path * @param {Path2} geometry - the given path * @returns {Path2} a new path with the appended points - * @alias module:modeling/geometries/path2.appendPoints + * @alias module:modeling/path2.appendPoints + * * @example - * let newPath = appendPoints([[3, 4], [4, 5]], oldPath) + * let newPath = path2.appendPoints([[3, 4], [4, 5]], oldPath) */ export const appendPoints = (points, geometry) => concat(geometry, create(points)) diff --git a/packages/modeling/src/geometries/path2/applyTransforms.js b/packages/modeling/src/geometries/path2/applyTransforms.js index 7430f0994..c7d6ed2cf 100644 --- a/packages/modeling/src/geometries/path2/applyTransforms.js +++ b/packages/modeling/src/geometries/path2/applyTransforms.js @@ -3,9 +3,12 @@ import * as vec2 from '../../maths/vec2/index.js' /* * Apply the transforms of the given geometry. + * * NOTE: This function must be called BEFORE exposing any data. See toPoints. + * * @param {path} geometry - the geometry to transform * @returns {path} the given geometry + * * @example * geometry = applyTransforms(geometry) */ diff --git a/packages/modeling/src/geometries/path2/clone.js b/packages/modeling/src/geometries/path2/clone.js index 7d83e70a3..bbcd54bf1 100644 --- a/packages/modeling/src/geometries/path2/clone.js +++ b/packages/modeling/src/geometries/path2/clone.js @@ -1,7 +1,11 @@ /** * Performs a shallow clone of the give geometry. + * * @param {Path2} geometry - the geometry to clone * @returns {Path2} a new path - * @alias module:modeling/geometries/path2.clone + * @alias module:modeling/path2.clone + * + * @example + * let newPath = path2.clone(oldPath) */ export const clone = (geometry) => Object.assign({}, geometry) diff --git a/packages/modeling/src/geometries/path2/close.js b/packages/modeling/src/geometries/path2/close.js index c886fe3c4..54fa3f943 100644 --- a/packages/modeling/src/geometries/path2/close.js +++ b/packages/modeling/src/geometries/path2/close.js @@ -6,9 +6,13 @@ import { clone } from './clone.js' /** * Close the given geometry. + * * @param {Path2} geometry - the path to close * @returns {Path2} a new path - * @alias module:modeling/geometries/path2.close + * @alias module:modeling/path2.close + * + * @example + * let newPath = path2.close(oldPath) */ export const close = (geometry) => { if (geometry.isClosed) return geometry diff --git a/packages/modeling/src/geometries/path2/concat.js b/packages/modeling/src/geometries/path2/concat.js index aeb2286b0..bcdc06bb2 100644 --- a/packages/modeling/src/geometries/path2/concat.js +++ b/packages/modeling/src/geometries/path2/concat.js @@ -10,12 +10,13 @@ import { toPoints } from './toPoints.js' * A concatenation of zero paths is an empty, open path. * A concatenation of one closed path to a series of open paths produces a closed path. * A concatenation of a path to a closed path is an error. + * * @param {...Path2} paths - the paths to concatenate * @returns {Path2} a new path - * @alias module:modeling/geometries/path2.concat + * @alias module:modeling/path2.concat * * @example - * let newPath = concat(fromPoints({}, [[1, 2]]), fromPoints({}, [[3, 4]])) + * let newPath = path2.concat(path2.fromPoints({}, [[1, 2]]), path2.fromPoints({}, [[3, 4]])) */ export const concat = (...paths) => { // Only the last path can be closed, producing a closed path. diff --git a/packages/modeling/src/geometries/path2/create.js b/packages/modeling/src/geometries/path2/create.js index ff76ce163..3160d559f 100644 --- a/packages/modeling/src/geometries/path2/create.js +++ b/packages/modeling/src/geometries/path2/create.js @@ -1,24 +1,12 @@ import * as mat4 from '../../maths/mat4/index.js' -/** - * Represents a 2D geometry consisting of a list of ordered points. - * @property {Array} points - list of ordered points - * @property {boolean} isClosed - true if the path is closed where start and end points are the same - * @property {Mat4} transforms - transforms to apply to the points, see transform() - * @example - * { - * "points": [[0,0], [4,0], [4,3]], - * "isClosed": true, - * "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1], - * } - */ - /** * Create an empty, open path. + * * @returns {Path2} a new path - * @alias module:modeling/geometries/path2.create + * @alias module:modeling/path2.create * * @example - * let newPath = create() + * let newPath = path2.create() */ export const create = (points = []) => ({ points: points, isClosed: false, transforms: mat4.create() }) diff --git a/packages/modeling/src/geometries/path2/equals.js b/packages/modeling/src/geometries/path2/equals.js index 0530d1c30..ac7e38a79 100644 --- a/packages/modeling/src/geometries/path2/equals.js +++ b/packages/modeling/src/geometries/path2/equals.js @@ -3,13 +3,18 @@ import * as vec2 from '../../maths/vec2/index.js' import { toPoints } from './toPoints.js' /** - * Determine if the given paths are equal. - * For closed paths, this includes equality under point order rotation. - * @param {Path2} a - the first path to compare - * @param {Path2} b - the second path to compare - * @returns {Boolean} - * @alias module:modeling/geometries/path2.equals - */ + * Determine if the given paths are equal. + * + * For closed paths, this includes equality under point order rotation. + * + * @param {Path2} a - the first path to compare + * @param {Path2} b - the second path to compare + * @returns {Boolean} + * @alias module:modeling/path2.equals + * + * @example + * if (path2.equals(pathA, pathB)) { ... } + */ export const equals = (a, b) => { if (a.isClosed !== b.isClosed) { return false diff --git a/packages/modeling/src/geometries/path2/fromPoints.js b/packages/modeling/src/geometries/path2/fromPoints.js index 90771ec62..331c715ae 100644 --- a/packages/modeling/src/geometries/path2/fromPoints.js +++ b/packages/modeling/src/geometries/path2/fromPoints.js @@ -7,16 +7,18 @@ import { create } from './create.js' /** * Create a new path from the given points. + * * The points must be provided an array of points, * where each point is an array of two numbers. + * * @param {object} options - options for construction * @param {boolean} [options.closed=false] - if the path should be open or closed * @param {Array} points - array of points (2D) from which to create the path * @returns {Path2} a new path - * @alias module:modeling/geometries/path2.fromPoints + * @alias module:modeling/path2.fromPoints * - * @example: - * my newPath = fromPoints({closed: true}, [[10, 10], [-10, 10]]) + * @example + * my newPath = path2.fromPoints({closed: true}, [[10, 10], [-10, 10]]) */ export const fromPoints = (options, points) => { const defaults = { closed: false } diff --git a/packages/modeling/src/geometries/path2/index.js b/packages/modeling/src/geometries/path2/index.js index a17b19555..63e6b5fd5 100644 --- a/packages/modeling/src/geometries/path2/index.js +++ b/packages/modeling/src/geometries/path2/index.js @@ -1,11 +1,28 @@ /** * Represents a 2D geometry consisting of a list of ordered points. - * @see {@link path2} for data structure information. - * @module modeling/geometries/path2 + * + * @see {@link Path2} for data structure information. + * @module modeling/path2 + * + * @example + * import { path2 } from '@jscad/modeling' + * let myShape = path2.fromPoints({ closed: true }, [[0,0], [4,0], [4,3]]) + */ + +/** + * @typedef Path2 + * @type {Object} + * @property {Array} points - list of ordered points + * @property {boolean} isClosed - true if the path is closed where start and end points are the same + * @property {Mat4} transforms - transforms to apply to the points, see transform() * * @example - * import { geometries } from '@jscad/modeling' - * let myShape = geometries.path2.fromPoints({ closed: true }, [[0,0], [4,0], [4,3]]) + * // data structure + * { + * "points": [[0,0], [4,0], [4,3]], + * "isClosed": true, + * "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1], + * } */ export { appendArc } from './appendArc.js' export { appendBezier } from './appendBezier.js' diff --git a/packages/modeling/src/geometries/path2/isA.js b/packages/modeling/src/geometries/path2/isA.js index 9ac5f2cb1..21830d614 100644 --- a/packages/modeling/src/geometries/path2/isA.js +++ b/packages/modeling/src/geometries/path2/isA.js @@ -1,8 +1,12 @@ /** * Determine if the given object is a path2 geometry. + * * @param {object} object - the object to interrogate * @returns {Boolean} true if the object matches a path2 - * @alias module:modeling/geometries/path2.isA + * @alias module:modeling/path2.isA + * + * @example + * if (path2.isA(geometry)) { ... } */ export const isA = (object) => { if (object && typeof object === 'object') { diff --git a/packages/modeling/src/geometries/path2/reverse.js b/packages/modeling/src/geometries/path2/reverse.js index 965b8c211..867237197 100644 --- a/packages/modeling/src/geometries/path2/reverse.js +++ b/packages/modeling/src/geometries/path2/reverse.js @@ -2,13 +2,15 @@ import { clone } from './clone.js' /** * Reverses the path so that the points are in the opposite order. + * * This swaps the left (interior) and right (exterior) edges. + * * @param {Path2} geometry - the path to reverse * @returns {Path2} a new path - * @alias module:modeling/geometries/path2.reverse + * @alias module:modeling/path2.reverse * * @example - * let newPath = reverse(myPath) + * let newPath = path2.reverse(oldPath) */ export const reverse = (geometry) => { // NOTE: this only updates the order of the points diff --git a/packages/modeling/src/geometries/path2/toPoints.js b/packages/modeling/src/geometries/path2/toPoints.js index e5106c4c5..d739358b6 100644 --- a/packages/modeling/src/geometries/path2/toPoints.js +++ b/packages/modeling/src/geometries/path2/toPoints.js @@ -2,12 +2,14 @@ import { applyTransforms } from './applyTransforms.js' /** * Produces an array of points from the given geometry. - * The returned array should not be modified as the data is shared with the geometry. + * + * NOTE: The returned array should not be modified as the data is shared with the geometry. + * * @param {Path2} geometry - the geometry * @returns {Array} an array of points - * @alias module:modeling/geometries/path2.toPoints + * @alias module:modeling/path2.toPoints * * @example - * let sharedPoints = toPoints(geometry) + * let sharedPoints = path2.toPoints(geometry) */ export const toPoints = (geometry) => applyTransforms(geometry).points diff --git a/packages/modeling/src/geometries/path2/toString.js b/packages/modeling/src/geometries/path2/toString.js index 382e51c0a..bbc9275bc 100644 --- a/packages/modeling/src/geometries/path2/toString.js +++ b/packages/modeling/src/geometries/path2/toString.js @@ -4,12 +4,13 @@ import { toPoints } from './toPoints.js' /** * Create a string representing the contents of the given path. + * * @param {Path2} geometry - the path * @returns {string} a representative string - * @alias module:modeling/geometries/path2.toString + * @alias module:modeling/path2.toString * * @example - * console.out(toString(path)) + * console.out(path2.toString(path)) */ export const toString = (geometry) => { const points = toPoints(geometry) diff --git a/packages/modeling/src/geometries/path2/transform.js b/packages/modeling/src/geometries/path2/transform.js index 81c8ef696..9cc5dff18 100644 --- a/packages/modeling/src/geometries/path2/transform.js +++ b/packages/modeling/src/geometries/path2/transform.js @@ -2,15 +2,17 @@ import * as mat4 from '../../maths/mat4/index.js' /** * Transform the given geometry using the given matrix. + * * This is a lazy transform of the points, as this function only adjusts the transforms. * The transforms are applied when accessing the points via toPoints(). + * * @param {Mat4} matrix - the matrix to transform with * @param {Path2} geometry - the geometry to transform * @returns {Path2} a new path - * @alias module:modeling/geometries/path2.transform + * @alias module:modeling/path2.transform * * @example - * let newPath = transform(fromZRotation(TAU / 8), path) + * let newPath = path2.transform(mat4.fromZRotation(TAU / 8), path) */ export const transform = (matrix, geometry) => { const transforms = mat4.multiply(mat4.create(), matrix, geometry.transforms) diff --git a/packages/modeling/src/geometries/path2/validate.js b/packages/modeling/src/geometries/path2/validate.js index d41b4b47c..50e98aaa2 100644 --- a/packages/modeling/src/geometries/path2/validate.js +++ b/packages/modeling/src/geometries/path2/validate.js @@ -4,13 +4,17 @@ import { isA } from './isA.js' /** * Determine if the given object is a valid path2. + * * Checks for valid data points, and duplicate points. * * **If the geometry is not valid, an exception will be thrown with details of the geometry error.** * * @param {object} object - the object to interrogate * @throws {Error} error if the geometry is not valid - * @alias module:modeling/geometries/path2.validate + * @alias module:modeling/path2.validate + * + * @example + * path2.validate(geometry) */ export const validate = (object) => { if (!isA(object)) { diff --git a/packages/modeling/src/geometries/path3/applyTransforms.js b/packages/modeling/src/geometries/path3/applyTransforms.js index c7430efe7..e68d69401 100644 --- a/packages/modeling/src/geometries/path3/applyTransforms.js +++ b/packages/modeling/src/geometries/path3/applyTransforms.js @@ -11,7 +11,7 @@ import * as vec3 from '../../maths/vec3/index.js' * @function * * @example - * geometry = applyTransforms(geometry) + * geometry = path3.applyTransforms(geometry) */ export const applyTransforms = (geometry) => { if (mat4.isIdentity(geometry.transforms)) return geometry diff --git a/packages/modeling/src/geometries/path3/close.js b/packages/modeling/src/geometries/path3/close.js index 27810b2cd..8ed560a0b 100644 --- a/packages/modeling/src/geometries/path3/close.js +++ b/packages/modeling/src/geometries/path3/close.js @@ -7,8 +7,10 @@ import * as vec3 from '../../maths/vec3/index.js' * * @param {Path3} geometry - the path to close * @returns {Path3} a new path - * @function - * @alias module:modeling/geometries/path3.close + * @alias module:modeling/path3.close + * + * @example + * const newPath = path3.close(oldPath) */ export const close = (geometry) => { if (geometry.isClosed) return geometry diff --git a/packages/modeling/src/geometries/path3/concat.js b/packages/modeling/src/geometries/path3/concat.js index 1e855134f..803f3364f 100644 --- a/packages/modeling/src/geometries/path3/concat.js +++ b/packages/modeling/src/geometries/path3/concat.js @@ -13,11 +13,10 @@ import { toVertices } from './toVertices.js' * * @param {...Path3} paths - the paths to concatenate * @returns {Path3} a new path - * @function - * @alias module:modeling/geometries/path3.concat + * @alias module:modeling/path3.concat * * @example - * let newPath = concat(fromVertices({}, [[1, 2, 3]]), fromVertices({}, [[4, 5, 6]])) + * let newPath = path3.concat(path3.fromVertices({}, [[1, 2, 3]]), path3.fromVertices({}, [[4, 5, 6]])) */ export const concat = (...paths) => { // Only the last path can be closed, producing a closed path. diff --git a/packages/modeling/src/geometries/path3/create.js b/packages/modeling/src/geometries/path3/create.js index 698dd0981..2fda45ee6 100644 --- a/packages/modeling/src/geometries/path3/create.js +++ b/packages/modeling/src/geometries/path3/create.js @@ -1,30 +1,13 @@ import * as mat4 from '../../maths/mat4/index.js' -/** - * Represents a 3D geometry consisting of a list of ordered vertices. - * - * @typedef {Object} Path3 - * @property {Array} vertices - list of ordered vertices - * @property {boolean} isClosed - true if the path is closed where start and end vertices are the same - * @property {Mat4} transforms - transforms to apply to the vertices, see transform() - * - * @example - * { - * vertices: [[0,0,0], [4,0,0], [4,3,0]], - * isClosed: true, - * transforms: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1], - * } - */ - /** * Create an empty, open path. * * @returns {Path3} a new path - * @function - * @alias module:modeling/geometries/path3.create + * @alias module:modeling/path3.create * * @example - * let pathA = create() - * let pathB = create([[0,0,0], [4,0,0], [4,3,0]]) + * let pathA = path3.create() + * let pathB = path3.create([[0,0,0], [4,0,0], [4,3,0]]) */ export const create = (vertices = []) => ({ vertices: vertices, isClosed: false, transforms: mat4.create() }) diff --git a/packages/modeling/src/geometries/path3/equals.js b/packages/modeling/src/geometries/path3/equals.js index 34d4bf279..605635e25 100644 --- a/packages/modeling/src/geometries/path3/equals.js +++ b/packages/modeling/src/geometries/path3/equals.js @@ -10,8 +10,10 @@ import { toVertices } from './toVertices.js' * @param {Path3} a - the first path to compare * @param {Path3} b - the second path to compare * @returns {boolean} - * @function - * @alias module:modeling/geometries/path3.equals + * @alias module:modeling/path3.equals + * + * @example + * if (path3.equals(pathA, pathB)) { ... } */ export const equals = (a, b) => { if (a.isClosed !== b.isClosed) { diff --git a/packages/modeling/src/geometries/path3/fromVertices.js b/packages/modeling/src/geometries/path3/fromVertices.js index 54c5abc5e..69b1ccebf 100644 --- a/packages/modeling/src/geometries/path3/fromVertices.js +++ b/packages/modeling/src/geometries/path3/fromVertices.js @@ -15,11 +15,10 @@ import { create } from './create.js' * @param {boolean} [options.closed=false] - if the path should be open or closed * @param {Array} vertices - array of vertices (3D) from which to create the path * @returns {Path3} a new path - * @function - * @alias module:modeling/geometries/path3.fromVertices + * @alias module:modeling/path3.fromVertices * * @example - * my newPath = fromVertices({closed: true}, [[10, 10, 10], [-10, 10, -10]]) + * my newPath = path3.fromVertices({closed: true}, [[10, 10, 10], [-10, 10, -10]]) */ export const fromVertices = (options, vertices) => { const defaults = { closed: false } diff --git a/packages/modeling/src/geometries/path3/index.js b/packages/modeling/src/geometries/path3/index.js index 60c1a5314..23cd6c76d 100644 --- a/packages/modeling/src/geometries/path3/index.js +++ b/packages/modeling/src/geometries/path3/index.js @@ -2,12 +2,28 @@ * Represents a 3D geometry consisting of a list of ordered vertices. * * @see {@link Path3} for data structure information. - * @module modeling/geometries/path3 + * @module modeling/path3 * * @example * import { path3 } from '@jscad/modeling' * let myShape = path3.fromVertices({ closed: true }, [[0,0,0], [4,0,0], [4,3,0]]) */ + +/** + * @typedef {Object} Path3 + * @property {Array} vertices - list of ordered vertices + * @property {boolean} isClosed - true if the path is closed where start and end vertices are the same + * @property {Mat4} transforms - transforms to apply to the vertices, see transform() + * + * @example + * // data structure + * { + * vertices: [[0,0,0], [4,0,0], [4,3,0]], + * isClosed: true, + * transforms: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1], + * } + */ + export { close } from './close.js' export { concat } from './concat.js' export { create } from './create.js' diff --git a/packages/modeling/src/geometries/path3/isA.js b/packages/modeling/src/geometries/path3/isA.js index ac017f9b9..4dfd9ce4c 100644 --- a/packages/modeling/src/geometries/path3/isA.js +++ b/packages/modeling/src/geometries/path3/isA.js @@ -3,8 +3,10 @@ * * @param {Object} object - the object to interrogate * @returns {boolean} true if the object matches a path3 - * @function - * @alias module:modeling/geometries/path3.isA + * @alias module:modeling/path3.isA + * + * @example + * if (path3.isA(geometry)) { ... } */ export const isA = (object) => { if (object && typeof object === 'object') { diff --git a/packages/modeling/src/geometries/path3/reverse.js b/packages/modeling/src/geometries/path3/reverse.js index 67978e611..be1e791d8 100644 --- a/packages/modeling/src/geometries/path3/reverse.js +++ b/packages/modeling/src/geometries/path3/reverse.js @@ -5,11 +5,10 @@ * * @param {Path3} geometry - the path to reverse * @returns {Path3} a new path - * @function - * @alias module:modeling/geometries/path3.reverse + * @alias module:modeling/path3.reverse * * @example - * let newPath = reverse(path) + * let newPath = path3.reverse(oldPath) */ export const reverse = (geometry) => { // NOTE: this only updates the order of the vertices diff --git a/packages/modeling/src/geometries/path3/toString.js b/packages/modeling/src/geometries/path3/toString.js index 4b1f04284..41bcfeb7c 100644 --- a/packages/modeling/src/geometries/path3/toString.js +++ b/packages/modeling/src/geometries/path3/toString.js @@ -7,11 +7,10 @@ import { toVertices } from './toVertices.js' * * @param {path} geometry - the path * @returns {string} a representative string - * @function - * @alias module:modeling/geometries/path3.toString + * @alias module:modeling/path3.toString * * @example - * console.out(toString(path)) + * console.out(path3.toString(geometry)) */ export const toString = (geometry) => { const vertices = toVertices(geometry) diff --git a/packages/modeling/src/geometries/path3/toVertices.js b/packages/modeling/src/geometries/path3/toVertices.js index 9b8278f50..a14470204 100644 --- a/packages/modeling/src/geometries/path3/toVertices.js +++ b/packages/modeling/src/geometries/path3/toVertices.js @@ -7,10 +7,9 @@ import { applyTransforms } from './applyTransforms.js' * * @param {Path3} geometry - the geometry * @returns {Array} an array of vertices - * @function - * @alias module:modeling/geometries/path3.toVertices + * @alias module:modeling/path3.toVertices * * @example - * let sharedVertices = toVertices(path) + * let sharedVertices = path3.toVertices(geometry) */ export const toVertices = (geometry) => applyTransforms(geometry).vertices diff --git a/packages/modeling/src/geometries/path3/transform.js b/packages/modeling/src/geometries/path3/transform.js index 97aa8b965..df4de233d 100644 --- a/packages/modeling/src/geometries/path3/transform.js +++ b/packages/modeling/src/geometries/path3/transform.js @@ -9,11 +9,10 @@ import * as mat4 from '../../maths/mat4/index.js' * @param {Mat4} matrix - the matrix to transform with * @param {Path3} geometry - the geometry to transform * @returns {Path3} a new path - * @function - * @alias module:modeling/geometries/path3.transform + * @alias module:modeling/path3.transform * * @example - * let newPath = transform(fromZRotation(TAU / 8), path) + * let newPath = path3.transform(mat4.fromZRotation(TAU / 8), oldPath) */ export const transform = (matrix, geometry) => { const transforms = mat4.multiply(mat4.create(), matrix, geometry.transforms) diff --git a/packages/modeling/src/geometries/path3/validate.js b/packages/modeling/src/geometries/path3/validate.js index 6bf15f550..887f10985 100644 --- a/packages/modeling/src/geometries/path3/validate.js +++ b/packages/modeling/src/geometries/path3/validate.js @@ -4,14 +4,17 @@ import { isA } from './isA.js' /** * Determine if the given object is a valid path3. + * * Checks for valid vertices, and duplicate vertices. * - * **If the geometry is not valid, an exception will be thrown with details of the geometry error.** + * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.** * * @param {Object} object - the object to interrogate * @throws {Error} error if the geometry is not valid - * @function - * @alias module:modeling/geometries/path3.validate + * @alias module:modeling/path3.validate + * + * @example + * path3.vaidate(geometry) */ export const validate = (object) => { if (!isA(object)) { diff --git a/packages/modeling/src/geometries/poly2/arePointsInside.js b/packages/modeling/src/geometries/poly2/arePointsInside.js index 3f6ad978f..0d8955955 100644 --- a/packages/modeling/src/geometries/poly2/arePointsInside.js +++ b/packages/modeling/src/geometries/poly2/arePointsInside.js @@ -7,7 +7,10 @@ import { reverse } from './reverse.js' * @param {Array} points - a list of points, where each point is an array with X and Y values * @param {Poly2} polygon - a 2D polygon * @return {number} 1 if all points are inside, 0 if some or none are inside - * @alias module:modeling/geometries/poly2.arePointsInside + * @alias module:modeling/poly2.arePointsInside + * + * @example + * if (poly2.arePointsInside([[0,0], [4,0], [4,3]], geometry) { ... } */ export const arePointsInside = (points, polygon) => { if (points.length === 0) return 0 // nothing to check diff --git a/packages/modeling/src/geometries/poly2/clone.js b/packages/modeling/src/geometries/poly2/clone.js index bf56240e2..341e201d4 100644 --- a/packages/modeling/src/geometries/poly2/clone.js +++ b/packages/modeling/src/geometries/poly2/clone.js @@ -3,6 +3,9 @@ * * @param {Poly2} polygon - polygon to clone * @returns {Poly2} a new polygon - * @alias module:modeling/geometries/poly2.clone + * @alias module:modeling/poly2.clone + * + * @example + * const newPoly = poly2.clone(oldPoly) */ export const clone = (polygon) => Object.assign({}, polygon) diff --git a/packages/modeling/src/geometries/poly2/create.js b/packages/modeling/src/geometries/poly2/create.js index 13335b911..bc4382701 100644 --- a/packages/modeling/src/geometries/poly2/create.js +++ b/packages/modeling/src/geometries/poly2/create.js @@ -1,18 +1,11 @@ -/** - * Represents a 2D polygon consisting of a list of ordered points - * which is closed between start and end points. - * @see https://en.wikipedia.org/wiki/Polygon - * @property {Array} points - list of ordered points (2D) - */ - /** * Creates a new polygon with initial values. * * @param {Array} [points] - list of points (2D) * @returns {Poly2} a new polygon - * @alias module:modeling/geometries/poly2.create + * @alias module:modeling/poly2.create * * @example - * let polygon = create([[0,0], [4,0], [4,3]]) + * let polygon = poly2.create([[0,0], [4,0], [4,3]]) */ export const create = (points = []) => ({ points }) diff --git a/packages/modeling/src/geometries/poly2/index.js b/packages/modeling/src/geometries/poly2/index.js index db20c5c1c..af0f88bc3 100644 --- a/packages/modeling/src/geometries/poly2/index.js +++ b/packages/modeling/src/geometries/poly2/index.js @@ -1,12 +1,24 @@ /** * Represents a 2D polygon consisting of a list of ordered points. - * @see {@link poly2} for data structure information. - * @module modeling/geometries/poly2 + * @see {@link Poly2} for data structure information. + * @module modeling/poly2 * * @example - * import { geometries } from '@jscad/modeling' - * const p1 = geometries.poly2.create([[0,0], [4,0], [4,3]]) + * import { poly2 } from '@jscad/modeling' + * const p1 = poly2.create([[0,0], [4,0], [4,3]]) */ + +/** + * @typedef {Object} Poly2 + * @property {Array} points - list of ordered points (2D) + * + * @example + * // data structure + * { + * points: [[0,0], [4,0], [4,3]], + * } + */ + export { arePointsInside } from './arePointsInside.js' export { clone } from './clone.js' export { create } from './create.js' diff --git a/packages/modeling/src/geometries/poly2/isA.js b/packages/modeling/src/geometries/poly2/isA.js index b3c283721..aad2888d0 100644 --- a/packages/modeling/src/geometries/poly2/isA.js +++ b/packages/modeling/src/geometries/poly2/isA.js @@ -1,8 +1,12 @@ /** * Determine if the given object is a 2D polygon. + * * @param {object} object - the object to interrogate * @returns {Boolean} true if the object matches a poly2 - * @alias module:modeling/geometries/poly2.isA + * @alias module:modeling/poly2.isA + * + * @example + * if (poly2.isA(geometry)) { ... } */ export const isA = (object) => { if (object && typeof object === 'object') { diff --git a/packages/modeling/src/geometries/poly2/isConvex.js b/packages/modeling/src/geometries/poly2/isConvex.js index d6a17fc66..57fdebbd0 100644 --- a/packages/modeling/src/geometries/poly2/isConvex.js +++ b/packages/modeling/src/geometries/poly2/isConvex.js @@ -1,8 +1,12 @@ /** * Check whether the given polygon is convex. + * * @param {Poly2} polygon - the polygon to interrogate * @returns {Boolean} true if convex - * @alias module:modeling/geometries/poly2.isConvex + * @alias module:modeling/poly2.isConvex + * + * @example + * if (poly2.isConvex(geometry)) { ... } */ export const isConvex = (polygon) => { const numPoints = polygon.points.length diff --git a/packages/modeling/src/geometries/poly2/isSimple.js b/packages/modeling/src/geometries/poly2/isSimple.js index a91816baf..ef715e0d5 100644 --- a/packages/modeling/src/geometries/poly2/isSimple.js +++ b/packages/modeling/src/geometries/poly2/isSimple.js @@ -3,9 +3,13 @@ import { intersect } from '../../maths/utils/intersect.js' /** * Check whether the given polygon is simple, i.e. does not intersect itself. * @see https://en.wikipedia.org/wiki/Simple_polygon + * * @param {Poly2} polygon - the polygon to interrogate * @returns {Boolean} true if simple - * @alias module:modeling/geometries/poly2.isSimple + * @alias module:modeling/poly2.isSimple + * + * @example + * if (poly2.isSimple(geometry)) { ... } */ export const isSimple = (polygon) => { const numPoints = polygon.points.length diff --git a/packages/modeling/src/geometries/poly2/measureArea.js b/packages/modeling/src/geometries/poly2/measureArea.js index 908f1bc5b..4a71a9234 100644 --- a/packages/modeling/src/geometries/poly2/measureArea.js +++ b/packages/modeling/src/geometries/poly2/measureArea.js @@ -5,6 +5,9 @@ import { area } from '../../maths/utils/area.js' * * @param {Poly2} polygon - the polygon to measure * @return {number} the area of the polygon - * @alias module:modeling/geometries/poly2.measureArea + * @alias module:modeling/poly2.measureArea + * + * @example + * const area = poly2.measureArea(geometry) */ export const measureArea = (polygon) => area(polygon.points) diff --git a/packages/modeling/src/geometries/poly2/measureBoundingBox.js b/packages/modeling/src/geometries/poly2/measureBoundingBox.js index 34ecce039..4e62087d9 100644 --- a/packages/modeling/src/geometries/poly2/measureBoundingBox.js +++ b/packages/modeling/src/geometries/poly2/measureBoundingBox.js @@ -1,9 +1,14 @@ import * as vec2 from '../../maths/vec2/index.js' /** + * Measure the min and max bounds of the given polygon. + * * @param {Poly2} polygon - the polygon to measure * @returns {Array} an array of two vectors (2D); minimum and maximum coordinates - * @alias module:modeling/geometries/poly2.measureBoundingBox + * @alias module:modeling/poly2.measureBoundingBox + * + * @example + * const bounds = poly2.measureBoundingBox(geometry) */ export const measureBoundingBox = (polygon) => { const points = polygon.points diff --git a/packages/modeling/src/geometries/poly2/reverse.js b/packages/modeling/src/geometries/poly2/reverse.js index 5550c39c8..ea873c9e9 100644 --- a/packages/modeling/src/geometries/poly2/reverse.js +++ b/packages/modeling/src/geometries/poly2/reverse.js @@ -5,7 +5,10 @@ import { create } from './create.js' * * @param {Poly2} polygon - the polygon to reverse * @returns {Poly2} a new polygon - * @alias module:modeling/geometries/poly2.reverse + * @alias module:modeling/poly2.reverse + * + * @example + * let newPoly = poly2.reverse(oldPoly) */ export const reverse = (polygon) => { const points = polygon.points.slice().reverse() diff --git a/packages/modeling/src/geometries/poly2/toPoints.js b/packages/modeling/src/geometries/poly2/toPoints.js index a942725f5..f11de0879 100644 --- a/packages/modeling/src/geometries/poly2/toPoints.js +++ b/packages/modeling/src/geometries/poly2/toPoints.js @@ -1,8 +1,13 @@ /** * Return the given polygon as a list of points. + * * NOTE: The returned array should not be modified as the points are shared with the geometry. + * * @param {Poly2} polygon - the polygon * @return {Array} list of points (2D) - * @alias module:modeling/geometries/poly2.toPoints + * @alias module:modeling/poly2.toPoints + * + * @example + * const sharedPoints = poly2.toPoints(geometry) */ export const toPoints = (polygon) => polygon.points diff --git a/packages/modeling/src/geometries/poly2/toString.js b/packages/modeling/src/geometries/poly2/toString.js index 0436e9313..1f5244351 100644 --- a/packages/modeling/src/geometries/poly2/toString.js +++ b/packages/modeling/src/geometries/poly2/toString.js @@ -2,8 +2,12 @@ import * as vec2 from '../../maths/vec2/index.js' /** * Convert the given polygon to a readable string. + * * @param {Poly2} polygon - the polygon to convert * @return {String} the string representation - * @alias module:modeling/geometries/poly2.toString + * @alias module:modeling/poly2.toString + * + * @example + * console.log(poly2.toString(geometry)) */ export const toString = (polygon) => `poly2: [${polygon.points.map(vec2.toString).join(', ')}]` diff --git a/packages/modeling/src/geometries/poly2/transform.js b/packages/modeling/src/geometries/poly2/transform.js index 6ccc5c460..c82958297 100644 --- a/packages/modeling/src/geometries/poly2/transform.js +++ b/packages/modeling/src/geometries/poly2/transform.js @@ -5,10 +5,14 @@ import { create } from './create.js' /** * Transform the given polygon using the given matrix. + * * @param {Mat4} matrix - the matrix to transform with * @param {Poly2} polygon - the polygon to transform * @returns {Poly2} a new polygon - * @alias module:modeling/geometries/poly2.transform + * @alias module:modeling/poly2.transform + * + * @example + * let newPoly = poly2.transfrom(oldPoly) */ export const transform = (matrix, polygon) => { const points = polygon.points.map((point) => vec2.transform(vec2.create(), point, matrix)) diff --git a/packages/modeling/src/geometries/poly2/validate.js b/packages/modeling/src/geometries/poly2/validate.js index bff2a0879..21f6ab35d 100644 --- a/packages/modeling/src/geometries/poly2/validate.js +++ b/packages/modeling/src/geometries/poly2/validate.js @@ -5,13 +5,17 @@ import { measureArea } from './measureArea.js' /** * Determine if the given object is a valid polygon. + * * Checks for valid data structure, convex polygons, and duplicate points. * - * **If the geometry is not valid, an exception will be thrown with details of the geometry error.** + * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.** * * @param {object} object - the object to interrogate * @throws {Error} error if the geometry is not valid - * @alias module:modeling/geometries/poly2.validate + * @alias module:modeling/poly2.validate + * + * @example + * poly2.validate(geometry) */ export const validate = (object) => { if (!isA(object)) { diff --git a/packages/modeling/src/geometries/poly3/clone.js b/packages/modeling/src/geometries/poly3/clone.js index 29d7a7e1d..b347be5dc 100644 --- a/packages/modeling/src/geometries/poly3/clone.js +++ b/packages/modeling/src/geometries/poly3/clone.js @@ -8,7 +8,10 @@ import { create } from './create.js' * @param {Poly3} [out] - receiving polygon * @param {Poly3} polygon - polygon to clone * @returns {Poly3} a new polygon - * @alias module:modeling/geometries/poly3.clone + * @alias module:modeling/poly3.clone + * + * @example + * const newPoly = poly3.clone(oldPoly) */ export const clone = (...params) => { let out diff --git a/packages/modeling/src/geometries/poly3/create.js b/packages/modeling/src/geometries/poly3/create.js index 3db8c4fd8..db473d293 100644 --- a/packages/modeling/src/geometries/poly3/create.js +++ b/packages/modeling/src/geometries/poly3/create.js @@ -1,19 +1,11 @@ -/** - * Represents a convex 3D polygon. The vertices used to initialize a polygon must - * be coplanar and form a convex shape. The vertices do not have to be `vec3` - * instances but they must behave similarly. - * @property {Array} vertices - list of ordered vertices (3D) - * @example - * {"vertices": [[0,0,0], [4,0,0], [4,3,12]]} - */ - /** * Creates a new 3D polygon with initial values. * * @param {Array} [vertices] - a list of vertices (3D) * @returns {Poly3} a new polygon - * @alias module:modeling/geometries/poly3.create + * @alias module:modeling/poly3.create + * * @example - * const polygon = create([[1, 0], [0, 1], [0, 0]]) + * const polygon = poly3.create([[1, 0], [0, 1], [0, 0]]) */ export const create = (vertices = []) => ({ vertices }) diff --git a/packages/modeling/src/geometries/poly3/fromVerticesAndPlane.js b/packages/modeling/src/geometries/poly3/fromVerticesAndPlane.js index 2d5e48672..41b23197b 100644 --- a/packages/modeling/src/geometries/poly3/fromVerticesAndPlane.js +++ b/packages/modeling/src/geometries/poly3/fromVerticesAndPlane.js @@ -2,11 +2,13 @@ import { create } from './create.js' /** * Create a polygon from the given vertices and plane. + * * NOTE: No checks are performed on the parameters. + * * @param {Array} vertices - list of vertices (3D) * @param {Plane} plane - plane of the polygon * @returns {Poly3} a new polygon - * @alias module:modeling/geometries/poly3.fromVerticesAndPlane + * @alias module:modeling/poly3.fromVerticesAndPlane */ export const fromVerticesAndPlane = (vertices, plane) => { const poly = create(vertices) diff --git a/packages/modeling/src/geometries/poly3/index.js b/packages/modeling/src/geometries/poly3/index.js index 9d0d4f5ba..c06bba8cd 100644 --- a/packages/modeling/src/geometries/poly3/index.js +++ b/packages/modeling/src/geometries/poly3/index.js @@ -1,12 +1,27 @@ /** * Represents a convex 3D polygon consisting of a list of ordered vertices. - * @see {@link poly3} for data structure information. - * @module modeling/geometries/poly3 + * + * The vertices used to initialize a polygon must be coplanar and form a convex shape. + * + * @see {@link Poly3} for data structure information. + * @module modeling/poly3 + * + * @example + * import { poly3 } from '@jscad/modeling' + * const polygon = poly3.create([[0,0,0], [4,0,0], [4,3,12]]) + */ + +/** + * @typedef {Object} Poly3 + * @property {Array} vertices - list of ordered vertices (3D) * * @example - * import { geometries } from '@jscad/modeling' - * const polygon = geometries.poly3.create([[0,0,0], [4,0,0], [4,3,12]]) + * // data structure + * { + * vertices: [[0,0,0], [4,0,0], [4,3,12]] + * } */ + export { clone } from './clone.js' export { create } from './create.js' export { fromVerticesAndPlane } from './fromVerticesAndPlane.js' diff --git a/packages/modeling/src/geometries/poly3/invert.js b/packages/modeling/src/geometries/poly3/invert.js index 609ec40ec..aa5196951 100644 --- a/packages/modeling/src/geometries/poly3/invert.js +++ b/packages/modeling/src/geometries/poly3/invert.js @@ -7,7 +7,10 @@ import { create } from './create.js' * * @param {Poly3} polygon - the polygon to invert * @returns {Poly3} a new poly3 - * @alias module:modeling/geometries/poly3.invert + * @alias module:modeling/poly3.invert + * + * @example + * const newPoly = poly3.invert(oldPoly) */ export const invert = (polygon) => { const vertices = polygon.vertices.slice().reverse() diff --git a/packages/modeling/src/geometries/poly3/isA.js b/packages/modeling/src/geometries/poly3/isA.js index 2dbbef03b..378eae8c0 100644 --- a/packages/modeling/src/geometries/poly3/isA.js +++ b/packages/modeling/src/geometries/poly3/isA.js @@ -1,8 +1,12 @@ /** * Determine if the given object is a polygon. + * * @param {object} object - the object to interrogate * @returns {Boolean} true if the object matches a poly3 - * @alias module:modeling/geometries/poly3.isA + * @alias module:modeling/poly3.isA + * + * @example + * if (poly3.isA(geometry)) { ... } */ export const isA = (object) => { if (object && typeof object === 'object') { diff --git a/packages/modeling/src/geometries/poly3/isConvex.js b/packages/modeling/src/geometries/poly3/isConvex.js index 6e1a08184..07c7df7e2 100644 --- a/packages/modeling/src/geometries/poly3/isConvex.js +++ b/packages/modeling/src/geometries/poly3/isConvex.js @@ -3,9 +3,13 @@ import * as vec3 from '../../maths/vec3/index.js' /** * Check whether the given polygon is convex. + * * @param {Poly3} polygon - the polygon to interrogate * @returns {Boolean} true if convex - * @alias module:modeling/geometries/poly3.isConvex + * @alias module:modeling/poly3.isConvex + * + * @example + * if (poly3.isConvex(geometry)) { ... } */ export const isConvex = (polygon) => areVerticesConvex(polygon.vertices) diff --git a/packages/modeling/src/geometries/poly3/measureArea.js b/packages/modeling/src/geometries/poly3/measureArea.js index c61bdd748..8eaeeb7c4 100644 --- a/packages/modeling/src/geometries/poly3/measureArea.js +++ b/packages/modeling/src/geometries/poly3/measureArea.js @@ -3,9 +3,13 @@ import { plane } from './plane.js' /** * Measure the area of the given polygon. * @see 2000 softSurfer http://geomalgorithms.com + * * @param {Poly3} polygon - the polygon to measure * @return {number} area of the polygon - * @alias module:modeling/geometries/poly3.measureArea + * @alias module:modeling/poly3.measureArea + * + * @example + * const area = poly3.measureArea(polyA) */ export const measureArea = (polygon) => { const n = polygon.vertices.length diff --git a/packages/modeling/src/geometries/poly3/measureBoundingBox.js b/packages/modeling/src/geometries/poly3/measureBoundingBox.js index 5f2e0636d..6d07859d7 100644 --- a/packages/modeling/src/geometries/poly3/measureBoundingBox.js +++ b/packages/modeling/src/geometries/poly3/measureBoundingBox.js @@ -5,7 +5,10 @@ import * as vec3 from '../../maths/vec3/index.js' * * @param {Poly3} polygon - the polygon to measure * @returns {Array} an array of two vectors (3D); minimum and maximum coordinates - * @alias module:modeling/geometries/poly3.measureBoundingBox + * @alias module:modeling/poly3.measureBoundingBox + * + * @example + * const bounds = poly3.measureBoundingBox(polyA) */ export const measureBoundingBox = (polygon) => { const vertices = polygon.vertices diff --git a/packages/modeling/src/geometries/poly3/measureBoundingSphere.js b/packages/modeling/src/geometries/poly3/measureBoundingSphere.js index bdf8f9756..8c4d09a5f 100644 --- a/packages/modeling/src/geometries/poly3/measureBoundingSphere.js +++ b/packages/modeling/src/geometries/poly3/measureBoundingSphere.js @@ -6,7 +6,10 @@ const cache = new WeakMap() * @param {Vec4} out - receiving vector * @param {Poly3} polygon - the polygon to measure * @returns {Vec4} the computed bounding sphere; center vertex (3D) and radius - * @alias module:modeling/geometries/poly3.measureBoundingSphere + * @alias module:modeling/poly3.measureBoundingSphere + * + * @example + * const bounds = poly2.measureBoundingSphere(polyA) */ export const measureBoundingSphere = (out, polygon) => { const vertices = polygon.vertices diff --git a/packages/modeling/src/geometries/poly3/measureSignedVolume.js b/packages/modeling/src/geometries/poly3/measureSignedVolume.js index 7f4131bab..cd65959ca 100644 --- a/packages/modeling/src/geometries/poly3/measureSignedVolume.js +++ b/packages/modeling/src/geometries/poly3/measureSignedVolume.js @@ -2,12 +2,17 @@ import * as vec3 from '../../maths/vec3/index.js' /** * Measure the signed volume of the given polygon, which must be convex. + * * The volume is that formed by the tetrahedron connected to the axis [0,0,0], * and will be positive or negative based on the rotation of the vertices. * @see http://chenlab.ece.cornell.edu/Publication/Cha/icip01_Cha.pdf + * * @param {Poly3} polygon - the polygon to measure * @return {number} volume of the polygon - * @alias module:modeling/geometries/poly3.measureSignedVolume + * @alias module:modeling/poly3.measureSignedVolume + * + * @example + * const volume = poly3.measureSignedVolumne(polyA) */ export const measureSignedVolume = (polygon) => { let signedVolume = 0 diff --git a/packages/modeling/src/geometries/poly3/plane.js b/packages/modeling/src/geometries/poly3/plane.js index 1cbf05b9c..008abe0c7 100644 --- a/packages/modeling/src/geometries/poly3/plane.js +++ b/packages/modeling/src/geometries/poly3/plane.js @@ -1,5 +1,8 @@ import * as mplane from '../../maths/plane/index.js' +/** + * Determine the plane of the given polygon. + */ export const plane = (polygon) => { if (!polygon.plane) { polygon.plane = mplane.fromPoints(mplane.create(), ...polygon.vertices) diff --git a/packages/modeling/src/geometries/poly3/toString.js b/packages/modeling/src/geometries/poly3/toString.js index b3310a626..558a78ddb 100644 --- a/packages/modeling/src/geometries/poly3/toString.js +++ b/packages/modeling/src/geometries/poly3/toString.js @@ -2,8 +2,12 @@ import * as vec3 from '../../maths/vec3/index.js' /** * Convert the given polygon to a readable string. + * * @param {Poly3} polygon - the polygon to convert * @return {String} the string representation - * @alias module:modeling/geometries/poly3.toString + * @alias module:modeling/poly3.toString + * + * @example + * console.log(poly3.toString(polyA)) */ export const toString = (polygon) => `poly3: [${polygon.vertices.map(vec3.toString).join(', ')}]` diff --git a/packages/modeling/src/geometries/poly3/toVertices.js b/packages/modeling/src/geometries/poly3/toVertices.js index f7bab9901..87994e665 100644 --- a/packages/modeling/src/geometries/poly3/toVertices.js +++ b/packages/modeling/src/geometries/poly3/toVertices.js @@ -1,8 +1,13 @@ /** * Return the given polygon as a list of vertices. + * * NOTE: The returned array should not be modified as the vertices are shared with the geometry. + * * @param {Poly3} polygon - the polygon * @return {Array} list of vertices (3D) - * @alias module:modeling/geometries/poly3.toVertices + * @alias module:modeling/poly3.toVertices + * + * @example + * const sharedVertices = poly3.toVertices(polyA) */ export const toVertices = (polygon) => polygon.vertices diff --git a/packages/modeling/src/geometries/poly3/transform.js b/packages/modeling/src/geometries/poly3/transform.js index 258e42436..9cd721181 100644 --- a/packages/modeling/src/geometries/poly3/transform.js +++ b/packages/modeling/src/geometries/poly3/transform.js @@ -5,10 +5,14 @@ import { create } from './create.js' /** * Transform the given polygon using the given matrix. + * * @param {Mat4} matrix - the matrix to transform with * @param {Poly3} polygon - the polygon to transform * @returns {Poly3} a new polygon - * @alias module:modeling/geometries/poly3.transform + * @alias module:modeling/poly3.transform + * + * @example + * const newPoly = poly3.transform(oldPoly) */ export const transform = (matrix, polygon) => { const vertices = polygon.vertices.map((vertex) => vec3.transform(vec3.create(), vertex, matrix)) diff --git a/packages/modeling/src/geometries/poly3/validate.js b/packages/modeling/src/geometries/poly3/validate.js index 8f0fedfbf..583a52c1a 100644 --- a/packages/modeling/src/geometries/poly3/validate.js +++ b/packages/modeling/src/geometries/poly3/validate.js @@ -9,13 +9,17 @@ import { plane } from './plane.js' /** * Determine if the given object is a valid polygon. + * * Checks for valid data structure, convex polygons, and duplicate vertices. * - * **If the geometry is not valid, an exception will be thrown with details of the geometry error.** + * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.** * * @param {object} object - the object to interrogate * @throws {Error} error if the geometry is not valid - * @alias module:modeling/geometries/poly3.validate + * @alias module:modeling/poly3.validate + * + * @example + * poly3.validate(geometry) */ export const validate = (object) => { if (!isA(object)) { diff --git a/packages/modeling/src/geometries/slice/calculatePlane.js b/packages/modeling/src/geometries/slice/calculatePlane.js index 1ea5d80de..b62720a7d 100644 --- a/packages/modeling/src/geometries/slice/calculatePlane.js +++ b/packages/modeling/src/geometries/slice/calculatePlane.js @@ -3,13 +3,13 @@ import * as vec3 from '../../maths/vec3/index.js' /** * Calculate the plane of the given slice. - * NOTE: The slice (and all vertices) are assumed to be planar from the beginning. + * * @param {Slice} slice - the slice * @returns {Plane} the plane of the slice - * @alias module:modeling/geometries/slice.calculatePlane + * @alias module:modeling/slice.calculatePlane * * @example - * let myPlane = calculatePlane(slice) + * const plane = slice.calculatePlane(sliceA) */ export const calculatePlane = (slice) => { if (slice.contours.length < 1) { diff --git a/packages/modeling/src/geometries/slice/clone.js b/packages/modeling/src/geometries/slice/clone.js index cf7abd490..03249aff9 100644 --- a/packages/modeling/src/geometries/slice/clone.js +++ b/packages/modeling/src/geometries/slice/clone.js @@ -4,6 +4,9 @@ * * @param {Slice} slice - slice to clone * @returns {Slice} a new slice - * @alias module:modeling/geometries/slice.clone + * @alias module:modeling/slice.clone + * + * @example + * const newSlice = slice.clone(oldSlice) */ export const clone = (slice) => Object.assign({}, slice) diff --git a/packages/modeling/src/geometries/slice/create.js b/packages/modeling/src/geometries/slice/create.js index c0ad1a081..d59e1bfa0 100644 --- a/packages/modeling/src/geometries/slice/create.js +++ b/packages/modeling/src/geometries/slice/create.js @@ -1,18 +1,13 @@ -/** - * Represents a 3D geometry consisting of a list of contours, - * where each contour consists of a list of planar vertices. - * @property {Array} contours - list of contours, each contour containing a list of 3D vertices - * @example - * {"contours": [[[0,0,1], [4,0,1], [4,3,1]]]} - */ - /** * Creates a new slice from the given contours. * + * NOTE: The slice (and all vertices) are assumed to be planar from the beginning. + * * @param {Array} [contours] - a list of contours, where each contour contains a list of vertices (3D) * @returns {Slice} a new slice - * @alias module:modeling/geometries/slice.create + * @alias module:modeling/slice.create + * * @example - * const slice = create([ [[0,0,1], [4,0,1], [4,3,1]] ]) + * const slice = slice.create([ [[0,0,1], [4,0,1], [4,3,1]] ]) */ export const create = (contours = []) => ({ contours }) diff --git a/packages/modeling/src/geometries/slice/equals.js b/packages/modeling/src/geometries/slice/equals.js index b88aae491..f93aaa288 100644 --- a/packages/modeling/src/geometries/slice/equals.js +++ b/packages/modeling/src/geometries/slice/equals.js @@ -2,10 +2,14 @@ import * as vec3 from '../../maths/vec3/index.js' /** * Determine if the given slices have the same contours. + * * @param {Slice} a - the first slice to compare * @param {Slice} b - the second slice to compare * @returns {Boolean} true if the slices are equal - * @alias module:modeling/geometries/slice.equals + * @alias module:modeling/slice.equals + * + * @example + * if (slice.equals(sliceA, sliceB)) { ... } */ export const equals = (a, b) => { if (a.contours.length !== b.contours.length) { diff --git a/packages/modeling/src/geometries/slice/fromGeom2.js b/packages/modeling/src/geometries/slice/fromGeom2.js index 058bebccf..64c026a78 100644 --- a/packages/modeling/src/geometries/slice/fromGeom2.js +++ b/packages/modeling/src/geometries/slice/fromGeom2.js @@ -8,7 +8,7 @@ import { create } from './create.js' * * @param {object} geometry - the 2D geometry to create a slice from * @returns {Slice} a new slice - * @alias module:modeling/geometries/slice.fromGeom2 + * @alias module:modeling/slice.fromGeom2 */ export const fromGeom2 = (geometry) => { // Convert from 2D points to 3D vertices diff --git a/packages/modeling/src/geometries/slice/fromVertices.js b/packages/modeling/src/geometries/slice/fromVertices.js index dc0554c81..836040cc9 100644 --- a/packages/modeling/src/geometries/slice/fromVertices.js +++ b/packages/modeling/src/geometries/slice/fromVertices.js @@ -3,11 +3,11 @@ import * as vec3 from '../../maths/vec3/index.js' import { create } from './create.js' /** - * Create a slice from the given vertices. + * Create a slice with a single contour from the given vertices. * * @param {Array} vertices - list of vertices, where each vertex is either 2D or 3D * @returns {Slice} a new slice - * @alias module:modeling/geometries/slice.fromVertices + * @alias module:modeling/slice.fromVertices * * @example * const vertices = [ @@ -15,7 +15,7 @@ import { create } from './create.js' * [0, 10, 3], * [0, 10, 6] * ] - * const slice = fromVertices(vertices) + * const slice = slice.fromVertices(vertices) */ export const fromVertices = (vertices) => { if (!Array.isArray(vertices)) throw new Error('the given vertices must be an array') diff --git a/packages/modeling/src/geometries/slice/index.js b/packages/modeling/src/geometries/slice/index.js index 38fb7faf2..51e1d90b1 100644 --- a/packages/modeling/src/geometries/slice/index.js +++ b/packages/modeling/src/geometries/slice/index.js @@ -1,12 +1,27 @@ /** * Represents a 3D geometry consisting of a list of contours, where each contour consists of a list of planar vertices. - * @see {@link slice} for data structure information. - * @module modeling/geometries/slice + * @see {@link Slice} for data structure information. + * @module modeling/slice * * @example - * import { geometries } from '@jscad/modeling' - * const slice = geometries.slice.create([[[0,0,0], [4,0,0], [4,3,12]]]) + * import { slice } from '@jscad/modeling' + * const slice = slice.create([[[0,0,0], [4,0,0], [4,3,12]]]) */ + +/** + * @typedef Slice + * @type {Object} + * @property {Array} contours - list of contours, each contour containing a list of 3D vertices + * + * @example + * // data structure + * { + * contours: [ + * [[0,0,1], [4,0,1], [4,3,1]] + * ] + * } + */ + export { calculatePlane } from './calculatePlane.js' export { clone } from './clone.js' export { create } from './create.js' diff --git a/packages/modeling/src/geometries/slice/isA.js b/packages/modeling/src/geometries/slice/isA.js index 6fb5372b2..92ad27038 100644 --- a/packages/modeling/src/geometries/slice/isA.js +++ b/packages/modeling/src/geometries/slice/isA.js @@ -1,8 +1,12 @@ /** * Determine if the given object is a slice. + * * @param {Slice} object - the object to interrogate * @returns {Boolean} true if the object matches a slice - * @alias module:modeling/geometries/slice.isA + * @alias module:modeling/slice.isA + * + * @example + * if (slice.isA(geometry)) { ... } */ export const isA = (object) => { if (object && typeof object === 'object') { diff --git a/packages/modeling/src/geometries/slice/reverse.js b/packages/modeling/src/geometries/slice/reverse.js index f3fb9025f..402015517 100644 --- a/packages/modeling/src/geometries/slice/reverse.js +++ b/packages/modeling/src/geometries/slice/reverse.js @@ -1,11 +1,14 @@ import { create } from './create.js' /** - * Reverse the edges of the given slice. + * Reverse the contours of the given slice. * * @param {Slice} slice - slice to reverse * @returns {Slice} reverse of the slice - * @alias module:modeling/geometries/slice.reverse + * @alias module:modeling/slice.reverse + * + * @example + * const newSlice = slice.reverse(oldSlice) */ export const reverse = (slice) => { // reverse each contour diff --git a/packages/modeling/src/geometries/slice/toEdges.js b/packages/modeling/src/geometries/slice/toEdges.js index 331873203..95e40406b 100644 --- a/packages/modeling/src/geometries/slice/toEdges.js +++ b/packages/modeling/src/geometries/slice/toEdges.js @@ -1,12 +1,14 @@ /** * Produces an array of edges from the given slice. - * The returned array should not be modified as the data is shared with the slice. + * + * NOTE: The returned array should not be modified as the data is shared with the slice. + * * @param {Slice} slice - the slice * @returns {Array} an array of edges, each edge contains an array of two vertices (3D) - * @alias module:modeling/geometries/slice.toEdges + * @alias module:modeling/slice.toEdges * * @example - * let sharedEdges = toEdges(slice) + * let sharedEdges = slice.toEdges(slice) */ export const toEdges = (slice) => { const edges = [] diff --git a/packages/modeling/src/geometries/slice/toPolygons.js b/packages/modeling/src/geometries/slice/toPolygons.js index 8f63bb262..fcb8c0fa5 100644 --- a/packages/modeling/src/geometries/slice/toPolygons.js +++ b/packages/modeling/src/geometries/slice/toPolygons.js @@ -5,9 +5,13 @@ import { PolygonHierarchy } from './earcut/polygonHierarchy.js' /** * Return a list of polygons which are enclosed by the slice. + * * @param {Slice} slice - the slice * @return {Array} a list of polygons (3D) - * @alias module:modeling/geometries/slice.toPolygons + * @alias module:modeling/slice.toPolygons + * + * @example + * const polygons = slice.toPolygons(sliceA) */ export const toPolygons = (slice) => { const hierarchy = new PolygonHierarchy(slice) diff --git a/packages/modeling/src/geometries/slice/toString.js b/packages/modeling/src/geometries/slice/toString.js index 6e8c81cbf..5e1350d2d 100644 --- a/packages/modeling/src/geometries/slice/toString.js +++ b/packages/modeling/src/geometries/slice/toString.js @@ -2,9 +2,13 @@ import * as vec3 from '../../maths/vec3/index.js' /** * Convert the given slice to a readable string. + * * @param {Slice} slice - the slice * @return {String} the string representation - * @alias module:modeling/geometries/slice.toString + * @alias module:modeling/slice.toString + * + * @example + * console.log(slice.toString(sliceA)) */ export const toString = (slice) => { let result = 'slice (' + slice.contours.length + ' contours):\n[\n' diff --git a/packages/modeling/src/geometries/slice/toVertices.js b/packages/modeling/src/geometries/slice/toVertices.js index bddbe66e1..da3cf2e59 100644 --- a/packages/modeling/src/geometries/slice/toVertices.js +++ b/packages/modeling/src/geometries/slice/toVertices.js @@ -1,12 +1,14 @@ /** * Produces an array of vertices from the given slice. - * The returned array should not be modified as the data is shared with the slice. + * + * NOTE: The returned array should not be modified as the data is shared with the slice. + * * @param {Slice} slice - the slice * @returns {Array} an array of 3D vertices - * @alias module:modeling/geometries/slice.toVertices + * @alias module:modeling/slice.toVertices * * @example - * let sharedVertices = toVertices(slice) + * let sharedVertices = slice.toVertices(slice) */ export const toVertices = (slice) => { const vertices = [] diff --git a/packages/modeling/src/geometries/slice/transform.js b/packages/modeling/src/geometries/slice/transform.js index 28649d96e..935b995e5 100644 --- a/packages/modeling/src/geometries/slice/transform.js +++ b/packages/modeling/src/geometries/slice/transform.js @@ -4,14 +4,15 @@ import { create } from './create.js' /** * Transform the given slice using the given matrix. + * * @param {Mat4} matrix - transform matrix * @param {Slice} slice - slice to transform * @returns {Slice} the transformed slice - * @alias module:modeling/geometries/slice.transform + * @alias module:modeling/slice.transform * * @example - * let matrix = mat4.fromTranslation([1, 2, 3]) - * let newSlice = transform(matrix, oldSlice) + * const matrix = mat4.fromTranslation([1, 2, 3]) + * const newSlice = slice.transform(matrix, oldSlice) */ export const transform = (matrix, slice) => { const contours = slice.contours.map((contour) => contour.map((vertex) => vec3.transform(vec3.create(), vertex, matrix))) diff --git a/packages/modeling/src/geometries/slice/validate.js b/packages/modeling/src/geometries/slice/validate.js index 5cb1ff29f..60634c48a 100644 --- a/packages/modeling/src/geometries/slice/validate.js +++ b/packages/modeling/src/geometries/slice/validate.js @@ -6,13 +6,14 @@ import { isA } from './isA.js' /** * Determine if the given object is a valid slice. + * * Checks for valid data points. * - * **If the geometry is not valid, an exception will be thrown with details of the geometry error.** + * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.** * * @param {object} object - the object to interrogate * @throws {Error} error if the geometry is not valid - * @alias module:modeling/geometries/slice.validate + * @alias module:modeling/slice.validate */ export const validate = (object) => { if (!isA(object)) { diff --git a/packages/modeling/src/index.js b/packages/modeling/src/index.js index 00c303627..2ed992492 100644 --- a/packages/modeling/src/index.js +++ b/packages/modeling/src/index.js @@ -1,3 +1,6 @@ +/** + * @module modeling + */ export * from './colors/index.js' export * from './curves/index.js' export * from './geometries/index.js' diff --git a/packages/modeling/src/maths/constants.js b/packages/modeling/src/maths/constants.js index f867e270e..d04a82496 100644 --- a/packages/modeling/src/maths/constants.js +++ b/packages/modeling/src/maths/constants.js @@ -1,19 +1,21 @@ /** * Epsilon used during determination of near zero distances. - * This should be 1 / spacialResolution. - * @default + * + * @constant * @alias module:modeling/maths.EPS * @example - * const { EPS } = maths.constants + * import { EPS } from '@jscad/modeling' */ export const EPS = 1e-5 /** * Smaller epsilon used for measuring near zero distances. - * @default + * + * @constant + * @static * @alias module:modeling/maths.NEPS * @example - * const { NEPS } = maths.constants + * import { NEPS } from '@jscad/modeling' */ export const NEPS = 1e-13 // NEPS is derived from a series of tests to determine the optimal precision @@ -22,10 +24,12 @@ export const NEPS = 1e-13 /** * The TAU property represents the ratio of the circumference of a circle to its radius. + * * Approximately 6.28318530717958647692 + * + * @constant * @alias module:modeling/maths.TAU - * @default * @example - * const { TAU } = maths.constants + * import { TAU } from '@jscad/modeling' */ export const TAU = Math.PI * 2 diff --git a/packages/modeling/src/maths/index.js b/packages/modeling/src/maths/index.js index 38419a5a1..5b3bf7a9b 100644 --- a/packages/modeling/src/maths/index.js +++ b/packages/modeling/src/maths/index.js @@ -1,10 +1,11 @@ /** * Maths are computational units for fundamental Euclidean geometry. All maths operate upon array data structures. + * * Note: Maths data structures are considered immutable, so never change the contents directly. * @see Most computations are based upon the glMatrix library (glmatrix.net) * @module modeling/maths * @example - * import { constants, line2, line3, mat4, plane, utils, vec2, vec3, vec4 } from '@jscad/modeling' + * import { TAU, line2, line3, mat4, plane, utils, vec2, vec3, vec4 } from '@jscad/modeling' */ export * from './constants.js' export * as line2 from './line2/index.js' diff --git a/packages/modeling/src/operations/booleans/index.js b/packages/modeling/src/operations/booleans/index.js index b9f5c4115..d9e60e2b2 100644 --- a/packages/modeling/src/operations/booleans/index.js +++ b/packages/modeling/src/operations/booleans/index.js @@ -1,8 +1,8 @@ /** * All shapes (primitives or the results of operations) can be passed to boolean functions * to perform logical operations, e.g. remove a hole from a board. + * * In all cases, the function returns the results, and never changes the original shapes. - * @module modeling/booleans * @example * import { intersect, scission, subtract, union } from '@jscad/modeling' */ diff --git a/packages/modeling/src/operations/booleans/intersect.js b/packages/modeling/src/operations/booleans/intersect.js index 2cbaf30c0..b7fdcef5e 100644 --- a/packages/modeling/src/operations/booleans/intersect.js +++ b/packages/modeling/src/operations/booleans/intersect.js @@ -6,7 +6,6 @@ import * as geom3 from '../../geometries/geom3/index.js' import { intersectGeom2 } from './intersectGeom2.js' import { intersectGeom3 } from './intersectGeom3.js' - /** * Return a new geometry representing space in both the first geometry and * all subsequent geometries. @@ -14,7 +13,7 @@ import { intersectGeom3 } from './intersectGeom3.js' * * @param {...Object} geometries - list of geometries * @returns {Geom2|Geom3} a new geometry - * @alias module:modeling/booleans.intersect + * @alias module:modeling.intersect * * @example * let myshape = intersect(cube({size: 5}), cube({size: 5, center: [3,3,3]})) diff --git a/packages/modeling/src/operations/booleans/scission.js b/packages/modeling/src/operations/booleans/scission.js index 38bcaceaf..4002ec5c8 100644 --- a/packages/modeling/src/operations/booleans/scission.js +++ b/packages/modeling/src/operations/booleans/scission.js @@ -1,7 +1,6 @@ import * as geom3 from '../../geometries/geom3/index.js' import { scissionGeom3 } from './scissionGeom3.js' - /** * Scission (divide) the given geometry into the component pieces. * @@ -9,7 +8,7 @@ import { scissionGeom3 } from './scissionGeom3.js' * * @param {...Object} objects - list of geometries * @returns {Array} list of pieces from each geometry - * @alias module:modeling/booleans.scission + * @alias module:modeling.scission * * @example * let figure = use('./my.stl') diff --git a/packages/modeling/src/operations/booleans/subtract.js b/packages/modeling/src/operations/booleans/subtract.js index e7f17efb3..37dc53e06 100644 --- a/packages/modeling/src/operations/booleans/subtract.js +++ b/packages/modeling/src/operations/booleans/subtract.js @@ -14,7 +14,7 @@ import { subtractGeom3 } from './subtractGeom3.js' * * @param {...Object} geometries - list of geometries * @returns {Geom2|Geom3} a new geometry - * @alias module:modeling/booleans.subtract + * @alias module:modeling.subtract * * @example * let myshape = subtract(cuboid({size: 5}), cuboid({size: 5, center: [3,3,3]})) diff --git a/packages/modeling/src/operations/booleans/union.js b/packages/modeling/src/operations/booleans/union.js index 2a8fb9710..9d6bad1f6 100644 --- a/packages/modeling/src/operations/booleans/union.js +++ b/packages/modeling/src/operations/booleans/union.js @@ -13,7 +13,7 @@ import { unionGeom3 } from './unionGeom3.js' * * @param {...Object} geometries - list of geometries * @returns {Geom2|Geom3} a new geometry - * @alias module:modeling/booleans.union + * @alias module:modeling.union * * @example * let myshape = union(cube({size: 5}), cube({size: 5, center: [3,3,3]})) From 4de8945cc548b13d1e2d5a39e3ce82ba2dc02f45 Mon Sep 17 00:00:00 2001 From: z3dev Date: Sun, 5 Apr 2026 09:14:46 +0900 Subject: [PATCH 4/8] docs(all): adjusted scope of docs --- jsdoc.json | 1 + 1 file changed, 1 insertion(+) diff --git a/jsdoc.json b/jsdoc.json index 46051db94..3aa910e1d 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -3,6 +3,7 @@ "include": [ "packages/array-utils/src", + "packages/modeling/src", "packages/modeling/src/colors", "packages/modeling/src/curves", "packages/modeling/src/curves/bezier", From c113da1a4ce1d298078d740ba36ad63589a7421c Mon Sep 17 00:00:00 2001 From: z3dev Date: Sat, 11 Apr 2026 14:24:16 +0900 Subject: [PATCH 5/8] docs(all): added hack to fix issues with jsdoc --- jsdoc.json | 2 +- jsdoc/assets/static/jscad-docs.css | 1 + jsdoc/jsdocFix.js | 9 +++++++++ jsdoc/package.json | 3 +++ 4 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 jsdoc/jsdocFix.js create mode 100644 jsdoc/package.json diff --git a/jsdoc.json b/jsdoc.json index 3aa910e1d..3ecf8e030 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -61,7 +61,7 @@ "tutorials": "./jsdoc/tutorials", "readme": "./jsdoc/assets/README.md" }, - "plugins": ["plugins/markdown"], + "plugins": ["jsdoc/jsdocFix","plugins/markdown"], "templates": { "default": { "staticFiles": { diff --git a/jsdoc/assets/static/jscad-docs.css b/jsdoc/assets/static/jscad-docs.css index 875c0c830..643616805 100644 --- a/jsdoc/assets/static/jscad-docs.css +++ b/jsdoc/assets/static/jscad-docs.css @@ -5,6 +5,7 @@ body { nav { background: none; + padding-bottom: 10px; } section { diff --git a/jsdoc/jsdocFix.js b/jsdoc/jsdocFix.js new file mode 100644 index 000000000..2913cfd9f --- /dev/null +++ b/jsdoc/jsdocFix.js @@ -0,0 +1,9 @@ +const newDocletFix = (docHandle) => { + if (docHandle.doclet.params) { + docHandle.doclet.kind = "function" + } +} + +exports.handlers = { + newDoclet: newDocletFix +} diff --git a/jsdoc/package.json b/jsdoc/package.json new file mode 100644 index 000000000..157f4c537 --- /dev/null +++ b/jsdoc/package.json @@ -0,0 +1,3 @@ +{ + "name": "package to fix jsdoc" +} From a5caba6c9b69571379120e337da67efea461335f Mon Sep 17 00:00:00 2001 From: z3dev Date: Sat, 11 Apr 2026 15:42:03 +0900 Subject: [PATCH 6/8] docs(all): adjusted module scopes for docs, and some cleanup --- packages/io/dxf-deserializer/src/DxfReader.js | 6 +++--- .../modeling/src/curves/bezier/arcLengthToT.js | 2 +- packages/modeling/src/curves/bezier/create.js | 2 +- packages/modeling/src/curves/bezier/index.js | 14 +++++++------- packages/modeling/src/curves/bezier/length.js | 2 +- packages/modeling/src/curves/bezier/lengths.js | 3 ++- packages/modeling/src/curves/bezier/tangentAt.js | 2 +- packages/modeling/src/curves/bezier/valueAt.js | 2 +- packages/modeling/src/curves/index.js | 6 +++--- packages/modeling/src/geometries/index.js | 10 +++++----- packages/modeling/src/geometries/poly3/plane.js | 2 ++ .../src/maths/mat4/isOnlyTransformScale.js | 2 +- packages/modeling/src/operations/booleans/index.js | 2 ++ .../modeling/src/operations/booleans/intersect.js | 2 +- .../modeling/src/operations/booleans/scission.js | 2 +- .../modeling/src/operations/booleans/subtract.js | 2 +- packages/modeling/src/operations/booleans/union.js | 2 +- .../src/operations/minkowski/minkowskiSum.js | 10 +++++----- 18 files changed, 39 insertions(+), 34 deletions(-) diff --git a/packages/io/dxf-deserializer/src/DxfReader.js b/packages/io/dxf-deserializer/src/DxfReader.js index 6ff334b5b..c879042b1 100644 --- a/packages/io/dxf-deserializer/src/DxfReader.js +++ b/packages/io/dxf-deserializer/src/DxfReader.js @@ -177,7 +177,7 @@ const parse = (reader, data) => { return reader } -/** +/* * Parse the given line in the context of the given reader, emitting group value pairs * @param reader {DxfReader} - context DxfReader to use * @param line {String} - line to parse @@ -200,7 +200,7 @@ const parseLine = (reader, line) => { } } -/** +/* * Parse the given line in the context of the given reader, and update the group * @param reader {DxfReader} - context DxfReader to use * @param line {String} - line to parse @@ -216,7 +216,7 @@ const setDxfGroup = (reader, line) => { } } -/** +/* * Parse the given line in the context of the given reader, and update the (group) value * @param reader {DxfReader} - context DxfReader to use * @param line {String} - line to parse diff --git a/packages/modeling/src/curves/bezier/arcLengthToT.js b/packages/modeling/src/curves/bezier/arcLengthToT.js index bb42f5cdd..9e3e5a8df 100644 --- a/packages/modeling/src/curves/bezier/arcLengthToT.js +++ b/packages/modeling/src/curves/bezier/arcLengthToT.js @@ -20,7 +20,7 @@ import { lengths } from './lengths.js' * @param {number} [options.segments=100] the number of segments to use when approximating the curve length. * @param {object} bezier a bezier curve. * @returns a number in the [0, 1] interval or NaN if the arcLength is negative or greater than the total length of the curve. - * @alias module:modeling/curves/bezier.arcLengthToT + * @alias module:modeling/bezier.arcLengthToT */ export const arcLengthToT = (options, bezier) => { const defaults = { diff --git a/packages/modeling/src/curves/bezier/create.js b/packages/modeling/src/curves/bezier/create.js index 0ea3d0751..81a49b204 100644 --- a/packages/modeling/src/curves/bezier/create.js +++ b/packages/modeling/src/curves/bezier/create.js @@ -23,7 +23,7 @@ * * @param {Array} points An array with at least 2 elements of either all numbers, or all arrays of numbers that are the same size. * @returns {bezier} a new bezier data object - * @alias module:modeling/curves/bezier.create + * @alias module:modeling/bezier.create */ export const create = (points) => { if (!Array.isArray(points)) throw new Error('Bezier points must be a valid array/') diff --git a/packages/modeling/src/curves/bezier/index.js b/packages/modeling/src/curves/bezier/index.js index 144462959..7be1693a1 100644 --- a/packages/modeling/src/curves/bezier/index.js +++ b/packages/modeling/src/curves/bezier/index.js @@ -1,14 +1,14 @@ /** * Represents a bezier easing function. * @see {@link bezier} for data structure information. - * @module modeling/curves/bezier + * @module modeling/bezier + * * @example - * import { curves } from '@jscad/modeling' - * const { bezier } = curves + * import { bezier } from '@jscad/modeling' */ +export { arcLengthToT } from './arcLengthToT.js' export { create } from './create.js' -export { valueAt } from './valueAt.js' -export { tangentAt } from './tangentAt.js' -export { lengths } from './lengths.js' export { length } from './length.js' -export { arcLengthToT } from './arcLengthToT.js' +export { lengths } from './lengths.js' +export { tangentAt } from './tangentAt.js' +export { valueAt } from './valueAt.js' diff --git a/packages/modeling/src/curves/bezier/length.js b/packages/modeling/src/curves/bezier/length.js index 544c9024a..c367fe4db 100644 --- a/packages/modeling/src/curves/bezier/length.js +++ b/packages/modeling/src/curves/bezier/length.js @@ -11,6 +11,6 @@ import { lengths } from './lengths.js' * @param {number} segments the number of segments to use when approximating the curve length. * @param {object} bezier a bezier curve. * @returns an approximation of the curve's length. - * @alias module:modeling/curves/bezier.length + * @alias module:modeling/bezier.length */ export const length = (segments, bezier) => lengths(segments, bezier)[segments] diff --git a/packages/modeling/src/curves/bezier/lengths.js b/packages/modeling/src/curves/bezier/lengths.js index ef9ae31fd..aaa3b8667 100644 --- a/packages/modeling/src/curves/bezier/lengths.js +++ b/packages/modeling/src/curves/bezier/lengths.js @@ -11,6 +11,7 @@ import { valueAt } from './valueAt.js' * @param {number} segments the number of segments to use when approximating the curve length. * @param {object} bezier a bezier curve. * @returns an array containing the cumulative length of the segments. + * @alias module:modeling/bezier.lengths */ export const lengths = (segments, bezier) => { let sum = 0 @@ -25,7 +26,7 @@ export const lengths = (segments, bezier) => { return lengths } -/** +/* * Calculates the Euclidean distance between two n-dimensional points. * * @example diff --git a/packages/modeling/src/curves/bezier/tangentAt.js b/packages/modeling/src/curves/bezier/tangentAt.js index 982308d51..8832f0336 100644 --- a/packages/modeling/src/curves/bezier/tangentAt.js +++ b/packages/modeling/src/curves/bezier/tangentAt.js @@ -10,7 +10,7 @@ * @param {number} t : the position of which to calculate the bezier's tangent value; 0 < t < 1 * @param {object} bezier : an array with at least 2 elements of either all numbers, or all arrays of numbers that are the same size. * @return {array | number} the tangent at the requested position. - * @alias module:modeling/curves/bezier.tangentAt + * @alias module:modeling/bezier.tangentAt */ export const tangentAt = (t, bezier) => { if (t < 0 || t > 1) { diff --git a/packages/modeling/src/curves/bezier/valueAt.js b/packages/modeling/src/curves/bezier/valueAt.js index 8e524ceb8..a32566909 100644 --- a/packages/modeling/src/curves/bezier/valueAt.js +++ b/packages/modeling/src/curves/bezier/valueAt.js @@ -11,7 +11,7 @@ * @param {number} t : the position of which to calculate the value; 0 < t < 1 * @param {object} bezier : a Bézier curve created with bezier.create(). * @returns {array | number} the value at the requested position. - * @alias module:modeling/curves/bezier.valueAt + * @alias module:modeling/bezier.valueAt */ export const valueAt = (t, bezier) => { if (t < 0 || t > 1) { diff --git a/packages/modeling/src/curves/index.js b/packages/modeling/src/curves/index.js index bf8c5bc41..195dbeb7e 100644 --- a/packages/modeling/src/curves/index.js +++ b/packages/modeling/src/curves/index.js @@ -1,8 +1,8 @@ /** * Curves are n-dimensional mathematical constructs that define a path from vertex 0 to vertex 1. - * @module modeling/curves + * @alias module:modeling.curves + * * @example - * import { curves } from '@jscad/modeling' - * const { bezier } = curves + * import { bezier } from '@jscad/modeling' */ export * as bezier from './bezier/index.js' diff --git a/packages/modeling/src/geometries/index.js b/packages/modeling/src/geometries/index.js index 6d16e8ba5..f12b76a5e 100644 --- a/packages/modeling/src/geometries/index.js +++ b/packages/modeling/src/geometries/index.js @@ -5,13 +5,13 @@ * * @see [Geom2]{@link module:modeling/geom2} - 2D geometry consisting of 2D outlines * @see [Geom3]{@link module:modeling/geom3} - 3D geometry consisting of polygons - * @see [Path2]{@link module:modeling/path2} - 2D geometry consisting of ordered points - * @see [Path3]{@link module:modeling/path3} - 3D geometry consisting of ordered vertices - * @see [Poly2]{@link module:modeling/poly2} - 2D polygon consisting of points - * @see [Poly3]{@link module:modeling/poly3} - 3D polygon consisting of vertices + * @see [Path2]{@link module:modeling/path2} - 2D geometry consisting of ordered 2D points + * @see [Path3]{@link module:modeling/path3} - 3D geometry consisting of ordered 3D vertices + * @see [Poly2]{@link module:modeling/poly2} - 2D polygon consisting of 2D points + * @see [Poly3]{@link module:modeling/poly3} - 3D polygon consisting of 3D vertices * @see [Slice]{@link module:modeling/slice} - 3D geometry consisting of 3D contours + * @alias module:modeling.geometry * - * @module modeling/geometries * @example * import { geom2, geom3, path2, poly2, poly3, slice } from '@jscad/modeling' */ diff --git a/packages/modeling/src/geometries/poly3/plane.js b/packages/modeling/src/geometries/poly3/plane.js index 008abe0c7..b62ba2b33 100644 --- a/packages/modeling/src/geometries/poly3/plane.js +++ b/packages/modeling/src/geometries/poly3/plane.js @@ -2,6 +2,8 @@ import * as mplane from '../../maths/plane/index.js' /** * Determine the plane of the given polygon. + * + * @alias module:modeling/poly3.plane */ export const plane = (polygon) => { if (!polygon.plane) { diff --git a/packages/modeling/src/maths/mat4/isOnlyTransformScale.js b/packages/modeling/src/maths/mat4/isOnlyTransformScale.js index 4c9c7c87f..0119bd200 100644 --- a/packages/modeling/src/maths/mat4/isOnlyTransformScale.js +++ b/packages/modeling/src/maths/mat4/isOnlyTransformScale.js @@ -17,7 +17,7 @@ export const isOnlyTransformScale = (matrix) => ( matrix[15] === 1 ) -/** +/* * @param {number} num * @returns {boolean} */ diff --git a/packages/modeling/src/operations/booleans/index.js b/packages/modeling/src/operations/booleans/index.js index d9e60e2b2..804c0a892 100644 --- a/packages/modeling/src/operations/booleans/index.js +++ b/packages/modeling/src/operations/booleans/index.js @@ -3,6 +3,8 @@ * to perform logical operations, e.g. remove a hole from a board. * * In all cases, the function returns the results, and never changes the original shapes. + * @module modeling/booleans + * * @example * import { intersect, scission, subtract, union } from '@jscad/modeling' */ diff --git a/packages/modeling/src/operations/booleans/intersect.js b/packages/modeling/src/operations/booleans/intersect.js index b7fdcef5e..092abe6bd 100644 --- a/packages/modeling/src/operations/booleans/intersect.js +++ b/packages/modeling/src/operations/booleans/intersect.js @@ -13,7 +13,7 @@ import { intersectGeom3 } from './intersectGeom3.js' * * @param {...Object} geometries - list of geometries * @returns {Geom2|Geom3} a new geometry - * @alias module:modeling.intersect + * @alias module:modeling/booleans.intersect * * @example * let myshape = intersect(cube({size: 5}), cube({size: 5, center: [3,3,3]})) diff --git a/packages/modeling/src/operations/booleans/scission.js b/packages/modeling/src/operations/booleans/scission.js index 4002ec5c8..876944f06 100644 --- a/packages/modeling/src/operations/booleans/scission.js +++ b/packages/modeling/src/operations/booleans/scission.js @@ -8,7 +8,7 @@ import { scissionGeom3 } from './scissionGeom3.js' * * @param {...Object} objects - list of geometries * @returns {Array} list of pieces from each geometry - * @alias module:modeling.scission + * @alias module:modeling/booleans.scission * * @example * let figure = use('./my.stl') diff --git a/packages/modeling/src/operations/booleans/subtract.js b/packages/modeling/src/operations/booleans/subtract.js index 37dc53e06..e7f17efb3 100644 --- a/packages/modeling/src/operations/booleans/subtract.js +++ b/packages/modeling/src/operations/booleans/subtract.js @@ -14,7 +14,7 @@ import { subtractGeom3 } from './subtractGeom3.js' * * @param {...Object} geometries - list of geometries * @returns {Geom2|Geom3} a new geometry - * @alias module:modeling.subtract + * @alias module:modeling/booleans.subtract * * @example * let myshape = subtract(cuboid({size: 5}), cuboid({size: 5, center: [3,3,3]})) diff --git a/packages/modeling/src/operations/booleans/union.js b/packages/modeling/src/operations/booleans/union.js index 9d6bad1f6..2a8fb9710 100644 --- a/packages/modeling/src/operations/booleans/union.js +++ b/packages/modeling/src/operations/booleans/union.js @@ -13,7 +13,7 @@ import { unionGeom3 } from './unionGeom3.js' * * @param {...Object} geometries - list of geometries * @returns {Geom2|Geom3} a new geometry - * @alias module:modeling.union + * @alias module:modeling/booleans.union * * @example * let myshape = union(cube({size: 5}), cube({size: 5, center: [3,3,3]})) diff --git a/packages/modeling/src/operations/minkowski/minkowskiSum.js b/packages/modeling/src/operations/minkowski/minkowskiSum.js index dc6f5398e..e1ec879aa 100644 --- a/packages/modeling/src/operations/minkowski/minkowskiSum.js +++ b/packages/modeling/src/operations/minkowski/minkowskiSum.js @@ -64,7 +64,7 @@ export const minkowskiSum = (...geometries) => { throw new Error('minkowskiSum of two non-convex geometries is not yet supported') } -/** +/* * Compute Minkowski sum of non-convex A with convex B. * * Decomposes A into tetrahedra, computes Minkowski sum of each with B, @@ -88,7 +88,7 @@ const minkowskiSumNonConvexConvex = (geomA, geomB) => { return unionGeom3(parts) } -/** +/* * Decompose a geom3 into tetrahedra using face-local apex points. * Each resulting tetrahedron is guaranteed to be convex. * @@ -155,7 +155,7 @@ const decomposeIntoTetrahedra = (geometry) => { return tetrahedra } -/** +/* * Create the 4 triangular faces of a tetrahedron. * * Tetrahedron has 4 faces, each a triangle @@ -167,7 +167,7 @@ const createTetrahedronPolygons = (p0, p1, p2, p3) => [ poly3.create([p2, p0, p3]) // face opposite p1 ] -/** +/* * Compute Minkowski sum of two convex polyhedra. * * For convex polyhedra, the Minkowski sum equals the convex hull of @@ -198,7 +198,7 @@ const minkowskiSumConvex = (geomA, geomB) => { return geom3.create(hullPolygons) } -/** +/* * Extract unique vertices from a geom3. * Uses a Set with string keys for deduplication. */ From 5e3c6d8c4218b6a695686e86e15ccceedc6ffe92 Mon Sep 17 00:00:00 2001 From: z3dev Date: Sat, 11 Apr 2026 15:55:50 +0900 Subject: [PATCH 7/8] docs(all): cleanup of docs --- packages/modeling/src/geometries/path2/create.js | 1 + packages/modeling/src/geometries/path3/create.js | 1 + packages/modeling/src/geometries/poly3/plane.js | 1 + 3 files changed, 3 insertions(+) diff --git a/packages/modeling/src/geometries/path2/create.js b/packages/modeling/src/geometries/path2/create.js index 3160d559f..84652e9b1 100644 --- a/packages/modeling/src/geometries/path2/create.js +++ b/packages/modeling/src/geometries/path2/create.js @@ -3,6 +3,7 @@ import * as mat4 from '../../maths/mat4/index.js' /** * Create an empty, open path. * + * @param {Array} [points] - a list of points of which to create the path * @returns {Path2} a new path * @alias module:modeling/path2.create * diff --git a/packages/modeling/src/geometries/path3/create.js b/packages/modeling/src/geometries/path3/create.js index 2fda45ee6..a9fbef560 100644 --- a/packages/modeling/src/geometries/path3/create.js +++ b/packages/modeling/src/geometries/path3/create.js @@ -3,6 +3,7 @@ import * as mat4 from '../../maths/mat4/index.js' /** * Create an empty, open path. * + * @param {Array} [vertices] - a list of vertices of which to create the path * @returns {Path3} a new path * @alias module:modeling/path3.create * diff --git a/packages/modeling/src/geometries/poly3/plane.js b/packages/modeling/src/geometries/poly3/plane.js index b62ba2b33..abc5c57c2 100644 --- a/packages/modeling/src/geometries/poly3/plane.js +++ b/packages/modeling/src/geometries/poly3/plane.js @@ -3,6 +3,7 @@ import * as mplane from '../../maths/plane/index.js' /** * Determine the plane of the given polygon. * + * @param {Poly3} polygon - the polygon of which to fetch the plane * @alias module:modeling/poly3.plane */ export const plane = (polygon) => { From c7d89bd48d33dfa1203c7a016b9b64524174571f Mon Sep 17 00:00:00 2001 From: z3dev Date: Sun, 12 Apr 2026 08:41:51 +0900 Subject: [PATCH 8/8] docs(all): added @jscad/io package docs --- jsdoc.json | 1 + packages/io/io/src/deserialize.js | 7 +++++-- packages/io/io/src/index.js | 3 +++ packages/io/io/src/serialize.js | 6 +++++- 4 files changed, 14 insertions(+), 3 deletions(-) diff --git a/jsdoc.json b/jsdoc.json index 3ecf8e030..2d550c295 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -36,6 +36,7 @@ "packages/modeling/src/text", "packages/modeling/src/utils", + "packages/io/io/src", "packages/io/io-utils", "packages/io/3mf-deserializer/src", "packages/io/3mf-serializer/src", diff --git a/packages/io/io/src/deserialize.js b/packages/io/io/src/deserialize.js index 23b56570e..e46905c53 100644 --- a/packages/io/io/src/deserialize.js +++ b/packages/io/io/src/deserialize.js @@ -14,14 +14,17 @@ const transformers = { /** * Deserialize the given source as per the given mimeType. + * * Options can be provided to over-ride or suppliment the defaults used during deserialization. - * Options must include 'output' as either 'script' or 'geometry'. + * * @param {Object} options - options used during deserializing * @param {String} mimeType - MIME type of the file * @param {String} source - the contents of the file - * @return {[objects]|string} a list of objects (geometry) or a string (script) + * @returns {(Array|String)} either an array of objects (geometry) or a string (script) + * @alias module:io.deserialize * * @example + * import { getMimeType, deserialize } from '@jscad/io' * const mimetype = getMimeType('svg') * const myobjects = deserialize({output: 'geometry', target: 'path2'}, mimetype, source) */ diff --git a/packages/io/io/src/index.js b/packages/io/io/src/index.js index b1f176983..f8bcec464 100644 --- a/packages/io/io/src/index.js +++ b/packages/io/io/src/index.js @@ -1,3 +1,6 @@ +/** + * @module io + */ export { deserialize } from './deserialize.js' export { deserializers } from './deserializers.js' diff --git a/packages/io/io/src/serialize.js b/packages/io/io/src/serialize.js index 5186f0f5e..988c540e7 100644 --- a/packages/io/io/src/serialize.js +++ b/packages/io/io/src/serialize.js @@ -4,14 +4,18 @@ import { serializers } from './serializers.js' /** * Serialize the given objects as per the given mimeType into the external format. + * * Options can be provided to over-ride or suppliment the defaults used during serialization. - * See each serializer package for available options. + * @See each serializer package for available options. + * * @param {Object} options - options used during deserializing * @param {String} mimeType - MIME type of the file * @param {Object} objects - one or more objects of which to serialize * @return {Object} an object containing the serialize data as well as mime type + * @alias module:io.serialize * * @example + * import { getMimeType, serialize } from '@jscad/io' * const mimetype = getMimeType('svg') * const shapes = [primitives.cirlce(), primitives.star()] * const output = serialize({units: 'inches'}, mimetype, shapes)