@lijuhong1981/three.utils 1.0.3

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm view *)",
+      "Bash(npm config *)",
+      "Bash(where node *)"
+    ]
+  }
+}

package/API.md

@@ -0,0 +1,179 @@
- 该方法基于threejs内部的intersect方法实现，增加了ignoreInvisible参数和checkIgnore回调函数参数，用于在检测前检查是否需要跳过该对象，以提升性能。
- 与threejs的Object3D.traverse方法类似，但增加了一个回调函数返回参数，用于在遍历过程中检查是否需要停止遍历该对象的子对象，以提升性能。
- 与threejs的Object3D.traverse方法类似，但增加了一个回调函数返回参数，用于在遍历过程中检查是否需要停止遍历该对象的子对象，以提升性能。
+## Functions
+
+<dl>
+<dt><a href="#intersect">intersect(object, raycaster, [intersects], [recursive], [ignoreInvisible], [checkIgnore])</a> ⇒ <code><a href="#Intersection">Array.&lt;Intersection&gt;</a></code></dt>
+<dd><p>检测对象与射线的相交情况，并将结果存储到相交结果数组中</p>
+<ul>
+<li>该方法基于threejs内部的intersect方法实现，增加了ignoreInvisible参数和checkIgnore回调函数参数，用于在检测前检查是否需要跳过该对象，以提升性能。</li>
+</ul>
+</dd>
+<dt><a href="#intersectObject">intersectObject(object, raycaster, [intersects], [recursive], [ignoreInvisible], [checkIgnore])</a> ⇒ <code><a href="#Intersection">Array.&lt;Intersection&gt;</a></code></dt>
+<dd><p>检查一个对象与射线的相交情况，并按由近到远顺序返回所有相交结果数组</p>
+</dd>
+<dt><a href="#intersectObjects">intersectObjects(objects, raycaster, [intersects], [recursive], [ignoreInvisible], [checkIgnore])</a> ⇒ <code><a href="#Intersection">Array.&lt;Intersection&gt;</a></code></dt>
+<dd><p>检查多个对象与射线的相交情况，并按由近到远顺序返回所有相交结果数组</p>
+</dd>
+<dt><a href="#setColorValue">setColorValue(color, value, [colorSpace])</a> ⇒ <code>Color</code></dt>
+<dd><p>为threejs的Color对象赋值</p>
+</dd>
+<dt><a href="#setValues">setValues(target, values)</a></dt>
+<dd><p>设置threejs的Obejct3D对象参数</p>
+</dd>
+<dt><a href="#setVectorValue">setVectorValue(vector, value)</a> ⇒ <code>Vector2</code> | <code>Vector3</code> | <code>Vector4</code> | <code>Euler</code> | <code>Quaternion</code> | <code>Spherical</code></dt>
+<dd><p>为threejs的Vector2或Vector3或Vector4或Euler或Quaternion或Spherical对象赋值</p>
+</dd>
+<dt><a href="#traverse">traverse(object, callback)</a></dt>
+<dd><p>遍历对象及其子对象，执行回调函数</p>
+<ul>
+<li>与threejs的Object3D.traverse方法类似，但增加了一个回调函数返回参数，用于在遍历过程中检查是否需要停止遍历该对象的子对象，以提升性能。</li>
+</ul>
+</dd>
+<dt><a href="#traverseVisible">traverseVisible(object, callback)</a></dt>
+<dd><p>遍历对象及其子对象中可见的对象，执行回调函数</p>
+<ul>
+<li>与threejs的Object3D.traverse方法类似，但增加了一个回调函数返回参数，用于在遍历过程中检查是否需要停止遍历该对象的子对象，以提升性能。</li>
+</ul>
+</dd>
+</dl>
+
+## Typedefs
+
+<dl>
+<dt><a href="#Intersection">Intersection</a> : <code>Object</code></dt>
+<dd><p>The intersection point of a raycaster intersection test.</p>
+</dd>
+</dl>
+
+<a name="intersect"></a>
+
+## intersect(object, raycaster, [intersects], [recursive], [ignoreInvisible], [checkIgnore]) ⇒ [<code>Array.&lt;Intersection&gt;</code>](#Intersection)
+检测对象与射线的相交情况，并将结果存储到相交结果数组中
+
+**Kind**: global function  
+**Returns**: [<code>Array.&lt;Intersection&gt;</code>](#Intersection) - 返回相交结果数组，如果没有相交对象，则返回空数组  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| object | <code>Object3D</code> |  | 要检测的对象实例 |
+| raycaster | <code>Raycaster</code> |  | 射线发射器对象 |
+| [intersects] | <code>Array</code> |  | 存储相交结果的数组，可不传 |
+| [recursive] | <code>boolean</code> | <code>true</code> | 是否递归检测子对象，默认true |
+| [ignoreInvisible] | <code>boolean</code> | <code>true</code> | 是否忽略不可见对象，默认true |
+| [checkIgnore] | <code>function</code> |  | 是否忽略对象的回调函数，参数为对象实例，返回true表示忽略该对象，false表示不忽略，可不传 |
+
+<a name="intersectObject"></a>
+
+## intersectObject(object, raycaster, [intersects], [recursive], [ignoreInvisible], [checkIgnore]) ⇒ [<code>Array.&lt;Intersection&gt;</code>](#Intersection)
+检查一个对象与射线的相交情况，并按由近到远顺序返回所有相交结果数组
+
+**Kind**: global function  
+**Returns**: [<code>Array.&lt;Intersection&gt;</code>](#Intersection) - 返回相交结果数组，按照距离从近到远排序，如果没有相交对象，则返回空数组  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| object | <code>Object3D</code> | 要检测的对象实例 |
+| raycaster | <code>Raycaster</code> | 射线发射器对象 |
+| [intersects] | <code>Array</code> | 存储相交结果的数组，可不传 |
+| [recursive] | <code>boolean</code> | 是否递归检测子对象，默认true |
+| [ignoreInvisible] | <code>boolean</code> | 是否忽略不可见对象，默认true |
+| [checkIgnore] | <code>function</code> | 是否忽略对象的回调函数，参数为对象实例，返回true表示忽略该对象，false表示不忽略，可不传 |
+
+<a name="intersectObjects"></a>
+
+## intersectObjects(objects, raycaster, [intersects], [recursive], [ignoreInvisible], [checkIgnore]) ⇒ [<code>Array.&lt;Intersection&gt;</code>](#Intersection)
+检查多个对象与射线的相交情况，并按由近到远顺序返回所有相交结果数组
+
+**Kind**: global function  
+**Returns**: [<code>Array.&lt;Intersection&gt;</code>](#Intersection) - 返回相交结果数组，按照距离从近到远排序，如果没有相交对象，则返回空数组  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| objects | <code>Array.&lt;Object3D&gt;</code> |  | 要检测的对象实例数组 |
+| raycaster | <code>Raycaster</code> |  | 射线发射器对象 |
+| [intersects] | <code>Array</code> |  | 存储相交结果的数组，可不传 |
+| [recursive] | <code>boolean</code> | <code>true</code> | 是否递归检测子对象，默认true |
+| [ignoreInvisible] | <code>boolean</code> | <code>true</code> | 是否忽略不可见对象，默认true |
+| [checkIgnore] | <code>function</code> |  | 是否忽略对象的回调函数，参数为对象实例，返回true表示忽略该对象，false表示不忽略，可不传 |
+
+<a name="setColorValue"></a>
+
+## setColorValue(color, value, [colorSpace]) ⇒ <code>Color</code>
+为threejs的Color对象赋值
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| color | <code>Color</code> | 要赋值的Color对象实例 |
+| value | <code>Array.&lt;number&gt;</code> \| <code>number</code> \| <code>string</code> \| <code>Color</code> | 颜色值，可以是一个包含RGB分量的数组（如[1, 0, 0]表示红色），一个十六进制数（如0xff0000表示红色），一个CSS颜色字符串（如"red"或"#ff0000"表示红色），或者另一个Color对象实例 |
+| [colorSpace] | <code>string</code> | 颜色空间，可选值为"srgb"或"srgb-linear"，仅当value为number或string时有效，表示输入的颜色值是sRGB空间还是线性空间，默认为"sRGB" |
+
+<a name="setValues"></a>
+
+## setValues(target, values)
+设置threejs的Obejct3D对象参数
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| target | <code>Object3D</code> | 要设置参数的Object3D对象实例 |
+| values | <code>object</code> | 参数对象，包含要设置的参数名称和对应的值 |
+
+<a name="setVectorValue"></a>
+
+## setVectorValue(vector, value) ⇒ <code>Vector2</code> \| <code>Vector3</code> \| <code>Vector4</code> \| <code>Euler</code> \| <code>Quaternion</code> \| <code>Spherical</code>
+为threejs的Vector2或Vector3或Vector4或Euler或Quaternion或Spherical对象赋值
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| vector | <code>Vector2</code> \| <code>Vector3</code> \| <code>Vector4</code> \| <code>Euler</code> \| <code>Quaternion</code> \| <code>Spherical</code> | 要赋值的Vector2或Vector3或Vector4或Euler或Quaternion或Spherical对象实例 |
+| value | <code>Array.&lt;number&gt;</code> \| <code>object</code> \| <code>number</code> | 向量值，可以是一个包含分量的数组（如[1, 2, 3]表示一个三维向量），或者另一个具有相同属性的对象实例（如{ x: 1, y: 2, z: 3 }表示一个三维向量），或者一个单一的数字（如0表示所有分量都设置为0） |
+
+<a name="traverse"></a>
+
+## traverse(object, callback)
+遍历对象及其子对象，执行回调函数
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| object | <code>Object3D</code> | 要遍历的对象实例 |
+| callback | <code>function</code> | 回调函数，参数为当前遍历的对象实例，返回true表示停止遍历该对象的子对象 |
+
+<a name="traverseVisible"></a>
+
+## traverseVisible(object, callback)
+遍历对象及其子对象中可见的对象，执行回调函数
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| object | <code>Object3D</code> | 要遍历的对象实例 |
+| callback | <code>function</code> | 回调函数，参数为当前遍历的对象实例，返回true表示停止遍历该对象的子对象 |
+
+<a name="Intersection"></a>
+
+## Intersection : <code>Object</code>
+The intersection point of a raycaster intersection test.
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| distance | <code>number</code> | The distance from the ray's origin to the intersection point. |
+| distanceToRay | <code>number</code> | Some 3D objects e.g. [Points](Points) provide the distance of the intersection to the nearest point on the ray. For other objects it will be `undefined`. |
+| point | <code>Vector3</code> | The intersection point, in world coordinates. |
+| face | <code>Object</code> | The face that has been intersected. |
+| faceIndex | <code>number</code> | The face index. |
+| object | <code>Object3D</code> | The 3D object that has been intersected. |
+| uv | <code>Vector2</code> | U,V coordinates at point of intersection. |
+| uv1 | <code>Vector2</code> | Second set of U,V coordinates at point of intersection. |
+| normal | <code>Vector3</code> | Interpolated normal vector at point of intersection. |
+| instanceId | <code>number</code> | The index number of the instance where the ray intersects the [InstancedMesh](InstancedMesh). |
+

package/README.md

@@ -0,0 +1,22 @@
+# threeUtils
+
+用来存放开发threejs过程中编写的一些小工具函数。
+
+## 安装
+
+```bash
+npm install @lijuhong1981/three.utils
+```
+
+## 使用
+
+```js
+import { traverse, setColorValue } from "@lijuhong1981/three.utils";
+...
+traverse(scene, (child)=>{
+    if (child.visible === false)
+        return true; //返回true表示中止遍历该对象的子对象
+});
+```
+
+## [API文档](./API.md)

package/index.js

@@ -0,0 +1,6 @@
+export * from "./src/intersect.js";
+export * from "./src/setColorValue.js";
+export * from "./src/setValues.js";
+export * from "./src/setVectorValue.js";
+export * from "./src/traverse.js";
+export * from "./src/traverseVisible.js";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@lijuhong1981/three.utils",
+  "version": "1.0.3",
+  "description": "",
+  "type": "module",
+  "module": "index.js",
+  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "docs": "jsdoc2md --files src/*.js > API.md"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lijuhong1981/threeUtils.git"
+  },
+  "keywords": [
+    "three",
+    "utils",
+    "intersect",
+    "traverse"
+  ],
+  "author": "lijuhong1981",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/lijuhong1981/threeUtils/issues"
+  },
+  "homepage": "https://github.com/lijuhong1981/threeUtils#readme",
+  "dependencies": {
+    "three": ">=0.171.0"
+  },
+  "devDependencies": {
+    "jsdoc-to-markdown": "^9.1.3"
+  }
+}

