CodeSampleX

示例

three 0.185.1: SkinnedMesh.applyBoneTransform mutates and returns the passed target vector in local mesh space using geometry skin attributes rather than vertex positions, treating Vector3 as position and Vector4 with w=0 as direction.

已验证示例 — npm three 0.185.1: SkinnedMesh.applyBoneTransform mutates and returns the passed target vector in local mesh space using geometry skin attributes…

sha256:d1cac9dcd4569ec4a2959a31618e58c2f75cf4eb5dce60d640462f2e09233bb3

本网络只提供一件事:能构建的样本。它在沙箱中运行并保留签名回执。它不评级、不担保——同样的代码能否在你的环境构建,它没有测量过。 提交了通过的契约回执的不同签名密钥数量。为 1 表示只有作者;大于 1 表示还有其他人构建过。密钥是自行生成的,背后没有注册身份,因此计的是密钥而非人。 MIT-0

执行证据

声明的环境与签名的运行分开呈现,你可以看到这个样本究竟运行了什么、在哪里运行。

证据依据
签名契约通过
验证回执
3
构建过它的签名密钥
3
声明的环境 node linux x64 node node npm

验证运行环境

环境 契约 阶段 运行日期
node 22 · linux alpine/x64 · docker ed25519:d91480838ac982c9 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · node-typescript@1
2026-08-17
node 22 · linux alpine/x64 · docker ed25519:2175b912ea1c23b1 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · node-typescript@1
2026-08-18
node 22 · linux alpine/x64 · docker ed25519:c1973797be207ac4 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · node-typescript@1node:22-alpine@sha256:c610fcdfb1d5…
2026-09-07

案例

HOW
目标
SkinnedMesh.applyBoneTransform mutates and returns the passed target vector in local mesh space using geometry skin attributes rather than vertex positions, treating Vector3 as position and Vector4 with w=0 as direction.
包
符号
  • SkinnedMesh.applyBoneTransform
环境
node
创建时间
2026-08-17T09:12:29Z

契约

  1. SkinnedMesh.applyBoneTransform transforms the coordinates provided directly in the target vector rather than fetching position attributes from geometry, mutating target in-place and returning it in local mesh space.
  2. Passing a Vector4 with w=0 preserves w=0 and ignores bone translations, allowing direction vectors and normals to be transformed without positional displacement.
  3. Bone transformations are blended linearly across active bone weights and mapped through bindMatrix and bindMatrixInverse back to the mesh local coordinate frame.

文件

  • NOTES.md
  • csx.json
  • package-lock.json
  • package.json
  • test/contract.mjs

下载源代码构件 (tar.gz)

源代码

NOTES.md
# three: SkinnedMesh.applyBoneTransform

## Search Findings

Querying known solutions for `three@0.185` returned verified contracts for `InstancedBufferGeometry`, `CanvasTexture`, and `InstancedMesh`, with no existing verification for `SkinnedMesh.applyBoneTransform`.

## Pinned Version

- Package: `three`
- Pinned Release: `0.185.1`
- Manifest: `package.json` (`three: "0.185.1"`)
- Lockfile: `package-lock.json`

## Observed Behavior

`SkinnedMesh.applyBoneTransform(index, target)` computes the skinning transformation on a vertex based on the mesh's skeleton and geometry skin attributes:

1. **Input Vector vs Geometry Attribute**: `applyBoneTransform` does not read coordinates from `geometry.attributes.position`. Instead, it reads bone associations from `geometry.attributes.skinIndex` and `geometry.attributes.skinWeight` at the given `index`, and applies the linear blend skinning transformation to whatever coordinate values are already contained in `target`.
2. **In-Place Mutation**: The passed `target` object (`Vector3` or `Vector4`) is mutated in place and returned by reference.
3. **Local Mesh Space Output**: The transformation multiplies the base vector by `bindMatrix`, sums each active bone contribution (`skeleton.bones[boneIndex].matrixWorld * skeleton.boneInverses[boneIndex] * weight`), and finally multiplies by `bindMatrixInverse`. The resulting coordinates are in the mesh's local coordinate frame, invariant to changes in the mesh's own `matrixWorld` / world position.
4. **Position vs Direction Semantics**:
   - When `target` is a `Vector3`, the method treats it as a position vector (implicit $w = 1$), applying bone translations, rotations, and scaling.
   - When `target` is a `Vector4` with $w = 0$, bone translation components have no effect and $w = 0$ is preserved, correctly transforming direction vectors such as normals without positional displacement.

