@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.
- package/LICENSE +21 -0
- package/README.md +377 -2
- package/dist/animation.d.ts +129 -0
- package/dist/animation.js +276 -0
- package/dist/batch.d.ts +118 -0
- package/dist/batch.js +186 -0
- package/dist/bone.d.ts +50 -0
- package/dist/bone.js +66 -0
- package/dist/camera.d.ts +61 -0
- package/dist/camera.js +120 -0
- package/dist/cinematics.d.ts +188 -0
- package/dist/cinematics.js +165 -0
- package/dist/client.d.ts +399 -0
- package/dist/client.js +769 -0
- package/dist/dforce.d.ts +15 -0
- package/dist/dforce.js +36 -0
- package/dist/element.d.ts +51 -0
- package/dist/element.js +141 -0
- package/dist/exceptions.d.ts +124 -0
- package/dist/exceptions.js +173 -0
- package/dist/geometry.d.ts +81 -0
- package/dist/geometry.js +433 -0
- package/dist/index.d.ts +50 -0
- package/dist/index.js +36 -0
- package/dist/light.d.ts +24 -0
- package/dist/light.js +40 -0
- package/dist/lighting.d.ts +120 -0
- package/dist/lighting.js +107 -0
- package/dist/material.d.ts +27 -0
- package/dist/material.js +63 -0
- package/dist/materials.d.ts +107 -0
- package/dist/materials.js +165 -0
- package/dist/math3.d.ts +204 -0
- package/dist/math3.js +502 -0
- package/dist/modifier.d.ts +14 -0
- package/dist/modifier.js +24 -0
- package/dist/morph.d.ts +11 -0
- package/dist/morph.js +24 -0
- package/dist/node.d.ts +196 -0
- package/dist/node.js +447 -0
- package/dist/polling.d.ts +24 -0
- package/dist/polling.js +50 -0
- package/dist/pose.d.ts +82 -0
- package/dist/pose.js +295 -0
- package/dist/poses.d.ts +54 -0
- package/dist/poses.js +40 -0
- package/dist/property.d.ts +64 -0
- package/dist/property.js +125 -0
- package/dist/render.d.ts +242 -0
- package/dist/render.js +811 -0
- package/dist/renderApi.d.ts +124 -0
- package/dist/renderApi.js +235 -0
- package/dist/result.d.ts +15 -0
- package/dist/result.js +1 -0
- package/dist/scene.d.ts +154 -0
- package/dist/scene.js +584 -0
- package/dist/sceneEvents.d.ts +63 -0
- package/dist/sceneEvents.js +102 -0
- package/dist/sceneState.d.ts +167 -0
- package/dist/sceneState.js +430 -0
- package/dist/scriptBuilder.d.ts +41 -0
- package/dist/scriptBuilder.js +72 -0
- package/dist/shotGeometry.d.ts +49 -0
- package/dist/shotGeometry.js +76 -0
- package/dist/skeleton.d.ts +120 -0
- package/dist/skeleton.js +561 -0
- package/dist/timeline.d.ts +24 -0
- package/dist/timeline.js +39 -0
- package/dist/undo.d.ts +24 -0
- package/dist/undo.js +45 -0
- package/dist/version.d.ts +31 -0
- package/dist/version.js +36 -0
- package/dist/viewport.d.ts +58 -0
- package/dist/viewport.js +239 -0
- package/package.json +52 -4
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A captured animation clip: bone rotations (and optionally morphs) for
|
|
3
|
+
* every frame in the play range. Mirrors dazpy's `_animation.py`.
|
|
4
|
+
*/
|
|
5
|
+
import * as fs from "node:fs";
|
|
6
|
+
import { NodeNotFoundError } from "./exceptions.js";
|
|
7
|
+
import { DazPose } from "./pose.js";
|
|
8
|
+
import { ScriptBuilder } from "./scriptBuilder.js";
|
|
9
|
+
/**
|
|
10
|
+
* A captured animation clip: bone rotations (and optionally morphs) for
|
|
11
|
+
* every frame in the play range.
|
|
12
|
+
*
|
|
13
|
+
* Created with {@link capture}; saved/loaded with {@link save}/{@link load}.
|
|
14
|
+
*
|
|
15
|
+
* Bones are stored as a parallel-list encoding -- a single ordered `bones`
|
|
16
|
+
* list of names, and per-frame `rotations` arrays aligned to that index --
|
|
17
|
+
* so payload size grows with bones x frames rather than with a full dict
|
|
18
|
+
* per frame.
|
|
19
|
+
*
|
|
20
|
+
* Typical workflow:
|
|
21
|
+
* ```ts
|
|
22
|
+
* const scene = new DazScene();
|
|
23
|
+
* const figure = await scene.findSkeletonByLabel("Genesis 9");
|
|
24
|
+
*
|
|
25
|
+
* const anim = await DazAnimation.capture(figure, true);
|
|
26
|
+
* anim.save("walk.json");
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
29
|
+
export class DazAnimation {
|
|
30
|
+
figure;
|
|
31
|
+
frameRange;
|
|
32
|
+
bones;
|
|
33
|
+
frames;
|
|
34
|
+
constructor(figure, frameRange, bones, frames) {
|
|
35
|
+
this.figure = figure;
|
|
36
|
+
this.frameRange = frameRange;
|
|
37
|
+
this.bones = bones;
|
|
38
|
+
this.frames = frames;
|
|
39
|
+
}
|
|
40
|
+
// ── construction ──────────────────────────────────────────────────────
|
|
41
|
+
/**
|
|
42
|
+
* Capture the full animation of `skeleton` in a single HTTP call.
|
|
43
|
+
*
|
|
44
|
+
* Scrubs every frame in the scene's play range server-side (no round-trip
|
|
45
|
+
* per frame). The timeline is restored to its original frame before the
|
|
46
|
+
* call returns.
|
|
47
|
+
*
|
|
48
|
+
* When `includeMorphs` is `true`, the script first identifies which
|
|
49
|
+
* geometry morphs and node-level properties actually vary across the
|
|
50
|
+
* timeline (channels that are keyed but static are excluded), then
|
|
51
|
+
* records their values per frame.
|
|
52
|
+
*
|
|
53
|
+
* @throws NodeNotFoundError If the skeleton is not found.
|
|
54
|
+
*/
|
|
55
|
+
static async capture(skeleton, includeMorphs = false) {
|
|
56
|
+
const lookup = ScriptBuilder.skeletonLookup(skeleton.identifier);
|
|
57
|
+
const includeMorphsJs = includeMorphs ? "true" : "false";
|
|
58
|
+
const script = ScriptBuilder.iife(`
|
|
59
|
+
${lookup}
|
|
60
|
+
if (!_skel) return null;
|
|
61
|
+
|
|
62
|
+
var _origFrame = Scene.getFrame();
|
|
63
|
+
|
|
64
|
+
var allBones = _skel.getAllBones();
|
|
65
|
+
var boneNames = [];
|
|
66
|
+
for (var i = 0; i < allBones.length; i++) boneNames.push(allBones[i].getName());
|
|
67
|
+
|
|
68
|
+
// Detect channels whose values actually vary across the timeline.
|
|
69
|
+
// Channels that are keyed but hold a constant value are excluded --
|
|
70
|
+
// they add payload without contributing animation data.
|
|
71
|
+
function isVaryingMorph(ch) {
|
|
72
|
+
var n = ch.getNumKeys();
|
|
73
|
+
if (n < 2) return false;
|
|
74
|
+
var first = ch.getKeyValue(0);
|
|
75
|
+
for (var k = 1; k < n; k++) {
|
|
76
|
+
if (Math.abs(ch.getKeyValue(k) - first) > 0.0001) return true;
|
|
77
|
+
}
|
|
78
|
+
return false;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
var animatedChannels = [];
|
|
82
|
+
if (${includeMorphsJs}) {
|
|
83
|
+
var obj = _skel.getObject();
|
|
84
|
+
if (obj) {
|
|
85
|
+
for (var i = 0; i < obj.getNumModifiers(); i++) {
|
|
86
|
+
var m = obj.getModifier(i);
|
|
87
|
+
if (m.className() === "DzMorph" && isVaryingMorph(m.getValueChannel()))
|
|
88
|
+
animatedChannels.push([m.getName(), m.getValueChannel()]);
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
for (var i = 0; i < _skel.getNumProperties(); i++) {
|
|
92
|
+
var p = _skel.getProperty(i);
|
|
93
|
+
if (p && p.getNumKeys && isVaryingMorph(p))
|
|
94
|
+
animatedChannels.push([p.getName(), p]);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
var step = Scene.getTimeStep();
|
|
99
|
+
var range = Scene.getPlayRange();
|
|
100
|
+
var start = Math.round(range.start / step);
|
|
101
|
+
var end = Math.round(range.end / step);
|
|
102
|
+
|
|
103
|
+
var frames = [];
|
|
104
|
+
for (var f = start; f <= end; f++) {
|
|
105
|
+
Scene.setFrame(f);
|
|
106
|
+
|
|
107
|
+
var rotations = [];
|
|
108
|
+
for (var i = 0; i < allBones.length; i++) {
|
|
109
|
+
var b = allBones[i];
|
|
110
|
+
rotations.push([
|
|
111
|
+
b.getXRotControl().getValue(),
|
|
112
|
+
b.getYRotControl().getValue(),
|
|
113
|
+
b.getZRotControl().getValue()
|
|
114
|
+
]);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
var morphs = {};
|
|
118
|
+
for (var i = 0; i < animatedChannels.length; i++) {
|
|
119
|
+
var v = animatedChannels[i][1].getValue();
|
|
120
|
+
if (Math.abs(v) > 0.0001) morphs[animatedChannels[i][0]] = v;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
frames.push({frame: f, rotations: rotations, morphs: morphs});
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
Scene.setFrame(_origFrame);
|
|
127
|
+
|
|
128
|
+
return {
|
|
129
|
+
figure: _skel.getLabel(),
|
|
130
|
+
frame_range: {start: start, end: end},
|
|
131
|
+
bones: boneNames,
|
|
132
|
+
frames: frames
|
|
133
|
+
};
|
|
134
|
+
`);
|
|
135
|
+
const result = (await skeleton.getClient().execute(script)).value;
|
|
136
|
+
if (result === null) {
|
|
137
|
+
throw new NodeNotFoundError(`Skeleton not found: ${JSON.stringify(skeleton.identifier.value)}`);
|
|
138
|
+
}
|
|
139
|
+
return new DazAnimation(result.figure, result.frame_range, result.bones, result.frames);
|
|
140
|
+
}
|
|
141
|
+
/** Load an animation from a JSON file. Accepts files produced by {@link save}. */
|
|
142
|
+
static load(path) {
|
|
143
|
+
const data = JSON.parse(fs.readFileSync(path, "utf-8"));
|
|
144
|
+
return new DazAnimation(data.figure ?? "", data.frame_range ?? { start: 0, end: 0 }, data.bones ?? [], data.frames ?? []);
|
|
145
|
+
}
|
|
146
|
+
// ── serialisation ─────────────────────────────────────────────────────
|
|
147
|
+
/** Write this animation to a JSON file. Parent directories must exist. */
|
|
148
|
+
save(path) {
|
|
149
|
+
fs.writeFileSync(path, JSON.stringify(this.toDict(), null, 2), "utf-8");
|
|
150
|
+
}
|
|
151
|
+
/** Return the animation as a plain dict (same schema as the JSON file). */
|
|
152
|
+
toDict() {
|
|
153
|
+
return { figure: this.figure, frame_range: this.frameRange, bones: this.bones, frames: this.frames };
|
|
154
|
+
}
|
|
155
|
+
// ── clip operations ───────────────────────────────────────────────────
|
|
156
|
+
/**
|
|
157
|
+
* Return a new animation containing only frames in [start, end].
|
|
158
|
+
*
|
|
159
|
+
* `start` and `end` are scene frame numbers (the `frame` value stored in
|
|
160
|
+
* each frame, not array indices). Both endpoints are inclusive.
|
|
161
|
+
*/
|
|
162
|
+
clip(start, end) {
|
|
163
|
+
const frames = this.frames.filter((f) => start <= f.frame && f.frame <= end);
|
|
164
|
+
const newStart = frames.length > 0 ? frames[0].frame : start;
|
|
165
|
+
const newEnd = frames.length > 0 ? frames[frames.length - 1].frame : end;
|
|
166
|
+
return new DazAnimation(this.figure, { start: newStart, end: newEnd }, this.bones, frames);
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* Blend this animation with `other` frame by frame.
|
|
170
|
+
*
|
|
171
|
+
* Each frame's bone rotations and morph values are linearly interpolated
|
|
172
|
+
* between `this` (`t=0`) and `other` (`t=1`). Pure -- no HTTP round-trip.
|
|
173
|
+
*
|
|
174
|
+
* If the two clips have different frame counts, the result is truncated
|
|
175
|
+
* to the shorter clip. Frame numbers are taken from `this`.
|
|
176
|
+
*
|
|
177
|
+
* @throws Error If `this` and `other` have different bone lists.
|
|
178
|
+
*/
|
|
179
|
+
blend(other, t) {
|
|
180
|
+
if (JSON.stringify(this.bones) !== JSON.stringify(other.bones)) {
|
|
181
|
+
throw new Error(`Cannot blend animations with different bone lists (${this.bones.length} vs ${other.bones.length} bones)`);
|
|
182
|
+
}
|
|
183
|
+
const s = 1.0 - t;
|
|
184
|
+
const frames = [];
|
|
185
|
+
const n = Math.min(this.frames.length, other.frames.length);
|
|
186
|
+
for (let i = 0; i < n; i++) {
|
|
187
|
+
const fa = this.frames[i];
|
|
188
|
+
const fb = other.frames[i];
|
|
189
|
+
const rotations = this.bones.map((_, bi) => [
|
|
190
|
+
fa.rotations[bi][0] * s + fb.rotations[bi][0] * t,
|
|
191
|
+
fa.rotations[bi][1] * s + fb.rotations[bi][1] * t,
|
|
192
|
+
fa.rotations[bi][2] * s + fb.rotations[bi][2] * t,
|
|
193
|
+
]);
|
|
194
|
+
const morphs = {};
|
|
195
|
+
for (const k of new Set([...Object.keys(fa.morphs), ...Object.keys(fb.morphs)])) {
|
|
196
|
+
const v = (fa.morphs[k] ?? 0.0) * s + (fb.morphs[k] ?? 0.0) * t;
|
|
197
|
+
if (Math.abs(v) > 1e-9)
|
|
198
|
+
morphs[k] = v;
|
|
199
|
+
}
|
|
200
|
+
frames.push({ frame: fa.frame, rotations, morphs });
|
|
201
|
+
}
|
|
202
|
+
const newEnd = frames.length > 0 ? frames[frames.length - 1].frame : this.frameRange.start;
|
|
203
|
+
return new DazAnimation(this.figure, { start: this.frameRange.start, end: newEnd }, this.bones, frames);
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Extract a single frame as a {@link DazPose}.
|
|
207
|
+
*
|
|
208
|
+
* Bone rotations are stored sparsely -- only bones with at least one
|
|
209
|
+
* non-zero component are included. Morph values are copied as-is. Pure --
|
|
210
|
+
* no HTTP round-trip.
|
|
211
|
+
*
|
|
212
|
+
* @param frameIndex 0-based index into {@link frames}.
|
|
213
|
+
*/
|
|
214
|
+
asPose(frameIndex = 0) {
|
|
215
|
+
const frame = this.frames[frameIndex];
|
|
216
|
+
const bones = {};
|
|
217
|
+
this.bones.forEach((name, i) => {
|
|
218
|
+
const rot = frame.rotations[i];
|
|
219
|
+
if (rot.some((v) => Math.abs(v) > 1e-9)) {
|
|
220
|
+
bones[name] = rot;
|
|
221
|
+
}
|
|
222
|
+
});
|
|
223
|
+
return new DazPose(this.figure, bones, { ...frame.morphs }, {});
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Apply a single frame of this animation to `skeleton`.
|
|
227
|
+
*
|
|
228
|
+
* Equivalent to `(await anim.asPose(frameIndex)).apply(skeleton)` -- one
|
|
229
|
+
* HTTP call that sets only the channels present in the frame.
|
|
230
|
+
*
|
|
231
|
+
* @param frameIndex 0-based index into {@link frames}. Defaults to 0.
|
|
232
|
+
*/
|
|
233
|
+
async apply(skeleton, frameIndex = 0) {
|
|
234
|
+
await this.asPose(frameIndex).apply(skeleton);
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Concatenate `other` immediately after this animation.
|
|
238
|
+
*
|
|
239
|
+
* The other clip's frame numbers are shifted so it starts on the frame
|
|
240
|
+
* following this animation's last frame. The figure label and bone list
|
|
241
|
+
* are taken from `this`. Pure -- no HTTP round-trip.
|
|
242
|
+
*
|
|
243
|
+
* @throws Error If `this` and `other` have different bone lists.
|
|
244
|
+
*/
|
|
245
|
+
append(other) {
|
|
246
|
+
if (JSON.stringify(this.bones) !== JSON.stringify(other.bones)) {
|
|
247
|
+
throw new Error(`Cannot append animations with different bone lists (${this.bones.length} vs ${other.bones.length} bones)`);
|
|
248
|
+
}
|
|
249
|
+
if (this.frames.length === 0) {
|
|
250
|
+
return new DazAnimation(this.figure, { ...other.frameRange }, [...other.bones], [...other.frames]);
|
|
251
|
+
}
|
|
252
|
+
const offset = this.frameRange.end + 1 - other.frameRange.start;
|
|
253
|
+
const otherFrames = other.frames.map((f) => ({
|
|
254
|
+
frame: f.frame + offset,
|
|
255
|
+
rotations: f.rotations,
|
|
256
|
+
morphs: f.morphs,
|
|
257
|
+
}));
|
|
258
|
+
const frames = [...this.frames, ...otherFrames];
|
|
259
|
+
return new DazAnimation(this.figure, { start: this.frameRange.start, end: frames[frames.length - 1].frame }, this.bones, frames);
|
|
260
|
+
}
|
|
261
|
+
// ── convenience ───────────────────────────────────────────────────────
|
|
262
|
+
/** Number of captured frames. */
|
|
263
|
+
get frameCount() {
|
|
264
|
+
return this.frames.length;
|
|
265
|
+
}
|
|
266
|
+
/** Number of bones in the skeleton at capture time. */
|
|
267
|
+
get boneCount() {
|
|
268
|
+
return this.bones.length;
|
|
269
|
+
}
|
|
270
|
+
// ── dunder ────────────────────────────────────────────────────────────
|
|
271
|
+
toString() {
|
|
272
|
+
return (`DazAnimation(figure=${JSON.stringify(this.figure)}, ` +
|
|
273
|
+
`frames=${this.frameCount}, bones=${this.boneCount}, ` +
|
|
274
|
+
`range=${this.frameRange.start}–${this.frameRange.end})`);
|
|
275
|
+
}
|
|
276
|
+
}
|
package/dist/batch.d.ts
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import type { DazClient } from "./client.js";
|
|
2
|
+
export declare const DEFAULT_MAX_OPERATIONS = 500;
|
|
3
|
+
export declare const DEFAULT_MAX_SCRIPT_LENGTH = 900000;
|
|
4
|
+
/**
|
|
5
|
+
* Build one IIFE script from a list of `[bodyLines, resultExpression]` pairs.
|
|
6
|
+
*
|
|
7
|
+
* Shared by {@link Batch}'s internal script builder and
|
|
8
|
+
* {@link DazClient.executeBatchAsync} so both produce scripts with an
|
|
9
|
+
* identical shape (keyed return object over `_r0`, `_r1`, ...).
|
|
10
|
+
*
|
|
11
|
+
* @param operations - `[bodyLines, resultExpression]` pairs, in submission order.
|
|
12
|
+
* @param preludeLines - Optional shared setup lines emitted once, before any
|
|
13
|
+
* operation's lines. Used by {@link Batch}, which deduplicates its preludes
|
|
14
|
+
* before passing them here; `executeBatchAsync` has no preludes and omits this.
|
|
15
|
+
*/
|
|
16
|
+
export declare function buildOperationsScript(operations: Array<[string[], string]>, preludeLines?: string[]): string;
|
|
17
|
+
/**
|
|
18
|
+
* Placeholder for a single result within a {@link Batch} execution.
|
|
19
|
+
*
|
|
20
|
+
* Created by {@link Batch.add} or {@link Batch.addOperation}; the `value`
|
|
21
|
+
* getter throws until the batch has been executed.
|
|
22
|
+
*/
|
|
23
|
+
export declare class BatchFuture {
|
|
24
|
+
private readonly key;
|
|
25
|
+
private resolved;
|
|
26
|
+
private resultValue;
|
|
27
|
+
constructor(key: string);
|
|
28
|
+
/** The result value. Throws if {@link Batch.execute} has not been called yet. */
|
|
29
|
+
get value(): unknown;
|
|
30
|
+
/** @internal */
|
|
31
|
+
_resolve(value: unknown): void;
|
|
32
|
+
/** @internal */
|
|
33
|
+
get _key(): string;
|
|
34
|
+
}
|
|
35
|
+
/** Options accepted by the {@link Batch} constructor. */
|
|
36
|
+
export interface BatchOptions {
|
|
37
|
+
/** Max queued operations before {@link Batch.add}/{@link Batch.addOperation} throw {@link BatchLimitExceededError}. */
|
|
38
|
+
maxOperations?: number;
|
|
39
|
+
/** Max generated script length (characters) before {@link Batch.execute} throws {@link BatchLimitExceededError}. */
|
|
40
|
+
maxScriptLength?: number;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Collect multiple DazScript operations and execute them in a single HTTP round-trip.
|
|
44
|
+
*
|
|
45
|
+
* Semantics (preserved exactly from dazpy, do not "improve" silently):
|
|
46
|
+
* execution is **serial**, there is **no parallelism**, and the batch is
|
|
47
|
+
* **not transactional** — if any operation throws, the whole call fails
|
|
48
|
+
* the same way a single failing `execute()` call would, and earlier
|
|
49
|
+
* mutations already applied to the live scene are **not** rolled back.
|
|
50
|
+
* Order destructive/hard-to-recover operations last.
|
|
51
|
+
*
|
|
52
|
+
* @example
|
|
53
|
+
* ```ts
|
|
54
|
+
* const batch = new Batch(client);
|
|
55
|
+
* const posFuture = batch.addOperation(
|
|
56
|
+
* ["var n = Scene.findNode('Figure');", "var p = [n.getWSPos().x, n.getWSPos().y, n.getWSPos().z];"],
|
|
57
|
+
* "p",
|
|
58
|
+
* );
|
|
59
|
+
* await batch.execute();
|
|
60
|
+
* console.log(posFuture.value);
|
|
61
|
+
* ```
|
|
62
|
+
*/
|
|
63
|
+
export declare class Batch {
|
|
64
|
+
private readonly client;
|
|
65
|
+
private readonly ops;
|
|
66
|
+
private readonly preludes;
|
|
67
|
+
private readonly preludeOrder;
|
|
68
|
+
private counter;
|
|
69
|
+
private readonly maxOperations;
|
|
70
|
+
private readonly maxScriptLength;
|
|
71
|
+
constructor(client: DazClient, options?: BatchOptions);
|
|
72
|
+
/**
|
|
73
|
+
* Queue DazScript lines to be included in the batch.
|
|
74
|
+
*
|
|
75
|
+
* The last line in `lines` should assign the desired result to a
|
|
76
|
+
* variable named after the internally generated key (`_r0`, `_r1`, ...
|
|
77
|
+
* in call order). Prefer {@link addOperation}, which does not require
|
|
78
|
+
* guessing the key name.
|
|
79
|
+
*
|
|
80
|
+
* @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
|
|
81
|
+
*/
|
|
82
|
+
add(lines: string[]): BatchFuture;
|
|
83
|
+
/**
|
|
84
|
+
* Register a shared setup block, emitted once per unique `preludeKey`.
|
|
85
|
+
*
|
|
86
|
+
* Call this before {@link addOperation} calls whose bodies depend on the
|
|
87
|
+
* prelude's bound variable(s). Repeated calls with the same `preludeKey`
|
|
88
|
+
* are no-ops after the first.
|
|
89
|
+
*/
|
|
90
|
+
addPrelude(preludeKey: string, lines: string[]): void;
|
|
91
|
+
/**
|
|
92
|
+
* Queue an operation whose result the builder assigns internally.
|
|
93
|
+
*
|
|
94
|
+
* @param bodyLines - DazScript source lines with no trailing result assignment.
|
|
95
|
+
* @param resultExpression - A JS expression evaluated once after `bodyLines`
|
|
96
|
+
* run, used as this operation's result. Mutation-only operations should pass `"null"`.
|
|
97
|
+
* @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
|
|
98
|
+
*/
|
|
99
|
+
addOperation(bodyLines: string[], resultExpression: string): BatchFuture;
|
|
100
|
+
private checkOperationLimit;
|
|
101
|
+
/**
|
|
102
|
+
* Build the combined script for this batch: shared preludes followed by
|
|
103
|
+
* every operation, via the same "operations → keyed return object → IIFE"
|
|
104
|
+
* builder used by {@link buildOperationsScript} (and, in turn,
|
|
105
|
+
* `DazClient.executeBatchAsync`). `this.ops` is always appended to in
|
|
106
|
+
* counter order, so array index `i` and each op's own `_r${i}` key line up
|
|
107
|
+
* exactly with the `_r${i}` keys `buildOperationsScript` generates from
|
|
108
|
+
* the array position.
|
|
109
|
+
*/
|
|
110
|
+
private buildScript;
|
|
111
|
+
/**
|
|
112
|
+
* Execute all queued operations in a single HTTP request and resolve every future.
|
|
113
|
+
*
|
|
114
|
+
* @throws {BatchLimitExceededError} If the generated script exceeds
|
|
115
|
+
* `maxScriptLength`. Raised before any HTTP call.
|
|
116
|
+
*/
|
|
117
|
+
execute(): Promise<void>;
|
|
118
|
+
}
|
package/dist/batch.js
ADDED
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
import { BatchLimitExceededError } from "./exceptions.js";
|
|
2
|
+
export const DEFAULT_MAX_OPERATIONS = 500;
|
|
3
|
+
export const DEFAULT_MAX_SCRIPT_LENGTH = 900_000; // stays under the server's default 1MB script cap
|
|
4
|
+
/**
|
|
5
|
+
* Build one IIFE script from a list of `[bodyLines, resultExpression]` pairs.
|
|
6
|
+
*
|
|
7
|
+
* Shared by {@link Batch}'s internal script builder and
|
|
8
|
+
* {@link DazClient.executeBatchAsync} so both produce scripts with an
|
|
9
|
+
* identical shape (keyed return object over `_r0`, `_r1`, ...).
|
|
10
|
+
*
|
|
11
|
+
* @param operations - `[bodyLines, resultExpression]` pairs, in submission order.
|
|
12
|
+
* @param preludeLines - Optional shared setup lines emitted once, before any
|
|
13
|
+
* operation's lines. Used by {@link Batch}, which deduplicates its preludes
|
|
14
|
+
* before passing them here; `executeBatchAsync` has no preludes and omits this.
|
|
15
|
+
*/
|
|
16
|
+
export function buildOperationsScript(operations, preludeLines = []) {
|
|
17
|
+
const bodyLines = [...preludeLines];
|
|
18
|
+
const returnParts = [];
|
|
19
|
+
operations.forEach(([lines, resultExpression], i) => {
|
|
20
|
+
const key = `_r${i}`;
|
|
21
|
+
bodyLines.push(...lines);
|
|
22
|
+
bodyLines.push(`var ${key} = ${resultExpression};`);
|
|
23
|
+
returnParts.push(`"${key}": ${key}`);
|
|
24
|
+
});
|
|
25
|
+
const returnObj = `{${returnParts.join(", ")}}`;
|
|
26
|
+
bodyLines.push(`return ${returnObj};`);
|
|
27
|
+
const body = bodyLines.join("\n");
|
|
28
|
+
return `(function(){\n${body}\n})()`;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Placeholder for a single result within a {@link Batch} execution.
|
|
32
|
+
*
|
|
33
|
+
* Created by {@link Batch.add} or {@link Batch.addOperation}; the `value`
|
|
34
|
+
* getter throws until the batch has been executed.
|
|
35
|
+
*/
|
|
36
|
+
export class BatchFuture {
|
|
37
|
+
key;
|
|
38
|
+
resolved = false;
|
|
39
|
+
resultValue = undefined;
|
|
40
|
+
constructor(key) {
|
|
41
|
+
this.key = key;
|
|
42
|
+
}
|
|
43
|
+
/** The result value. Throws if {@link Batch.execute} has not been called yet. */
|
|
44
|
+
get value() {
|
|
45
|
+
if (!this.resolved) {
|
|
46
|
+
throw new Error("Batch has not been executed yet");
|
|
47
|
+
}
|
|
48
|
+
return this.resultValue;
|
|
49
|
+
}
|
|
50
|
+
/** @internal */
|
|
51
|
+
_resolve(value) {
|
|
52
|
+
this.resultValue = value;
|
|
53
|
+
this.resolved = true;
|
|
54
|
+
}
|
|
55
|
+
/** @internal */
|
|
56
|
+
get _key() {
|
|
57
|
+
return this.key;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Collect multiple DazScript operations and execute them in a single HTTP round-trip.
|
|
62
|
+
*
|
|
63
|
+
* Semantics (preserved exactly from dazpy, do not "improve" silently):
|
|
64
|
+
* execution is **serial**, there is **no parallelism**, and the batch is
|
|
65
|
+
* **not transactional** — if any operation throws, the whole call fails
|
|
66
|
+
* the same way a single failing `execute()` call would, and earlier
|
|
67
|
+
* mutations already applied to the live scene are **not** rolled back.
|
|
68
|
+
* Order destructive/hard-to-recover operations last.
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```ts
|
|
72
|
+
* const batch = new Batch(client);
|
|
73
|
+
* const posFuture = batch.addOperation(
|
|
74
|
+
* ["var n = Scene.findNode('Figure');", "var p = [n.getWSPos().x, n.getWSPos().y, n.getWSPos().z];"],
|
|
75
|
+
* "p",
|
|
76
|
+
* );
|
|
77
|
+
* await batch.execute();
|
|
78
|
+
* console.log(posFuture.value);
|
|
79
|
+
* ```
|
|
80
|
+
*/
|
|
81
|
+
export class Batch {
|
|
82
|
+
client;
|
|
83
|
+
ops = [];
|
|
84
|
+
preludes = new Map();
|
|
85
|
+
preludeOrder = [];
|
|
86
|
+
counter = 0;
|
|
87
|
+
maxOperations;
|
|
88
|
+
maxScriptLength;
|
|
89
|
+
constructor(client, options = {}) {
|
|
90
|
+
this.client = client;
|
|
91
|
+
this.maxOperations = options.maxOperations ?? DEFAULT_MAX_OPERATIONS;
|
|
92
|
+
this.maxScriptLength = options.maxScriptLength ?? DEFAULT_MAX_SCRIPT_LENGTH;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Queue DazScript lines to be included in the batch.
|
|
96
|
+
*
|
|
97
|
+
* The last line in `lines` should assign the desired result to a
|
|
98
|
+
* variable named after the internally generated key (`_r0`, `_r1`, ...
|
|
99
|
+
* in call order). Prefer {@link addOperation}, which does not require
|
|
100
|
+
* guessing the key name.
|
|
101
|
+
*
|
|
102
|
+
* @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
|
|
103
|
+
*/
|
|
104
|
+
add(lines) {
|
|
105
|
+
this.checkOperationLimit();
|
|
106
|
+
const key = `_r${this.counter++}`;
|
|
107
|
+
const future = new BatchFuture(key);
|
|
108
|
+
// `lines` is expected to already assign `key` itself, so the result
|
|
109
|
+
// "expression" fed to the shared builder is just the key it already holds.
|
|
110
|
+
this.ops.push({ key, lines: [...lines], resultExpression: key, future });
|
|
111
|
+
return future;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Register a shared setup block, emitted once per unique `preludeKey`.
|
|
115
|
+
*
|
|
116
|
+
* Call this before {@link addOperation} calls whose bodies depend on the
|
|
117
|
+
* prelude's bound variable(s). Repeated calls with the same `preludeKey`
|
|
118
|
+
* are no-ops after the first.
|
|
119
|
+
*/
|
|
120
|
+
addPrelude(preludeKey, lines) {
|
|
121
|
+
if (!this.preludes.has(preludeKey)) {
|
|
122
|
+
this.preludes.set(preludeKey, [...lines]);
|
|
123
|
+
this.preludeOrder.push(preludeKey);
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Queue an operation whose result the builder assigns internally.
|
|
128
|
+
*
|
|
129
|
+
* @param bodyLines - DazScript source lines with no trailing result assignment.
|
|
130
|
+
* @param resultExpression - A JS expression evaluated once after `bodyLines`
|
|
131
|
+
* run, used as this operation's result. Mutation-only operations should pass `"null"`.
|
|
132
|
+
* @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
|
|
133
|
+
*/
|
|
134
|
+
addOperation(bodyLines, resultExpression) {
|
|
135
|
+
this.checkOperationLimit();
|
|
136
|
+
const key = `_r${this.counter++}`;
|
|
137
|
+
const future = new BatchFuture(key);
|
|
138
|
+
this.ops.push({ key, lines: [...bodyLines], resultExpression, future });
|
|
139
|
+
return future;
|
|
140
|
+
}
|
|
141
|
+
checkOperationLimit() {
|
|
142
|
+
if (this.ops.length >= this.maxOperations) {
|
|
143
|
+
throw new BatchLimitExceededError(`Batch already has ${this.ops.length} operations (maxOperations=${this.maxOperations})`);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Build the combined script for this batch: shared preludes followed by
|
|
148
|
+
* every operation, via the same "operations → keyed return object → IIFE"
|
|
149
|
+
* builder used by {@link buildOperationsScript} (and, in turn,
|
|
150
|
+
* `DazClient.executeBatchAsync`). `this.ops` is always appended to in
|
|
151
|
+
* counter order, so array index `i` and each op's own `_r${i}` key line up
|
|
152
|
+
* exactly with the `_r${i}` keys `buildOperationsScript` generates from
|
|
153
|
+
* the array position.
|
|
154
|
+
*/
|
|
155
|
+
buildScript() {
|
|
156
|
+
const preludeLines = [];
|
|
157
|
+
for (const preludeKey of this.preludeOrder) {
|
|
158
|
+
preludeLines.push(...(this.preludes.get(preludeKey) ?? []));
|
|
159
|
+
}
|
|
160
|
+
const operations = this.ops.map(({ lines, resultExpression }) => [
|
|
161
|
+
lines,
|
|
162
|
+
resultExpression,
|
|
163
|
+
]);
|
|
164
|
+
return buildOperationsScript(operations, preludeLines);
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Execute all queued operations in a single HTTP request and resolve every future.
|
|
168
|
+
*
|
|
169
|
+
* @throws {BatchLimitExceededError} If the generated script exceeds
|
|
170
|
+
* `maxScriptLength`. Raised before any HTTP call.
|
|
171
|
+
*/
|
|
172
|
+
async execute() {
|
|
173
|
+
if (this.ops.length === 0) {
|
|
174
|
+
return;
|
|
175
|
+
}
|
|
176
|
+
const script = this.buildScript();
|
|
177
|
+
if (script.length > this.maxScriptLength) {
|
|
178
|
+
throw new BatchLimitExceededError(`Generated batch script is ${script.length} characters (maxScriptLength=${this.maxScriptLength})`);
|
|
179
|
+
}
|
|
180
|
+
const result = await this.client.execute(script);
|
|
181
|
+
const data = result.value ?? {};
|
|
182
|
+
for (const { key, future } of this.ops) {
|
|
183
|
+
future._resolve(data[key]);
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
}
|
package/dist/bone.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type { DazClient } from "./client.js";
|
|
2
|
+
import { DazNode, type NodeIdentifier } from "./node.js";
|
|
3
|
+
/**
|
|
4
|
+
* Proxy for a `DzBone` (a single joint within a {@link DazSkeleton}).
|
|
5
|
+
* Extends `DazNode` with bone-specific rotation helpers.
|
|
6
|
+
*
|
|
7
|
+
* Resolution note: only this class's own overrides — `localEuler`,
|
|
8
|
+
* `localRotation`, `setLocalRotation`, `localPosition`, `rotationOrder`, and
|
|
9
|
+
* `getSkeleton` (all routed through the private `nb()` helper) — resolve via
|
|
10
|
+
* the skeleton-relative `locator` passed to {@link fromLocator}. Every method
|
|
11
|
+
* `DazBone` inherits from `DazNode` without overriding (e.g. `position`,
|
|
12
|
+
* `setPosition`, `setRotation`, `label`, `select`, `parent`, `children`,
|
|
13
|
+
* `modifiers`, `materials`, ...) resolves via `this.identifier` instead — a
|
|
14
|
+
* scene-wide `Scene.findNode()`-style lookup that ignores the locator. See
|
|
15
|
+
* the constructor overload doc on `DazNode` for details.
|
|
16
|
+
*/
|
|
17
|
+
export declare class DazBone extends DazNode {
|
|
18
|
+
/**
|
|
19
|
+
* Construct from a standard scene node lookup by identifier.
|
|
20
|
+
*/
|
|
21
|
+
constructor(client: DazClient, identifier: NodeIdentifier);
|
|
22
|
+
/**
|
|
23
|
+
* Construct from a pre-built skeleton-relative locator (used by {@link fromLocator}).
|
|
24
|
+
* The identifier's value provides the bone's name.
|
|
25
|
+
*/
|
|
26
|
+
constructor(client: DazClient, identifier: NodeIdentifier, locator: string);
|
|
27
|
+
/** Construct a `DazBone` from a pre-built skeleton-relative locator (see `DazSkeleton`'s bone lookup). */
|
|
28
|
+
static fromLocator(client: DazClient, locator: string, name: string): DazBone;
|
|
29
|
+
private nb;
|
|
30
|
+
/** Local-space rotation as `(x, y, z)` Euler degrees; exact inverse of {@link setLocalRotation}. */
|
|
31
|
+
localEuler(): Promise<[number, number, number] | null>;
|
|
32
|
+
/** Local-space rotation as `{x, y, z, w}` quaternion (read-only). */
|
|
33
|
+
localRotation(): Promise<{
|
|
34
|
+
x: number;
|
|
35
|
+
y: number;
|
|
36
|
+
z: number;
|
|
37
|
+
w: number;
|
|
38
|
+
} | null>;
|
|
39
|
+
setLocalRotation(x: number, y: number, z: number): Promise<void>;
|
|
40
|
+
/** Local-space position as `{x, y, z}` (read-only). */
|
|
41
|
+
localPosition(): Promise<{
|
|
42
|
+
x: number;
|
|
43
|
+
y: number;
|
|
44
|
+
z: number;
|
|
45
|
+
} | null>;
|
|
46
|
+
/** Rotation order string (e.g. `"XYZ"`), or `null`. */
|
|
47
|
+
rotationOrder(): Promise<string | null>;
|
|
48
|
+
/** The parent skeleton, or `null`. */
|
|
49
|
+
getSkeleton(): Promise<import("./skeleton.js").DazSkeleton | null>;
|
|
50
|
+
}
|