package/src/intersect.js

@@ -0,0 +1,90 @@
+import { InstancedMesh, Object3D, Points, Raycaster } from "three";
+
+/**
+ * The intersection point of a raycaster intersection test.
+ * @typedef {Object} Intersection
+ * @property {number} distance - The distance from the ray's origin to the intersection point.
+ * @property {number} distanceToRay -  Some 3D objects e.g. {@link Points} provide the distance of the intersection to the nearest point on the ray. For other objects it will be `undefined`.
+ * @property {Vector3} point - The intersection point, in world coordinates.
+ * @property {Object} face - The face that has been intersected.
+ * @property {number} faceIndex - The face index.
+ * @property {Object3D} object - The 3D object that has been intersected.
+ * @property {Vector2} uv - U,V coordinates at point of intersection.
+ * @property {Vector2} uv1 - Second set of U,V coordinates at point of intersection.
+ * @property {Vector3} normal - Interpolated normal vector at point of intersection.
+ * @property {number} instanceId - The index number of the instance where the ray intersects the {@link InstancedMesh}.
+*/
+
+/**
+ * 检测对象与射线的相交情况，并将结果存储到相交结果数组中
+ * - 该方法基于threejs内部的intersect方法实现，增加了ignoreInvisible参数和checkIgnore回调函数参数，用于在检测前检查是否需要跳过该对象，以提升性能。
+ * @param {Object3D} object - 要检测的对象实例
+ * @param {Raycaster} raycaster - 射线发射器对象
+ * @param {Array} [intersects] - 存储相交结果的数组，可不传
+ * @param {boolean} [recursive] - 是否递归检测子对象，默认true
+ * @param {boolean} [ignoreInvisible] - 是否忽略不可见对象，默认true
+ * @param {Function} [checkIgnore] - 是否忽略对象的回调函数，参数为对象实例，返回true表示忽略该对象，false表示不忽略，可不传
+ * @returns {Array<Intersection>} 返回相交结果数组，如果没有相交对象，则返回空数组
+*/
+function intersect(object, raycaster, intersects = [], recursive = true, ignoreInvisible = true, checkIgnore) {
+    if ((ignoreInvisible && !object.visible) ||
+        (typeof checkIgnore === 'function' && checkIgnore(object)))
+        return;
+
+    let propagate = true;
+    if (object.layers.test(raycaster.layers)) {
+        const result = object.raycast(raycaster, intersects);
+        if (result === false) propagate = false;
+    }
+
+    if (propagate === true && recursive === true) {
+        const children = object.children;
+        for (let i = 0, l = children.length; i < l; i++) {
+            intersect(children[i], raycaster, intersects, true, ignoreInvisible, checkIgnore);
+        }
+    }
+
+    return intersects;
+};
+
+function ascSort(a, b) {
+    return a.distance - b.distance;
+};
+
+/**
+ * 检查一个对象与射线的相交情况，并按由近到远顺序返回所有相交结果数组
+ * @param {Object3D} object - 要检测的对象实例
+ * @param {Raycaster} raycaster - 射线发射器对象
+ * @param {Array} [intersects] - 存储相交结果的数组，可不传
+ * @param {boolean} [recursive] - 是否递归检测子对象，默认true
+ * @param {boolean} [ignoreInvisible] - 是否忽略不可见对象，默认true
+ * @param {Function} [checkIgnore] - 是否忽略对象的回调函数，参数为对象实例，返回true表示忽略该对象，false表示不忽略，可不传
+ * @returns {Array<Intersection>} 返回相交结果数组，按照距离从近到远排序，如果没有相交对象，则返回空数组
+*/
+function intersectObject(object, raycaster, intersects, recursive, ignoreInvisible, checkIgnore) {
+    intersect(object, raycaster, intersects, recursive, ignoreInvisible, checkIgnore);
+    intersects.sort(ascSort);
+    return intersects;
+};
+
+
+/**
+ * 检查多个对象与射线的相交情况，并按由近到远顺序返回所有相交结果数组
+ * @param {Array<Object3D>} objects - 要检测的对象实例数组
+ * @param {Raycaster} raycaster - 射线发射器对象
+ * @param {Array} [intersects] - 存储相交结果的数组，可不传
+ * @param {boolean} [recursive] - 是否递归检测子对象，默认true
+ * @param {boolean} [ignoreInvisible] - 是否忽略不可见对象，默认true
+ * @param {Function} [checkIgnore] - 是否忽略对象的回调函数，参数为对象实例，返回true表示忽略该对象，false表示不忽略，可不传
+ * @returns {Array<Intersection>} 返回相交结果数组，按照距离从近到远排序，如果没有相交对象，则返回空数组
+*/
+function intersectObjects(objects, raycaster, intersects = [], recursive = true, ignoreInvisible = true, checkIgnore) {
+    for (let i = 0, l = objects.length; i < l; i++) {
+        intersect(objects[i], raycaster, intersects, recursive, ignoreInvisible, checkIgnore);
+    }
+    intersects.sort(ascSort);
+    return intersects;
+};
+
+export default intersect;
+export { intersect, intersectObject, intersectObjects };

