@visactor/vutils 1.0.24 → 1.0.26

package/README.zh-CN.md

@@ -0,0 +1,12 @@
+## 标准正态逆 CDF
+
+```ts
+import { normalQuantile } from '@visactor/vutils';
+normalQuantile(0.975); // 约 1.95996398454
+```
+
+`normalQuantile(p)` 复用回归区间原有的 Acklam 近似。p 在 (0,1) 返回有限分位数，0 / 1 返回 −Infinity / Infinity，非法概率或非有限输入返回 NaN。SciPy 1.13.1 基准检查尾部 1e-12 至 1−1e-12 和分段边界，绝对误差小于 5e-8。回归区间也调用此工具，避免维护重复实现。
+
+回归区间的 `alpha` 表示显著性水平，置信度为 `1-alpha`，默认 `alpha=0.05`。区间通过下尾概率计算临界值，避免 `1-alpha/2` 在 `alpha` 极小时舍入为 1。
+
+`alpha=0` 时，正标准误产生无限区间，零标准误产生退化区间；`alpha=1` 产生退化区间。非有限 `alpha` 或超出 `[0,1]` 的值产生 NaN 区间端点。

package/REGRESSION.md

@@ -0,0 +1,36 @@
+# 一元回归与成对 bootstrap 契约
+
+本轮修正面向 VUtil 1.0.25 的回归工具；正式 npm 1.0.25 不包含这些修复和新 API。
+
+- regressionLinear：使用中心化/缩放的一元 OLS，预测在稳定坐标中求值，保留 coef.a/b。增加 rank；常量 x 的历史常数估计继续有定义，图表需要可识别斜率时由输入边界拒绝。
+- regressionPolynomial：以归一化设计矩阵做增量 Givens QR；秩不足时对小型 R 做 Jacobi SVD 得到最小范数解，增加 rank，不再返回伪造零系数。coef 保持升幂的原始 x 坐标含义，predict 用稳定基底。degree 为非负整数，默认仍为 0。原始系数不能有限表示时明确报 RangeError。
+- regressionLowess：默认 span 从 0.3 改为 2/3、iterations 从 2 改为 3，使用全部有效观测；不再隐藏抽样或按 N 关闭稳健迭代。拟合时固定稳健状态，predict/evaluateGrid/fitted 节点一致。显式 maxSamples 保留历史抽样用途，并包含端点；delta 默认为 0，正值以观测锚点插值加速，全量观测仍参与局部权重与稳健残差。fitted 按 x 排序，保留重复样本。此默认行为调整会改变旧 LOWESS 曲线，调用方需要明确选择参数。
+- LOWESS 使用查询点附近的局部 x/y 坐标，避免远处观测压缩近邻精度；只有距离或插值区间溢出时才改用归一化 x 距离。
+- 等距离邻域选择较小 x，再按 y 排序，不依赖调用方行顺序。相同 x 的零半径邻域包含所有相同 x 观测。零核权重时用最近有效观测的加权常数，等距离取均值；没有有效稳健观测时明确报错。median=0 时保留数值精度内零残差点的权重，对明显非零残差赋零权重。
+- regressionBootstrap 从包根导出，仅 linear/polynomial。options 为 method/degree?/grid/level/resamples/seed，完整 (x,y) 成对有放回抽样，每次拟合一次。原始组须有满秩设计及正残差自由度，退化重采样在原始固定归一化基底中取最小范数解，不删抽样或重抽。每个 grid 位置按线性插值分位数生成 lower/upper，表示均值响应的逐点 percentile CI，不是预测区间。
+
+既有 confidenceInterval 的正态临界值与旧区间用途没有在本轮改成 bootstrap。尤其旧多项式/LOWESS 区间近似不能用来声称符合新的回归置信带契约；完整整理独立处理。
+
+缺失 accessor 的既有排除行为保留；无穷大不参与拟合，StatPlots 另有更严格的有限原始观测边界。新增求解器不修改输入。bootstrap 在内部对配对排序，同组同 seed 可复现；不承诺与 NumPy RNG 相同。
+
+独立数值对照使用 __tests__/fixtures/regression-python.json 的固定参考数据，文件记录参考环境的 Python、NumPy 和 statsmodels 版本；TypeScript 测试直接读取 JSON，无需 Python 运行环境。LOWESS 正常非退化数据对照 statsmodels，bootstrap 重放同一抽样索引后对照 NumPy 最小二乘与分位数。退化/ties 行为及坐标基底差异单独声明，不承诺全部参数逐位相同。
+
+性能在真实 Node 构建产物测量，避免 Jest VM 对 Math 属性代理的显著额外成本；先 npm run build，再运行 lowess-performance.test.ts 或 node benchmarks/lowess.cjs。保留原 100/150/200ms 预算，使用显式 delta 并断言所有节点保留，精确路径另由数值测试和浏览器实测覆盖。VUtils 的 Jest 配置使用单 worker，CI 的 Rush test 使用 --parallelism 1，避免同包或其他包并发测试影响墙钟预算；所有单元与性能用例均执行。
+
+## 调用示例
+
+```ts
+import { regressionLinear, regressionBootstrap, regressionLowess } from '@visactor/vutils';
+
+const samples = [{ x: 0, y: 1 }, { x: 1, y: 3 }, { x: 2, y: 4 }, { x: 3, y: 7 }];
+const model = regressionLinear(samples);
+const curve = model.evaluateGrid(100);
+const bounds = regressionBootstrap(samples, {
+  method: 'linear', grid: curve.map(p => p.x), level: 0.95, resamples: 1000, seed: 0
+});
+const smooth = regressionLowess(samples, undefined, undefined, { span: 2 / 3, iterations: 3, delta: 0 });
+// bounds 与 curve 使用相同 x；LOWESS 的 fitted 保留排序后的全部有效观测。
+const prediction = smooth.predict(1);
+```
+
+bootstrap 的 level 严格在 (0,1)，resamples 为正整数，seed 为 uint32；grid 为有限数字数组。主模型不满秩或没有残差自由度时抛出 RangeError。bootstrap 的多项式使用 method='polynomial' 和正整数 degree。图表层可采用更严格的次数和预算上限，不改变通用求解器契约。

