@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
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 DazScriptServer contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,378 @@
|
|
|
1
|
-
#
|
|
1
|
+
# daz-ts
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
TypeScript SDK for [DazScriptServer](../README.md), the HTTP server plugin
|
|
4
|
+
that embeds an HTTP API inside DAZ Studio for remotely executing DazScript
|
|
5
|
+
code. `daz-ts` is the Node.js/TypeScript counterpart to
|
|
6
|
+
[`dazpy`](../dazpy), the mature Python SDK — same wire protocol, same
|
|
7
|
+
server, a single `DazClient` class (no sync/async split; `async`/`await`
|
|
8
|
+
covers both). Phase 1 shipped the client core (`execute`, async job
|
|
9
|
+
submission/polling, batching, render submission, SSE plumbing) plus a
|
|
10
|
+
dependency-free `math3` module. Phase 2 (below) adds the scene-graph proxy
|
|
11
|
+
layer (nodes, materials, skeletons, etc.).
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @bluemoonfoundry/daz-ts
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
For offline installs, each `daz-ts-v*` [GitHub release](https://github.com/bluemoonfoundry/daz-script-server/releases)
|
|
20
|
+
also carries the `bluemoonfoundry-daz-ts-*.tgz` tarball:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install ./bluemoonfoundry-daz-ts-0.1.0.tgz
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Requires Node.js >= 18 (for built-in `fetch`/`AbortController`).
|
|
27
|
+
|
|
28
|
+
## Auth
|
|
29
|
+
|
|
30
|
+
Same convention as `dazpy`: requests carry an `X-API-Token` header. By
|
|
31
|
+
default, `DazClient` auto-loads the token from
|
|
32
|
+
`~/.daz3d/dazscriptserver_token.txt` (the file DazScriptServer writes on
|
|
33
|
+
first run). You can also pass a token explicitly, or pass `token: ""` to
|
|
34
|
+
disable authentication (only if the server has auth disabled too):
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { DazClient } from "@bluemoonfoundry/daz-ts";
|
|
38
|
+
|
|
39
|
+
const client = new DazClient(); // auto-loads token from ~/.daz3d/...
|
|
40
|
+
const explicit = new DazClient({ token: "your-token-here" });
|
|
41
|
+
const noAuth = new DazClient({ token: "" });
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`DazClientOptions` also accepts `host` (default `"127.0.0.1"`), `port`
|
|
45
|
+
(default `18811`), and `timeoutMs` (default `30000`).
|
|
46
|
+
|
|
47
|
+
## Usage
|
|
48
|
+
|
|
49
|
+
### `DazClient.execute()`
|
|
50
|
+
|
|
51
|
+
Run a DazScript string synchronously and get back its result, captured
|
|
52
|
+
console output, and timing:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
import { DazClient } from "@bluemoonfoundry/daz-ts";
|
|
56
|
+
|
|
57
|
+
const client = new DazClient();
|
|
58
|
+
|
|
59
|
+
const result = await client.execute("2 + 2;");
|
|
60
|
+
console.log(result.value); // 4
|
|
61
|
+
console.log(result.output); // string[] of captured log lines
|
|
62
|
+
console.log(result.durationMs);
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Pass a JSON-serializable `args` value as the script's `getArguments()[0]`:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
await client.execute("var n = getArguments()[0].count; n * 2;", { count: 21 });
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Script errors and busy/authentication failures throw typed exceptions
|
|
72
|
+
(`ScriptSyntaxError`, `ScriptRuntimeError`, `StudioBusyError`,
|
|
73
|
+
`ConcurrencyLimitError`, `AuthenticationError`, `ConnectionError`,
|
|
74
|
+
`DazTimeoutError`, ...) — see `src/exceptions.ts` for the full hierarchy.
|
|
75
|
+
Any method that accepts a trailing `{ retryOnBusy, maxWait }` option
|
|
76
|
+
(`RetryOptions`) will transparently retry with linear backoff on
|
|
77
|
+
`StudioBusyError`/`ConcurrencyLimitError` instead of throwing immediately:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
await client.execute("doSomethingSlow();", undefined, { retryOnBusy: true, maxWait: 30 });
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### `Batch`
|
|
84
|
+
|
|
85
|
+
Collect multiple operations and run them as a single HTTP round-trip
|
|
86
|
+
(one script, one `/execute` call). Execution is **serial**, with **no
|
|
87
|
+
parallelism** and **no transactionality** — a failing operation fails the
|
|
88
|
+
whole call, and earlier mutations already applied to the live scene are
|
|
89
|
+
**not** rolled back:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import { Batch, DazClient } from "@bluemoonfoundry/daz-ts";
|
|
93
|
+
|
|
94
|
+
const client = new DazClient();
|
|
95
|
+
const batch = new Batch(client); // options: { maxOperations, maxScriptLength }
|
|
96
|
+
|
|
97
|
+
const nameFuture = batch.addOperation(["var n = Scene.findNode('Genesis9');"], "n.getLabel()");
|
|
98
|
+
const posFuture = batch.addOperation(
|
|
99
|
+
["var n = Scene.findNode('Genesis9');", "var p = n.getWSPos();"],
|
|
100
|
+
"[p.x, p.y, p.z]",
|
|
101
|
+
);
|
|
102
|
+
|
|
103
|
+
await batch.execute(); // one HTTP call resolves every future
|
|
104
|
+
|
|
105
|
+
console.log(nameFuture.value, posFuture.value);
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`addPrelude(preludeKey, lines)` registers a shared setup block emitted once
|
|
109
|
+
per unique key, useful when several operations depend on the same lookup.
|
|
110
|
+
`DazClient.executeBatchAsync(operations, args?)` submits the same
|
|
111
|
+
single-script batch shape to the async endpoint (`/execute/async`) for
|
|
112
|
+
long-running batches — poll it like any other async request.
|
|
113
|
+
|
|
114
|
+
### `executeLong()`
|
|
115
|
+
|
|
116
|
+
Run a potentially long-running script via the async endpoint, with polling
|
|
117
|
+
handled for you:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import { executeLong } from "@bluemoonfoundry/daz-ts";
|
|
121
|
+
|
|
122
|
+
const result = await executeLong(client, "renderEverything();", undefined, {
|
|
123
|
+
timeoutMs: 300_000, // default 120000
|
|
124
|
+
pollIntervalMs: 500, // default 500
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
It submits the script with `executeAsyncSubmit`, then long-polls
|
|
129
|
+
`/requests/:id/result` until the script completes, fails, is cancelled, or
|
|
130
|
+
`timeoutMs` elapses (throwing `AsyncExecutionError` or `DazTimeoutError`
|
|
131
|
+
respectively).
|
|
132
|
+
|
|
133
|
+
A running script can't be interrupted, so cancelling it only moves it to
|
|
134
|
+
`cancel_requested`; `executeLong` keeps waiting, and resolves with the result
|
|
135
|
+
if the job ends `completed_after_cancel_request`. A job running past the
|
|
136
|
+
server's Stuck Job Timeout becomes `stale`, which ends the wait with
|
|
137
|
+
`AsyncExecutionError` (the script may still finish later, as
|
|
138
|
+
`completed_after_stale`). The `RequestStatus` type and
|
|
139
|
+
`FINAL_REQUEST_STATUSES` list every status, and
|
|
140
|
+
`client.cancelRequestDetail(id)` returns the server's cancel response
|
|
141
|
+
(`status` is `cancelled`, `cancel_requested` or `stale`).
|
|
142
|
+
|
|
143
|
+
### `DazClient.checkServerVersion()`
|
|
144
|
+
|
|
145
|
+
daz-ts needs DazScriptServer plugin 2.11 or newer (`MIN_SERVER_VERSION`).
|
|
146
|
+
Unlike dazpy, it never checks the plugin version on its own. Call
|
|
147
|
+
`checkServerVersion()` once after connecting if you want to warn about an
|
|
148
|
+
old plugin:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
const check = await client.checkServerVersion(); // GET /status
|
|
152
|
+
if (check.compatible === false) console.warn(check.message);
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`compatible` is `null` when the plugin reports no parseable version.
|
|
156
|
+
`evaluateServerVersion(url, statusBody)` and `parseVersion()` are exported
|
|
157
|
+
for callers that fetch `/status` themselves.
|
|
158
|
+
|
|
159
|
+
### `DazClient.capabilities()`
|
|
160
|
+
|
|
161
|
+
Ask the server what it supports instead of hard-coding versions (requires a
|
|
162
|
+
DazScriptServer with `GET /capabilities`; older servers throw `DazError` on
|
|
163
|
+
404):
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
const caps = await client.capabilities();
|
|
167
|
+
if (caps.render_engines.selectable.includes("iray")) {
|
|
168
|
+
await client.renderSubmit("C:\\out.png", { engine: "iray" });
|
|
169
|
+
}
|
|
170
|
+
caps.limits.max_batch_variants; // current server limit
|
|
171
|
+
caps.compatibility_hash; // changes only when routes/features change
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`render_engines.source` is `"snapshot"` when Studio was busy and the server
|
|
175
|
+
answered from its last cached document.
|
|
176
|
+
|
|
177
|
+
### Artifacts: downloading job outputs
|
|
178
|
+
|
|
179
|
+
Fetch the files a job declared without sharing DAZ Studio's filesystem
|
|
180
|
+
(requires a DazScriptServer with `GET /artifacts`). A job's artifacts are its
|
|
181
|
+
`reportFile` outputs plus the image(s) a render wrote:
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
const sub = await client.renderSubmit("C:/renders/shot.png", { engine: "iray" });
|
|
185
|
+
const request_id = sub.request_id as string;
|
|
186
|
+
await client.getRequestResult(request_id, true, 600);
|
|
187
|
+
|
|
188
|
+
const list = await client.listArtifacts(request_id); // size, content_type, available
|
|
189
|
+
const png = await client.downloadArtifact(request_id, 0); // Buffer
|
|
190
|
+
await client.downloadArtifact(request_id, 0, "./shot.png"); // stream to file
|
|
191
|
+
const head = await client.downloadArtifact(request_id, 0, { range: [0, 1023] });
|
|
192
|
+
await client.downloadArtifacts(request_id, "./out"); // all available
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Rejections throw `ArtifactError` with `statusCode` and `errorCode`
|
|
196
|
+
(`ARTIFACT_NOT_FOUND` 404, `ARTIFACT_UNAVAILABLE` 410, `REQUEST_NOT_FOUND`
|
|
197
|
+
404, or 416 for a range outside the file).
|
|
198
|
+
|
|
199
|
+
## What else is here
|
|
200
|
+
|
|
201
|
+
- `math3.ts` — dependency-free `Vec3`, `Quat`, `BoundingBox`, `AxisRemap`
|
|
202
|
+
math utilities (no HTTP coupling).
|
|
203
|
+
- `ScriptBuilder` — the injection-safety helpers (`escapeString`, `iife`,
|
|
204
|
+
`serializeArg`) used internally to build generated DazScript source; every
|
|
205
|
+
injected string goes through `JSON.stringify`.
|
|
206
|
+
- Render submission methods (`renderSubmit`, `renderBatchSubmit`,
|
|
207
|
+
`renderAnimationSubmit`, ...) and SSE streaming helpers
|
|
208
|
+
(`streamRenderProgress`, `streamSceneEvents`, `parseSseStream`) on
|
|
209
|
+
`DazClient` — see `src/client.ts` for full signatures. The stream methods
|
|
210
|
+
take `{ timeoutMs, signal }`: `timeoutMs` caps the stream's whole lifetime
|
|
211
|
+
(reads throw `DazTimeoutError` when it elapses) and `signal` lets you
|
|
212
|
+
cancel it. They throw `ConnectionError`/`AuthenticationError` rather than
|
|
213
|
+
returning `null`; `null` means the server answered with another status
|
|
214
|
+
(e.g. 404).
|
|
215
|
+
|
|
216
|
+
The client's `timeoutMs` covers the whole request, including reading the
|
|
217
|
+
response body. Long-polls (`getRequestResult(id, true, waitTimeout)`) get
|
|
218
|
+
`waitTimeout` plus 10 seconds instead, and artifact downloads are streamed,
|
|
219
|
+
so only their time to first byte is bounded.
|
|
220
|
+
|
|
221
|
+
## Phase 2: Scene Graph Proxies
|
|
222
|
+
|
|
223
|
+
Phase 2 adds a scene-graph proxy layer on top of the Phase 1 client core —
|
|
224
|
+
typed, promise-based wrappers around DAZ Studio's `DzNode`/`DzElement`
|
|
225
|
+
object model, ported from `dazpy`'s equivalent classes. Every property
|
|
226
|
+
getter/setter is an async method pair (`foo()`/`setFoo()`) rather than a TS
|
|
227
|
+
accessor, since accessors can't be `async`.
|
|
228
|
+
|
|
229
|
+
- `DazElement` — base proxy for any `DzElement`-derived object (locator
|
|
230
|
+
resolution and property get/set by label).
|
|
231
|
+
- `DazProperty` — a single node/material property (`value()`, `setValue()`,
|
|
232
|
+
keyframe helpers, and the `rawValue`/`setDoubleValue`/`getNumKeys` gotchas
|
|
233
|
+
ported from dazpy).
|
|
234
|
+
- `DazNode`, `NodeIdentifier` — the general scene-node proxy (transforms,
|
|
235
|
+
visibility, selection, parenting, `findProperty()`) and the `{value, kind}`
|
|
236
|
+
shape used to resolve nodes by name or label.
|
|
237
|
+
- `DazScene` — the primary entry point: node/camera/light/skeleton
|
|
238
|
+
factories, selection, bulk scene snapshots (`overview()`,
|
|
239
|
+
`sceneSnapshot()`, `allNodeTransforms()`, `nodeTree()`,
|
|
240
|
+
`nodeHierarchy()`), scene I/O (`load()`, `save()`, `exportFbx()`,
|
|
241
|
+
`exportObj()`), playback/frame range, dForce simulation, and
|
|
242
|
+
`undo()`/`UndoGroup` integration.
|
|
243
|
+
- `DazSkeleton` — figure proxy: bones, pose/morph values, bone-rotation
|
|
244
|
+
bake, IK-free pose evaluation.
|
|
245
|
+
- `DazBone` — a single skeleton bone (rotation, local/world position).
|
|
246
|
+
- `DazCamera` — camera-specific node proxy (focal length, FOV, DOF).
|
|
247
|
+
- `DazLight` — light-specific node proxy (intensity, color, shadow
|
|
248
|
+
settings).
|
|
249
|
+
- `DazMaterial` — a single surface's material properties.
|
|
250
|
+
- `DazModifier`, `DazMorph`, `DazDForce` — modifier-stack proxies: general
|
|
251
|
+
modifiers, ERC morphs, and dForce simulation modifiers.
|
|
252
|
+
- `DazGeometry` — a node's resolved mesh geometry (vertex positions,
|
|
253
|
+
bounding box, posed vs. unposed).
|
|
254
|
+
- `DazViewport` — the active 3D viewport (draw style, size, `capture()`).
|
|
255
|
+
- `DazTimeline` — the global timeline (current frame, frame range,
|
|
256
|
+
play/pause).
|
|
257
|
+
- `UndoGroup`, `withUndo` — group a series of changes into a single undo
|
|
258
|
+
step; `withUndo(client, label, fn)` is the TS equivalent of dazpy's
|
|
259
|
+
`with scene.undo(label): ...` context manager (TS has no `with`
|
|
260
|
+
statement).
|
|
261
|
+
|
|
262
|
+
`capture_sprite()` (dazpy's `rembg`-based background removal) and
|
|
263
|
+
IK-dependent methods (`DazSkeleton.handToTarget`/`.footToTarget`,
|
|
264
|
+
`DazScene.applyInteractionRecipe`) are out of scope for this phase — they
|
|
265
|
+
require the Phase 5 IK solver.
|
|
266
|
+
|
|
267
|
+
See `test/integration/proxies.integration.test.ts` for a live-server
|
|
268
|
+
integration suite covering these classes (gated on `DAZ_SERVER_URL`, same
|
|
269
|
+
pattern as Phase 1's `client.integration.test.ts`; run with
|
|
270
|
+
`DAZ_SERVER_URL=http://127.0.0.1:18811 npm run test:integration`).
|
|
271
|
+
|
|
272
|
+
See `docs/superpowers/specs/2026-09-06-daz-ts-design.md` (in the repo root)
|
|
273
|
+
for the full design spec and phased roadmap.
|
|
274
|
+
|
|
275
|
+
## Phase 3: Rendering
|
|
276
|
+
|
|
277
|
+
Phase 3 adds live Render Settings control and high-level render helpers on
|
|
278
|
+
top of Phase 1's raw job-queue client methods, ported from `dazpy`'s
|
|
279
|
+
`_render.py` and `_render_api(_aio).py`.
|
|
280
|
+
|
|
281
|
+
- `DazRenderSettings` — talks directly to DAZ Studio's render manager
|
|
282
|
+
(`App.getRenderMgr()`) via `DazClient.execute()`: engine selection
|
|
283
|
+
(`activeEngine()`/`setActiveEngine()`, plus the stricter
|
|
284
|
+
`renderEngineState()`/`setRenderEngine()` pair that requires an exact live
|
|
285
|
+
readback before reporting success), resolution, output path, gamma,
|
|
286
|
+
double-sided rendering, Iray quality (`maxSamples`, `maxTimeSecs`,
|
|
287
|
+
`quality`, `setQualityPreset()`), Iray Canvases (`listCanvases()`,
|
|
288
|
+
`addCanvas()`, `removeCanvas()`, `canvasOutputPaths()`), and `render()` /
|
|
289
|
+
`renderAndWait()`, which drive `DzRenderMgr.doRender()` synchronously and
|
|
290
|
+
resolve from its `renderFinished(bool)` signal rather than trusting
|
|
291
|
+
`doRender()`'s own (undocumented, unreliable-on-cancel) return value.
|
|
292
|
+
- `Canvas`, `RenderOutcome` — plain result types for the above. Unlike
|
|
293
|
+
dazpy's `RenderOutcome` (which overrides `__bool__`), TS callers must
|
|
294
|
+
check `.success` explicitly.
|
|
295
|
+
- `render()`, `renderVariants()` (in `renderApi.ts`) — high-level helpers
|
|
296
|
+
over the HTTP `/render` and `/render/batch` job-queue endpoints already on
|
|
297
|
+
`DazClient` (`renderSubmit`, `renderBatchSubmit`, `streamRenderProgress`).
|
|
298
|
+
Both wait for completion via the SSE progress stream
|
|
299
|
+
(`GET /render/:id/progress`), falling back to long-poll on
|
|
300
|
+
`/requests/:id/result` if the stream is unavailable or ends without a
|
|
301
|
+
`complete`/`error` event. `renderVariants()` submits every variant in one
|
|
302
|
+
batch request, then awaits each in order, recording a failed variant's
|
|
303
|
+
error without aborting the rest.
|
|
304
|
+
|
|
305
|
+
`DazRenderSettings`'s environment-map/property methods
|
|
306
|
+
(`getEnvironmentProperty`, `setEnvironmentProperty`,
|
|
307
|
+
`setEnvironmentPropertyFromString`, `setEnvironmentMap`) are exposed
|
|
308
|
+
primarily for the Phase 4 `lighting.ts` domain helper, mirroring dazpy's
|
|
309
|
+
`lighting.py` usage of `_render.py`'s equivalent internal methods.
|
|
310
|
+
|
|
311
|
+
## Phase 4: Capture/Restore and Domain Helpers
|
|
312
|
+
|
|
313
|
+
Phase 4 ports dazpy's checkpoint/restore primitives and its higher-level
|
|
314
|
+
domain-helper modules, which apply typed configuration objects to the Phase
|
|
315
|
+
2/3 proxies rather than wrapping them in new classes ("typed data +
|
|
316
|
+
`apply()` function", matching dazpy's own module-function style for these).
|
|
317
|
+
|
|
318
|
+
- `DazPose` (`pose.ts`, from `_pose.py`) — a figure's complete pose
|
|
319
|
+
(sparse bone rotations, morphs, node properties), captured/applied via
|
|
320
|
+
each channel's *raw* (pre-ERC) value so repeated capture/apply cycles stay
|
|
321
|
+
idempotent even on `DzERCLink`-driven dials. `capture()`/`apply()`/
|
|
322
|
+
`applyFull()` are async (one HTTP call each); `lerp()`/`toDict()`/
|
|
323
|
+
`fromDict()`/`save()`/`load()` are pure/local.
|
|
324
|
+
- `DazSceneState` (`sceneState.ts`, from `_scene_state.py`) — a pose
|
|
325
|
+
checkpoint, not a full scene snapshot: every skeleton's `DazPose`, plus
|
|
326
|
+
camera/light transforms and a few extra light properties, restored in a
|
|
327
|
+
small fixed number of HTTP calls. Materials, render settings and deleted
|
|
328
|
+
nodes are not covered; `capture(scene, { backupPath })` first writes a
|
|
329
|
+
full-scene backup via `saveCopy()` for that. `apply()` returns a report:
|
|
330
|
+
`restored`, `skipped` (nodes deleted since capture, each also listed in
|
|
331
|
+
`errors`), `errors`, `complete` and `backup`. `apply()` independently verifies each skeleton restore with a
|
|
332
|
+
fresh `DazPose.capture()` read-back (retrying up to `maxVerifyRetries`
|
|
333
|
+
times on mismatch) since a 200 response can reflect a restore DAZ
|
|
334
|
+
Studio's main thread only partially executed under contention, and
|
|
335
|
+
restores each skeleton's conform/fit-to relationship via the real
|
|
336
|
+
`followTarget()`/`fitTo()`/`unfit()` API rather than trusting
|
|
337
|
+
`DazPose.applyFull()`'s generic property write-back.
|
|
338
|
+
- `DazAnimation` (`animation.ts`, from `_animation.py`) — a captured
|
|
339
|
+
timeline clip (parallel-list bone rotations + optional varying-morph
|
|
340
|
+
detection per frame). `capture()`/`apply()` are async; `clip()`/`blend()`/
|
|
341
|
+
`asPose()`/`append()` are pure.
|
|
342
|
+
- `shotGeometry.ts` (from `_shot_geometry.py`) — pure camera/light placement
|
|
343
|
+
math (`sphericalOffset`, `lookAtEuler`, `resolveTarget`) shared by
|
|
344
|
+
`lighting.ts` and `cinematics.ts`. `resolveTarget` is async in TS (unlike
|
|
345
|
+
Python's synchronous property access) since resolving a `DazNode` target
|
|
346
|
+
requires an HTTP round-trip via `position()`.
|
|
347
|
+
- `poses.ts` (from `poses.py`) — `applyPose`, `resetTransforms`,
|
|
348
|
+
`zeroFigure` convenience wrappers over `DazPose`/`DazNode`/`DazSkeleton`.
|
|
349
|
+
- `materials.ts` (from `materials.py`) — `IrayMaterial`/`TextureMap`/
|
|
350
|
+
`SurfaceProperty` typed specs plus `applyIrayMaterial`/`applyTextureMap`/
|
|
351
|
+
`getSurfaceProperty`/`setSurfaceProperty` over `DazMaterial`. Texture
|
|
352
|
+
paths are validated (absolute + exists on disk) before any DazScript call
|
|
353
|
+
is made, since an invalid path passed to the underlying `setMap()` can
|
|
354
|
+
hang or crash DAZ Studio via a blocking file-not-found dialog.
|
|
355
|
+
- `lighting.ts` (from `lighting.py`) — `applyThreePointLightSetup` (key/
|
|
356
|
+
fill/rim rig via `shotGeometry`) and `applyHdriEnvironment` (drives
|
|
357
|
+
`DazRenderSettings`'s environment-holder methods, verifying the apply via
|
|
358
|
+
an "Environment Intensity" readback).
|
|
359
|
+
- `cinematics.ts` (from `cinematics.py`) — `applyStaticShot`,
|
|
360
|
+
`applyOrbitCamera` (a per-frame sweep via `scene.setFrame()`, **not** real
|
|
361
|
+
keyframes — widens the scene's animation range as a documented side
|
|
362
|
+
effect), `applyFrameSubject` (shot-distance presets), and
|
|
363
|
+
`applyAnimatedShot` (real DAZ Studio keyframes via
|
|
364
|
+
`setPositionAtFrame`/`setRotationAtFrame`, letting DAZ Studio interpolate).
|
|
365
|
+
- `sceneEvents.ts` (from `_scene_events.py`) — `watchSceneEvents`/
|
|
366
|
+
`waitForSceneEvent`, typed SSE parsing over `GET /scene/events`, reusing
|
|
367
|
+
`client.ts`'s `parseSseStream`/`streamSceneEvents` already added in
|
|
368
|
+
Phase 3 for the render-progress stream.
|
|
369
|
+
|
|
370
|
+
Client-side input validation (file existence, path shape) happens in every
|
|
371
|
+
domain helper that touches user-supplied filesystem paths (`materials.ts`,
|
|
372
|
+
`lighting.ts`'s `applyHdriEnvironment`), matching dazpy's
|
|
373
|
+
blocking-dialog-avoidance pattern — a bad path reaching DAZ Studio's
|
|
374
|
+
underlying `setMap()`/environment-map call can hang or crash the app via a
|
|
375
|
+
modal file-not-found dialog rather than raising a script error.
|
|
376
|
+
|
|
377
|
+
Not ported in Phase 4: `_interaction.py` (multi-figure IK posing) — that's
|
|
378
|
+
Phase 5 (`daz-script-server-sf7y`).
|
|
@@ -0,0 +1,129 @@
|
|
|
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 { DazPose } from "./pose.js";
|
|
6
|
+
import type { DazSkeleton } from "./skeleton.js";
|
|
7
|
+
/** One captured timeline frame. */
|
|
8
|
+
export interface AnimationFrame {
|
|
9
|
+
frame: number;
|
|
10
|
+
rotations: Array<[number, number, number]>;
|
|
11
|
+
morphs: Record<string, number>;
|
|
12
|
+
}
|
|
13
|
+
/** Plain-object schema matching {@link DazAnimation.toDict} and the animation JSON file format. */
|
|
14
|
+
export interface DazAnimationDict {
|
|
15
|
+
figure: string;
|
|
16
|
+
frame_range: {
|
|
17
|
+
start: number;
|
|
18
|
+
end: number;
|
|
19
|
+
};
|
|
20
|
+
bones: string[];
|
|
21
|
+
frames: AnimationFrame[];
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* A captured animation clip: bone rotations (and optionally morphs) for
|
|
25
|
+
* every frame in the play range.
|
|
26
|
+
*
|
|
27
|
+
* Created with {@link capture}; saved/loaded with {@link save}/{@link load}.
|
|
28
|
+
*
|
|
29
|
+
* Bones are stored as a parallel-list encoding -- a single ordered `bones`
|
|
30
|
+
* list of names, and per-frame `rotations` arrays aligned to that index --
|
|
31
|
+
* so payload size grows with bones x frames rather than with a full dict
|
|
32
|
+
* per frame.
|
|
33
|
+
*
|
|
34
|
+
* Typical workflow:
|
|
35
|
+
* ```ts
|
|
36
|
+
* const scene = new DazScene();
|
|
37
|
+
* const figure = await scene.findSkeletonByLabel("Genesis 9");
|
|
38
|
+
*
|
|
39
|
+
* const anim = await DazAnimation.capture(figure, true);
|
|
40
|
+
* anim.save("walk.json");
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
export declare class DazAnimation {
|
|
44
|
+
readonly figure: string;
|
|
45
|
+
readonly frameRange: {
|
|
46
|
+
start: number;
|
|
47
|
+
end: number;
|
|
48
|
+
};
|
|
49
|
+
readonly bones: string[];
|
|
50
|
+
readonly frames: AnimationFrame[];
|
|
51
|
+
constructor(figure: string, frameRange: {
|
|
52
|
+
start: number;
|
|
53
|
+
end: number;
|
|
54
|
+
}, bones: string[], frames: AnimationFrame[]);
|
|
55
|
+
/**
|
|
56
|
+
* Capture the full animation of `skeleton` in a single HTTP call.
|
|
57
|
+
*
|
|
58
|
+
* Scrubs every frame in the scene's play range server-side (no round-trip
|
|
59
|
+
* per frame). The timeline is restored to its original frame before the
|
|
60
|
+
* call returns.
|
|
61
|
+
*
|
|
62
|
+
* When `includeMorphs` is `true`, the script first identifies which
|
|
63
|
+
* geometry morphs and node-level properties actually vary across the
|
|
64
|
+
* timeline (channels that are keyed but static are excluded), then
|
|
65
|
+
* records their values per frame.
|
|
66
|
+
*
|
|
67
|
+
* @throws NodeNotFoundError If the skeleton is not found.
|
|
68
|
+
*/
|
|
69
|
+
static capture(skeleton: DazSkeleton, includeMorphs?: boolean): Promise<DazAnimation>;
|
|
70
|
+
/** Load an animation from a JSON file. Accepts files produced by {@link save}. */
|
|
71
|
+
static load(path: string): DazAnimation;
|
|
72
|
+
/** Write this animation to a JSON file. Parent directories must exist. */
|
|
73
|
+
save(path: string): void;
|
|
74
|
+
/** Return the animation as a plain dict (same schema as the JSON file). */
|
|
75
|
+
toDict(): DazAnimationDict;
|
|
76
|
+
/**
|
|
77
|
+
* Return a new animation containing only frames in [start, end].
|
|
78
|
+
*
|
|
79
|
+
* `start` and `end` are scene frame numbers (the `frame` value stored in
|
|
80
|
+
* each frame, not array indices). Both endpoints are inclusive.
|
|
81
|
+
*/
|
|
82
|
+
clip(start: number, end: number): DazAnimation;
|
|
83
|
+
/**
|
|
84
|
+
* Blend this animation with `other` frame by frame.
|
|
85
|
+
*
|
|
86
|
+
* Each frame's bone rotations and morph values are linearly interpolated
|
|
87
|
+
* between `this` (`t=0`) and `other` (`t=1`). Pure -- no HTTP round-trip.
|
|
88
|
+
*
|
|
89
|
+
* If the two clips have different frame counts, the result is truncated
|
|
90
|
+
* to the shorter clip. Frame numbers are taken from `this`.
|
|
91
|
+
*
|
|
92
|
+
* @throws Error If `this` and `other` have different bone lists.
|
|
93
|
+
*/
|
|
94
|
+
blend(other: DazAnimation, t: number): DazAnimation;
|
|
95
|
+
/**
|
|
96
|
+
* Extract a single frame as a {@link DazPose}.
|
|
97
|
+
*
|
|
98
|
+
* Bone rotations are stored sparsely -- only bones with at least one
|
|
99
|
+
* non-zero component are included. Morph values are copied as-is. Pure --
|
|
100
|
+
* no HTTP round-trip.
|
|
101
|
+
*
|
|
102
|
+
* @param frameIndex 0-based index into {@link frames}.
|
|
103
|
+
*/
|
|
104
|
+
asPose(frameIndex?: number): DazPose;
|
|
105
|
+
/**
|
|
106
|
+
* Apply a single frame of this animation to `skeleton`.
|
|
107
|
+
*
|
|
108
|
+
* Equivalent to `(await anim.asPose(frameIndex)).apply(skeleton)` -- one
|
|
109
|
+
* HTTP call that sets only the channels present in the frame.
|
|
110
|
+
*
|
|
111
|
+
* @param frameIndex 0-based index into {@link frames}. Defaults to 0.
|
|
112
|
+
*/
|
|
113
|
+
apply(skeleton: DazSkeleton, frameIndex?: number): Promise<void>;
|
|
114
|
+
/**
|
|
115
|
+
* Concatenate `other` immediately after this animation.
|
|
116
|
+
*
|
|
117
|
+
* The other clip's frame numbers are shifted so it starts on the frame
|
|
118
|
+
* following this animation's last frame. The figure label and bone list
|
|
119
|
+
* are taken from `this`. Pure -- no HTTP round-trip.
|
|
120
|
+
*
|
|
121
|
+
* @throws Error If `this` and `other` have different bone lists.
|
|
122
|
+
*/
|
|
123
|
+
append(other: DazAnimation): DazAnimation;
|
|
124
|
+
/** Number of captured frames. */
|
|
125
|
+
get frameCount(): number;
|
|
126
|
+
/** Number of bones in the skeleton at capture time. */
|
|
127
|
+
get boneCount(): number;
|
|
128
|
+
toString(): string;
|
|
129
|
+
}
|