package/src/setColorValue.js

@@ -0,0 +1,25 @@
+import { Color } from "three";
+
+/**
+ * 为threejs的Color对象赋值
+ * @param {Color} color - 要赋值的Color对象实例
+ * @param {Array<number>|number|string|Color} value - 颜色值，可以是一个包含RGB分量的数组（如[1, 0, 0]表示红色），一个十六进制数（如0xff0000表示红色），一个CSS颜色字符串（如"red"或"#ff0000"表示红色），或者另一个Color对象实例
+ * @param {string} [colorSpace] - 颜色空间，可选值为"srgb"或"srgb-linear"，仅当value为number或string时有效，表示输入的颜色值是sRGB空间还是线性空间，默认为"sRGB"
+ * @returns {Color}
+ */
+function setColorValue(color, value, colorSpace) {
+    if (Array.isArray(value))
+        color.fromArray(value);
+    else if (typeof value === 'number')
+        color.setHex(value, colorSpace);
+    else if (typeof value === 'string')
+        color.setStyle(value, colorSpace);
+    else if (typeof value === 'object')
+        color.copy(value);
+    else
+        console.warn("The setColorValue error, unsupported value.", value);
+    return color;
+};
+
+export default setColorValue;
+export { setColorValue };

package/src/setValues.js

