@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
package/dist/render.js ADDED
@@ -0,0 +1,811 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { DazClient as DazClientImpl } from "./client.js";
4
+ import { RenderError } from "./exceptions.js";
5
+ import { ScriptBuilder } from "./scriptBuilder.js";
6
+ // Access path: App.getRenderMgr() -> DzRenderMgr
7
+ // Render options: mgr.getRenderOptions() -> DzRenderOptions
8
+ // imageSize is a QSize value type -- read via .width/.height, write back by
9
+ // calling setWidth/setHeight on the copy then reassigning opts.imageSize.
10
+ //
11
+ // Iray-specific quality/samples settings (Max Samples, Max Time, Rendering
12
+ // Quality, ...) are not exposed on DzRenderOptions or DzIrayRenderer directly
13
+ // -- they live on the active renderer's property holder:
14
+ // mgr.getActiveRenderer().getPropertyHolder().findProperty("Max Samples").
15
+ // Confirmed against a live DAZ Studio instance; property names match the
16
+ // labels shown in the Render Settings pane's Advanced tab.
17
+ const RENDER_MGR = "App.getRenderMgr()";
18
+ /**
19
+ * Mirrors the engineMap in DzScriptServerPane.cpp's render script builder --
20
+ * keep in sync. 3Delight is no longer supported by DAZ Studio and excluded.
21
+ */
22
+ const ENGINE_CLASS_TO_NAME = {
23
+ DzIrayRenderer: "iray",
24
+ DzFilamentRenderer: "filament",
25
+ };
26
+ const ENGINE_NAME_TO_CLASS = Object.fromEntries(Object.entries(ENGINE_CLASS_TO_NAME).map(([k, v]) => [v, k]));
27
+ /** The two non-pluggable `DzRenderOptions.renderType` modes (see {@link DazRenderSettings.activeEngine} for why these are distinct from the `DzRenderer` plugin lookup). */
28
+ const NON_SOFTWARE_ENGINES = new Set(["viewport", "multi_pass_opengl"]);
29
+ const ENGINE_SELECTOR_SCHEMA = 1;
30
+ const ENGINE_MUTATION_SCHEMA = 1;
31
+ const ENGINE_SELECTOR_METHOD = "render_settings_engine_selector";
32
+ const RENDER_TYPE_NAMES = { 0: "ScreenShot", 1: "HardwareAssisted", 2: "Software" };
33
+ function engineStateUnavailable(reason, opts = {}) {
34
+ const { renderType = null, activeRendererClass = null, activeRendererName = null, factsObserved = false } = opts;
35
+ const provenanceKind = factsObserved ? "live_readback" : "unavailable";
36
+ return {
37
+ selector_schema: ENGINE_SELECTOR_SCHEMA,
38
+ status: "unavailable",
39
+ engine: null,
40
+ method: ENGINE_SELECTOR_METHOD,
41
+ reason,
42
+ render_type: {
43
+ raw: renderType,
44
+ name: renderType !== null ? (RENDER_TYPE_NAMES[renderType] ?? null) : null,
45
+ provenance: { kind: provenanceKind, source: "DzRenderOptions.renderType" },
46
+ },
47
+ active_renderer: {
48
+ class_name: activeRendererClass,
49
+ name: activeRendererName,
50
+ provenance: { kind: provenanceKind, source: "DzRenderMgr.getActiveRenderer" },
51
+ },
52
+ };
53
+ }
54
+ /** Normalize one bounded live read without inferring from renderer identity alone. */
55
+ function normalizeEngineReadback(raw) {
56
+ if (typeof raw !== "object" || raw === null || raw.read_schema !== 1) {
57
+ return engineStateUnavailable("malformed_readback");
58
+ }
59
+ const facts = raw;
60
+ if (facts.ok !== true) {
61
+ let reason = facts.reason;
62
+ if (reason !== "render_manager_unavailable" && reason !== "render_options_unavailable" && reason !== "probe_failed") {
63
+ reason = "probe_failed";
64
+ }
65
+ return engineStateUnavailable(reason);
66
+ }
67
+ const renderType = facts.render_type;
68
+ const rendererClass = facts.active_renderer_class;
69
+ const rendererName = facts.active_renderer_name;
70
+ if (typeof renderType !== "number" ||
71
+ (rendererClass !== null && rendererClass !== undefined && typeof rendererClass !== "string") ||
72
+ (rendererName !== null && rendererName !== undefined && typeof rendererName !== "string")) {
73
+ return engineStateUnavailable("malformed_readback");
74
+ }
75
+ const state = engineStateUnavailable("unknown_render_type", {
76
+ renderType,
77
+ activeRendererClass: rendererClass ?? null,
78
+ activeRendererName: rendererName ?? null,
79
+ factsObserved: true,
80
+ });
81
+ if (renderType === 0 || renderType === 1) {
82
+ Object.assign(state, { status: "verified_non_iray", engine: "viewport_gl", reason: "non_iray_engine" });
83
+ }
84
+ else if (renderType === 2 && rendererClass === "DzIrayRenderer") {
85
+ Object.assign(state, { status: "verified_iray", engine: "iray", reason: null });
86
+ }
87
+ else if (renderType === 2 && rendererClass !== null && rendererClass !== undefined) {
88
+ Object.assign(state, { status: "verified_non_iray", engine: "other_non_iray", reason: "non_iray_engine" });
89
+ }
90
+ else if (renderType === 2) {
91
+ state.reason = "active_renderer_unavailable";
92
+ }
93
+ return state;
94
+ }
95
+ const QUALITY_PRESETS = {
96
+ draft: { maxSamples: 100, maxTime: 300, qualityEnable: false },
97
+ preview: { maxSamples: 500, maxTime: 900, qualityEnable: true, quality: 2.0 },
98
+ good: { maxSamples: 1500, maxTime: 3600, qualityEnable: true, quality: 1.0 },
99
+ final: { maxSamples: 5000, maxTime: 7200, qualityEnable: true, quality: 1.0 },
100
+ };
101
+ /**
102
+ * Live control of DAZ Studio's Render Settings pane: engine selection,
103
+ * resolution, gamma, Iray quality presets, Iray Canvases, and a
104
+ * `render()` helper that drives `DzRenderMgr.doRender()` synchronously and
105
+ * waits for its `renderFinished(bool)` signal.
106
+ *
107
+ * This talks directly to the DazScript render manager (`App.getRenderMgr()`)
108
+ * via {@link DazClient.execute}, distinct from the HTTP `/render` job-queue
109
+ * endpoints exposed on {@link DazClient} itself (`renderSubmit`,
110
+ * `renderBatchSubmit`, ...) and the {@link render}/{@link renderVariants}
111
+ * helpers in `renderApi.ts` that submit to that queue.
112
+ */
113
+ export class DazRenderSettings {
114
+ client;
115
+ constructor(client) {
116
+ this.client = client ?? new DazClientImpl();
117
+ }
118
+ irayPropertyHolderExpr() {
119
+ return `${RENDER_MGR}.getActiveRenderer().getPropertyHolder()`;
120
+ }
121
+ async getIrayProperty(name) {
122
+ const script = ScriptBuilder.iife(`
123
+ var holder = ${this.irayPropertyHolderExpr()};
124
+ if (!holder) return null;
125
+ var p = holder.findProperty(${ScriptBuilder.escapeString(name)});
126
+ return p ? p.getValue() : null;
127
+ `);
128
+ return (await this.client.execute(script)).value;
129
+ }
130
+ async setIrayProperty(name, value) {
131
+ const script = ScriptBuilder.iife(`
132
+ var holder = ${this.irayPropertyHolderExpr()};
133
+ if (!holder) return;
134
+ var p = holder.findProperty(${ScriptBuilder.escapeString(name)});
135
+ if (p) p.setValue(${ScriptBuilder.serializeArg(value)});
136
+ `);
137
+ await this.client.execute(script);
138
+ }
139
+ /**
140
+ * Index 3 of the 4 fixed render element groups (General Render, Iray,
141
+ * Tonemapper, Environment) -- confirmed against a live instance alongside
142
+ * index 1 (see {@link irayRenderOptionsHolderExpr}).
143
+ */
144
+ environmentHolderExpr() {
145
+ return `${RENDER_MGR}.getRenderElementObjects()[3]`;
146
+ }
147
+ /** Read an Environment-holder property by label (e.g. `"Environment Intensity"`, `"Dome Rotation"`). Primarily for domain-helper use (see `lighting.ts`). */
148
+ async getEnvironmentProperty(name) {
149
+ const script = ScriptBuilder.iife(`
150
+ var holder = ${this.environmentHolderExpr()};
151
+ if (!holder) return null;
152
+ var p = holder.findProperty(${ScriptBuilder.escapeString(name)});
153
+ return p ? p.getValue() : null;
154
+ `);
155
+ return (await this.client.execute(script)).value;
156
+ }
157
+ /** Set an Environment-holder property by label. Primarily for domain-helper use (see `lighting.ts`). */
158
+ async setEnvironmentProperty(name, value) {
159
+ const script = ScriptBuilder.iife(`
160
+ var holder = ${this.environmentHolderExpr()};
161
+ if (!holder) return;
162
+ var p = holder.findProperty(${ScriptBuilder.escapeString(name)});
163
+ if (p) p.setValue(${ScriptBuilder.serializeArg(value)});
164
+ `);
165
+ await this.client.execute(script);
166
+ }
167
+ /** Set an Environment-holder property from a string value via `setValueFromString()`. Primarily for domain-helper use. */
168
+ async setEnvironmentPropertyFromString(name, value) {
169
+ const script = ScriptBuilder.iife(`
170
+ var holder = ${this.environmentHolderExpr()};
171
+ if (!holder) return;
172
+ var p = holder.findProperty(${ScriptBuilder.escapeString(name)});
173
+ if (p) p.setValueFromString(${ScriptBuilder.escapeString(value)});
174
+ `);
175
+ await this.client.execute(script);
176
+ }
177
+ /**
178
+ * Set the "Environment Map" (HDRI) path, validating it against the local
179
+ * filesystem before sending `setMap()`.
180
+ *
181
+ * Requires an absolute path: a local existence check against a relative
182
+ * path resolves against this process's cwd, not DAZ Studio's, so a
183
+ * relative path could pass this check yet still resolve to a different
184
+ * (or unresolvable) file in DAZ Studio -- reproducing the blocking
185
+ * file-not-found dialog this validation exists to prevent (see
186
+ * `feedback_dazscript_blocking_dialogs` in project memory). The existence
187
+ * check validates against the local/client-side filesystem, which is
188
+ * correct when DAZ Studio and this client are co-located but will
189
+ * misbehave against a remote DAZ Studio server.
190
+ */
191
+ async setEnvironmentMap(mapPath) {
192
+ if (!path.isAbsolute(mapPath)) {
193
+ throw new Error(`HDRI/environment map path must be absolute: ${mapPath}`);
194
+ }
195
+ if (!fs.existsSync(mapPath) || !fs.statSync(mapPath).isFile()) {
196
+ throw new Error(`HDRI/environment map not found: ${mapPath}`);
197
+ }
198
+ const script = ScriptBuilder.iife(`
199
+ var holder = ${this.environmentHolderExpr()};
200
+ if (!holder) return;
201
+ var p = holder.findProperty(${ScriptBuilder.escapeString("Environment Map")});
202
+ if (p) p.setMap(${ScriptBuilder.escapeString(mapPath)});
203
+ `);
204
+ await this.client.execute(script);
205
+ }
206
+ /**
207
+ * Canvas definitions live on this holder, not on
208
+ * `getActiveRenderer().getPropertyHolder()` -- confirmed against a live
209
+ * instance; index 1 is "NVIDIA Iray Render Options" among the 4 fixed
210
+ * render element groups (General Render, Iray, Tonemapper, Environment).
211
+ */
212
+ irayRenderOptionsHolderExpr() {
213
+ return `${RENDER_MGR}.getRenderElementObjects()[1]`;
214
+ }
215
+ static refreshRenderSettingsPaneScript() {
216
+ return 'var _pane = MainWindow.getPaneMgr().findPane("DzRenderSettingsPane");if (_pane) _pane.refresh();';
217
+ }
218
+ /** `true` if the render manager is accessible. */
219
+ async isAvailable() {
220
+ const script = ScriptBuilder.iife(`
221
+ var mgr = ${RENDER_MGR};
222
+ return (mgr !== null && mgr !== undefined);
223
+ `);
224
+ return Boolean((await this.client.execute(script)).value);
225
+ }
226
+ /** `true` if a render is currently in progress. */
227
+ async isRendering() {
228
+ const script = ScriptBuilder.iife(`
229
+ var mgr = ${RENDER_MGR};
230
+ if (!mgr) return false;
231
+ return mgr.isRendering();
232
+ `);
233
+ return Boolean((await this.client.execute(script)).value);
234
+ }
235
+ /** DazScript body returning bounded raw selector and renderer facts. */
236
+ static engineReadbackBody() {
237
+ return `
238
+ function _readEngineFacts() {
239
+ try {
240
+ var mgr = App.getRenderMgr();
241
+ if (!mgr) return {
242
+ read_schema: 1, ok: false,
243
+ reason: "render_manager_unavailable",
244
+ render_type: null,
245
+ active_renderer_class: null,
246
+ active_renderer_name: null
247
+ };
248
+ var opts = mgr.getRenderOptions();
249
+ if (!opts) return {
250
+ read_schema: 1, ok: false,
251
+ reason: "render_options_unavailable",
252
+ render_type: null,
253
+ active_renderer_class: null,
254
+ active_renderer_name: null
255
+ };
256
+ var renderer = mgr.getActiveRenderer();
257
+ return {
258
+ read_schema: 1, ok: true, reason: null,
259
+ render_type: Number(opts.renderType),
260
+ active_renderer_class: renderer ? String(renderer.className()) : null,
261
+ active_renderer_name: renderer ? String(renderer.getName()) : null
262
+ };
263
+ } catch (_readError) {
264
+ return {
265
+ read_schema: 1, ok: false, reason: "probe_failed",
266
+ render_type: null,
267
+ active_renderer_class: null,
268
+ active_renderer_name: null
269
+ };
270
+ }
271
+ }
272
+ `;
273
+ }
274
+ /**
275
+ * Return truthful Render Settings engine facts and a normalized verdict.
276
+ *
277
+ * `DzRenderOptions.renderType` is the effective render-operation selector.
278
+ * The active renderer class/name is returned as a separate fact and only
279
+ * participates in normalization when `renderType` is `Software`. In
280
+ * particular, an Iray active-renderer name cannot turn a ScreenShot or
281
+ * HardwareAssisted operation into an Iray verdict.
282
+ */
283
+ async renderEngineState() {
284
+ const script = ScriptBuilder.iife(`${DazRenderSettings.engineReadbackBody()}\nreturn _readEngineFacts();`);
285
+ return normalizeEngineReadback((await this.client.execute(script)).value);
286
+ }
287
+ /**
288
+ * Persist `"iray"` or `"viewport"` and require exact live readback.
289
+ *
290
+ * This is an explicit persistent setter, not a transactional render
291
+ * helper. It calls `applyChanges()` so the selected render operation is
292
+ * written via DAZ's settings manager. Any lookup, mutation, apply, or
293
+ * readback failure throws {@link RenderError}; unknown engine names never
294
+ * silently continue.
295
+ */
296
+ async setRenderEngine(engine) {
297
+ const requested = engine.trim().toLowerCase();
298
+ if (requested !== "iray" && requested !== "viewport") {
299
+ throw new Error(`Unknown render engine ${JSON.stringify(engine)}; expected 'iray' or 'viewport'`);
300
+ }
301
+ const requestedJs = ScriptBuilder.escapeString(requested);
302
+ const script = ScriptBuilder.iife(`
303
+ ${DazRenderSettings.engineReadbackBody()}
304
+ var requested = ${requestedJs};
305
+ var mgr = App.getRenderMgr();
306
+ if (!mgr) return {
307
+ mutation_schema: 1, ok: false,
308
+ requested_engine: requested, persisted: false,
309
+ reason: "render_manager_unavailable", readback: _readEngineFacts()
310
+ };
311
+ var opts = mgr.getRenderOptions();
312
+ if (!opts) return {
313
+ mutation_schema: 1, ok: false,
314
+ requested_engine: requested, persisted: false,
315
+ reason: "render_options_unavailable", readback: _readEngineFacts()
316
+ };
317
+ try {
318
+ if (requested === "iray") {
319
+ var iray = mgr.findRenderer("DzIrayRenderer");
320
+ if (!iray) return {
321
+ mutation_schema: 1, ok: false,
322
+ requested_engine: requested, persisted: false,
323
+ reason: "iray_renderer_unavailable", readback: _readEngineFacts()
324
+ };
325
+ mgr.setActiveRenderer(iray);
326
+ opts.renderType = opts.Software;
327
+ } else {
328
+ opts.renderType = opts.ScreenShot;
329
+ }
330
+ opts.applyChanges();
331
+ } catch (_mutationError) {
332
+ return {
333
+ mutation_schema: 1, ok: false,
334
+ requested_engine: requested, persisted: false,
335
+ reason: "mutation_failed", readback: _readEngineFacts()
336
+ };
337
+ }
338
+ var readback = _readEngineFacts();
339
+ var matches = readback.ok && (
340
+ (requested === "iray"
341
+ && readback.render_type === Number(opts.Software)
342
+ && readback.active_renderer_class === "DzIrayRenderer")
343
+ || (requested === "viewport"
344
+ && readback.render_type === Number(opts.ScreenShot))
345
+ );
346
+ return {
347
+ mutation_schema: 1, ok: matches,
348
+ requested_engine: requested, persisted: matches,
349
+ reason: matches ? null : "readback_mismatch",
350
+ readback: readback
351
+ };
352
+ `);
353
+ const raw = (await this.client.execute(script)).value;
354
+ if (raw === null || typeof raw !== "object" || raw.mutation_schema !== 1) {
355
+ throw new RenderError("Render engine mutation failed: malformed_response");
356
+ }
357
+ const readback = normalizeEngineReadback(raw.readback);
358
+ const expected = requested === "iray"
359
+ ? readback.status === "verified_iray" &&
360
+ readback.engine === "iray" &&
361
+ readback.render_type?.raw === 2 &&
362
+ readback.active_renderer?.class_name === "DzIrayRenderer"
363
+ : readback.status === "verified_non_iray" &&
364
+ readback.engine === "viewport_gl" &&
365
+ readback.render_type?.raw === 0;
366
+ if (raw.ok !== true || raw.requested_engine !== requested || raw.persisted !== true || !expected) {
367
+ let reason = raw.reason;
368
+ const knownReasons = new Set([
369
+ "render_manager_unavailable",
370
+ "render_options_unavailable",
371
+ "iray_renderer_unavailable",
372
+ "mutation_failed",
373
+ "readback_mismatch",
374
+ ]);
375
+ if (!reason || !knownReasons.has(reason)) {
376
+ reason = "readback_mismatch";
377
+ }
378
+ throw new RenderError(`Render engine mutation failed: ${reason}`);
379
+ }
380
+ return {
381
+ mutation_schema: ENGINE_MUTATION_SCHEMA,
382
+ success: true,
383
+ requested_engine: requested,
384
+ persisted: true,
385
+ reason: null,
386
+ readback,
387
+ };
388
+ }
389
+ /**
390
+ * Return the active render engine name.
391
+ *
392
+ * The Render Settings pane's "Engine" dropdown conflates two separate
393
+ * DazScript concepts, confirmed against a live instance:
394
+ * `DzRenderOptions.renderType` is a 3-value enum (ScreenShot,
395
+ * HardwareAssisted, Software) picking *how* the scene is rendered; only
396
+ * when it's `Software` does `renderMgr.getActiveRenderer()` (the
397
+ * pluggable Iray/Filament/... renderer) apply. Returns `"viewport"` or
398
+ * `"multi_pass_opengl"` for the first two modes, otherwise the mapped
399
+ * engine name (e.g. `"iray"`, `"filament"`), falling back to the raw
400
+ * DazScript class name (e.g. `"DzIrayRenderer"`) if it isn't one of the
401
+ * known engines.
402
+ */
403
+ async activeEngine() {
404
+ const script = ScriptBuilder.iife(`
405
+ var mgr = ${RENDER_MGR};
406
+ if (!mgr) return null;
407
+ var opts = mgr.getRenderOptions();
408
+ if (opts.renderType === opts.ScreenShot) return "viewport";
409
+ if (opts.renderType === opts.HardwareAssisted) return "multi_pass_opengl";
410
+ var renderer = mgr.getActiveRenderer();
411
+ return renderer ? renderer.className() : null;
412
+ `);
413
+ const className = (await this.client.execute(script)).value;
414
+ if (className === null)
415
+ return null;
416
+ return ENGINE_CLASS_TO_NAME[className] ?? className;
417
+ }
418
+ /**
419
+ * Set the active render engine.
420
+ *
421
+ * @param engine `"viewport"` or `"multi_pass_opengl"` to switch
422
+ * `DzRenderOptions.renderType` to one of the two non-pluggable modes, or a
423
+ * pluggable renderer name (e.g. `"iray"`, `"filament"`, or a raw
424
+ * DazScript class name like `"DzIrayRenderer"`) to set `renderType` to
425
+ * `Software` and activate that renderer.
426
+ * @throws RenderError If a pluggable renderer name doesn't resolve to a
427
+ * renderer registered with the render manager (e.g. the Filament plugin
428
+ * isn't installed).
429
+ */
430
+ async setActiveEngine(engine) {
431
+ const normalized = engine.trim();
432
+ const lower = normalized.toLowerCase();
433
+ if (NON_SOFTWARE_ENGINES.has(lower)) {
434
+ const renderTypeExpr = lower === "viewport" ? "opts.ScreenShot" : "opts.HardwareAssisted";
435
+ const script = ScriptBuilder.iife(`
436
+ var mgr = ${RENDER_MGR};
437
+ if (!mgr) return false;
438
+ var opts = mgr.getRenderOptions();
439
+ opts.renderType = ${renderTypeExpr};
440
+ opts.applyChanges();
441
+ ${DazRenderSettings.refreshRenderSettingsPaneScript()}
442
+ return true;
443
+ `);
444
+ await this.client.execute(script);
445
+ return;
446
+ }
447
+ const engineClass = ENGINE_NAME_TO_CLASS[lower] ?? normalized;
448
+ const script = ScriptBuilder.iife(`
449
+ var mgr = ${RENDER_MGR};
450
+ if (!mgr) return false;
451
+ var renderer = mgr.findRenderer(${ScriptBuilder.escapeString(engineClass)});
452
+ if (!renderer) return false;
453
+ var opts = mgr.getRenderOptions();
454
+ opts.renderType = opts.Software;
455
+ opts.applyChanges();
456
+ mgr.setActiveRenderer(renderer);
457
+ ${DazRenderSettings.refreshRenderSettingsPaneScript()}
458
+ return true;
459
+ `);
460
+ const found = (await this.client.execute(script)).value;
461
+ if (!found) {
462
+ throw new RenderError(`Render engine not available: ${JSON.stringify(engine)} (class ${JSON.stringify(engineClass)})`);
463
+ }
464
+ }
465
+ /** Return the render image size as `{width, height}`. */
466
+ async resolution() {
467
+ const script = ScriptBuilder.iife(`
468
+ var mgr = ${RENDER_MGR};
469
+ if (!mgr) return null;
470
+ var opts = mgr.getRenderOptions();
471
+ var sz = opts.imageSize;
472
+ return {width: sz.width, height: sz.height};
473
+ `);
474
+ return (await this.client.execute(script)).value;
475
+ }
476
+ /**
477
+ * Set the render image size in pixels.
478
+ *
479
+ * `QSize` is exposed as a constructor in DazScript; plain object literals
480
+ * are not coerced, so `new QSize(w, h)` is required.
481
+ */
482
+ async setResolution(width, height) {
483
+ const w = Math.trunc(width);
484
+ const h = Math.trunc(height);
485
+ const script = ScriptBuilder.iife(`
486
+ var mgr = ${RENDER_MGR};
487
+ if (!mgr) return;
488
+ var opts = mgr.getRenderOptions();
489
+ opts.imageSize = new QSize(${w}, ${h});
490
+ opts.applyChanges();
491
+ `);
492
+ await this.client.execute(script);
493
+ }
494
+ /** Return the filename set for rendered images. */
495
+ async outputPath() {
496
+ const script = ScriptBuilder.iife(`
497
+ var mgr = ${RENDER_MGR};
498
+ if (!mgr) return null;
499
+ return mgr.getRenderOptions().renderImgFilename;
500
+ `);
501
+ return (await this.client.execute(script)).value;
502
+ }
503
+ async setOutputPath(outPath) {
504
+ const script = ScriptBuilder.iife(`
505
+ var mgr = ${RENDER_MGR};
506
+ if (!mgr) return;
507
+ var opts = mgr.getRenderOptions();
508
+ opts.renderImgFilename = ${ScriptBuilder.escapeString(outPath)};
509
+ opts.applyChanges();
510
+ `);
511
+ await this.client.execute(script);
512
+ }
513
+ /** Return the gamma correction value. */
514
+ async gamma() {
515
+ const script = ScriptBuilder.iife(`
516
+ var mgr = ${RENDER_MGR};
517
+ if (!mgr) return null;
518
+ var opts = mgr.getRenderOptions();
519
+ return opts.gamma;
520
+ `);
521
+ return (await this.client.execute(script)).value;
522
+ }
523
+ async setGamma(value) {
524
+ const script = ScriptBuilder.iife(`
525
+ var mgr = ${RENDER_MGR};
526
+ if (!mgr) return;
527
+ var opts = mgr.getRenderOptions();
528
+ opts.gamma = ${Number(value)};
529
+ opts.applyChanges();
530
+ `);
531
+ await this.client.execute(script);
532
+ }
533
+ /** Return whether polygons are rendered as double-sided. */
534
+ async doubleSided() {
535
+ const script = ScriptBuilder.iife(`
536
+ var mgr = ${RENDER_MGR};
537
+ if (!mgr) return null;
538
+ return mgr.getRenderOptions().doubleSided;
539
+ `);
540
+ const result = (await this.client.execute(script)).value;
541
+ return result === null || result === undefined ? null : Boolean(result);
542
+ }
543
+ async setDoubleSided(value) {
544
+ const jsBool = value ? "true" : "false";
545
+ const script = ScriptBuilder.iife(`
546
+ var mgr = ${RENDER_MGR};
547
+ if (!mgr) return;
548
+ var opts = mgr.getRenderOptions();
549
+ opts.doubleSided = ${jsBool};
550
+ opts.applyChanges();
551
+ `);
552
+ await this.client.execute(script);
553
+ }
554
+ /**
555
+ * Render the scene to {@link outputPath}.
556
+ *
557
+ * DAZ Studio's `doRender()` only writes to disk when `renderImgToId` is
558
+ * set to `DzRenderOptions.DirectToFile` and the camera is applied to both
559
+ * the render options and the active viewport before the call.
560
+ *
561
+ * @returns A {@link RenderOutcome} with `success` and the resolved
562
+ * `outputPath` actually written by `doRender()` (`opts.renderImgFilename`
563
+ * after the call).
564
+ * @throws Error If both `cameraName` and `cameraLabel` are given.
565
+ */
566
+ async render(opts = {}) {
567
+ const { cameraName, cameraLabel } = opts;
568
+ if (cameraName !== undefined && cameraLabel !== undefined) {
569
+ throw new Error("Pass at most one of cameraName or cameraLabel");
570
+ }
571
+ let camExpr;
572
+ if (cameraLabel !== undefined) {
573
+ camExpr = `Scene.findCameraByLabel(${ScriptBuilder.escapeString(cameraLabel)})`;
574
+ }
575
+ else if (cameraName !== undefined) {
576
+ camExpr = `Scene.findCamera(${ScriptBuilder.escapeString(cameraName)})`;
577
+ }
578
+ else {
579
+ camExpr = "MainWindow.getViewportMgr().getActiveViewport().get3DViewport().getCamera()";
580
+ }
581
+ const script = ScriptBuilder.iife(`
582
+ var mgr = ${RENDER_MGR};
583
+ if (!mgr) return {success: false, output_path: null};
584
+ var cam = ${camExpr};
585
+ if (!cam) return {success: false, output_path: null};
586
+ var opts = mgr.getRenderOptions();
587
+ opts.camera = cam;
588
+ opts.renderImgToId = DzRenderOptions.DirectToFile;
589
+ // findCanvasDefinition(name, true) implicitly reassigns the
590
+ // "Active Canvas" property to whatever canvas was most recently
591
+ // created/looked-up (confirmed against a live instance). Once
592
+ // any non-Beauty canvas exists (Depth, MaterialID, ...), doRender()
593
+ // saves *that* canvas's pass to the primary output file instead
594
+ // of the true beauty image -- the "clown render" bug (GH #32).
595
+ // Force it back to Beauty right before rendering so the primary
596
+ // output always matches this method's documented contract,
597
+ // regardless of what canvases were added or last touched.
598
+ var canvasHolder = ${this.irayRenderOptionsHolderExpr()};
599
+ if (canvasHolder && canvasHolder.renderToCanvases) {
600
+ var beautyCanvas = canvasHolder.findCanvasDefinition("Beauty", true);
601
+ beautyCanvas.canvasType = beautyCanvas.canvasTypeFromString("Beauty");
602
+ var activeCanvasProp = canvasHolder.findProperty("Active Canvas");
603
+ if (activeCanvasProp) activeCanvasProp.setValueFromString("Beauty");
604
+ }
605
+ var vp = MainWindow.getViewportMgr().getActiveViewport().get3DViewport();
606
+ var prevCam = vp ? vp.getCamera() : null;
607
+ if (vp) vp.setCamera(cam);
608
+ // doRender()'s own return value is undocumented in the SDK (no
609
+ // "Returns:" section at all) and was found to report success even
610
+ // for a render the user cancelled mid-progress via the DAZ Studio
611
+ // UI. DzRenderMgr.renderFinished(bool succeeded) is the SDK's
612
+ // explicit, named completion signal -- SceneEventBroker.cpp
613
+ // already relies on it as the "guaranteed exit path" that fires
614
+ // correctly across error/cancel cases -- so capture it directly
615
+ // instead of guessing at doRender()'s return code.
616
+ var renderSucceeded = null;
617
+ function _onRenderFinished(succeeded) { renderSucceeded = succeeded; }
618
+ mgr["renderFinished(bool)"].connect(_onRenderFinished);
619
+ try {
620
+ mgr.doRender(opts);
621
+ } finally {
622
+ mgr["renderFinished(bool)"].disconnect(_onRenderFinished);
623
+ }
624
+ if (vp && prevCam) vp.setCamera(prevCam);
625
+ return {
626
+ success: renderSucceeded === true,
627
+ output_path: mgr.getRenderOptions().renderImgFilename
628
+ };
629
+ `);
630
+ const result = (await this.client.execute(script)).value ?? {};
631
+ return {
632
+ success: Boolean(result.success ?? false),
633
+ outputPath: result.output_path ?? null,
634
+ };
635
+ }
636
+ /**
637
+ * Alias for {@link render} kept for parity with dazpy's backwards-compatible name.
638
+ * `doRender()` is synchronous in DAZ Studio so no polling is required.
639
+ */
640
+ async renderAndWait() {
641
+ return this.render();
642
+ }
643
+ /** `true` if there is a completed render available to save. */
644
+ async hasRender() {
645
+ const script = ScriptBuilder.iife(`
646
+ var mgr = ${RENDER_MGR};
647
+ if (!mgr) return false;
648
+ return mgr.hasRender();
649
+ `);
650
+ return Boolean((await this.client.execute(script)).value);
651
+ }
652
+ /** Iray progressive rendering sample cap (`Max Samples` in the Advanced tab). */
653
+ async maxSamples() {
654
+ const result = await this.getIrayProperty("Max Samples");
655
+ return result === null || result === undefined ? null : Number(result);
656
+ }
657
+ async setMaxSamples(value) {
658
+ await this.setIrayProperty("Max Samples", Math.trunc(value));
659
+ }
660
+ /** Iray progressive rendering time cap in seconds (`Max Time` in the Advanced tab). */
661
+ async maxTimeSecs() {
662
+ const result = await this.getIrayProperty("Max Time");
663
+ return result === null || result === undefined ? null : Number(result);
664
+ }
665
+ async setMaxTimeSecs(value) {
666
+ await this.setIrayProperty("Max Time", Math.trunc(value));
667
+ }
668
+ /** Iray `Rendering Quality` convergence target (higher converges further). */
669
+ async quality() {
670
+ const result = await this.getIrayProperty("Rendering Quality");
671
+ return result === null || result === undefined ? null : Number(result);
672
+ }
673
+ async setQuality(value) {
674
+ await this.setIrayProperty("Rendering Quality", Number(value));
675
+ }
676
+ /**
677
+ * Apply a named Iray quality preset, controlling sample count and render time.
678
+ *
679
+ * @param preset One of `"draft"`, `"preview"`, `"good"`, `"final"`
680
+ * (fastest/lowest quality to slowest/highest quality).
681
+ * @throws Error If `preset` is not a recognized preset name.
682
+ */
683
+ async setQualityPreset(preset) {
684
+ const settings = QUALITY_PRESETS[preset];
685
+ if (settings === undefined) {
686
+ throw new Error(`Unknown quality preset ${JSON.stringify(preset)}; expected one of ${JSON.stringify(Object.keys(QUALITY_PRESETS).sort())}`);
687
+ }
688
+ await this.setIrayProperty("Max Samples", settings.maxSamples);
689
+ await this.setIrayProperty("Max Time", settings.maxTime);
690
+ await this.setIrayProperty("Rendering Quality Enable", settings.qualityEnable);
691
+ if (settings.quality !== undefined) {
692
+ await this.setIrayProperty("Rendering Quality", settings.quality);
693
+ }
694
+ }
695
+ /** Master on/off switch for all Iray Canvas output (`Render to Canvases`). */
696
+ async canvasesEnabled() {
697
+ const script = ScriptBuilder.iife(`
698
+ var holder = ${this.irayRenderOptionsHolderExpr()};
699
+ if (!holder) return null;
700
+ return holder.renderToCanvases;
701
+ `);
702
+ const result = (await this.client.execute(script)).value;
703
+ return result === null || result === undefined ? null : Boolean(result);
704
+ }
705
+ async setCanvasesEnabled(value) {
706
+ const jsBool = value ? "true" : "false";
707
+ const script = ScriptBuilder.iife(`
708
+ var holder = ${this.irayRenderOptionsHolderExpr()};
709
+ if (!holder) return;
710
+ holder.renderToCanvases = ${jsBool};
711
+ ${DazRenderSettings.refreshRenderSettingsPaneScript()}
712
+ `);
713
+ await this.client.execute(script);
714
+ }
715
+ /** List the Iray Canvases currently configured on the active render. */
716
+ async listCanvases() {
717
+ const script = ScriptBuilder.iife(`
718
+ var holder = ${this.irayRenderOptionsHolderExpr()};
719
+ if (!holder) return [];
720
+ var result = [];
721
+ var n = holder.getNumCanvasDefinitions();
722
+ for (var i = 0; i < n; i++) {
723
+ var c = holder.getCanvasDefinition(i);
724
+ result.push({
725
+ name: c.name,
726
+ canvasType: c.canvasTypeToString(c.canvasType),
727
+ index: c.index
728
+ });
729
+ }
730
+ return result;
731
+ `);
732
+ return (await this.client.execute(script)).value ?? [];
733
+ }
734
+ /**
735
+ * Add (or reconfigure) an Iray Canvas by name.
736
+ *
737
+ * @param name Canvas name. If a canvas with this name already exists it
738
+ * is reconfigured to `canvasType` rather than duplicated.
739
+ * @param canvasType One of `"Beauty"`, `"Diffuse"`, `"Specular"`,
740
+ * `"Glossy"`, `"Emission"`, `"LightGroup"`, `"EnvironmentLighting"`,
741
+ * `"LPE"`, `"Irradiance"`, `"Alpha"`, `"Shadow"`, `"AmbientOcclusion"`,
742
+ * `"Distance"`, `"Depth"`, `"MaterialTag"`, `"MaterialID"`, `"ObjectID"`,
743
+ * `"Normal"`, `"TextureCoordinate"`, `"BSDFWeight"`,
744
+ * `"ConvergenceHeatmap"`, `"PostToon"`, `"WorldPosition"`.
745
+ * @throws RenderError If the render manager or Iray property holder is unavailable.
746
+ */
747
+ async addCanvas(name, canvasType) {
748
+ const script = ScriptBuilder.iife(`
749
+ var holder = ${this.irayRenderOptionsHolderExpr()};
750
+ if (!holder) return null;
751
+ var c = holder.findCanvasDefinition(${ScriptBuilder.escapeString(name)}, true);
752
+ c.canvasType = c.canvasTypeFromString(${ScriptBuilder.escapeString(canvasType)});
753
+ ${DazRenderSettings.refreshRenderSettingsPaneScript()}
754
+ return {
755
+ name: c.name,
756
+ canvasType: c.canvasTypeToString(c.canvasType),
757
+ index: c.index
758
+ };
759
+ `);
760
+ const result = (await this.client.execute(script)).value;
761
+ if (result === null) {
762
+ throw new RenderError("Failed to add canvas: render manager or Iray property holder unavailable");
763
+ }
764
+ return result;
765
+ }
766
+ /**
767
+ * Remove a configured Iray Canvas by name.
768
+ * @returns `true` if a matching canvas was found and removed, `false` if no canvas with `name` exists.
769
+ */
770
+ async removeCanvas(name) {
771
+ const script = ScriptBuilder.iife(`
772
+ var holder = ${this.irayRenderOptionsHolderExpr()};
773
+ if (!holder) return false;
774
+ var c = holder.findCanvasDefinition(${ScriptBuilder.escapeString(name)}, false);
775
+ if (!c) return false;
776
+ holder.removeCanvasDefinition(c);
777
+ ${DazRenderSettings.refreshRenderSettingsPaneScript()}
778
+ return true;
779
+ `);
780
+ return Boolean((await this.client.execute(script)).value);
781
+ }
782
+ /**
783
+ * Return each configured canvas's resolved output file path for a render to `outputPath`.
784
+ *
785
+ * Derived from DAZ Studio's naming convention -- canvases are written to
786
+ * `<dir>/<basename>_canvases/<basename>-<canvasName>-<canvasType>.exr`
787
+ * alongside the main render output. Confirmed empirically against a live
788
+ * render; DazScript does not expose these paths directly, so this is
789
+ * computed rather than queried.
790
+ *
791
+ * @param outputPath The path passed as the main render's `outputPath`
792
+ * (i.e. what {@link setOutputPath} would be called with).
793
+ * @returns A map from each canvas's name to its resolved output path.
794
+ */
795
+ async canvasOutputPaths(outputPath) {
796
+ const sepIdx = Math.max(outputPath.lastIndexOf("/"), outputPath.lastIndexOf("\\"));
797
+ const directory = sepIdx >= 0 ? outputPath.slice(0, sepIdx) : "";
798
+ const filename = outputPath.slice(sepIdx + 1);
799
+ const dotIdx = filename.lastIndexOf(".");
800
+ const basename = dotIdx >= 0 ? filename.slice(0, dotIdx) : filename;
801
+ const sep = sepIdx >= 0 ? outputPath[sepIdx] : "/";
802
+ const prefix = directory ? `${directory}${sep}` : "";
803
+ const canvasesDir = `${basename}_canvases`;
804
+ const canvases = await this.listCanvases();
805
+ const result = {};
806
+ for (const canvas of canvases) {
807
+ result[canvas.name] = `${prefix}${canvasesDir}${sep}${basename}-${canvas.name}-${canvas.canvasType}.exr`;
808
+ }
809
+ return result;
810
+ }
811
+ }