Пример
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…
sha256:d1cac9dcd4569ec4a2959a31618e58c2f75cf4eb5dce60d640462f2e09233bb3
Эта сеть предлагает одно: образец, который собирается. Она запустила его в песочнице и сохранила подписанную квитанцию. Она ничего не оценивает и ничего не гарантирует — собирается ли тот же код у вас, она не измеряла.
Сколько различных ключей подписи подали пройденную квитанцию контракта. Один — только автор; больше одного — значит, кто-то ещё тоже собрал. Ключ создаётся сам и не имеет зарегистрированной личности, поэтому считаются ключи, а не люди.
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
Контракт
- 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.
Файлы
- NOTES.md
- csx.json
- package-lock.json
- package.json
- test/contract.mjs
Исходный код
# 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.
{"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"}
{
"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"
}
}
}
{
"name": "three-skinnedmesh-applybonetransform-sample",
"version": "1.0.0",
"type": "module",
"dependencies": {
"three": "0.185.1"
}
}
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'
);