@@ -0,0 +1,36 @@
+import { Object3D } from "three";
+import setColorValue from "./setColorValue.js";
+import setVectorValue from "./setVectorValue.js";
+
+/**
+ * 设置threejs的Obejct3D对象参数
+ * @param {Object3D} target - 要设置参数的Object3D对象实例
+ * @param {object} values - 参数对象，包含要设置的参数名称和对应的值
+ */
+function setValues(target, values) {
+    for (const key in values) {
+        if (values.hasOwnProperty(key) === false)
+            continue;
+        if (key in target) {
+            const newValue = values[key];
+            if (newValue === undefined) {
+                console.warn(`${values}: parameter '${key}' value is undefined.`);
+                continue;
+            }
+            const currentValue = target[key];
+            if (currentValue && currentValue.isColor) {
+                setColorValue(currentValue, newValue);
+            } else if (currentValue && (currentValue.isVector2 || currentValue.isVector3 || currentValue.isVector4 || currentValue.isEuler || currentValue.isQuaternion || currentValue.isSpherical)) {
+                setVectorValue(currentValue, newValue);
+            } else {
+                target[key] = newValue;
+            }
+        } else {
+            console.warn(`${target}: parameter '${key}' is not exist.`);
+        }
+    }
+};
+
+export default setValues;
+export { setValues };
+

