@bluemoonfoundry/daz-ts 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +377 -2
  3. package/dist/animation.d.ts +129 -0
  4. package/dist/animation.js +276 -0
  5. package/dist/batch.d.ts +118 -0
  6. package/dist/batch.js +186 -0
  7. package/dist/bone.d.ts +50 -0
  8. package/dist/bone.js +66 -0
  9. package/dist/camera.d.ts +61 -0
  10. package/dist/camera.js +120 -0
  11. package/dist/cinematics.d.ts +188 -0
  12. package/dist/cinematics.js +165 -0
  13. package/dist/client.d.ts +399 -0
  14. package/dist/client.js +769 -0
  15. package/dist/dforce.d.ts +15 -0
  16. package/dist/dforce.js +36 -0
  17. package/dist/element.d.ts +51 -0
  18. package/dist/element.js +141 -0
  19. package/dist/exceptions.d.ts +124 -0
  20. package/dist/exceptions.js +173 -0
  21. package/dist/geometry.d.ts +81 -0
  22. package/dist/geometry.js +433 -0
  23. package/dist/index.d.ts +50 -0
  24. package/dist/index.js +36 -0
  25. package/dist/light.d.ts +24 -0
  26. package/dist/light.js +40 -0
  27. package/dist/lighting.d.ts +120 -0
  28. package/dist/lighting.js +107 -0
  29. package/dist/material.d.ts +27 -0
  30. package/dist/material.js +63 -0
  31. package/dist/materials.d.ts +107 -0
  32. package/dist/materials.js +165 -0
  33. package/dist/math3.d.ts +204 -0
  34. package/dist/math3.js +502 -0
  35. package/dist/modifier.d.ts +14 -0
  36. package/dist/modifier.js +24 -0
  37. package/dist/morph.d.ts +11 -0
  38. package/dist/morph.js +24 -0
  39. package/dist/node.d.ts +196 -0
  40. package/dist/node.js +447 -0
  41. package/dist/polling.d.ts +24 -0
  42. package/dist/polling.js +50 -0
  43. package/dist/pose.d.ts +82 -0
  44. package/dist/pose.js +295 -0
  45. package/dist/poses.d.ts +54 -0
  46. package/dist/poses.js +40 -0
  47. package/dist/property.d.ts +64 -0
  48. package/dist/property.js +125 -0
  49. package/dist/render.d.ts +242 -0
  50. package/dist/render.js +811 -0
  51. package/dist/renderApi.d.ts +124 -0
  52. package/dist/renderApi.js +235 -0
  53. package/dist/result.d.ts +15 -0
  54. package/dist/result.js +1 -0
  55. package/dist/scene.d.ts +154 -0
  56. package/dist/scene.js +584 -0
  57. package/dist/sceneEvents.d.ts +63 -0
  58. package/dist/sceneEvents.js +102 -0
  59. package/dist/sceneState.d.ts +167 -0
  60. package/dist/sceneState.js +430 -0
  61. package/dist/scriptBuilder.d.ts +41 -0
  62. package/dist/scriptBuilder.js +72 -0
  63. package/dist/shotGeometry.d.ts +49 -0
  64. package/dist/shotGeometry.js +76 -0
  65. package/dist/skeleton.d.ts +120 -0
  66. package/dist/skeleton.js +561 -0
  67. package/dist/timeline.d.ts +24 -0
  68. package/dist/timeline.js +39 -0
  69. package/dist/undo.d.ts +24 -0
  70. package/dist/undo.js +45 -0
  71. package/dist/version.d.ts +31 -0
  72. package/dist/version.js +36 -0
  73. package/dist/viewport.d.ts +58 -0
  74. package/dist/viewport.js +239 -0
  75. package/package.json +52 -4
