@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,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
+ }