package/src/setVectorValue.js

@@ -0,0 +1,26 @@
+import { Euler, Quaternion, Spherical, Vector2, Vector3, Vector4 } from "three";
+
+/**
+ * 为threejs的Vector2或Vector3或Vector4或Euler或Quaternion或Spherical对象赋值
+ * @param {Vector2|Vector3|Vector4|Euler|Quaternion|Spherical} vector - 要赋值的Vector2或Vector3或Vector4或Euler或Quaternion或Spherical对象实例
+ * @param {Array<number>|object|number} value - 向量值，可以是一个包含分量的数组（如[1, 2, 3]表示一个三维向量），或者另一个具有相同属性的对象实例（如{ x: 1, y: 2, z: 3 }表示一个三维向量），或者一个单一的数字（如0表示所有分量都设置为0）
+ * @returns {Vector2|Vector3|Vector4|Euler|Quaternion|Spherical}
+ */
+function setVectorValue(vector, value) {
+    if (Array.isArray(value))
+        vector.set(...value);
+    else if (typeof value === 'number') {
+        if (vector.isEuler)
+            vector.set(value, value, value);
+        else
+            vector.set(value, value, value, value);
+    } else if (typeof value === 'object')
+        vector.copy(value);
+    else
+        console.warn("The setVectorValue error, unsupported value.", value);
+    return vector;
+};
+
+export default setVectorValue;
+export { setVectorValue };
+