@@ -0,0 +1,120 @@
1
+ import type { DazClient } from "./client.js";
2
+ import { DazBone } from "./bone.js";
3
+ import { DazNode, type NodeIdentifier } from "./node.js";
4
+ /**
5
+ * Proxy for a `DzSkeleton` (a rigged figure such as Genesis 9). Extends
6
+ * `DazNode` with bone-access helpers.
7
+ *
8
+ * This file covers bone lookup and bulk bone/morph state (Phase 2 Task 10);
9
+ * a later task (Task 11) adds pose-evaluation/baking methods to this same
10
+ * class.
11
+ */
12
+ export declare class DazSkeleton extends DazNode {
13
+ constructor(client: DazClient, identifier: NodeIdentifier);
14
+ /**
15
+ * Wrap `body` in an IIFE that resolves this skeleton via
16
+ * `Scene.getSkeletonList()` (bound to `_node`), not `Scene.findNode()` —
17
+ * `findNode()` returns a plain `DzNode` lacking `DzSkeleton` methods like
18
+ * `findBone()`.
19
+ */
20
+ private skeletonScript;
21
+ /** Build a locator that resolves a bone through this specific skeleton (keeps same-named figures distinct). */
22
+ private boneLocator;
23
+ /** Return all bones in this skeleton. */
24
+ bones(): Promise<DazBone[]>;
25
+ /** Bulk metadata for every bone in one HTTP call (name/label/parentName/rotationOrder/localPosition/worldPosition/localEuler). */
26
+ boneMetadata(): Promise<Array<Record<string, unknown>>>;
27
+ /** Find a bone by internal name (naming conventions differ by figure generation — see {@link bones}). */
28
+ findBone(name: string): Promise<DazBone>;
29
+ /** Find a bone by its user-visible label. */
30
+ findBoneByLabel(label: string): Promise<DazBone>;
31
+ numBones(): Promise<number>;
32
+ /** Euler rotations (degrees) for every bone in one HTTP call. */
33
+ boneRotations(): Promise<Record<string, [number, number, number]>>;
34
+ /** Local-space quaternion rotations for every bone in one HTTP call — avoids per-bone Euler rotation-order ambiguity. */
35
+ boneRotationsQuat(): Promise<Record<string, {
36
+ x: number;
37
+ y: number;
38
+ z: number;
39
+ w: number;
40
+ }>>;
41
+ /** Set Euler rotations for any subset of bones in one HTTP call; bones not named are left unchanged. */
42
+ setBoneRotations(data: Record<string, [number, number, number]>): Promise<void>;
43
+ /**
44
+ * Set bone rotations, morph values, and/or node properties in one call.
45
+ * Each argument is independently optional and uses plain `setValue()`
46
+ * writes (same as {@link setBoneRotations}/{@link setMorphValues}) — `props`
47
+ * is NOT routed through any ERC-avoidance logic, so on ERC-driven node
48
+ * properties this can double-apply a controller contribution the same
49
+ * way `DazElement.setProperty` already can.
50
+ */
51
+ setState(opts: {
52
+ bones?: Record<string, [number, number, number]>;
53
+ morphs?: Record<string, number>;
54
+ props?: Record<string, unknown>;
55
+ }): Promise<void>;
56
+ /** Current value of every `DzMorph` modifier in one HTTP call; `nonzeroOnly` excludes values with `|v| <= 0.0001`. */
57
+ morphValues(nonzeroOnly?: boolean): Promise<Record<string, number>>;
58
+ /** Set the value of any subset of morphs in one HTTP call; morphs not named are left unchanged. */
59
+ setMorphValues(data: Record<string, number>): Promise<void>;
60
+ /**
61
+ * Apply candidate rotations, read effector world positions, then restore —
62
+ * the figure is left in its original state after this call.
63
+ */
64
+ evaluatePose(rotations: Record<string, [number, number, number]>, effectorBoneNames: string[]): Promise<Record<string, [number, number, number]>>;
65
+ /**
66
+ * Compute the IK Jacobian for a bone chain server-side in one HTTP call:
67
+ * perturbs each (bone, axis) pair by `stepDegrees`, reads the effector
68
+ * world position, and restores the original rotation. The figure is left
69
+ * unchanged. Returns `null` if the effector bone cannot be found.
70
+ */
71
+ evaluatePoseJacobian(chainBoneNames: string[], effectorBoneName: string, stepDegrees?: number): Promise<{
72
+ basePosition: [number, number, number];
73
+ columns: Array<[number, number, number]>;
74
+ } | null>;
75
+ /** Bake bone rotation keyframes for every frame in the range via `insertKey`. The original frame is restored before returning. */
76
+ bakeBoneRotations(opts?: {
77
+ start?: number;
78
+ end?: number;
79
+ boneNames?: string[];
80
+ }): Promise<{
81
+ framesBaked: number;
82
+ bonesBaked: number;
83
+ }>;
84
+ /** Bake morph channel keyframes for every frame in the range via `insertKey`. The original frame is restored before returning. */
85
+ bakeMorphs(opts?: {
86
+ start?: number;
87
+ end?: number;
88
+ morphNames?: string[];
89
+ }): Promise<{
90
+ framesBaked: number;
91
+ morphsBaked: number;
92
+ }>;
93
+ /** Bake bone rotations and optionally morphs in a single HTTP call (scrubs the timeline once instead of twice). */
94
+ bake(opts?: {
95
+ start?: number;
96
+ end?: number;
97
+ boneNames?: string[];
98
+ includeMorphs?: boolean;
99
+ morphNames?: string[];
100
+ }): Promise<{
101
+ framesBaked: number;
102
+ bonesBaked: number;
103
+ morphsBaked: number;
104
+ }>;
105
+ /**
106
+ * Drive every bone rotation to 0 and every non-zero `DzMorph` to 0, in one
107
+ * DazScript evaluation. Used by `poses.ts`'s `zeroFigure()` default
108
+ * (`includeProps: false`) path -- does not touch node-level properties or
109
+ * the figure root transform.
110
+ */
111
+ zeroBonesAndMorphs(): Promise<void>;
112
+ /**
113
+ * The IK follow-target skeleton, or `null` if not set.
114
+ * @remarks Aligning a limb *toward* a target ({@link DazSkeleton}'s Python
115
+ * counterpart's `hand_to_target`/`foot_to_target`) requires the Jacobian
116
+ * IK solver in `_interaction.py`, ported in Phase 5 (`daz-script-server-sf7y`) —
117
+ * not available in this phase.
118
+ */
119
+ followTarget(): Promise<DazSkeleton | null>;
120
+ }
@@ -0,0 +1,561 @@
1
+ import { DazBone } from "./bone.js";
2
+ import { NodeNotFoundError } from "./exceptions.js";
3
+ import { DazNode } from "./node.js";
4
+ import { ScriptBuilder } from "./scriptBuilder.js";
5
+ /**
6
+ * Proxy for a `DzSkeleton` (a rigged figure such as Genesis 9). Extends
7
+ * `DazNode` with bone-access helpers.
8
+ *
9
+ * This file covers bone lookup and bulk bone/morph state (Phase 2 Task 10);
10
+ * a later task (Task 11) adds pose-evaluation/baking methods to this same
11
+ * class.
12
+ */
13
+ export class DazSkeleton extends DazNode {
14
+ constructor(client, identifier) {
15
+ super(client, identifier);
16
+ }
17
+ // ---------------------------------------------------------------------
18
+ // Internal helpers
19
+ // ---------------------------------------------------------------------
20
+ /**
21
+ * Wrap `body` in an IIFE that resolves this skeleton via
22
+ * `Scene.getSkeletonList()` (bound to `_node`), not `Scene.findNode()` —
23
+ * `findNode()` returns a plain `DzNode` lacking `DzSkeleton` methods like
24
+ * `findBone()`.
25
+ */
26
+ skeletonScript(body) {
27
+ return ScriptBuilder.iife(`${ScriptBuilder.skeletonLookupAsNode(this.identifier)}\nif (!_node) return null;\n${body}`);
28
+ }
29
+ /** Build a locator that resolves a bone through this specific skeleton (keeps same-named figures distinct). */
30
+ boneLocator(boneName) {
31
+ const lookup = ScriptBuilder.skeletonLookup(this.identifier);
32
+ return `(function(){${lookup}return _skel?_skel.findBone(${ScriptBuilder.escapeString(boneName)}):null;})()`;
33
+ }
34
+ // ---------------------------------------------------------------------
35
+ // Bone lookup
36
+ // ---------------------------------------------------------------------
37
+ /** Return all bones in this skeleton. */
38
+ async bones() {
39
+ const names = (await this.client.execute(this.skeletonScript("var bones = _node.getAllBones(); var names = []; for (var i = 0; i < bones.length; i++) { names.push(bones[i].getName()); } return names;"))).value ?? [];
40
+ return names.map((n) => DazBone.fromLocator(this.client, this.boneLocator(n), n));
41
+ }
42
+ /** Bulk metadata for every bone in one HTTP call (name/label/parentName/rotationOrder/localPosition/worldPosition/localEuler). */
43
+ async boneMetadata() {
44
+ const script = this.skeletonScript(`
45
+ var bones = _node.getAllBones();
46
+ var result = [];
47
+ for (var i = 0; i < bones.length; i++) {
48
+ var b = bones[i];
49
+ var parent = b.getNodeParent();
50
+ var parent_name = null;
51
+ if (parent && parent.className && parent.className() === "DzBone") {
52
+ parent_name = parent.getName();
53
+ }
54
+ var pos = b.getLocalPos();
55
+ var wpos = b.getWSPos();
56
+ result.push({
57
+ name: b.getName(),
58
+ label: b.getLabel(),
59
+ parent_name: parent_name,
60
+ rotation_order: b.getRotationOrder(),
61
+ local_position: {x: pos.x, y: pos.y, z: pos.z},
62
+ world_position: {x: wpos.x, y: wpos.y, z: wpos.z},
63
+ local_euler: {
64
+ x: b.getXRotControl().getValue(),
65
+ y: b.getYRotControl().getValue(),
66
+ z: b.getZRotControl().getValue()
67
+ }
68
+ });
69
+ }
70
+ return result;
71
+ `);
72
+ return (await this.client.execute(script)).value ?? [];
73
+ }
74
+ /** Find a bone by internal name (naming conventions differ by figure generation — see {@link bones}). */
75
+ async findBone(name) {
76
+ const script = this.skeletonScript(`var b = _node.findBone(${ScriptBuilder.escapeString(name)}); return b ? b.getName() : null;`);
77
+ const result = (await this.client.execute(script)).value;
78
+ if (result === null) {
79
+ throw new NodeNotFoundError(`Bone not found: ${JSON.stringify(name)}. ` +
80
+ `Bone naming differs by figure generation — e.g. Genesis 9 uses ` +
81
+ `'r_forearm', Genesis 3/8 uses 'rForearmBend', Genesis 1/2 uses 'rForeArm'. ` +
82
+ `Call figure.bones() to list every bone name for this figure.`);
83
+ }
84
+ return DazBone.fromLocator(this.client, this.boneLocator(result), result);
85
+ }
86
+ /** Find a bone by its user-visible label. */
87
+ async findBoneByLabel(label) {
88
+ const script = this.skeletonScript(`var b = _node.findBoneByLabel(${ScriptBuilder.escapeString(label)}); return b ? b.getName() : null;`);
89
+ const result = (await this.client.execute(script)).value;
90
+ if (result === null) {
91
+ throw new NodeNotFoundError(`Bone with label not found: ${JSON.stringify(label)}`);
92
+ }
93
+ return DazBone.fromLocator(this.client, this.boneLocator(result), result);
94
+ }
95
+ async numBones() {
96
+ return (await this.client.execute(this.skeletonScript("return _node.getAllBones().length;"))).value ?? 0;
97
+ }
98
+ // ---------------------------------------------------------------------
99
+ // Bulk bone state
100
+ // ---------------------------------------------------------------------
101
+ /** Euler rotations (degrees) for every bone in one HTTP call. */
102
+ async boneRotations() {
103
+ const script = this.skeletonScript(`
104
+ var _bones = _node.getAllBones();
105
+ var _result = {};
106
+ for (var i = 0; i < _bones.length; i++) {
107
+ var _b = _bones[i];
108
+ _result[_b.getName()] = [
109
+ _b.getXRotControl().getValue(),
110
+ _b.getYRotControl().getValue(),
111
+ _b.getZRotControl().getValue()
112
+ ];
113
+ }
114
+ return _result;
115
+ `);
116
+ const raw = (await this.client.execute(script)).value ?? {};
117
+ const out = {};
118
+ for (const [name, v] of Object.entries(raw)) {
119
+ out[name] = [v[0], v[1], v[2]];
120
+ }
121
+ return out;
122
+ }
123
+ /** Local-space quaternion rotations for every bone in one HTTP call — avoids per-bone Euler rotation-order ambiguity. */
124
+ async boneRotationsQuat() {
125
+ const script = this.skeletonScript(`
126
+ var _bones = _node.getAllBones();
127
+ var _result = {};
128
+ for (var i = 0; i < _bones.length; i++) {
129
+ var _b = _bones[i];
130
+ var _r = _b.getLocalRot();
131
+ _result[_b.getName()] = {x: _r.x, y: _r.y, z: _r.z, w: _r.w};
132
+ }
133
+ return _result;
134
+ `);
135
+ return (await this.client.execute(script)).value ?? {};
136
+ }
137
+ /** Set Euler rotations for any subset of bones in one HTTP call; bones not named are left unchanged. */
138
+ async setBoneRotations(data) {
139
+ const dataJson = JSON.stringify(data);
140
+ const script = this.skeletonScript(`
141
+ var _data = ${dataJson};
142
+ var _bones = _node.getAllBones();
143
+ for (var i = 0; i < _bones.length; i++) {
144
+ var _b = _bones[i];
145
+ var _n = _b.getName();
146
+ if (_data.hasOwnProperty(_n)) {
147
+ var _r = _data[_n];
148
+ _b.getXRotControl().setValue(_r[0]);
149
+ _b.getYRotControl().setValue(_r[1]);
150
+ _b.getZRotControl().setValue(_r[2]);
151
+ }
152
+ }
153
+ `);
154
+ await this.client.execute(script);
155
+ }
156
+ /**
157
+ * Set bone rotations, morph values, and/or node properties in one call.
158
+ * Each argument is independently optional and uses plain `setValue()`
159
+ * writes (same as {@link setBoneRotations}/{@link setMorphValues}) — `props`
160
+ * is NOT routed through any ERC-avoidance logic, so on ERC-driven node
161
+ * properties this can double-apply a controller contribution the same
162
+ * way `DazElement.setProperty` already can.
163
+ */
164
+ async setState(opts) {
165
+ const lines = [];
166
+ if (opts.bones) {
167
+ lines.push(`
168
+ var _bonesData = ${JSON.stringify(opts.bones)};
169
+ var _allBones = _node.getAllBones();
170
+ for (var i = 0; i < _allBones.length; i++) {
171
+ var _b = _allBones[i];
172
+ var _bn = _b.getName();
173
+ if (_bonesData.hasOwnProperty(_bn)) {
174
+ var _r = _bonesData[_bn];
175
+ _b.getXRotControl().setValue(_r[0]);
176
+ _b.getYRotControl().setValue(_r[1]);
177
+ _b.getZRotControl().setValue(_r[2]);
178
+ }
179
+ }
180
+ `);
181
+ }
182
+ if (opts.morphs) {
183
+ lines.push(`
184
+ var _morphsData = ${JSON.stringify(opts.morphs)};
185
+ var _obj = _node.getObject();
186
+ if (_obj) {
187
+ for (var j = 0; j < _obj.getNumModifiers(); j++) {
188
+ var _m = _obj.getModifier(j);
189
+ if (_m.className() === "DzMorph" && _morphsData.hasOwnProperty(_m.getName())) {
190
+ _m.getValueChannel().setValue(_morphsData[_m.getName()]);
191
+ }
192
+ }
193
+ }
194
+ `);
195
+ }
196
+ if (opts.props) {
197
+ lines.push(`
198
+ var _propsData = ${JSON.stringify(opts.props)};
199
+ for (var k = 0; k < _node.getNumProperties(); k++) {
200
+ var _p = _node.getProperty(k);
201
+ var _pl = _p.getLabel();
202
+ if (_propsData.hasOwnProperty(_pl)) {
203
+ _p.setValue(_propsData[_pl]);
204
+ }
205
+ }
206
+ `);
207
+ }
208
+ if (lines.length === 0)
209
+ return;
210
+ await this.client.execute(this.skeletonScript(lines.join("\n")));
211
+ }
212
+ // ---------------------------------------------------------------------
213
+ // Bulk morph state
214
+ // ---------------------------------------------------------------------
215
+ /** Current value of every `DzMorph` modifier in one HTTP call; `nonzeroOnly` excludes values with `|v| <= 0.0001`. */
216
+ async morphValues(nonzeroOnly = false) {
217
+ const nzJs = nonzeroOnly ? "true" : "false";
218
+ const script = this.skeletonScript(`
219
+ var _obj = _node.getObject();
220
+ if (!_obj) return {};
221
+ var _result = {};
222
+ var _nz = ${nzJs};
223
+ for (var i = 0; i < _obj.getNumModifiers(); i++) {
224
+ var _m = _obj.getModifier(i);
225
+ if (_m.className() === "DzMorph") {
226
+ var _v = _m.getValueChannel().getValue();
227
+ if (!_nz || Math.abs(_v) > 0.0001) {
228
+ _result[_m.getName()] = _v;
229
+ }
230
+ }
231
+ }
232
+ return _result;
233
+ `);
234
+ return (await this.client.execute(script)).value ?? {};
235
+ }
236
+ /** Set the value of any subset of morphs in one HTTP call; morphs not named are left unchanged. */
237
+ async setMorphValues(data) {
238
+ const dataJson = JSON.stringify(data);
239
+ const script = this.skeletonScript(`
240
+ var _data = ${dataJson};
241
+ var _obj = _node.getObject();
242
+ if (!_obj) return null;
243
+ for (var i = 0; i < _obj.getNumModifiers(); i++) {
244
+ var _m = _obj.getModifier(i);
245
+ if (_m.className() === "DzMorph" && _data.hasOwnProperty(_m.getName())) {
246
+ _m.getValueChannel().setValue(_data[_m.getName()]);
247
+ }
248
+ }
249
+ `);
250
+ await this.client.execute(script);
251
+ }
252
+ // ---------------------------------------------------------------------
253
+ // Pose evaluation
254
+ // ---------------------------------------------------------------------
255
+ /**
256
+ * Apply candidate rotations, read effector world positions, then restore —
257
+ * the figure is left in its original state after this call.
258
+ */
259
+ async evaluatePose(rotations, effectorBoneNames) {
260
+ const rotationsJson = JSON.stringify(rotations);
261
+ const effectorsJson = ScriptBuilder.serializeArg(effectorBoneNames);
262
+ const script = this.skeletonScript(`
263
+ var _data = ${rotationsJson};
264
+ var _effNames = ${effectorsJson};
265
+ var _allBones = _node.getAllBones();
266
+
267
+ var _originals = {};
268
+ for (var i = 0; i < _allBones.length; i++) {
269
+ var _b = _allBones[i]; var _n = _b.getName();
270
+ if (_data.hasOwnProperty(_n)) {
271
+ _originals[_n] = [
272
+ _b.getXRotControl().getValue(),
273
+ _b.getYRotControl().getValue(),
274
+ _b.getZRotControl().getValue()
275
+ ];
276
+ var _r = _data[_n];
277
+ _b.getXRotControl().setValue(_r[0]);
278
+ _b.getYRotControl().setValue(_r[1]);
279
+ _b.getZRotControl().setValue(_r[2]);
280
+ }
281
+ }
282
+
283
+ var _result = {};
284
+ var _effSet = {};
285
+ for (var j = 0; j < _effNames.length; j++) { _effSet[_effNames[j]] = true; }
286
+ for (var i = 0; i < _allBones.length; i++) {
287
+ var _b = _allBones[i]; var _n = _b.getName();
288
+ if (_effSet.hasOwnProperty(_n)) {
289
+ var _p = _b.getWSPos();
290
+ _result[_n] = [_p.x, _p.y, _p.z];
291
+ }
292
+ }
293
+
294
+ for (var i = 0; i < _allBones.length; i++) {
295
+ var _b = _allBones[i]; var _n = _b.getName();
296
+ if (_originals.hasOwnProperty(_n)) {
297
+ var _r = _originals[_n];
298
+ _b.getXRotControl().setValue(_r[0]);
299
+ _b.getYRotControl().setValue(_r[1]);
300
+ _b.getZRotControl().setValue(_r[2]);
301
+ }
302
+ }
303
+ return _result;
304
+ `);
305
+ const raw = (await this.client.execute(script)).value ?? {};
306
+ const out = {};
307
+ for (const [name, v] of Object.entries(raw)) {
308
+ out[name] = [v[0], v[1], v[2]];
309
+ }
310
+ return out;
311
+ }
312
+ /**
313
+ * Compute the IK Jacobian for a bone chain server-side in one HTTP call:
314
+ * perturbs each (bone, axis) pair by `stepDegrees`, reads the effector
315
+ * world position, and restores the original rotation. The figure is left
316
+ * unchanged. Returns `null` if the effector bone cannot be found.
317
+ */
318
+ async evaluatePoseJacobian(chainBoneNames, effectorBoneName, stepDegrees = 1.0) {
319
+ const chainJson = ScriptBuilder.serializeArg(chainBoneNames);
320
+ const effectorJson = ScriptBuilder.escapeString(effectorBoneName);
321
+ const script = this.skeletonScript(`
322
+ var _chain = ${chainJson};
323
+ var _effName = ${effectorJson};
324
+ var _step = ${ScriptBuilder.serializeArg(stepDegrees)};
325
+
326
+ var _allBones = _node.getAllBones();
327
+ var _boneMap = {};
328
+ for (var i = 0; i < _allBones.length; i++) {
329
+ _boneMap[_allBones[i].getName()] = _allBones[i];
330
+ }
331
+
332
+ var _eff = _boneMap[_effName];
333
+ if (!_eff) return null;
334
+
335
+ var _bp = _eff.getWSPos();
336
+ var _base = [_bp.x, _bp.y, _bp.z];
337
+
338
+ var _columns = [];
339
+ for (var c = 0; c < _chain.length; c++) {
340
+ var _b = _boneMap[_chain[c]];
341
+ if (!_b) {
342
+ _columns.push([0,0,0]); _columns.push([0,0,0]); _columns.push([0,0,0]);
343
+ continue;
344
+ }
345
+ var _ctrls = [_b.getXRotControl(), _b.getYRotControl(), _b.getZRotControl()];
346
+ for (var axis = 0; axis < 3; axis++) {
347
+ var _ctrl = _ctrls[axis];
348
+ var _orig = _ctrl.getValue();
349
+ _ctrl.setValue(_orig + _step);
350
+ var _tp = _eff.getWSPos();
351
+ _ctrl.setValue(_orig);
352
+ _columns.push([
353
+ (_tp.x - _base[0]) / _step,
354
+ (_tp.y - _base[1]) / _step,
355
+ (_tp.z - _base[2]) / _step
356
+ ]);
357
+ }
358
+ }
359
+ return {base_position: _base, columns: _columns};
360
+ `);
361
+ const result = (await this.client.execute(script)).value;
362
+ if (result === null)
363
+ return null;
364
+ return { basePosition: result.base_position, columns: result.columns };
365
+ }
366
+ // ---------------------------------------------------------------------
367
+ // Keyframe baking
368
+ // ---------------------------------------------------------------------
369
+ /** Bake bone rotation keyframes for every frame in the range via `insertKey`. The original frame is restored before returning. */
370
+ async bakeBoneRotations(opts = {}) {
371
+ const startJs = opts.start !== undefined ? ScriptBuilder.serializeArg(opts.start) : "null";
372
+ const endJs = opts.end !== undefined ? ScriptBuilder.serializeArg(opts.end) : "null";
373
+ const boneFilterJs = opts.boneNames !== undefined ? JSON.stringify(Object.fromEntries(opts.boneNames.map((n) => [n, true]))) : "null";
374
+ const script = this.skeletonScript(`
375
+ var _step = Scene.getTimeStep();
376
+ var _pr = Scene.getPlayRange();
377
+ var _prStart = Math.round(_pr.start / _step);
378
+ var _prEnd = Math.round(_pr.end / _step);
379
+ var _bkStart = (${startJs} !== null) ? ${startJs} : _prStart;
380
+ var _bkEnd = (${endJs} !== null) ? ${endJs} : _prEnd;
381
+ var _filter = ${boneFilterJs};
382
+
383
+ var _all = _node.getAllBones();
384
+ var _bones = [];
385
+ for (var i = 0; i < _all.length; i++) {
386
+ if (_filter === null || _filter.hasOwnProperty(_all[i].getName()))
387
+ _bones.push(_all[i]);
388
+ }
389
+
390
+ var _origFrame = Scene.getFrame();
391
+ for (var f = _bkStart; f <= _bkEnd; f++) {
392
+ Scene.setFrame(f);
393
+ var _t = f * _step;
394
+ for (var i = 0; i < _bones.length; i++) {
395
+ var _b = _bones[i];
396
+ _b.getXRotControl().insertKey(_t, _b.getXRotControl().getValue());
397
+ _b.getYRotControl().insertKey(_t, _b.getYRotControl().getValue());
398
+ _b.getZRotControl().insertKey(_t, _b.getZRotControl().getValue());
399
+ }
400
+ }
401
+ Scene.setFrame(_origFrame);
402
+ return {frames_baked: _bkEnd - _bkStart + 1, bones_baked: _bones.length};
403
+ `);
404
+ const result = (await this.client.execute(script)).value;
405
+ return { framesBaked: result?.frames_baked ?? 0, bonesBaked: result?.bones_baked ?? 0 };
406
+ }
407
+ /** Bake morph channel keyframes for every frame in the range via `insertKey`. The original frame is restored before returning. */
408
+ async bakeMorphs(opts = {}) {
409
+ const startJs = opts.start !== undefined ? ScriptBuilder.serializeArg(opts.start) : "null";
410
+ const endJs = opts.end !== undefined ? ScriptBuilder.serializeArg(opts.end) : "null";
411
+ const morphFilterJs = opts.morphNames !== undefined ? JSON.stringify(Object.fromEntries(opts.morphNames.map((n) => [n, true]))) : "null";
412
+ const script = this.skeletonScript(`
413
+ var _step = Scene.getTimeStep();
414
+ var _pr = Scene.getPlayRange();
415
+ var _prStart = Math.round(_pr.start / _step);
416
+ var _prEnd = Math.round(_pr.end / _step);
417
+ var _bkStart = (${startJs} !== null) ? ${startJs} : _prStart;
418
+ var _bkEnd = (${endJs} !== null) ? ${endJs} : _prEnd;
419
+ var _filter = ${morphFilterJs};
420
+
421
+ var _obj = _node.getObject();
422
+ if (!_obj) return {frames_baked: 0, morphs_baked: 0};
423
+ var _channels = [];
424
+ for (var i = 0; i < _obj.getNumModifiers(); i++) {
425
+ var _m = _obj.getModifier(i);
426
+ if (_m.className() === "DzMorph" &&
427
+ (_filter === null || _filter.hasOwnProperty(_m.getName())))
428
+ _channels.push(_m.getValueChannel());
429
+ }
430
+
431
+ var _origFrame = Scene.getFrame();
432
+ for (var f = _bkStart; f <= _bkEnd; f++) {
433
+ Scene.setFrame(f);
434
+ var _t = f * _step;
435
+ for (var i = 0; i < _channels.length; i++) {
436
+ _channels[i].insertKey(_t, _channels[i].getValue());
437
+ }
438
+ }
439
+ Scene.setFrame(_origFrame);
440
+ return {frames_baked: _bkEnd - _bkStart + 1, morphs_baked: _channels.length};
441
+ `);
442
+ const result = (await this.client.execute(script)).value;
443
+ return { framesBaked: result?.frames_baked ?? 0, morphsBaked: result?.morphs_baked ?? 0 };
444
+ }
445
+ /** Bake bone rotations and optionally morphs in a single HTTP call (scrubs the timeline once instead of twice). */
446
+ async bake(opts = {}) {
447
+ const startJs = opts.start !== undefined ? ScriptBuilder.serializeArg(opts.start) : "null";
448
+ const endJs = opts.end !== undefined ? ScriptBuilder.serializeArg(opts.end) : "null";
449
+ const boneFilterJs = opts.boneNames !== undefined ? JSON.stringify(Object.fromEntries(opts.boneNames.map((n) => [n, true]))) : "null";
450
+ const morphFilterJs = opts.morphNames !== undefined ? JSON.stringify(Object.fromEntries(opts.morphNames.map((n) => [n, true]))) : "null";
451
+ const withMorphsJs = opts.includeMorphs ? "true" : "false";
452
+ const script = this.skeletonScript(`
453
+ var _step = Scene.getTimeStep();
454
+ var _pr = Scene.getPlayRange();
455
+ var _prStart = Math.round(_pr.start / _step);
456
+ var _prEnd = Math.round(_pr.end / _step);
457
+ var _bkStart = (${startJs} !== null) ? ${startJs} : _prStart;
458
+ var _bkEnd = (${endJs} !== null) ? ${endJs} : _prEnd;
459
+ var _boneFilter = ${boneFilterJs};
460
+ var _mFilter = ${morphFilterJs};
461
+ var _withMorphs = ${withMorphsJs};
462
+
463
+ var _all = _node.getAllBones();
464
+ var _bones = [];
465
+ for (var i = 0; i < _all.length; i++) {
466
+ if (_boneFilter === null || _boneFilter.hasOwnProperty(_all[i].getName()))
467
+ _bones.push(_all[i]);
468
+ }
469
+
470
+ var _mChannels = [];
471
+ if (_withMorphs) {
472
+ var _obj = _node.getObject();
473
+ if (_obj) {
474
+ for (var i = 0; i < _obj.getNumModifiers(); i++) {
475
+ var _m = _obj.getModifier(i);
476
+ if (_m.className() === "DzMorph" &&
477
+ (_mFilter === null || _mFilter.hasOwnProperty(_m.getName())))
478
+ _mChannels.push(_m.getValueChannel());
479
+ }
480
+ }
481
+ }
482
+
483
+ var _origFrame = Scene.getFrame();
484
+ for (var f = _bkStart; f <= _bkEnd; f++) {
485
+ Scene.setFrame(f);
486
+ var _t = f * _step;
487
+ for (var i = 0; i < _bones.length; i++) {
488
+ var _b = _bones[i];
489
+ _b.getXRotControl().insertKey(_t, _b.getXRotControl().getValue());
490
+ _b.getYRotControl().insertKey(_t, _b.getYRotControl().getValue());
491
+ _b.getZRotControl().insertKey(_t, _b.getZRotControl().getValue());
492
+ }
493
+ for (var i = 0; i < _mChannels.length; i++) {
494
+ _mChannels[i].insertKey(_t, _mChannels[i].getValue());
495
+ }
496
+ }
497
+ Scene.setFrame(_origFrame);
498
+ return {
499
+ frames_baked: _bkEnd - _bkStart + 1,
500
+ bones_baked: _bones.length,
501
+ morphs_baked: _mChannels.length
502
+ };
503
+ `);
504
+ const result = (await this.client.execute(script)).value;
505
+ return {
506
+ framesBaked: result?.frames_baked ?? 0,
507
+ bonesBaked: result?.bones_baked ?? 0,
508
+ morphsBaked: result?.morphs_baked ?? 0,
509
+ };
510
+ }
511
+ // ---------------------------------------------------------------------
512
+ // Zeroing
513
+ // ---------------------------------------------------------------------
514
+ /**
515
+ * Drive every bone rotation to 0 and every non-zero `DzMorph` to 0, in one
516
+ * DazScript evaluation. Used by `poses.ts`'s `zeroFigure()` default
517
+ * (`includeProps: false`) path -- does not touch node-level properties or
518
+ * the figure root transform.
519
+ */
520
+ async zeroBonesAndMorphs() {
521
+ const script = this.skeletonScript(`
522
+ var _bones = _node.getAllBones();
523
+ for (var i = 0; i < _bones.length; i++) {
524
+ var _b = _bones[i];
525
+ _b.getXRotControl().setValue(0);
526
+ _b.getYRotControl().setValue(0);
527
+ _b.getZRotControl().setValue(0);
528
+ }
529
+ var _obj = _node.getObject();
530
+ if (_obj) {
531
+ for (var j = 0; j < _obj.getNumModifiers(); j++) {
532
+ var _m = _obj.getModifier(j);
533
+ if (_m.className() === "DzMorph") {
534
+ var _ch = _m.getValueChannel();
535
+ if (Math.abs(_ch.getValue()) > 0.0001) {
536
+ _ch.setValue(0);
537
+ }
538
+ }
539
+ }
540
+ }
541
+ `);
542
+ await this.client.execute(script);
543
+ }
544
+ // ---------------------------------------------------------------------
545
+ // Follow target
546
+ // ---------------------------------------------------------------------
547
+ /**
548
+ * The IK follow-target skeleton, or `null` if not set.
549
+ * @remarks Aligning a limb *toward* a target ({@link DazSkeleton}'s Python
550
+ * counterpart's `hand_to_target`/`foot_to_target`) requires the Jacobian
551
+ * IK solver in `_interaction.py`, ported in Phase 5 (`daz-script-server-sf7y`) —
552
+ * not available in this phase.
553
+ */
554
+ async followTarget() {
555
+ const name = (await this.client.execute(this.skeletonScript("var t = _node.getFollowTarget(); return t ? t.getName() : null;")))
556
+ .value;
557
+ if (name === null)
558
+ return null;
559
+ return new DazSkeleton(this.client, { value: name, kind: "name" });
560
+ }
561
+ }