package/cjs/angle.d.ts

@@ -1,21 +1,82 @@
 import type { IPointLike } from './data-structure/point';
+/**
+ * degree -> radian
+ * @param degree
+ * @returns radian
+ */
 export declare function degreeToRadian(degree: number): number;
+/**
+ * radian -> degree
+ * @param radian
+ * @returns
+ */
 export declare function radianToDegree(radian: number): number;
+/**
+ * 对弧度进行格式化
+ * @param a 传入的弧度
+ * @returns
+ */
 export declare const clampRadian: (angle?: number) => number;
 export declare const clampAngleByRadian: (angle?: number) => number;
+/**
+ * 对角度进行格式化
+ * @param a 角度
+ * @returns
+ */
 export declare const clampDegree: (a?: number) => number;
 export declare const clampAngleByDegree: (a?: number) => number;
+/**
+ * 根据弧度及半径计算极坐标系下的坐标点
+ * @param centerX 圆心坐标
+ * @param radius 半径
+ * @param angleInRadian 弧度
+ * @returns 返回笛卡尔坐标点
+ */
 export declare function polarToCartesian(center: IPointLike, radius: number, angleInRadian: number): {
     x: number;
     y: number;
 };
+/**
+ * 根据笛卡尔坐标系坐标计算极坐标坐标点
+ * @param point
+ * @param center 极坐标系中心点坐标
+ * @param startAngle 极坐标系起始角度
+ * @param endAngle 极坐标系结束角度
+ * @returns 极坐标系坐标点
+ */
 export declare function cartesianToPolar(point: IPointLike, center?: IPointLike, startAngle?: number, endAngle?: number): {
     radius: number;
     angle: number;
 };
+/**
+ * 根据点的笛卡尔坐标获取该点与圆心的连线同正 x 轴方向的夹角
+ * @param center 圆心坐标
+ * @param point 待求的点坐标
+ * @returns 返回夹角对应的弧度值
+ */
 export declare function getAngleByPoint(center: IPointLike, point: IPointLike): number;
+/**
+ * 角度标准化处理
+ * @param angle 弧度角
+ */
 export declare function normalizeAngle(angle: number): number;
+/**
+ * 指定开始角度和结束角度，计算这个范围内的边界角度，
+ * 即起始角度以及经过的东、南、西、北四个方向的角度
+ * 计算这个角度，可以用于计算一个弧度的bounding box 等
+ * @param startAngle 起始角度的弧度值
+ * @param endAngle    结束角度的弧度值
+ * @returns 边界角度数组
+ */
 export declare function findBoundaryAngles(startAngle: number, endAngle: number): number[];
