@d3plus/math 3.0.0-alpha.0

package/README.md

@@ -0,0 +1,216 @@
+# @d3plus/math
+  
+Mathematical functions to aid in calculating visualizations.
+
+## Installing
+
+If using npm, `npm install @d3plus/math`. Otherwise, you can download the [latest release from GitHub](https://github.com/d3plus/d3plus/releases/latest) or load from a [CDN](https://cdn.jsdelivr.net/npm/@d3plus/math@3.0.0-alpha.0/+esm).
+
+```js
+import modules from "@d3plus/math";
+```
+
+In vanilla JavaScript, a `d3plus` global is exported from the pre-bundled version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@d3plus/math@3.0.0-alpha.0"></script>
+<script>
+  console.log(d3plus);
+</script>
+```
+
+## Examples
+
+Live examples can be found on [d3plus.org](https://d3plus.org/), which includes a collection of example visualizations using @d3plus/react.
+
+## API Reference
+
+##### 
+* [closest](#closest) - Finds the closest numeric value in an array.
+* [largestRect](#largestRect) - An angle of zero means that the longer side of the polygon (the width) will be aligned with the x axis. An angle of 90 and/or -90 means that the longer side of the polygon (the width) will be aligned with the y axis. The value can be a number between -90 and 90 specifying the angle of rotation of the polygon, a string which is parsed to a number, or an array of numbers specifying the possible rotations of the polygon.
+* [lineIntersection](#lineIntersection) - Finds the intersection point (if there is one) of the lines p1q1 and p2q2.
+* [path2polygon](#path2polygon) - Transforms a path string into an Array of points.
+* [pointDistance](#pointDistance) - Calculates the pixel distance between two points.
+* [pointDistanceSquared](#pointDistanceSquared) - Returns the squared euclidean distance between two points.
+* [pointRotate](#pointRotate) - Rotates a point around a given origin.
+* [polygonInside](#polygonInside) - Checks if one polygon is inside another polygon.
+* [polygonRayCast](#polygonRayCast) - Gives the two closest intersection points between a ray cast from a point inside a polygon. The two points should lie on opposite sides of the origin.
+* [polygonRotate](#polygonRotate) - Rotates a point around a given origin.
+* [segmentBoxContains](#segmentBoxContains) - Checks whether a point is inside the bounding box of a line segment.
+* [segmentsIntersect](#segmentsIntersect) - Checks whether the line segments p1q1 && p2q2 intersect.
+* [shapeEdgePoint](#shapeEdgePoint) - Calculates the x/y position of a point at the edge of a shape, from the center of the shape, given a specified pixel distance and radian angle.
+* [largestRect](#largestRect) - Simplifies the points of a polygon using both the Ramer-Douglas-Peucker algorithm and basic distance-based simplification. Adapted to an ES6 module from the excellent [Simplify.js](http://mourner.github.io/simplify-js/).
+
+##### 
+* [LargestRect](#LargestRect) - The returned Object of the largestRect function.
+
+---
+
+<a name="closest"></a>
+#### d3plus.**closest**(n, arr) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/closest.js#L1)
+
+Finds the closest numeric value in an array.
+
+
+This is a global function
+
+---
+
+<a name="largestRect"></a>
+#### d3plus.**largestRect**(poly, [options]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/largestRect.js#L28)
+
+An angle of zero means that the longer side of the polygon (the width) will be aligned with the x axis. An angle of 90 and/or -90 means that the longer side of the polygon (the width) will be aligned with the y axis. The value can be a number between -90 and 90 specifying the angle of rotation of the polygon, a string which is parsed to a number, or an array of numbers specifying the possible rotations of the polygon.
+
+
+This is a global function
+**Author**: Daniel Smilkov [dsmilkov@gmail.com]  
+
+---
+
+<a name="lineIntersection"></a>
+#### d3plus.**lineIntersection**(p1, q1, p2, q2) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/lineIntersection.js#L1)
+
+Finds the intersection point (if there is one) of the lines p1q1 and p2q2.
+
+
+This is a global function
+
+---
+
+<a name="path2polygon"></a>
+#### d3plus.**path2polygon**(path, [segmentLength]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/path2polygon.js#L1)
+
+Transforms a path string into an Array of points.
+
+
+This is a global function
+
+---
+
+<a name="pointDistance"></a>
+#### d3plus.**pointDistance**(p1, p2) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/pointDistance.js#L3)
+
+Calculates the pixel distance between two points.
+
+
+This is a global function
+
+---
+
+<a name="pointDistanceSquared"></a>
+#### d3plus.**pointDistanceSquared**(p1, p2) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/pointDistanceSquared.js#L1)
+
+Returns the squared euclidean distance between two points.
+
+
+This is a global function
+
+---
+
+<a name="pointRotate"></a>
+#### d3plus.**pointRotate**(p, alpha, [origin]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/pointRotate.js#L1)
+
+Rotates a point around a given origin.
+
+
+This is a global function
+
+---
+
+<a name="polygonInside"></a>
+#### d3plus.**polygonInside**(polyA, polyB) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/polygonInside.js#L5)
+
+Checks if one polygon is inside another polygon.
+
+
+This is a global function
+
+---
+
+<a name="polygonRayCast"></a>
+#### d3plus.**polygonRayCast**(poly, origin, [alpha]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/polygonRayCast.js#L5)
+
+Gives the two closest intersection points between a ray cast from a point inside a polygon. The two points should lie on opposite sides of the origin.
+
+
+This is a global function
+**Returns**: <code>Array</code> - An array containing two values, the closest point on the left and the closest point on the right. If either point cannot be found, that value will be `null`.  
+
+---
+
+<a name="polygonRotate"></a>
+#### d3plus.**polygonRotate**(poly, alpha, [origin]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/polygonRotate.js#L3)
+
+Rotates a point around a given origin.
+
+
+This is a global function
+
+---
+
+<a name="segmentBoxContains"></a>
+#### d3plus.**segmentBoxContains**(s1, s2, p) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/segmentBoxContains.js#L1)
+
+Checks whether a point is inside the bounding box of a line segment.
+
+
+This is a global function
+
+---
+
+<a name="segmentsIntersect"></a>
+#### d3plus.**segmentsIntersect**(p1, q1, p2, q2) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/segmentsIntersect.js#L4)
+
+Checks whether the line segments p1q1 && p2q2 intersect.
+
+
+This is a global function
+
+---
+
+<a name="shapeEdgePoint"></a>
+#### d3plus.**shapeEdgePoint**(angle, distance) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/shapeEdgePoint.js#L3)
+
+Calculates the x/y position of a point at the edge of a shape, from the center of the shape, given a specified pixel distance and radian angle.
+
+
+This is a global function
+**Returns**: <code>String</code> - [shape = "circle"] The type of shape, which can be either "circle" or "square".  
+
+---
+
+<a name="largestRect"></a>
+#### d3plus.**largestRect**(poly, [tolerance], [highestQuality]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/simplify.js#L112)
+
+Simplifies the points of a polygon using both the Ramer-Douglas-Peucker algorithm and basic distance-based simplification. Adapted to an ES6 module from the excellent [Simplify.js](http://mourner.github.io/simplify-js/).
+
+
+This is a global function
+**Author**: Vladimir Agafonkin  
+
+---
+
+<a name="LargestRect"></a>
+#### **LargestRect** [<>](https://github.com/d3plus/d3plus/blob/main/packages/math/src/largestRect.js#L16)
+
+The returned Object of the largestRect function.
+
+
+This is a global typedef
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| width | <code>Number</code> | The width of the rectangle |
+| height | <code>Number</code> | The height of the rectangle |
+| cx | <code>Number</code> | The x coordinate of the rectangle's center |
+| cy | <code>Number</code> | The y coordinate of the rectangle's center |
+| angle | <code>Number</code> | The rotation angle of the rectangle in degrees. The anchor of rotation is the center point. |
+| area | <code>Number</code> | The area of the largest rectangle. |
+| points | <code>Array</code> | An array of x/y coordinates for each point in the rectangle, useful for rendering paths. |
+
+
+---
+
+
+###### <sub>Documentation generated on Thu, 13 Mar 2025 19:58:29 GMT</sub>

package/es/index.js

@@ -0,0 +1,15 @@
+export { default as ckmeans } from "./src/ckmeans.js";
+export { default as closest } from "./src/closest.js";
+export { default as largestRect } from "./src/largestRect.js";
+export { default as lineIntersection } from "./src/lineIntersection.js";
+export { default as path2polygon } from "./src/path2polygon.js";
+export { default as pointDistance } from "./src/pointDistance.js";
+export { default as pointDistanceSquared } from "./src/pointDistanceSquared.js";
+export { default as pointRotate } from "./src/pointRotate.js";
+export { default as polygonInside } from "./src/polygonInside.js";
+export { default as polygonRayCast } from "./src/polygonRayCast.js";
+export { default as polygonRotate } from "./src/polygonRotate.js";
+export { default as segmentBoxContains } from "./src/segmentBoxContains.js";
+export { default as segmentsIntersect } from "./src/segmentsIntersect.js";
+export { default as shapeEdgePoint } from "./src/shapeEdgePoint.js";
+export { default as simplify } from "./src/simplify.js";

package/es/src/ckmeans.js

@@ -0,0 +1,204 @@
+/**
+    @desc Sort an array of numbers by their numeric value, ensuring that the array is not changed in place.
+
+This is necessary because the default behavior of .sort in JavaScript is to sort arrays as string values
+
+[1, 10, 12, 102, 20].sort()
+// output
+[1, 10, 102, 12, 20]
+
+    @param {Array<number>} array input array
+    @return {Array<number>} sorted array
+    @private
+    @example
+numericSort([3, 2, 1]) // => [1, 2, 3]
+*/ function numericSort(array) {
+    return array.slice().sort(function(a, b) {
+        return a - b;
+    });
+}
+/**
+    For a sorted input, counting the number of unique values is possible in constant time and constant memory. This is a simple implementation of the algorithm.
+
+    Values are compared with `===`, so objects and non-primitive objects are not handled in any special way.
+    @private
+    @param {Array} input an array of primitive values.
+    @returns {number} count of unique values
+    @example
+uniqueCountSorted([1, 2, 3]); // => 3
+uniqueCountSorted([1, 1, 1]); // => 1
+*/ function uniqueCountSorted(input) {
+    var lastSeenValue, uniqueValueCount = 0;
+    for(var i = 0; i < input.length; i++){
+        if (i === 0 || input[i] !== lastSeenValue) {
+            lastSeenValue = input[i];
+            uniqueValueCount++;
+        }
+    }
+    return uniqueValueCount;
+}
+/**
+    Create a new column x row matrix.
+    @private
+    @param {number} columns
+    @param {number} rows
+    @return {Array<Array<number>>} matrix
+    @example
+makeMatrix(10, 10);
+*/ function makeMatrix(columns, rows) {
+    var matrix = [];
+    for(var i = 0; i < columns; i++){
+        var column = [];
+        for(var j = 0; j < rows; j++)column.push(0);
+        matrix.push(column);
+    }
+    return matrix;
+}
+/**
+    Generates incrementally computed values based on the sums and sums of squares for the data array
+    @private
+    @param {number} j
+    @param {number} i
+    @param {Array<number>} sums
+    @param {Array<number>} sumsOfSquares
+    @return {number}
+    @example
+ssq(0, 1, [-1, 0, 2], [1, 1, 5]);
+*/ function ssq(j, i, sums, sumsOfSquares) {
+    var sji; // s(j, i)
+    if (j > 0) {
+        var muji = (sums[i] - sums[j - 1]) / (i - j + 1); // mu(j, i)
+        sji = sumsOfSquares[i] - sumsOfSquares[j - 1] - (i - j + 1) * muji * muji;
+    } else sji = sumsOfSquares[i] - sums[i] * sums[i] / (i + 1);
+    if (sji < 0) return 0;
+    return sji;
+}
+/**
+    Function that recursively divides and conquers computations for cluster j
+    @private
+    @param {number} iMin Minimum index in cluster to be computed
+    @param {number} iMax Maximum index in cluster to be computed
+    @param {number} cluster Index of the cluster currently being computed
+    @param {Array<Array<number>>} matrix
+    @param {Array<Array<number>>} backtrackMatrix
+    @param {Array<number>} sums
+    @param {Array<number>} sumsOfSquares
+*/ function fillMatrixColumn(iMin, iMax, cluster, matrix, backtrackMatrix, sums, sumsOfSquares) {
+    if (iMin > iMax) return;
+    // Start at midpoint between iMin and iMax
+    var i = Math.floor((iMin + iMax) / 2);
+    matrix[cluster][i] = matrix[cluster - 1][i - 1];
+    backtrackMatrix[cluster][i] = i;
+    var jlow = cluster; // the lower end for j
+    if (iMin > cluster) jlow = Math.max(jlow, backtrackMatrix[cluster][iMin - 1] || 0);
+    jlow = Math.max(jlow, backtrackMatrix[cluster - 1][i] || 0);
+    var jhigh = i - 1; // the upper end for j
+    if (iMax < matrix.length - 1) jhigh = Math.min(jhigh, backtrackMatrix[cluster][iMax + 1] || 0);
+    for(var j = jhigh; j >= jlow; --j){
+        var sji = ssq(j, i, sums, sumsOfSquares);
+        if (sji + matrix[cluster - 1][jlow - 1] >= matrix[cluster][i]) break;
+        // Examine the lower bound of the cluster border
+        var sjlowi = ssq(jlow, i, sums, sumsOfSquares);
+        var ssqjlow = sjlowi + matrix[cluster - 1][jlow - 1];
+        if (ssqjlow < matrix[cluster][i]) {
+            // Shrink the lower bound
+            matrix[cluster][i] = ssqjlow;
+            backtrackMatrix[cluster][i] = jlow;
+        }
+        jlow++;
+        var ssqj = sji + matrix[cluster - 1][j - 1];
+        if (ssqj < matrix[cluster][i]) {
+            matrix[cluster][i] = ssqj;
+            backtrackMatrix[cluster][i] = j;
+        }
+    }
+    fillMatrixColumn(iMin, i - 1, cluster, matrix, backtrackMatrix, sums, sumsOfSquares);
+    fillMatrixColumn(i + 1, iMax, cluster, matrix, backtrackMatrix, sums, sumsOfSquares);
+}
+/**
+    Initializes the main matrices used in Ckmeans and kicks off the divide and conquer cluster computation strategy
+    @private
+    @param {Array<number>} data sorted array of values
+    @param {Array<Array<number>>} matrix
+    @param {Array<Array<number>>} backtrackMatrix
+*/ function fillMatrices(data, matrix, backtrackMatrix) {
+    var nValues = matrix[0] ? matrix[0].length : 0;
+    // Shift values by the median to improve numeric stability
+    var shift = data[Math.floor(nValues / 2)];
+    // Cumulative sum and cumulative sum of squares for all values in data array
+    var sums = [];
+    var sumsOfSquares = [];
+    // Initialize first column in matrix & backtrackMatrix
+    for(var i = 0, shiftedValue = void 0; i < nValues; ++i){
+        shiftedValue = data[i] - shift;
+        if (i === 0) {
+            sums.push(shiftedValue);
+            sumsOfSquares.push(shiftedValue * shiftedValue);
+        } else {
+            sums.push(sums[i - 1] + shiftedValue);
+            sumsOfSquares.push(sumsOfSquares[i - 1] + shiftedValue * shiftedValue);
+        }
+        // Initialize for cluster = 0
+        matrix[0][i] = ssq(0, i, sums, sumsOfSquares);
+        backtrackMatrix[0][i] = 0;
+    }
+    // Initialize the rest of the columns
+    for(var cluster = 1; cluster < matrix.length; ++cluster){
+        var iMin = nValues - 1;
+        if (cluster < matrix.length - 1) iMin = cluster;
+        fillMatrixColumn(iMin, nValues - 1, cluster, matrix, backtrackMatrix, sums, sumsOfSquares);
+    }
+}
+/**
+    @module ckmeans
+    @desc Ported to ES6 from the excellent [simple-statistics](https://github.com/simple-statistics/simple-statistics) packages.
+
+Ckmeans clustering is an improvement on heuristic-based clustering approaches like Jenks. The algorithm was developed in [Haizhou Wang and Mingzhou Song](http://journal.r-project.org/archive/2011-2/RJournal_2011-2_Wang+Song.pdf) as a [dynamic programming](https://en.wikipedia.org/wiki/Dynamic_programming) approach to the problem of clustering numeric data into groups with the least within-group sum-of-squared-deviations.
+
+Minimizing the difference within groups - what Wang & Song refer to as `withinss`, or within sum-of-squares, means that groups are optimally homogenous within and the data is split into representative groups. This is very useful for visualization, where you may want to represent a continuous variable in discrete color or style groups. This function can provide groups that emphasize differences between data.
+
+Being a dynamic approach, this algorithm is based on two matrices that store incrementally-computed values for squared deviations and backtracking indexes.
+
+This implementation is based on Ckmeans 3.4.6, which introduced a new divide and conquer approach that improved runtime from O(kn^2) to O(kn log(n)).
+
+Unlike the [original implementation](https://cran.r-project.org/web/packages/Ckmeans.1d.dp/index.html), this implementation does not include any code to automatically determine the optimal number of clusters: this information needs to be explicitly provided.
+
+### References
+_Ckmeans.1d.dp: Optimal k-means Clustering in One Dimension by Dynamic
+Programming_ Haizhou Wang and Mingzhou Song ISSN 2073-4859 from The R Journal Vol. 3/2, December 2011
+    @param {Array<number>} data input data, as an array of number values
+    @param {number} nClusters number of desired classes. This cannot be greater than the number of values in the data array.
+    @returns {Array<Array<number>>} clustered input
+    @private
+    @example
+ckmeans([-1, 2, -1, 2, 4, 5, 6, -1, 2, -1], 3);
+// The input, clustered into groups of similar numbers.
+//= [[-1, -1, -1, -1], [2, 2, 2], [4, 5, 6]]);
+*/ export default function(data, nClusters) {
+    if (nClusters > data.length) {
+        throw new Error("Cannot generate more classes than there are data values");
+    }
+    var sorted = numericSort(data);
+    // we'll use this as the maximum number of clusters
+    var uniqueCount = uniqueCountSorted(sorted);
+    // if all of the input values are identical, there's one cluster with all of the input in it.
+    if (uniqueCount === 1) {
+        return [
+            sorted
+        ];
+    }
+    var backtrackMatrix = makeMatrix(nClusters, sorted.length), matrix = makeMatrix(nClusters, sorted.length);
+    // This is a dynamic programming way to solve the problem of minimizing within-cluster sum of squares. It's similar to linear regression in this way, and this calculation incrementally computes the sum of squares that are later read.
+    fillMatrices(sorted, matrix, backtrackMatrix);
+    // The real work of Ckmeans clustering happens in the matrix generation: the generated matrices encode all possible clustering combinations, and once they're generated we can solve for the best clustering groups very quickly.
+    var clusterRight = backtrackMatrix[0] ? backtrackMatrix[0].length - 1 : 0;
+    var clusters = [];
+    // Backtrack the clusters from the dynamic programming matrix. This starts at the bottom-right corner of the matrix (if the top-left is 0, 0), and moves the cluster target with the loop.
+    for(var cluster = backtrackMatrix.length - 1; cluster >= 0; cluster--){
+        var clusterLeft = backtrackMatrix[cluster][clusterRight];
+        // fill the cluster from the sorted input by taking a slice of the array. the backtrack matrix makes this easy - it stores the indexes where the cluster should start and end.
+        clusters[cluster] = sorted.slice(clusterLeft, clusterRight + 1);
+        if (cluster > 0) clusterRight = clusterLeft - 1;
+    }
+    return clusters;
+}

package/es/src/closest.js

@@ -0,0 +1,19 @@
+/**
+    @function closest
+    @desc Finds the closest numeric value in an array.
+    @param {Number} n The number value to use when searching the array.
+    @param {Array} arr The array of values to test against.
+*/ function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+export default function(n) {
+    var arr = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : [];
+    if (!arr || !_instanceof(arr, Array) || !arr.length) return undefined;
+    return arr.reduce(function(prev, curr) {
+        return Math.abs(curr - n) < Math.abs(prev - n) ? curr : prev;
+    });
+}