package/src/traverse.js

@@ -0,0 +1,19 @@
+import { Object3D } from "three";
+
+/**
+ * 遍历对象及其子对象，执行回调函数
+ * - 与threejs的Object3D.traverse方法类似，但增加了一个回调函数返回参数，用于在遍历过程中检查是否需要停止遍历该对象的子对象，以提升性能。
+ * @param {Object3D} object - 要遍历的对象实例
+ * @param {Function} callback - 回调函数，参数为当前遍历的对象实例，返回true表示停止遍历该对象的子对象
+*/
+function traverse(object, callback) {
+    if (callback(object) === true)
+        return;
+    const children = object.children;
+    for (let i = 0, l = children.length; i < l; i++) {
+        traverse(children[i], callback);
+    }
+};
+
+export default traverse;
+export { traverse };

package/src/traverseVisible.js

@@ -0,0 +1,21 @@
+import { Object3D } from "three";
+
+/**
+ * 遍历对象及其子对象中可见的对象，执行回调函数
+ * - 与threejs的Object3D.traverse方法类似，但增加了一个回调函数返回参数，用于在遍历过程中检查是否需要停止遍历该对象的子对象，以提升性能。
+ * @param {Object3D} object - 要遍历的对象实例
+ * @param {Function} callback - 回调函数，参数为当前遍历的对象实例，返回true表示停止遍历该对象的子对象
+*/
+function traverseVisible(object, callback) {
+    if (object.visible === false)
+        return;
+    if (callback(object) === true)
+        return;
+    const children = object.children;
+    for (let i = 0, l = children.length; i < l; i++) {
+        traverseVisible(children[i], callback);
+    }
+};
+
+export default traverseVisible;
+export { traverseVisible };