@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,102 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* General scene-change event stream -- SSE-based watcher for `GET /scene/events`.
|
|
3
|
+
* Mirrors dazpy's `_scene_events.py`.
|
|
4
|
+
*
|
|
5
|
+
* Mirrors the shape of the render-progress stream (`renderApi.ts`'s
|
|
6
|
+
* `waitRenderSse`/`parseSseStream`) but for the broader set of scene-change
|
|
7
|
+
* notifications DAZ Studio emits: nodes/skeletons/lights/cameras added or
|
|
8
|
+
* removed, selection changes, time scrubs, scene load/save, and render
|
|
9
|
+
* start/end.
|
|
10
|
+
*/
|
|
11
|
+
import { AuthenticationError, ConnectionError, DazTimeoutError } from "./exceptions.js";
|
|
12
|
+
import { parseSseStream } from "./client.js";
|
|
13
|
+
const VALID_CATEGORIES = new Set(["node", "skeleton", "light", "camera", "selection", "scene", "time", "render"]);
|
|
14
|
+
async function* parseSceneEvents(response) {
|
|
15
|
+
for await (const { data } of parseSseStream(response)) {
|
|
16
|
+
let raw;
|
|
17
|
+
try {
|
|
18
|
+
raw = JSON.parse(data);
|
|
19
|
+
}
|
|
20
|
+
catch {
|
|
21
|
+
continue;
|
|
22
|
+
}
|
|
23
|
+
yield {
|
|
24
|
+
type: raw.type ?? "",
|
|
25
|
+
ts: raw.ts ?? 0,
|
|
26
|
+
data: raw.data ?? {},
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Yield {@link SceneEvent} objects as DAZ Studio reports scene changes.
|
|
32
|
+
*
|
|
33
|
+
* Opens an SSE connection to `GET /scene/events` and yields events as they
|
|
34
|
+
* arrive, filtered server-side by `categories` and optionally client-side
|
|
35
|
+
* by exact `eventTypes` (e.g. `["node.added", "node.removed"]`).
|
|
36
|
+
*
|
|
37
|
+
* The connection stays open until the caller stops iterating (e.g. via
|
|
38
|
+
* `break`) or the server closes the stream.
|
|
39
|
+
*
|
|
40
|
+
* @param categories Optional subset of event categories to subscribe to
|
|
41
|
+
* server-side. Omit to subscribe to all categories.
|
|
42
|
+
* @param eventTypes Optional set of exact event types to keep; all others
|
|
43
|
+
* are dropped client-side. Omit to yield every event received.
|
|
44
|
+
* @param streamTimeoutMs Maximum lifetime of the stream in milliseconds;
|
|
45
|
+
* when it elapses iteration throws `DazTimeoutError`. Omit to wait
|
|
46
|
+
* indefinitely -- the server sends a keepalive comment every 15 seconds, so
|
|
47
|
+
* the connection never idles out.
|
|
48
|
+
*
|
|
49
|
+
* @throws ConnectionError If the SSE endpoint could not be reached.
|
|
50
|
+
* @throws AuthenticationError If the server rejects the token.
|
|
51
|
+
* @throws DazTimeoutError If `streamTimeoutMs` elapses.
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* ```ts
|
|
55
|
+
* const client = new DazClient();
|
|
56
|
+
* for await (const event of watchSceneEvents(client, ["node", "selection"])) {
|
|
57
|
+
* console.log(event.type, event.data);
|
|
58
|
+
* if (event.type === "node.added") break;
|
|
59
|
+
* }
|
|
60
|
+
* ```
|
|
61
|
+
*/
|
|
62
|
+
export async function* watchSceneEvents(client, categories, eventTypes, streamTimeoutMs) {
|
|
63
|
+
const resp = await client.streamSceneEvents(categories, { timeoutMs: streamTimeoutMs });
|
|
64
|
+
if (resp === null) {
|
|
65
|
+
throw new ConnectionError("Could not open /scene/events stream");
|
|
66
|
+
}
|
|
67
|
+
const eventTypeSet = eventTypes !== undefined ? new Set(eventTypes) : undefined;
|
|
68
|
+
for await (const event of parseSceneEvents(resp)) {
|
|
69
|
+
if (eventTypeSet !== undefined && !eventTypeSet.has(event.type)) {
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
yield event;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Block until a scene event of `eventType` arrives, then return it.
|
|
77
|
+
*
|
|
78
|
+
* @param eventType Exact event type to wait for, e.g. `"node.added"` or
|
|
79
|
+
* `"render.finished"`. The category prefix (text before the first `.`) is
|
|
80
|
+
* used to narrow the server-side subscription.
|
|
81
|
+
* @param timeoutMs Maximum milliseconds to wait. Default `300000` (5 minutes).
|
|
82
|
+
*
|
|
83
|
+
* @throws DazTimeoutError If `timeoutMs` elapses before a matching event arrives.
|
|
84
|
+
* @throws ConnectionError If the SSE endpoint could not be reached.
|
|
85
|
+
* @throws AuthenticationError If the server rejects the token.
|
|
86
|
+
*/
|
|
87
|
+
export async function waitForSceneEvent(client, eventType, timeoutMs = 300_000) {
|
|
88
|
+
const category = eventType.split(".")[0];
|
|
89
|
+
const categories = VALID_CATEGORIES.has(category) ? [category] : undefined;
|
|
90
|
+
try {
|
|
91
|
+
for await (const event of watchSceneEvents(client, categories, [eventType], timeoutMs)) {
|
|
92
|
+
return event;
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
catch (e) {
|
|
96
|
+
if (e instanceof ConnectionError || e instanceof AuthenticationError) {
|
|
97
|
+
throw e;
|
|
98
|
+
}
|
|
99
|
+
// stream timed out or connection dropped -- fall through
|
|
100
|
+
}
|
|
101
|
+
throw new DazTimeoutError(`Timed out after ${timeoutMs / 1000}s waiting for ${JSON.stringify(eventType)}`);
|
|
102
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An in-memory pose checkpoint: figure poses plus camera and light placement.
|
|
3
|
+
* Mirrors dazpy's `_scene_state.py`.
|
|
4
|
+
*/
|
|
5
|
+
import { DazPose, type DazPoseDict } from "./pose.js";
|
|
6
|
+
import type { DazScene } from "./scene.js";
|
|
7
|
+
/** Plain-object schema matching {@link DazSceneState.toDict}/{@link DazSceneState.fromDict}. */
|
|
8
|
+
export interface DazSceneStateDict {
|
|
9
|
+
skeletons: Record<string, DazPoseDict>;
|
|
10
|
+
cameras: Record<string, Record<string, number>>;
|
|
11
|
+
lights: {
|
|
12
|
+
transforms: Record<string, Record<string, number>>;
|
|
13
|
+
extra: Record<string, Record<string, number>>;
|
|
14
|
+
};
|
|
15
|
+
follow_targets: Record<string, string | null>;
|
|
16
|
+
backup?: Record<string, unknown> | null;
|
|
17
|
+
}
|
|
18
|
+
/** Options for {@link DazSceneState.apply}. */
|
|
19
|
+
export interface ApplyOptions {
|
|
20
|
+
/**
|
|
21
|
+
* How many additional `applyFull` attempts to make for a skeleton whose
|
|
22
|
+
* read-back doesn't verify, before giving up on it.
|
|
23
|
+
*/
|
|
24
|
+
maxVerifyRetries?: number;
|
|
25
|
+
/**
|
|
26
|
+
* Per-channel tolerance (degrees for bones, raw value units for
|
|
27
|
+
* morphs/props) allowed between the checkpoint and the read-back before
|
|
28
|
+
* it's considered a mismatch.
|
|
29
|
+
*/
|
|
30
|
+
verifyTolerance?: number;
|
|
31
|
+
}
|
|
32
|
+
/** Options for {@link DazSceneState.capture}. */
|
|
33
|
+
export interface CaptureOptions {
|
|
34
|
+
/**
|
|
35
|
+
* If given, first write a full-scene backup to this absolute path on the
|
|
36
|
+
* server host via {@link DazScene.saveCopy}, before anything else is
|
|
37
|
+
* captured. Use it before destructive work (deleting nodes, changing
|
|
38
|
+
* materials or render settings), which this checkpoint cannot undo. The
|
|
39
|
+
* save-copy result is kept in {@link DazSceneState.backup} and reported
|
|
40
|
+
* again by {@link DazSceneState.apply}. If the backup fails, the error is
|
|
41
|
+
* thrown and nothing is captured.
|
|
42
|
+
*/
|
|
43
|
+
backupPath?: string;
|
|
44
|
+
}
|
|
45
|
+
/** A node in the checkpoint that no longer exists in the scene. */
|
|
46
|
+
export interface SkippedNode {
|
|
47
|
+
/**
|
|
48
|
+
* `follow_target` means the skeleton was restored but the figure it was
|
|
49
|
+
* fitted to is gone, so the fit was not restored.
|
|
50
|
+
*/
|
|
51
|
+
kind: "skeleton" | "camera" | "light" | "follow_target";
|
|
52
|
+
name: string;
|
|
53
|
+
reason: "not_found";
|
|
54
|
+
}
|
|
55
|
+
/** Verification report returned by {@link DazSceneState.apply}. */
|
|
56
|
+
export interface ApplyResult {
|
|
57
|
+
/** Names applied (skeletons read back and verified). */
|
|
58
|
+
restored: string[];
|
|
59
|
+
/** Nodes no longer in the scene. Each also has a line in `errors`. */
|
|
60
|
+
skipped: SkippedNode[];
|
|
61
|
+
/** Every problem, skips included. */
|
|
62
|
+
errors: string[];
|
|
63
|
+
/** `true` only if nothing was skipped or failed. */
|
|
64
|
+
complete: boolean;
|
|
65
|
+
/** `saveCopy()` result from `capture(scene, { backupPath })`, or `null`. */
|
|
66
|
+
backup: Record<string, unknown> | null;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* An in-memory pose checkpoint: figure poses plus camera and light placement.
|
|
70
|
+
*
|
|
71
|
+
* This is not a full scene snapshot. For anything it does not cover, take a
|
|
72
|
+
* full-scene backup with {@link DazScene.saveCopy}, or pass `backupPath` to
|
|
73
|
+
* {@link DazSceneState.capture} to do both at once.
|
|
74
|
+
*
|
|
75
|
+
* Captured, for nodes that exist at capture time:
|
|
76
|
+
*
|
|
77
|
+
* - every skeleton (figure): bone rotations, morph values and the figure
|
|
78
|
+
* node's own numeric properties (see {@link DazPose});
|
|
79
|
+
* - every skeleton's fit-to (follow) target;
|
|
80
|
+
* - every camera: X/Y/Z translate, X/Y/Z rotate and Scale;
|
|
81
|
+
* - every light: the same transform channels, plus Flux, Shadow Softness and
|
|
82
|
+
* Spread Angle.
|
|
83
|
+
*
|
|
84
|
+
* Not captured:
|
|
85
|
+
*
|
|
86
|
+
* - materials and surface properties;
|
|
87
|
+
* - HDRI / environment and render settings;
|
|
88
|
+
* - nodes added or deleted after capture (restore never creates or deletes
|
|
89
|
+
* nodes; missing ones are reported as skipped);
|
|
90
|
+
* - props and any other node that is not a skeleton, camera or light;
|
|
91
|
+
* - bone translations, keyframes / animation, and any other camera or light
|
|
92
|
+
* property (focal length, color, etc.).
|
|
93
|
+
*
|
|
94
|
+
* Everything is captured and restored via each property's raw (pre-ERC) value, so
|
|
95
|
+
* repeated capture/apply cycles are idempotent even for properties driven
|
|
96
|
+
* by `DzERCLink` controllers (e.g. a "Scale" dial fed by dozens of linked
|
|
97
|
+
* morphs) -- see {@link DazPose} for why this matters.
|
|
98
|
+
*
|
|
99
|
+
* Skeletons, cameras, and lights are all keyed by their internal name (not
|
|
100
|
+
* display label), since labels are user-editable and not guaranteed unique.
|
|
101
|
+
*
|
|
102
|
+
* Typical workflow:
|
|
103
|
+
* ```ts
|
|
104
|
+
* const scene = new DazScene();
|
|
105
|
+
* const checkpoint = await DazSceneState.capture(scene);
|
|
106
|
+
* // ...experimental changes
|
|
107
|
+
* await checkpoint.apply(scene);
|
|
108
|
+
* ```
|
|
109
|
+
*/
|
|
110
|
+
export declare class DazSceneState {
|
|
111
|
+
readonly skeletonPoses: Record<string, DazPose>;
|
|
112
|
+
readonly cameraTransforms: Record<string, Record<string, number>>;
|
|
113
|
+
readonly lightTransforms: Record<string, Record<string, number>>;
|
|
114
|
+
readonly lightExtra: Record<string, Record<string, number>>;
|
|
115
|
+
/**
|
|
116
|
+
* Each skeleton's conform/fit-to relationship (by target skeleton name,
|
|
117
|
+
* or `null` if unfitted), captured and restored independently of
|
|
118
|
+
* `DazPose`'s generic bones/morphs/props. `DazPose.applyFull()` writes
|
|
119
|
+
* back every property on a skeleton, including the internal "FID_<name>"
|
|
120
|
+
* property DAZ Studio uses to persist a conforming item's fit
|
|
121
|
+
* registration -- rewriting that property (even to the exact value
|
|
122
|
+
* captured) desyncs the live `getFollowTarget()` pointer without raising
|
|
123
|
+
* any error. See daz-script-server-jz0e: a dedicated capture/restore pass
|
|
124
|
+
* via the real `getFollowTarget()`/`setFollowTarget()` API is the only
|
|
125
|
+
* reliable fix.
|
|
126
|
+
*/
|
|
127
|
+
readonly followTargets: Record<string, string | null>;
|
|
128
|
+
/**
|
|
129
|
+
* Result of the {@link DazScene.saveCopy} call made by
|
|
130
|
+
* `capture(scene, { backupPath })`, or `null` if no full-scene backup was taken.
|
|
131
|
+
*/
|
|
132
|
+
readonly backup: Record<string, unknown> | null;
|
|
133
|
+
constructor(skeletonPoses: Record<string, DazPose>, cameraTransforms: Record<string, Record<string, number>>, lightTransforms: Record<string, Record<string, number>>, lightExtra: Record<string, Record<string, number>>, followTargets?: Record<string, string | null>, backup?: Record<string, unknown> | null);
|
|
134
|
+
/** Capture the current state of every skeleton, camera, and light in `scene`. */
|
|
135
|
+
static capture(scene: DazScene, opts?: CaptureOptions): Promise<DazSceneState>;
|
|
136
|
+
/** Return this snapshot as a plain, JSON-serialisable dict. */
|
|
137
|
+
toDict(): DazSceneStateDict;
|
|
138
|
+
/** Reconstruct a snapshot from {@link toDict}'s output. */
|
|
139
|
+
static fromDict(data: Partial<DazSceneStateDict>): DazSceneState;
|
|
140
|
+
/**
|
|
141
|
+
* Apply this snapshot's skeleton poses, camera transforms, and light
|
|
142
|
+
* properties back onto `scene` in a small, fixed number of HTTP calls.
|
|
143
|
+
*
|
|
144
|
+
* Restore is best effort. A skeleton, camera or light that no longer
|
|
145
|
+
* exists in the scene (deleted or renamed since capture) is skipped and
|
|
146
|
+
* listed in `skipped`, and the rest of the checkpoint is still applied.
|
|
147
|
+
* Nothing is recreated: this restores values, not the scene graph. To get
|
|
148
|
+
* deleted nodes back, reload the full-scene backup taken by
|
|
149
|
+
* `capture(scene, { backupPath })`.
|
|
150
|
+
*
|
|
151
|
+
* Each skeleton restore is independently verified: after
|
|
152
|
+
* `pose.applyFull(skel)` returns, a fresh {@link DazPose.capture} is taken
|
|
153
|
+
* and compared against the checkpoint. This guards against `applyFull()`
|
|
154
|
+
* reporting success for a restore DAZ Studio's single-threaded main loop
|
|
155
|
+
* only partially executed under contention (see dpi-mxq) -- the HTTP call
|
|
156
|
+
* can return normally even though some bone/morph/prop writes never
|
|
157
|
+
* happened. A skeleton whose read-back doesn't match is retried
|
|
158
|
+
* (re-running `applyFull` and re-verifying) up to `maxVerifyRetries`
|
|
159
|
+
* times before being reported in `errors` instead of `restored`, so
|
|
160
|
+
* callers never trust an unverified result.
|
|
161
|
+
*
|
|
162
|
+
* Each skipped node also has a line in `errors`, so a caller that treats
|
|
163
|
+
* any `errors` entry as a failed restore stays safe.
|
|
164
|
+
*/
|
|
165
|
+
apply(scene: DazScene, opts?: ApplyOptions): Promise<ApplyResult>;
|
|
166
|
+
toString(): string;
|
|
167
|
+
}
|