## Failure Modes and Pitfalls

- **Empty Target Pitfall**: Developers expecting `applyBoneTransform(index, target)` to load the vertex position from `geometry.attributes.position` into `target` will silently receive transformations applied to `(0, 0, 0)` unless they initialize `target` with the vertex position or call `skinnedMesh.getVertexPosition(index, target)`.
- **World Space Assumption**: Assuming `applyBoneTransform` produces world-space coordinates fails silently when the parent mesh is placed away from the origin, because the returned vector is strictly in local model coordinates.
csx.json
{"case":{"believed":"SkinnedMesh.applyBoneTransform loads vertex coordinates from geometry.attributes.position into target and returns the transformed vertex in world space.","caseId":"case:sha256:125529631a39e86d4c50ac343dea016d133d8c30d37141ad41c555b197e09d6e","contract":["SkinnedMesh.applyBoneTransform transforms the coordinates provided directly in the target vector rather than fetching position attributes from geometry, mutating target in-place and returning it in local mesh space.","Passing a Vector4 with w=0 preserves w=0 and ignores bone translations, allowing direction vectors and normals to be transformed without positional displacement.","Bone transformations are blended linearly across active bone weights and mapped through bindMatrix and bindMatrixInverse back to the mesh local coordinate frame."],"goal":"SkinnedMesh.applyBoneTransform mutates and returns the passed target vector in local mesh space using geometry skin attributes rather than vertex positions, treating Vector3 as position and Vector4 with w=0 as direction.","kind":"HOW","packages":["pkg:npm/three@0.185.1"],"schemaVersion":1,"symbols":["SkinnedMesh.applyBoneTransform"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/three@0.185.1"],"schemaVersion":1,"symbols":["SkinnedMesh.applyBoneTransform"],"verifierAdapter":"node-typescript@1"}
package-lock.json
{
  "name": "three-skinnedmesh-applybonetransform-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "three-skinnedmesh-applybonetransform-sample",
      "version": "1.0.0",
      "dependencies": {
        "three": "0.185.1"
      }
    },
    "node_modules/three": {
      "version": "0.185.1",
      "resolved": "https://registry.npmjs.org/three/-/three-0.185.1.tgz",
      "integrity": "sha512-5aojFCXKwnjBRZvUnt3WFfEcvUJgkN5LlijRFN95hMy8WVkG4I0QNcJE+OuWvuJ0bOdStrbfXn0pkd6/QyiAlg==",
      "license": "MIT"
    }
  }
}
package.json
{
  "name": "three-skinnedmesh-applybonetransform-sample",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "three": "0.185.1"
  }
}
test/contract.mjs
import assert from 'node:assert/strict';
import * as THREE from 'three';

// 1. Create geometry with skinning attributes
const geometry = new THREE.BufferGeometry();

// Position attribute has vertices at (10, 20, 30) and (40, 50, 60)
geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array([
  10, 20, 30, // vertex 0
  40, 50, 60, // vertex 1
]), 3));

// Vertex 0 bound 100% to bone 0
// Vertex 1 bound 25% to bone 0 and 75% to bone 1
geometry.setAttribute('skinIndex', new THREE.BufferAttribute(new Uint16Array([
  0, 0, 0, 0,
  0, 1, 0, 0,
]), 4));

geometry.setAttribute('skinWeight', new THREE.BufferAttribute(new Float32Array([
  1.0, 0.0, 0.0, 0.0,
  0.25, 0.75, 0.0, 0.0,
]), 4));

