diff --git a/package.json b/package.json index dcb9d8b..aef7c27 100644 --- a/package.json +++ b/package.json @@ -39,7 +39,7 @@ "lint-eslint": "eslint './**/*.{ts, js, jcjs}'", "build": "vite build && pnpm run docs", "build-watch": "vite build --watch", - "docs": "npx typedoc src/index.ts", + "docs": "typedoc", "docs-open": "open ./docs/index.html", "release-preview": "semantic-release --no-ci --dry-run --debug", "link": "pnpm link --global", diff --git a/src/index.ts b/src/index.ts index 2f27198..f2c7d9b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -25,6 +25,11 @@ import { validateGetSurfacePointArguments, } from './utils/validation' +/** + * @groupDescription API + * The API of the package + */ + // ----------------------------------------------------------------------------- // Const // ----------------------------------------------------------------------------- @@ -59,17 +64,17 @@ export { interpolatePointOnCurveLinear } from './interpolate/pointOnCurve/linear * Computes a point on a surface defined by bounding curves at parameters u and * v. * - * @param {Object} boundingCurves - An object containing curves that define the - * surface boundaries. - * @param {number} u - The parameter along the first dimension (typically - * between 0 and 1). - * @param {number} v - The parameter along the second dimension (typically - * between 0 and 1). + * @param {BoundingCurves} boundingCurves - An object containing curves that + * define the surface boundaries. + * @param {number} u - The parameter along the first dimension (0–1). + * @param {number} v - The parameter along the second dimension (0–1). + * @param {Object} [config] - Configuration object. * @param {Function} - * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to - * interpolate points on the curves. - * @returns {Object} The interpolated point on the surface. + * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function + * to interpolate points on the curves. + * @returns {Point} The interpolated point on the surface. * @throws {Error} If the arguments are invalid. + * @group API */ export const getSurfacePoint = ( boundingCurves: BoundingCurves, @@ -97,19 +102,22 @@ export const getSurfacePoint = ( * Generates intersection points on the surface based on the provided bounding * curves, columns, and rows. * - * @param {Object} boundingCurves - An object containing curves that define the - * surface boundaries. + * @param {BoundingCurves} boundingCurves - An object containing curves that + * define the surface boundaries. * @param {number | Array | Array} columns - Either a number, an * array of numbers, or an array of column definitions, each containing a value * and an optional isGutter flag. * @param {number | Array | Array} rows - Either a number, an - * array of numbers, or an array of row definitions. + * array of numbers, or an array of row definitions, each containing a value and + * an optional isGutter flag. + * @param {Object} [config] - Configuration object. * @param {Function} - * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to - * interpolate points on the curves. - * @returns {Array} An array of points representing the intersections on - * the surface. + * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function + * to interpolate points on the curves. + * @returns {Points} An array of points representing the intersections on the + * surface. * @throws {Error} If the arguments are invalid. + * @group API */ export const getSurfaceIntersectionPoints = ( boundingCurves: BoundingCurves, @@ -168,22 +176,24 @@ export const getSurfaceIntersectionPoints = ( * Generates surface curves along the U-axis based on the provided bounding * curves, columns, and rows. * - * @param {Object} boundingCurves - An object containing curves that define the - * surface boundaries. + * @param {BoundingCurves} boundingCurves - An object containing curves that + * define the surface boundaries. * @param {number | Array | Array} columns - Either a number, an * array of numbers, or an array of column definitions, each containing a value * and an optional isGutter flag. * @param {number | Array | Array} rows - Either a number, an - * array of numbers, or an array of row definitions, each containing a value - * and an optional isGutter flag. + * array of numbers, or an array of row definitions, each containing a value and + * an optional isGutter flag. + * @param {Object} [config] - Configuration object. * @param {Function} - * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to - * interpolate points on the curves. - * @param {Function} [interpolateLineU=interpolateStraightLineU] - A + * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function + * to interpolate points on the curves. + * @param {Function} [config.interpolateLineU=interpolateStraightLineU] - A * function to interpolate lines along the U-axis. - * @returns {Array>} A 2D array of curves representing the surface - * along the U-axis. + * @returns {StepCurves[]} A 2D array of curves representing the surface along + * the U-axis. * @throws {Error} If the arguments are invalid. + * @group API */ export const getSurfaceCurvesU = ( boundingCurves: BoundingCurves, @@ -259,22 +269,24 @@ export const getSurfaceCurvesU = ( * Generates surface curves along the V-axis based on the provided bounding * curves, columns, and rows. * - * @param {Object} boundingCurves - An object containing curves that define the - * surface boundaries. + * @param {BoundingCurves} boundingCurves - An object containing curves that + * define the surface boundaries. * @param {number | Array | Array} columns - Either a number, an * array of numbers, or an array of column definitions, each containing a value * and an optional isGutter flag. * @param {number | Array | Array} rows - Either a number, an - * array of numbers, or an array of row definitions, each containing a value - * and an optional isGutter flag. + * array of numbers, or an array of row definitions, each containing a value and + * an optional isGutter flag. + * @param {Object} [config] - Configuration object. * @param {Function} - * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to - * interpolate points on the curves. - * @param {Function} [interpolateLineV=interpolateStraightLineV] - A + * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function + * to interpolate points on the curves. + * @param {Function} [config.interpolateLineV=interpolateStraightLineV] - A * function to interpolate lines along the V-axis. * @returns {Array>} A 2D array of curves representing the surface * along the V-axis. * @throws {Error} If the arguments are invalid. + * @group API */ export const getSurfaceCurvesV = ( boundingCurves: BoundingCurves, @@ -351,23 +363,25 @@ export const getSurfaceCurvesV = ( * Generates surface curves along both the U-axis and V-axis based on the * provided bounding curves, columns, and rows. * - * @param {Object} boundingCurves - An object containing curves that define the + * @param {BoundingCurves} boundingCurves - An object containing curves that define the * surface boundaries. * @param {number | Array | Array} columns - Either a number, an * array of numbers, or an array of column definitions, each containing a value * and an optional isGutter flag. * @param {number | Array | Array} rows - Either a number, an - * array of numbers, or an array of row definitions. - * @param {Function} - * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to + * array of numbers, or an array of row definitions, each containing a value + * and an optional isGutter flag. + * @param {Object} [config] - Configuration object. + * @param {Function} [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function to * interpolate points on the curves. - * @param {Function} [interpolateLineU=interpolateStraightLineU] - A + * @param {Function} [config.interpolateLineU=interpolateStraightLineU] - A * function to interpolate lines along the U-axis. - * @param {Function} [interpolateLineV=interpolateStraightLineV] - A + * @param {Function} [config.interpolateLineV=interpolateStraightLineV] - A * function to interpolate lines along the V-axis. - * @returns {Object} An object containing 2D arrays of curves representing the + * @returns {UVCurves} An object containing 2D arrays of curves representing the * surface along both the U-axis and V-axis. * @throws {Error} If the arguments are invalid. + * @group API */ export const getSurfaceCurves = ( boundingCurves: BoundingCurves, diff --git a/src/interpolate/curves/curved.ts b/src/interpolate/curves/curved.ts index ee699bc..1763ac4 100644 --- a/src/interpolate/curves/curved.ts +++ b/src/interpolate/curves/curved.ts @@ -10,6 +10,24 @@ import { interpolateStraightLineU, interpolateStraightLineV } from './straight' const T_MIDPOINT_1 = 0.25 const T_MIDPOINT_2 = 0.75 +// ----------------------------------------------------------------------------- +// Exports +// ----------------------------------------------------------------------------- + +/** + * Interpolates a cubic Bezier curve along the U direction of a surface defined + * by bounding curves. + * + * @param {BoundingCurves} boundingCurves - An object containing curves that + * define the surface boundaries. + * @param {number} vStart - The starting parameter along the V direction. + * @param {number} vSize - The size of the step along the V direction. + * @param {number} vEnd - The ending parameter along the V direction. + * @param {number} uStart - The starting parameter along the U direction. + * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to + * interpolate points on the curves. + * @returns {Curve} The interpolated cubic Bezier curve. + */ export const interpolateCurveU = ( boundingCurves: BoundingCurves, vStart: number, @@ -49,6 +67,20 @@ export const interpolateCurveU = ( return curve } +/** + * Interpolates a cubic Bezier curve along the V direction of a surface defined + * by bounding curves. + * + * @param {BoundingCurves} boundingCurves - An object containing curves that + * define the surface boundaries. + * @param {number} uStart - The starting parameter along the U direction. + * @param {number} uSize - The size of the step along the U direction. + * @param {number} uEnd - The ending parameter along the U direction. + * @param {number} vStart - The starting parameter along the V direction. + * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to + * interpolate points on the curves. + * @returns {Curve} The interpolated cubic Bezier curve. + */ export const interpolateCurveV = ( boundingCurves: BoundingCurves, uStart: number, diff --git a/src/interpolate/curves/straight.ts b/src/interpolate/curves/straight.ts index 67d36f4..7c01220 100644 --- a/src/interpolate/curves/straight.ts +++ b/src/interpolate/curves/straight.ts @@ -5,6 +5,19 @@ import { interpolatePointOnSurface } from '../pointOnSurface/bilinear' // Exports // ----------------------------------------------------------------------------- +/** + * Interpolates a straight line along the U direction of a surface defined + * by bounding curves. + * + * @param {BoundingCurves} boundingCurves - An object containing curves that define the + * surface boundaries. + * @param {number} uStart - The starting parameter along the U direction. + * @param {number} uSize - The size of the step along the U direction. + * @param {number} uEnd - The ending parameter along the U direction. + * @param {number} vStart - The starting parameter along the V direction. + * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to interpolate points on the curves. + * @returns {Curve} The interpolated straight line as a cubic Bezier curve. + */ export const interpolateStraightLineU = ( boundingCurves: BoundingCurves, uStart: number, @@ -36,6 +49,20 @@ export const interpolateStraightLineU = ( } } +/** + * Interpolates a straight line along the V direction of a surface defined by + * bounding curves. + * + * @param {BoundingCurves} boundingCurves - An object containing curves that + * define the surface boundaries. + * @param {number} uStart - The starting parameter along the U direction. + * @param {number} uSize - The size of the step along the U direction. + * @param {number} uEnd - The ending parameter along the U direction. + * @param {number} vStart - The starting parameter along the V direction. + * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to + * interpolate points on the curves. + * @returns {Curve} The interpolated straight line as a cubic Bezier curve. + */ export const interpolateStraightLineV = ( boundingCurves: BoundingCurves, uStart: number, diff --git a/src/interpolate/pointOnCurve/even.ts b/src/interpolate/pointOnCurve/even.ts index 20f5321..b100686 100644 --- a/src/interpolate/pointOnCurve/even.ts +++ b/src/interpolate/pointOnCurve/even.ts @@ -61,6 +61,16 @@ const getLutForCurve = memoize((curve, precision) => { // Exports // ----------------------------------------------------------------------------- +/** + * Interpolates a point on a curve such that the points are evenly spaced. + * + * @param {Object} options - Configuration options. + * @param {number} options.precision - The number of points used to approximate + * the curve. Increasing this number improves accuracy at the cost of + * performance. + * @returns {Function} A function that takes a parameter `t` and a `curve`, and + * returns an interpolated point on the curve. + */ export const interpolatePointOnCurveEvenlySpaced = ( // Get an approximation using an arbitrary number of points. Increase for diff --git a/src/interpolate/pointOnCurve/linear.ts b/src/interpolate/pointOnCurve/linear.ts index 533d7fb..b7b2f54 100644 --- a/src/interpolate/pointOnCurve/linear.ts +++ b/src/interpolate/pointOnCurve/linear.ts @@ -37,6 +37,14 @@ const interpolate = ( // Exports // ----------------------------------------------------------------------------- +/** + * Interpolates a point on a curve using linear interpolation. Note that this + * will not result in the points being evenly spaced. + * + * @param {number} t - The parameter along the curve, typically between 0 and 1. + * @param {Curve} curve - The curve on which to interpolate the point. + * @returns {Point} The interpolated point on the curve. + */ export const interpolatePointOnCurveLinear = ( t: number, curve: Curve diff --git a/tests/snapshotData.js b/tests/snapshotData.js index bc86a77..d1b5dff 100644 --- a/tests/snapshotData.js +++ b/tests/snapshotData.js @@ -6,6 +6,7 @@ import { getSurfaceIntersectionPoints, getSurfacePoint, } from '../src/index.js' + import fixtures from './fixtures.js' import { __dirname, writeFileAsync } from './helpers.js' diff --git a/typedoc.cjs b/typedoc.cjs new file mode 100644 index 0000000..c168e07 --- /dev/null +++ b/typedoc.cjs @@ -0,0 +1,8 @@ +/** @type {import('typedoc').TypeDocOptions} */ +module.exports = { + entryPoints: ['./src/index.ts'], + out: 'docs', + categorizeByGroup: true, + groupOrder: ['API', '*'], + sort: 'source-order', +}