+/**
+ * 计算指定范围内，指定中心的情况下，不超出边界的最大可用半径
+ * @param rect 矩形的大小
+ * @param center 中心点
+ * @param startAngle 起始角度的弧度值
+ * @param endAngle 结束角度的弧度值
+ * @returns 最大半径
+ */
 export declare function calculateMaxRadius(rect: {
     width: number;
     height: number;

package/cjs/angle.js

@@ -4,27 +4,58 @@ Object.defineProperty(exports, "__esModule", {
     value: !0
 }), exports.computeQuadrant = exports.calculateMaxRadius = exports.findBoundaryAngles = exports.normalizeAngle = exports.getAngleByPoint = exports.cartesianToPolar = exports.polarToCartesian = exports.clampAngleByDegree = exports.clampDegree = exports.clampAngleByRadian = exports.clampRadian = exports.radianToDegree = exports.degreeToRadian = void 0;
 
+/**
+ * 处理角度相关的数据计算
+ */
 const math_1 = require("./math");
 
-function degreeToRadian(degree) {
+/**
+ * degree -> radian
+ * @param degree
+ * @returns radian
+ */ function degreeToRadian(degree) {
     return degree * (Math.PI / 180);
 }
 
+/**
+ * radian -> degree
+ * @param radian
+ * @returns
+ */
 function radianToDegree(radian) {
     return 180 * radian / Math.PI;
 }
 
 exports.degreeToRadian = degreeToRadian, exports.radianToDegree = radianToDegree;
 
+/**
+ * 对弧度进行格式化
+ * @param a 传入的弧度
+ * @returns
+ */
 const clampRadian = (angle = 0) => {
     if (angle < 0) for (;angle < -math_1.tau; ) angle += math_1.tau; else if (angle > 0) for (;angle > math_1.tau; ) angle -= math_1.tau;
     return angle;
 };
 
-exports.clampRadian = clampRadian, exports.clampAngleByRadian = exports.clampRadian;
+exports.clampRadian = clampRadian, 
+// alias of clampRadian
+exports.clampAngleByRadian = exports.clampRadian;
 
+/**
+ * 对角度进行格式化
+ * @param a 角度
+ * @returns
+ */
 const clampDegree = (a = 0) => a > 360 || a < -360 ? a % 360 : a;
 
+/**
+ * 根据弧度及半径计算极坐标系下的坐标点
+ * @param centerX 圆心坐标
+ * @param radius 半径
+ * @param angleInRadian 弧度
+ * @returns 返回笛卡尔坐标点
+ */
 function polarToCartesian(center, radius, angleInRadian) {
     return radius ? {
         x: center.x + radius * Math.cos(angleInRadian),
@@ -35,6 +66,14 @@ function polarToCartesian(center, radius, angleInRadian) {
     };
 }
 
+/**
+ * 根据笛卡尔坐标系坐标计算极坐标坐标点
+ * @param point
+ * @param center 极坐标系中心点坐标
+ * @param startAngle 极坐标系起始角度
+ * @param endAngle 极坐标系结束角度
+ * @returns 极坐标系坐标点
+ */
 function cartesianToPolar(point, center = {
     x: 0,
     y: 0
@@ -56,16 +95,34 @@ function cartesianToPolar(point, center = {
     };
 }
 
+/**
+ * 根据点的笛卡尔坐标获取该点与圆心的连线同正 x 轴方向的夹角
+ * @param center 圆心坐标
+ * @param point 待求的点坐标
+ * @returns 返回夹角对应的弧度值
+ */
 function getAngleByPoint(center, point) {
     return Math.atan2(point.y - center.y, point.x - center.x);
 }
 
+/**
+ * 角度标准化处理
+ * @param angle 弧度角
+ */
 function normalizeAngle(angle) {
     for (;angle < 0; ) angle += 2 * Math.PI;
     for (;angle >= 2 * Math.PI; ) angle -= 2 * Math.PI;
     return angle;
 }
 
+/**
+ * 指定开始角度和结束角度，计算这个范围内的边界角度，
+ * 即起始角度以及经过的东、南、西、北四个方向的角度
+ * 计算这个角度，可以用于计算一个弧度的bounding box 等
+ * @param startAngle 起始角度的弧度值
+ * @param endAngle    结束角度的弧度值
+ * @returns 边界角度数组
+ */
 function findBoundaryAngles(startAngle, endAngle) {
     const deltaAngle = Math.abs(endAngle - startAngle);
     if (deltaAngle >= 2 * Math.PI || 2 * Math.PI - deltaAngle < 1e-6) return [ 0, Math.PI / 2, Math.PI, 1.5 * Math.PI ];
@@ -76,6 +133,14 @@ function findBoundaryAngles(startAngle, endAngle) {
     return steps;
 }
 
+/**
+ * 计算指定范围内，指定中心的情况下，不超出边界的最大可用半径
+ * @param rect 矩形的大小
+ * @param center 中心点
+ * @param startAngle 起始角度的弧度值
+ * @param endAngle 结束角度的弧度值
+ * @returns 最大半径
+ */
 function calculateMaxRadius(rect, center, startAngle, endAngle) {
     const {x: x, y: y} = center, steps = findBoundaryAngles(startAngle, endAngle), {width: width, height: height} = rect, radiusList = [];
     return steps.forEach((step => {
@@ -89,8 +154,9 @@ function computeQuadrant(angle) {
     return (angle = normalizeAngle(angle)) > 0 && angle <= Math.PI / 2 ? 2 : angle > Math.PI / 2 && angle <= Math.PI ? 3 : angle > Math.PI && angle <= 3 * Math.PI / 2 ? 4 : 1;
 }
 
-exports.clampDegree = clampDegree, exports.clampAngleByDegree = exports.clampDegree, 
-exports.polarToCartesian = polarToCartesian, exports.cartesianToPolar = cartesianToPolar, 
-exports.getAngleByPoint = getAngleByPoint, exports.normalizeAngle = normalizeAngle, 
-exports.findBoundaryAngles = findBoundaryAngles, exports.calculateMaxRadius = calculateMaxRadius, 
-exports.computeQuadrant = computeQuadrant;
+exports.clampDegree = clampDegree, 
+// alias of clampDegree
+exports.clampAngleByDegree = exports.clampDegree, exports.polarToCartesian = polarToCartesian, 
+exports.cartesianToPolar = cartesianToPolar, exports.getAngleByPoint = getAngleByPoint, 
+exports.normalizeAngle = normalizeAngle, exports.findBoundaryAngles = findBoundaryAngles, 
+exports.calculateMaxRadius = calculateMaxRadius, exports.computeQuadrant = computeQuadrant;

package/cjs/angle.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/angle.ts"],"names":[],"mappings":"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","file":"angle.js","sourcesContent":["import type { IPointLike } from './data-structure/point';\n/**\n * 处理角度相关的数据计算\n */\n\nimport { tau } from './math';\n\n/**\n * degree -> radian\n * @param degree\n * @returns radian\n */\nexport function degreeToRadian(degree: number) {\n  return degree * (Math.PI / 180);\n}\n\n/**\n * radian -> degree\n * @param radian\n * @returns\n */\nexport function radianToDegree(radian: number) {\n  return (radian * 180) / Math.PI;\n}\n\n/**\n * 对弧度进行格式化\n * @param a 传入的弧度\n * @returns\n */\nexport const clampRadian = (angle: number = 0) => {\n  if (angle < 0) {\n    while (angle < -tau) {\n      angle += tau;\n    }\n  } else if (angle > 0) {\n    while (angle > tau) {\n      angle -= tau;\n    }\n  }\n\n  return angle;\n};\n\n// alias of clampRadian\nexport const clampAngleByRadian = clampRadian;\n\n/**\n * 对角度进行格式化\n * @param a 角度\n * @returns\n */\nexport const clampDegree = (a: number = 0) => {\n  if (a > 360 || a < -360) {\n    return a % 360;\n  }\n\n  return a;\n};\n\n// alias of clampDegree\nexport const clampAngleByDegree = clampDegree;\n\n/**\n * 根据弧度及半径计算极坐标系下的坐标点\n * @param centerX 圆心坐标\n * @param radius 半径\n * @param angleInRadian 弧度\n * @returns 返回笛卡尔坐标点\n */\nexport function polarToCartesian(center: IPointLike, radius: number, angleInRadian: number): { x: number; y: number } {\n  if (!radius) {\n    return { x: center.x, y: center.y };\n  }\n\n  return {\n    x: center.x + radius * Math.cos(angleInRadian),\n    y: center.y + radius * Math.sin(angleInRadian)\n  };\n}\n\n/**\n * 根据笛卡尔坐标系坐标计算极坐标坐标点\n * @param point\n * @param center 极坐标系中心点坐标\n * @param startAngle 极坐标系起始角度\n * @param endAngle 极坐标系结束角度\n * @returns 极坐标系坐标点\n */\nexport function cartesianToPolar(\n  point: IPointLike,\n  center: IPointLike = { x: 0, y: 0 },\n  startAngle = 0,\n  endAngle = 2 * Math.PI\n) {\n  const { x, y } = point;\n  const { x: centerX, y: centerY } = center;\n\n  let dx = x - centerX;\n  let dy = y - centerY;\n  const radius = Math.sqrt(dx * dx + dy * dy);\n\n  if (radius === 0) {\n    return {\n      radius: 0,\n      angle: 0\n    };\n  }\n\n  dx /= radius;\n  dy /= radius;\n\n  let radian = Math.atan2(dy, dx);\n  if (radian < startAngle) {\n    while (radian <= startAngle) {\n      radian += Math.PI * 2;\n    }\n  }\n  if (radian > endAngle) {\n    while (radian >= endAngle) {\n      radian -= Math.PI * 2;\n    }\n  }\n  return {\n    radius,\n    angle: radian\n  };\n}\n\n/**\n * 根据点的笛卡尔坐标获取该点与圆心的连线同正 x 轴方向的夹角\n * @param center 圆心坐标\n * @param point 待求的点坐标\n * @returns 返回夹角对应的弧度值\n */\nexport function getAngleByPoint(center: IPointLike, point: IPointLike): number {\n  return Math.atan2(point.y - center.y, point.x - center.x);\n}\n\n/**\n * 角度标准化处理\n * @param angle 弧度角\n */\nexport function normalizeAngle(angle: number): number {\n  while (angle < 0) {\n    angle += Math.PI * 2;\n  }\n  while (angle >= Math.PI * 2) {\n    angle -= Math.PI * 2;\n  }\n  return angle;\n}\n\n/**\n * 指定开始角度和结束角度，计算这个范围内的边界角度，\n * 即起始角度以及经过的东、南、西、北四个方向的角度\n * 计算这个角度，可以用于计算一个弧度的bounding box 等\n * @param startAngle 起始角度的弧度值\n * @param endAngle    结束角度的弧度值\n * @returns 边界角度数组\n */\nexport function findBoundaryAngles(startAngle: number, endAngle: number) {\n  const deltaAngle = Math.abs(endAngle - startAngle);\n\n  if (deltaAngle >= 2 * Math.PI || 2 * Math.PI - deltaAngle < 1e-6) {\n    return [0, Math.PI / 2, Math.PI, 1.5 * Math.PI];\n  }\n  const min = Math.min(startAngle, endAngle);\n  const normalMin = normalizeAngle(min);\n  const normalMax = normalMin + deltaAngle;\n  const steps = [normalMin, normalMax];\n  let directionAngle = (Math.floor(normalMin / Math.PI) * Math.PI) / 2;\n\n  while (directionAngle < normalMax) {\n    if (directionAngle > normalMin) {\n      steps.push(directionAngle);\n    }\n    directionAngle += Math.PI / 2;\n  }\n\n  return steps;\n}\n/**\n * 计算指定范围内，指定中心的情况下，不超出边界的最大可用半径\n * @param rect 矩形的大小\n * @param center 中心点\n * @param startAngle 起始角度的弧度值\n * @param endAngle 结束角度的弧度值\n * @returns 最大半径\n */\nexport function calculateMaxRadius(\n  rect: { width: number; height: number },\n  center: { x: number; y: number },\n  startAngle: number,\n  endAngle: number\n) {\n  const { x, y } = center;\n  const steps = findBoundaryAngles(startAngle, endAngle);\n  const { width, height } = rect;\n\n  const radiusList: number[] = [];\n\n  steps.forEach(step => {\n    const sin = Math.sin(step);\n    const cos = Math.cos(step);\n\n    if (sin === 1) {\n      radiusList.push(height - y);\n    } else if (sin === -1) {\n      radiusList.push(y);\n    } else if (cos === 1) {\n      radiusList.push(width - x);\n    } else if (cos === -1) {\n      radiusList.push(x);\n    } else {\n      if (sin > 0) {\n        radiusList.push(Math.abs((height - y) / sin));\n      } else {\n        radiusList.push(Math.abs(y / sin));\n      }\n\n      if (cos > 0) {\n        radiusList.push(Math.abs((width - x) / cos));\n      } else {\n        radiusList.push(Math.abs(x / cos));\n      }\n    }\n  });\n\n  return Math.min.apply(null, radiusList);\n}\n\nexport type Quadrant = 1 | 2 | 3 | 4;\n\nexport function computeQuadrant(angle: number): Quadrant {\n  angle = normalizeAngle(angle);\n  if (angle > 0 && angle <= Math.PI / 2) {\n    return 2;\n  } else if (angle > Math.PI / 2 && angle <= Math.PI) {\n    return 3;\n  } else if (angle > Math.PI && angle <= (3 * Math.PI) / 2) {\n    return 4;\n  }\n  return 1;\n}\n"]}
+{"version":3,"sources":["../src/angle.ts"],"names":[],"mappings":"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","file":"angle.js","sourcesContent":["import type { IPointLike } from './data-structure/point';\n/**\n * 处理角度相关的数据计算\n */\n\nimport { tau } from './math';\n\n/**\n * degree -> radian\n * @param degree\n * @returns radian\n */\nexport function degreeToRadian(degree: number) {\n  return degree * (Math.PI / 180);\n}\n\n/**\n * radian -> degree\n * @param radian\n * @returns\n */\nexport function radianToDegree(radian: number) {\n  return (radian * 180) / Math.PI;\n}\n\n/**\n * 对弧度进行格式化\n * @param a 传入的弧度\n * @returns\n */\nexport const clampRadian = (angle: number = 0) => {\n  if (angle < 0) {\n    while (angle < -tau) {\n      angle += tau;\n    }\n  } else if (angle > 0) {\n    while (angle > tau) {\n      angle -= tau;\n    }\n  }\n\n  return angle;\n};\n\n// alias of clampRadian\nexport const clampAngleByRadian = clampRadian;\n\n/**\n * 对角度进行格式化\n * @param a 角度\n * @returns\n */\nexport const clampDegree = (a: number = 0) => {\n  if (a > 360 || a < -360) {\n    return a % 360;\n  }\n\n  return a;\n};\n\n// alias of clampDegree\nexport const clampAngleByDegree = clampDegree;\n\n/**\n * 根据弧度及半径计算极坐标系下的坐标点\n * @param centerX 圆心坐标\n * @param radius 半径\n * @param angleInRadian 弧度\n * @returns 返回笛卡尔坐标点\n */\nexport function polarToCartesian(center: IPointLike, radius: number, angleInRadian: number): { x: number; y: number } {\n  if (!radius) {\n    return { x: center.x, y: center.y };\n  }\n\n  return {\n    x: center.x + radius * Math.cos(angleInRadian),\n    y: center.y + radius * Math.sin(angleInRadian)\n  };\n}\n\n/**\n * 根据笛卡尔坐标系坐标计算极坐标坐标点\n * @param point\n * @param center 极坐标系中心点坐标\n * @param startAngle 极坐标系起始角度\n * @param endAngle 极坐标系结束角度\n * @returns 极坐标系坐标点\n */\nexport function cartesianToPolar(\n  point: IPointLike,\n  center: IPointLike = { x: 0, y: 0 },\n  startAngle = 0,\n  endAngle = 2 * Math.PI\n) {\n  const { x, y } = point;\n  const { x: centerX, y: centerY } = center;\n\n  let dx = x - centerX;\n  let dy = y - centerY;\n  const radius = Math.sqrt(dx * dx + dy * dy);\n\n  if (radius === 0) {\n    return {\n      radius: 0,\n      angle: 0\n    };\n  }\n\n  dx /= radius;\n  dy /= radius;\n\n  let radian = Math.atan2(dy, dx);\n  if (radian < startAngle) {\n    while (radian <= startAngle) {\n      radian += Math.PI * 2;\n    }\n  }\n  if (radian > endAngle) {\n    while (radian >= endAngle) {\n      radian -= Math.PI * 2;\n    }\n  }\n  return {\n    radius,\n    angle: radian\n  };\n}\n\n/**\n * 根据点的笛卡尔坐标获取该点与圆心的连线同正 x 轴方向的夹角\n * @param center 圆心坐标\n * @param point 待求的点坐标\n * @returns 返回夹角对应的弧度值\n */\nexport function getAngleByPoint(center: IPointLike, point: IPointLike): number {\n  return Math.atan2(point.y - center.y, point.x - center.x);\n}\n\n/**\n * 角度标准化处理\n * @param angle 弧度角\n */\nexport function normalizeAngle(angle: number): number {\n  while (angle < 0) {\n    angle += Math.PI * 2;\n  }\n  while (angle >= Math.PI * 2) {\n    angle -= Math.PI * 2;\n  }\n  return angle;\n}\n\n/**\n * 指定开始角度和结束角度，计算这个范围内的边界角度，\n * 即起始角度以及经过的东、南、西、北四个方向的角度\n * 计算这个角度，可以用于计算一个弧度的bounding box 等\n * @param startAngle 起始角度的弧度值\n * @param endAngle    结束角度的弧度值\n * @returns 边界角度数组\n */\nexport function findBoundaryAngles(startAngle: number, endAngle: number) {\n  const deltaAngle = Math.abs(endAngle - startAngle);\n\n  if (deltaAngle >= 2 * Math.PI || 2 * Math.PI - deltaAngle < 1e-6) {\n    return [0, Math.PI / 2, Math.PI, 1.5 * Math.PI];\n  }\n  const min = Math.min(startAngle, endAngle);\n  const normalMin = normalizeAngle(min);\n  const normalMax = normalMin + deltaAngle;\n  const steps = [normalMin, normalMax];\n  let directionAngle = (Math.floor(normalMin / Math.PI) * Math.PI) / 2;\n\n  while (directionAngle < normalMax) {\n    if (directionAngle > normalMin) {\n      steps.push(directionAngle);\n    }\n    directionAngle += Math.PI / 2;\n  }\n\n  return steps;\n}\n/**\n * 计算指定范围内，指定中心的情况下，不超出边界的最大可用半径\n * @param rect 矩形的大小\n * @param center 中心点\n * @param startAngle 起始角度的弧度值\n * @param endAngle 结束角度的弧度值\n * @returns 最大半径\n */\nexport function calculateMaxRadius(\n  rect: { width: number; height: number },\n  center: { x: number; y: number },\n  startAngle: number,\n  endAngle: number\n) {\n  const { x, y } = center;\n  const steps = findBoundaryAngles(startAngle, endAngle);\n  const { width, height } = rect;\n\n  const radiusList: number[] = [];\n\n  steps.forEach(step => {\n    const sin = Math.sin(step);\n    const cos = Math.cos(step);\n\n    if (sin === 1) {\n      radiusList.push(height - y);\n    } else if (sin === -1) {\n      radiusList.push(y);\n    } else if (cos === 1) {\n      radiusList.push(width - x);\n    } else if (cos === -1) {\n      radiusList.push(x);\n    } else {\n      if (sin > 0) {\n        radiusList.push(Math.abs((height - y) / sin));\n      } else {\n        radiusList.push(Math.abs(y / sin));\n      }\n\n      if (cos > 0) {\n        radiusList.push(Math.abs((width - x) / cos));\n      } else {\n        radiusList.push(Math.abs(x / cos));\n      }\n    }\n  });\n\n  return Math.min.apply(null, radiusList);\n}\n\nexport type Quadrant = 1 | 2 | 3 | 4;\n\nexport function computeQuadrant(angle: number): Quadrant {\n  angle = normalizeAngle(angle);\n  if (angle > 0 && angle <= Math.PI / 2) {\n    return 2;\n  } else if (angle > Math.PI / 2 && angle <= Math.PI) {\n    return 3;\n  } else if (angle > Math.PI && angle <= (3 * Math.PI) / 2) {\n    return 4;\n  }\n  return 1;\n}\n"]}

package/cjs/color/Color.d.ts

@@ -174,6 +174,9 @@ export declare class Color {
     getLuminance(): number;
     getLuminance2(): number;
     getLuminance3(): number;
+    /**
+     * https://www.w3.org/TR/WCAG21/#use-of-color
+     */
     getLuminanceWCAG(): number;
     clone(): Color;
     copyGammaToLinear(color: Color, gammaFactor?: number): this;

package/cjs/color/Color.js

@@ -1,6 +1,33 @@
 "use strict";
 
-var __importDefault = this && this.__importDefault || function(mod) {
+/*
+Copyright (c) 2013, Jason Davies.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+  * The name Jason Davies may not be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL JASON DAVIES BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/ var __importDefault = this && this.__importDefault || function(mod) {
     return mod && mod.__esModule ? mod : {
         default: mod
     };
@@ -10,6 +37,11 @@ Object.defineProperty(exports, "__esModule", {
     value: !0
 }), exports.RGB = exports.Color = exports.DEFAULT_COLORS = void 0;
 
+// Mike Bostock, https://github.com/d3/d3-color
+/**
+ * 参考 d3-color 实现。用于颜色转化
+ * 16进制/rgb 转化为r，g，b， o
+ */
 const common_1 = require("../common"), hslToRgb_1 = __importDefault(require("./hslToRgb")), rgbToHsl_1 = __importDefault(require("./rgbToHsl")), REG_HEX = /^#([0-9a-f]{3,8})$/, DEFAULT_COLORS_OPACITY = {
     transparent: 4294967040
 };
@@ -21,11 +53,13 @@ function hex(value) {
 function rgb(value) {
     return (0, common_1.isNumber)(value) ? new RGB(value >> 16, value >> 8 & 255, 255 & value, 1) : (0, 
     common_1.isArray)(value) ? new RGB(value[0], value[1], value[2]) : new RGB(255, 255, 255);
+    // default return
 }
 
 function rgba(value) {
     return (0, common_1.isNumber)(value) ? new RGB(value >>> 24, value >>> 16 & 255, value >>> 8 & 255, 255 & value) : (0, 
     common_1.isArray)(value) ? new RGB(value[0], value[1], value[2], value[3]) : new RGB(255, 255, 255, 1);
+    // default return
 }
 
 function SRGBToLinear(c) {
@@ -191,7 +225,10 @@ const setHex = (formatValue, forceHex) => {
     const isHex = REG_HEX.exec(formatValue);
     if (forceHex || isHex) {
         const hex = parseInt(isHex[1], 16), hexLength = isHex[1].length;
-        return 3 === hexLength ? new RGB((hex >> 8 & 15) + ((hex >> 8 & 15) << 4), (hex >> 4 & 15) + ((hex >> 4 & 15) << 4), (15 & hex) + ((15 & hex) << 4), 1) : 6 === hexLength ? rgb(hex) : 8 === hexLength ? new RGB(hex >> 24 & 255, hex >> 16 & 255, hex >> 8 & 255, (255 & hex) / 255) : null;
+        // #fff
+        return 3 === hexLength ? new RGB((hex >> 8 & 15) + ((hex >> 8 & 15) << 4), (hex >> 4 & 15) + ((hex >> 4 & 15) << 4), (15 & hex) + ((15 & hex) << 4), 1) : 
+        // #ffffff
+        6 === hexLength ? rgb(hex) : 8 === hexLength ? new RGB(hex >> 24 & 255, hex >> 16 & 255, hex >> 8 & 255, (255 & hex) / 255) : null;
     }
 };
 
@@ -226,15 +263,20 @@ class Color {
         }
     }
     static parseColorString(value) {
+        // case0: transparent
         if ((0, common_1.isValid)(DEFAULT_COLORS_OPACITY[value])) return rgba(DEFAULT_COLORS_OPACITY[value]);
-        if ((0, common_1.isValid)(exports.DEFAULT_COLORS[value])) return rgb(exports.DEFAULT_COLORS[value]);
+        // case1: 简写 ['blue','red']
+                if ((0, common_1.isValid)(exports.DEFAULT_COLORS[value])) return rgb(exports.DEFAULT_COLORS[value]);
         const formatValue = `${value}`.trim().toLowerCase(), hexRes = setHex(formatValue);
-        if (void 0 !== hexRes) return hexRes;
-        if (/^(rgb|RGB|rgba|RGBA)/.test(formatValue)) {
+        // case2: 16进制
+                if (void 0 !== hexRes) return hexRes;
+        // case3 : rgb
+                if (/^(rgb|RGB|rgba|RGBA)/.test(formatValue)) {
             const aColor = formatValue.replace(/(?:\(|\)|rgba|RGBA|rgb|RGB)*/g, "").split(",");
             return new RGB(parseInt(aColor[0], 10), parseInt(aColor[1], 10), parseInt(aColor[2], 10), parseFloat(aColor[3]));
         }
-        if (/^(hsl|HSL|hsla|HSLA)/.test(formatValue)) {
+        // case4: hsl
+                if (/^(hsl|HSL|hsla|HSLA)/.test(formatValue)) {
             const aColor = formatValue.replace(/(?:\(|\)|hsla|HSLA|hsl|HSL)*/g, "").split(","), rgb = (0, 
             hslToRgb_1.default)(parseInt(aColor[0], 10), parseInt(aColor[1], 10), parseInt(aColor[2], 10));
             return new RGB(rgb.r, rgb.g, rgb.b, parseFloat(aColor[3]));
@@ -242,7 +284,10 @@ class Color {
     }
     constructor(value) {
         const color = Color.parseColorString(value);
-        color ? this.color = color : (console.warn(`Warn: 传入${value}无法解析为Color`), this.color = new RGB(255, 255, 255));
+        // case0: transparent
+                color ? this.color = color : (
+        // default: 白色
+        console.warn(`Warn: 传入${value}无法解析为Color`), this.color = new RGB(255, 255, 255));
     }
     toRGBA() {
         return this.color.formatRgb();
@@ -276,6 +321,7 @@ class Color {
         this.color.g = Math.max(0, Math.min(255, Math.floor(g * color.color.g))), this.color.b = Math.max(0, Math.min(255, Math.floor(b * color.color.b))), 
         this;
     }
+    // todo: 这里亮度计算都没考虑alpha通道
     getHSVBrightness() {
         return Math.max(this.color.r, this.color.g, this.color.b) / 255;
     }
@@ -297,9 +343,13 @@ class Color {
         return null != res ? res : this;
     }
     setColorName(name) {
+        // color keywords
         const hex = exports.DEFAULT_COLORS[name.toLowerCase()];
-        return void 0 !== hex ? this.setHex(hex) : console.warn("THREE.Color: Unknown color " + name), 
-        this;
+        return void 0 !== hex ? 
+        // red
+        this.setHex(hex) : 
+        // unknown color
+        console.warn("THREE.Color: Unknown color " + name), this;
     }
     setScalar(scalar) {
         return this.color.r = scalar, this.color.g = scalar, this.color.b = scalar, this;
@@ -316,7 +366,9 @@ class Color {
     getLuminance3() {
         return (.299 * this.color.r + .587 * this.color.g + .114 * this.color.b) / 255;
     }
-    getLuminanceWCAG() {
+    /**
+     * https://www.w3.org/TR/WCAG21/#use-of-color
+     */    getLuminanceWCAG() {
         const RsRGB = this.color.r / 255, GsRGB = this.color.g / 255, BsRGB = this.color.b / 255;
         let R, G, B;
         R = RsRGB <= .03928 ? RsRGB / 12.92 : Math.pow((RsRGB + .055) / 1.055, 2.4), G = GsRGB <= .03928 ? GsRGB / 12.92 : Math.pow((GsRGB + .055) / 1.055, 2.4), 
@@ -364,6 +416,7 @@ class RGB {
         this.r = isNaN(+r) ? 255 : Math.max(0, Math.min(255, +r)), this.g = isNaN(+g) ? 255 : Math.max(0, Math.min(255, +g)), 
         this.b = isNaN(+b) ? 255 : Math.max(0, Math.min(255, +b)), (0, common_1.isValid)(opacity) ? this.opacity = isNaN(+opacity) ? 1 : Math.max(0, Math.min(1, +opacity)) : this.opacity = 1;
     }
+    // 转为16进制
     formatHex() {
         return `#${hex(this.r) + hex(this.g) + hex(this.b) + (1 === this.opacity ? "" : hex(255 * this.opacity))}`;
     }
@@ -375,6 +428,7 @@ class RGB {
         const opacity = this.opacity, {h: h, s: s, l: l} = (0, rgbToHsl_1.default)(this.r, this.g, this.b);
         return `${1 === opacity ? "hsl(" : "hsla("}${h},${s}%,${l}%${1 === opacity ? ")" : `,${opacity})`}`;
     }
+    // 转为16进制
     toString() {
         return this.formatHex();
     }