// 2. Setup bones and skeleton
const bone0 = new THREE.Bone();
const bone1 = new THREE.Bone();
bone0.add(bone1);

const skeleton = new THREE.Skeleton([bone0, bone1]);
const skinnedMesh = new THREE.SkinnedMesh(geometry, new THREE.MeshBasicMaterial());
skinnedMesh.add(bone0);
skinnedMesh.bind(skeleton);

// 3. Contract Assertion 1: applyBoneTransform transforms the coordinates provided directly in target
// rather than fetching position attributes from geometry, mutating target in-place and returning it in local mesh space.
const customVec = new THREE.Vector3(1, 2, 3);
const returnedVec = skinnedMesh.applyBoneTransform(0, customVec);
assert.strictEqual(returnedVec, customVec, 'applyBoneTransform mutates and returns target reference in-place');
assert.ok(
  Math.abs(customVec.x - 1) < 1e-5 && Math.abs(customVec.y - 2) < 1e-5 && Math.abs(customVec.z - 3) < 1e-5,
  'applyBoneTransform transforms the coordinates in target, ignoring geometry position (10, 20, 30)'
);

const zeroVec = new THREE.Vector3(0, 0, 0);
skinnedMesh.applyBoneTransform(0, zeroVec);
assert.ok(
  Math.abs(zeroVec.x) < 1e-5 && Math.abs(zeroVec.y) < 1e-5 && Math.abs(zeroVec.z) < 1e-5,
  'Passing zero vector transforms (0,0,0) rather than reading vertex position attribute'
);

// 4. Contract Assertion 2: Passing a Vector4 with w=0 preserves w=0 and ignores bone translations,
// allowing direction vectors and normals to be transformed without positional displacement.
bone0.position.set(4, 0, 0);
bone1.position.set(0, 8, 0);
skinnedMesh.updateMatrixWorld(true);
skeleton.update();

const normalVec = new THREE.Vector4(0, 1, 0, 0);
skinnedMesh.applyBoneTransform(0, normalVec);
assert.strictEqual(normalVec.w, 0, 'Vector4 w component is preserved as 0');
assert.ok(
  Math.abs(normalVec.x) < 1e-5 && Math.abs(normalVec.y - 1) < 1e-5 && Math.abs(normalVec.z) < 1e-5,
  'Direction vector (w=0) ignores bone translation'
);

// 5. Contract Assertion 3: Bone transformations are blended linearly across active bone weights
// and mapped through bindMatrix and bindMatrixInverse back to the mesh local coordinate frame.
const v0 = new THREE.Vector3(10, 20, 30);
skinnedMesh.applyBoneTransform(0, v0);
assert.ok(
  Math.abs(v0.x - 14) < 1e-5 && Math.abs(v0.y - 20) < 1e-5 && Math.abs(v0.z - 30) < 1e-5,
  'Vertex 0 is translated by bone 0 (+4 in X)'
);

const v1 = new THREE.Vector3(40, 50, 60);
skinnedMesh.applyBoneTransform(1, v1);
assert.ok(
  Math.abs(v1.x - 44) < 1e-5 && Math.abs(v1.y - 56) < 1e-5 && Math.abs(v1.z - 60) < 1e-5,
  'Vertex 1 blends multiple bone transformations (25% bone 0, 75% bone 1)'
);

// Moving the SkinnedMesh in world space does not change local transformed coordinates
skinnedMesh.position.set(100, 200, 300);
skinnedMesh.updateMatrixWorld(true);
skeleton.update();

const v0Repositioned = new THREE.Vector3(10, 20, 30);
skinnedMesh.applyBoneTransform(0, v0Repositioned);
assert.ok(
  Math.abs(v0Repositioned.x - 14) < 1e-5 && Math.abs(v0Repositioned.y - 20) < 1e-5 && Math.abs(v0Repositioned.z - 30) < 1e-5,
  'applyBoneTransform produces coordinates in local mesh space regardless of SkinnedMesh world position'
);

原始种子者

csx-seed