@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,120 @@
1
+ /**
2
+ * Domain-level lighting rigs built on the DazLight/DazScene primitives.
3
+ * Mirrors dazpy's `lighting.py`.
4
+ *
5
+ * Provides {@link applyThreePointLightSetup} for creating a conventional
6
+ * key/fill/rim light rig around a target, either via angle/distance
7
+ * placement or explicit world-space positions. Also provides
8
+ * {@link applyHdriEnvironment} for image-based (HDRI/dome) lighting via
9
+ * {@link HDRIEnvironment}, and {@link setLightColor} as a submodule-level
10
+ * entry point for the color-setting already available via
11
+ * `DazLight.setColor`.
12
+ */
13
+ import { Vec3 } from "./math3.js";
14
+ import type { DazLight } from "./light.js";
15
+ import type { DazNode } from "./node.js";
16
+ import type { DazRenderSettings } from "./render.js";
17
+ import type { DazScene } from "./scene.js";
18
+ /**
19
+ * One light's placement and output within a rig.
20
+ *
21
+ * @param role Informational label, e.g. `"key"`, `"fill"`, `"rim"`.
22
+ * @param azimuthDeg See `sphericalOffset`. Ignored if `position` is set.
23
+ * @param elevationDeg See `sphericalOffset`. Ignored if `position` is set.
24
+ * @param distance Distance from the target, in DAZ Studio units (cm).
25
+ * Ignored if `position` is set.
26
+ * @param intensity Passed to `DazLight.setIntensity`.
27
+ * @param color `(r, g, b)` in the 0-255 range, passed to `DazLight.setColor`.
28
+ * @param position Explicit world-space override. When set, `azimuthDeg`,
29
+ * `elevationDeg`, and `distance` are ignored entirely.
30
+ */
31
+ export interface LightSpec {
32
+ role: string;
33
+ azimuthDeg: number;
34
+ elevationDeg: number;
35
+ distance: number;
36
+ intensity: number;
37
+ color?: [number, number, number];
38
+ position?: Vec3;
39
+ }
40
+ /**
41
+ * Input spec for a three-point light rig.
42
+ *
43
+ * @param target The point to light, as a {@link Vec3} world position or a
44
+ * `DazNode` (its `position()` is used).
45
+ * @param key Key light placement/output. Defaults to a 45deg/30deg key light.
46
+ * @param fill Fill light placement/output. Defaults to a -45deg/15deg fill light.
47
+ * @param rim Rim light placement/output. Defaults to a 180deg/45deg rim light.
48
+ * @param lightType Forwarded to `DazScene.createLight` for all three lights
49
+ * -- one of `"spot"`, `"point"`, `"distant"`.
50
+ */
51
+ export interface ThreePointLightSetup {
52
+ target: Vec3 | DazNode;
53
+ key?: LightSpec;
54
+ fill?: LightSpec;
55
+ rim?: LightSpec;
56
+ lightType?: "spot" | "point" | "distant";
57
+ }
58
+ /** Handles to the three lights created by {@link applyThreePointLightSetup}. */
59
+ export interface ThreePointLightRig {
60
+ key: DazLight;
61
+ fill: DazLight;
62
+ rim: DazLight;
63
+ }
64
+ /**
65
+ * Create and place a key/fill/rim light rig around `setup.target`.
66
+ *
67
+ * @returns A {@link ThreePointLightRig} with handles to the three created lights.
68
+ */
69
+ export declare function applyThreePointLightSetup(scene: DazScene, setup: ThreePointLightSetup): Promise<ThreePointLightRig>;
70
+ /**
71
+ * Image-based (HDRI/dome) lighting configuration.
72
+ *
73
+ * @param imagePath Absolute path to an HDRI/environment map on disk. Must
74
+ * exist -- validated by {@link applyHdriEnvironment} before any DazScript
75
+ * call is made.
76
+ * @param intensity Passed to the Iray "Environment Intensity" property.
77
+ * @param rotationDeg Passed to the Iray "Dome Rotation" property.
78
+ * @param mode One of `"dome_only"`, `"dome_and_scene"`, `"scene_only"`. Maps
79
+ * to the DazScript "Environment Mode" enum. Procedural Sun-Sky mode is
80
+ * intentionally not exposed here.
81
+ * @param drawDome Whether the dome image is visible as a backdrop in the
82
+ * viewport/render (Iray "Draw Dome"), independent of whether it lights the
83
+ * scene.
84
+ * @param resolution Iray "Environment Lighting Resolution" (IBL sampling
85
+ * quality). Omit to leave DAZ Studio's current value untouched.
86
+ */
87
+ export interface HDRIEnvironment {
88
+ imagePath: string;
89
+ intensity?: number;
90
+ rotationDeg?: number;
91
+ mode?: "dome_only" | "dome_and_scene" | "scene_only";
92
+ drawDome?: boolean;
93
+ resolution?: number;
94
+ }
95
+ /**
96
+ * Apply image-based (HDRI/dome) lighting via `renderSettings`.
97
+ *
98
+ * @throws Error If `env.imagePath` does not exist on disk. Checked before
99
+ * any DazScript call is made -- an invalid path passed to the underlying
100
+ * `setMap()` call can hang or crash DAZ Studio via a blocking
101
+ * file-not-found dialog. Also thrown if `env.mode` is not one of
102
+ * `"dome_only"`, `"dome_and_scene"`, `"scene_only"`.
103
+ * @throws RenderError If a post-apply readback of "Environment Intensity"
104
+ * doesn't match `env.intensity`. All of this module's environment writes go
105
+ * through `DazRenderSettings`'s environment-holder methods, which assume
106
+ * `getRenderElementObjects()[3]` is always the Environment property holder
107
+ * -- confirmed on one live DAZ Studio 4.x instance only. If that index is
108
+ * wrong on a different DAZ Studio version, every write above silently
109
+ * no-ops with no exception, so this readback is what actually catches it.
110
+ */
111
+ export declare function applyHdriEnvironment(renderSettings: DazRenderSettings, env: HDRIEnvironment): Promise<void>;
112
+ /**
113
+ * Set `light`'s diffuse color.
114
+ *
115
+ * A thin `lighting.ts`-level entry point for `DazLight.setColor`, so
116
+ * color-setting is discoverable alongside {@link applyThreePointLightSetup}
117
+ * and {@link applyHdriEnvironment} without needing to know the lower-level
118
+ * `DazLight` primitive lives in a different module.
119
+ */
120
+ export declare function setLightColor(light: DazLight, r: number, g: number, b: number): Promise<void>;
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Domain-level lighting rigs built on the DazLight/DazScene primitives.
3
+ * Mirrors dazpy's `lighting.py`.
4
+ *
5
+ * Provides {@link applyThreePointLightSetup} for creating a conventional
6
+ * key/fill/rim light rig around a target, either via angle/distance
7
+ * placement or explicit world-space positions. Also provides
8
+ * {@link applyHdriEnvironment} for image-based (HDRI/dome) lighting via
9
+ * {@link HDRIEnvironment}, and {@link setLightColor} as a submodule-level
10
+ * entry point for the color-setting already available via
11
+ * `DazLight.setColor`.
12
+ */
13
+ import * as fs from "node:fs";
14
+ import { RenderError } from "./exceptions.js";
15
+ import { lookAtEuler, resolveTarget, sphericalOffset } from "./shotGeometry.js";
16
+ const DEFAULT_KEY = { role: "key", azimuthDeg: 45.0, elevationDeg: 30.0, distance: 150.0, intensity: 100.0 };
17
+ const DEFAULT_FILL = { role: "fill", azimuthDeg: -45.0, elevationDeg: 15.0, distance: 150.0, intensity: 50.0 };
18
+ const DEFAULT_RIM = { role: "rim", azimuthDeg: 180.0, elevationDeg: 45.0, distance: 150.0, intensity: 75.0 };
19
+ function resolveLightPosition(target, spec) {
20
+ if (spec.position !== undefined) {
21
+ return spec.position;
22
+ }
23
+ return sphericalOffset(target, spec.azimuthDeg, spec.elevationDeg, spec.distance);
24
+ }
25
+ async function placeLight(scene, target, spec, lightType) {
26
+ const light = await scene.createLight(lightType, spec.role);
27
+ const pos = resolveLightPosition(target, spec);
28
+ await light.setPosition(pos.x, pos.y, pos.z);
29
+ const [pitch, yaw, roll] = lookAtEuler(pos, target);
30
+ await light.setRotation(pitch, yaw, roll);
31
+ await light.setIntensity(spec.intensity);
32
+ const [r, g, b] = spec.color ?? [255, 255, 255];
33
+ await light.setColor(r, g, b);
34
+ return light;
35
+ }
36
+ /**
37
+ * Create and place a key/fill/rim light rig around `setup.target`.
38
+ *
39
+ * @returns A {@link ThreePointLightRig} with handles to the three created lights.
40
+ */
41
+ export async function applyThreePointLightSetup(scene, setup) {
42
+ const target = await resolveTarget(setup.target);
43
+ const lightType = setup.lightType ?? "spot";
44
+ const keyLight = await placeLight(scene, target, setup.key ?? DEFAULT_KEY, lightType);
45
+ const fillLight = await placeLight(scene, target, setup.fill ?? DEFAULT_FILL, lightType);
46
+ const rimLight = await placeLight(scene, target, setup.rim ?? DEFAULT_RIM, lightType);
47
+ return { key: keyLight, fill: fillLight, rim: rimLight };
48
+ }
49
+ const HDRI_MODE_LABELS = {
50
+ dome_only: "Dome Only",
51
+ dome_and_scene: "Dome and Scene",
52
+ scene_only: "Scene Only",
53
+ };
54
+ /**
55
+ * Apply image-based (HDRI/dome) lighting via `renderSettings`.
56
+ *
57
+ * @throws Error If `env.imagePath` does not exist on disk. Checked before
58
+ * any DazScript call is made -- an invalid path passed to the underlying
59
+ * `setMap()` call can hang or crash DAZ Studio via a blocking
60
+ * file-not-found dialog. Also thrown if `env.mode` is not one of
61
+ * `"dome_only"`, `"dome_and_scene"`, `"scene_only"`.
62
+ * @throws RenderError If a post-apply readback of "Environment Intensity"
63
+ * doesn't match `env.intensity`. All of this module's environment writes go
64
+ * through `DazRenderSettings`'s environment-holder methods, which assume
65
+ * `getRenderElementObjects()[3]` is always the Environment property holder
66
+ * -- confirmed on one live DAZ Studio 4.x instance only. If that index is
67
+ * wrong on a different DAZ Studio version, every write above silently
68
+ * no-ops with no exception, so this readback is what actually catches it.
69
+ */
70
+ export async function applyHdriEnvironment(renderSettings, env) {
71
+ if (!fs.existsSync(env.imagePath) || !fs.statSync(env.imagePath).isFile()) {
72
+ throw new Error(`HDRI/environment map not found: ${env.imagePath}`);
73
+ }
74
+ const mode = env.mode ?? "dome_only";
75
+ if (!(mode in HDRI_MODE_LABELS)) {
76
+ throw new Error(`Invalid HDRIEnvironment.mode ${JSON.stringify(mode)}; must be one of ${JSON.stringify(Object.keys(HDRI_MODE_LABELS).sort())}`);
77
+ }
78
+ const intensity = env.intensity ?? 1.0;
79
+ await renderSettings.setEnvironmentMap(env.imagePath);
80
+ await renderSettings.setEnvironmentProperty("Environment Intensity", intensity);
81
+ await renderSettings.setEnvironmentProperty("Dome Rotation", env.rotationDeg ?? 0.0);
82
+ await renderSettings.setEnvironmentPropertyFromString("Environment Mode", HDRI_MODE_LABELS[mode]);
83
+ await renderSettings.setEnvironmentProperty("Draw Dome", env.drawDome ?? false);
84
+ if (env.resolution !== undefined) {
85
+ await renderSettings.setEnvironmentProperty("Environment Lighting Resolution", env.resolution);
86
+ }
87
+ const readback = await renderSettings.getEnvironmentProperty("Environment Intensity");
88
+ if (readback === null || readback === undefined || Math.abs(Number(readback) - intensity) > 1e-6) {
89
+ throw new RenderError("HDRI environment apply failed verification: 'Environment Intensity' " +
90
+ `readback (${JSON.stringify(readback)}) does not match the requested value ` +
91
+ `(${JSON.stringify(intensity)}). The environment property holder ` +
92
+ "(getRenderElementObjects()[3]) may be unavailable or at a " +
93
+ "different index on this DAZ Studio version/build -- the HDRI " +
94
+ "was likely never applied.");
95
+ }
96
+ }
97
+ /**
98
+ * Set `light`'s diffuse color.
99
+ *
100
+ * A thin `lighting.ts`-level entry point for `DazLight.setColor`, so
101
+ * color-setting is discoverable alongside {@link applyThreePointLightSetup}
102
+ * and {@link applyHdriEnvironment} without needing to know the lower-level
103
+ * `DazLight` primitive lives in a different module.
104
+ */
105
+ export async function setLightColor(light, r, g, b) {
106
+ await light.setColor(r, g, b);
107
+ }
@@ -0,0 +1,27 @@
1
+ import { DazElement } from "./element.js";
2
+ /** Proxy for a `DzMaterial` surface, obtained via `DazNode.materials()`/`.findMaterial()`. */
3
+ export declare class DazMaterial extends DazElement {
4
+ materialName(): Promise<string | null>;
5
+ /** Diffuse colour as `{r, g, b}` (0-255, read/write via {@link setDiffuseColor}). */
6
+ diffuseColor(): Promise<{
7
+ r: number;
8
+ g: number;
9
+ b: number;
10
+ } | null>;
11
+ setDiffuseColor(value: {
12
+ r: number;
13
+ g: number;
14
+ b: number;
15
+ } | [number, number, number]): Promise<void>;
16
+ /** Base opacity/transparency (0.0 transparent - 1.0 opaque, read/write). */
17
+ opacity(): Promise<number | null>;
18
+ setOpacity(value: number): Promise<void>;
19
+ /** File path of the diffuse colour texture, or `null`. */
20
+ colorMap(): Promise<string | null>;
21
+ isSmoothingOn(): Promise<boolean | null>;
22
+ /** Normal smoothing angle in degrees (read/write). */
23
+ smoothingAngle(): Promise<number | null>;
24
+ setSmoothingAngle(value: number): Promise<void>;
25
+ /** `true` if the material is fully opaque (opacity == 1.0). */
26
+ isOpaque(): Promise<boolean | null>;
27
+ }
@@ -0,0 +1,63 @@
1
+ import { DazElement } from "./element.js";
2
+ import { ScriptBuilder } from "./scriptBuilder.js";
3
+ /** Proxy for a `DzMaterial` surface, obtained via `DazNode.materials()`/`.findMaterial()`. */
4
+ export class DazMaterial extends DazElement {
5
+ async materialName() {
6
+ const script = ScriptBuilder.iife(`var m = ${this.locator}; return m ? m.getName() : null;`);
7
+ return (await this.client.execute(script)).value;
8
+ }
9
+ /** Diffuse colour as `{r, g, b}` (0-255, read/write via {@link setDiffuseColor}). */
10
+ async diffuseColor() {
11
+ const script = ScriptBuilder.iife(" var m = " + this.locator + ";\n" +
12
+ " if (!m) return null;\n" +
13
+ " var c = m.getDiffuseColor();\n" +
14
+ " return {r: c.red, g: c.green, b: c.blue};\n" +
15
+ " ");
16
+ return (await this.client.execute(script)).value;
17
+ }
18
+ async setDiffuseColor(value) {
19
+ const [r, g, b] = Array.isArray(value) ? value : [value.r, value.g, value.b];
20
+ const script = ScriptBuilder.iife(" var m = " + this.locator + ";\n" +
21
+ " if (!m) return;\n" +
22
+ " var c = new Color(" + ScriptBuilder.serializeArg(Math.trunc(r)) + ", " + ScriptBuilder.serializeArg(Math.trunc(g)) + ", " + ScriptBuilder.serializeArg(Math.trunc(b)) + ");\n" +
23
+ " m.setDiffuseColor(c);\n" +
24
+ " ");
25
+ await this.client.execute(script);
26
+ }
27
+ /** Base opacity/transparency (0.0 transparent - 1.0 opaque, read/write). */
28
+ async opacity() {
29
+ const script = ScriptBuilder.iife(`var m = ${this.locator}; return m ? m.getBaseOpacity() : null;`);
30
+ return (await this.client.execute(script)).value;
31
+ }
32
+ async setOpacity(value) {
33
+ const script = ScriptBuilder.iife(`var m = ${this.locator}; if (m) m.setBaseOpacity(${ScriptBuilder.serializeArg(value)});`);
34
+ await this.client.execute(script);
35
+ }
36
+ /** File path of the diffuse colour texture, or `null`. */
37
+ async colorMap() {
38
+ const script = ScriptBuilder.iife(" var m = " + this.locator + ";\n" +
39
+ " if (!m) return null;\n" +
40
+ " var t = m.getColorMap();\n" +
41
+ " return t ? t.getFilename() : null;\n" +
42
+ " ");
43
+ return (await this.client.execute(script)).value;
44
+ }
45
+ async isSmoothingOn() {
46
+ const script = ScriptBuilder.iife(`var m = ${this.locator}; return m ? m.isSmoothingOn() : null;`);
47
+ return (await this.client.execute(script)).value;
48
+ }
49
+ /** Normal smoothing angle in degrees (read/write). */
50
+ async smoothingAngle() {
51
+ const script = ScriptBuilder.iife(`var m = ${this.locator}; return m ? m.getSmoothingAngle() : null;`);
52
+ return (await this.client.execute(script)).value;
53
+ }
54
+ async setSmoothingAngle(value) {
55
+ const script = ScriptBuilder.iife(`var m = ${this.locator}; if (m) m.setSmoothingAngle(${ScriptBuilder.serializeArg(value)});`);
56
+ await this.client.execute(script);
57
+ }
58
+ /** `true` if the material is fully opaque (opacity == 1.0). */
59
+ async isOpaque() {
60
+ const script = ScriptBuilder.iife(`var m = ${this.locator}; return m ? m.isOpaque() : null;`);
61
+ return (await this.client.execute(script)).value;
62
+ }
63
+ }
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Domain-level Iray Uber Base material setup built on the DazMaterial
3
+ * primitive. Mirrors dazpy's `materials.py`.
4
+ *
5
+ * `DzMaterial` has no dedicated Iray property-holder indirection the way
6
+ * `DzRenderMgr.getActiveRenderer().getPropertyHolder()` does for render
7
+ * settings -- it inherits `findProperty`/`findPropertyByLabel` directly from
8
+ * `DzElement`, and Iray Uber Base channels (Base Color, Metallic Weight,
9
+ * Glossy Roughness, ...) are ordinary named properties on the material
10
+ * itself. Texture-slot assignment goes through the *property* object's
11
+ * `setMap(path)` (defined on `DzNumericProperty`), not through the
12
+ * material. The channel labels in {@link CHANNEL_LABELS} are confirmed
13
+ * against a live DAZ Studio instance -- see
14
+ * `docs/superpowers/specs/2026-08-15-dazpy-materials-design.md` for details.
15
+ */
16
+ import type { DazMaterial } from "./material.js";
17
+ /**
18
+ * One texture-slot assignment for an Iray material channel.
19
+ *
20
+ * @param channel A key into the known Iray channel labels (e.g.
21
+ * `"base_color"`, `"normal"`, `"bump"`, `"metallic"`, `"roughness"`,
22
+ * `"cutout_opacity"`) or an arbitrary DazScript property display label not
23
+ * in that table.
24
+ * @param filePath Absolute path to an image file on disk. Must exist --
25
+ * validated by {@link applyTextureMap} before any DazScript call is made,
26
+ * since an invalid path passed to `setMap()` can hang or crash DAZ Studio
27
+ * via a blocking file-not-found dialog.
28
+ */
29
+ export interface TextureMap {
30
+ channel: string;
31
+ filePath: string;
32
+ }
33
+ /**
34
+ * Generic named Iray surface-channel override, for channels not covered by
35
+ * {@link IrayMaterial}'s typed fields.
36
+ *
37
+ * @param label The DazScript property display label (`getLabel()`).
38
+ * @param value The value to set. Must be JSON-serialisable.
39
+ */
40
+ export interface SurfaceProperty {
41
+ label: string;
42
+ value: unknown;
43
+ }
44
+ /**
45
+ * Declarative Iray Uber Base material spec.
46
+ *
47
+ * Targets the classic Iray Uber Base shader specifically. Figures using the
48
+ * PBRSkin shader variant (e.g. default Genesis 9 skin materials, which have
49
+ * no `Cutout Opacity`/`Glossy Roughness` channels at all) need different
50
+ * channel labels -- use {@link SurfaceProperty}/{@link setSurfaceProperty}
51
+ * with PBRSkin's own labels instead.
52
+ */
53
+ export interface IrayMaterial {
54
+ /** `(r, g, b)` in the 0-255 range. */
55
+ baseColor?: [number, number, number];
56
+ /** 0.0-1.0. */
57
+ metallicWeight?: number;
58
+ /** 0.0-1.0 (Glossy Roughness). */
59
+ roughness?: number;
60
+ /** 0.0-1.0. */
61
+ glossyReflectivity?: number;
62
+ /** 0.0 (fully cut out) - 1.0 (opaque). */
63
+ cutoutOpacity?: number;
64
+ /** Bump map strength multiplier. */
65
+ bumpStrength?: number;
66
+ /** 0.0-1.0. */
67
+ topCoatWeight?: number;
68
+ /** Texture-slot assignments, applied after the typed fields above. */
69
+ textures?: TextureMap[];
70
+ /** Ad hoc named-channel overrides, applied last so they can supersede any typed field or texture set in the same call. */
71
+ properties?: SurfaceProperty[];
72
+ }
73
+ /**
74
+ * Assign `texture` to `material`'s corresponding Iray channel.
75
+ *
76
+ * @throws Error If `texture.filePath` is not an absolute path, or does not
77
+ * exist on disk. Checked before any DazScript call is made.
78
+ * @throws MaterialError If the material or the resolved channel property
79
+ * cannot be found on the live material.
80
+ */
81
+ export declare function applyTextureMap(material: DazMaterial, texture: TextureMap): Promise<void>;
82
+ /**
83
+ * Return the current value of the named Iray surface property.
84
+ *
85
+ * @throws MaterialError If the material or property cannot be found.
86
+ */
87
+ export declare function getSurfaceProperty(material: DazMaterial, label: string): Promise<unknown>;
88
+ /**
89
+ * Set a single named Iray surface property.
90
+ *
91
+ * @throws MaterialError If the material or property cannot be found.
92
+ */
93
+ export declare function setSurfaceProperty(material: DazMaterial, prop: SurfaceProperty): Promise<void>;
94
+ /**
95
+ * Apply `spec` to `material` in typed-fields -> textures -> properties order.
96
+ *
97
+ * `undefined`-valued typed fields are skipped. `spec.properties` is applied
98
+ * last, so it can supersede any typed field or texture set earlier in the
99
+ * same call.
100
+ *
101
+ * @throws Error If any `spec.textures[*].filePath` is not absolute, or does
102
+ * not exist on disk. All texture paths are validated before any DazScript
103
+ * call is made, for the same reason as {@link applyTextureMap}.
104
+ * @throws MaterialError If the material or a resolved channel property
105
+ * cannot be found on the live material.
106
+ */
107
+ export declare function applyIrayMaterial(material: DazMaterial, spec: IrayMaterial): Promise<void>;
@@ -0,0 +1,165 @@
1
+ /**
2
+ * Domain-level Iray Uber Base material setup built on the DazMaterial
3
+ * primitive. Mirrors dazpy's `materials.py`.
4
+ *
5
+ * `DzMaterial` has no dedicated Iray property-holder indirection the way
6
+ * `DzRenderMgr.getActiveRenderer().getPropertyHolder()` does for render
7
+ * settings -- it inherits `findProperty`/`findPropertyByLabel` directly from
8
+ * `DzElement`, and Iray Uber Base channels (Base Color, Metallic Weight,
9
+ * Glossy Roughness, ...) are ordinary named properties on the material
10
+ * itself. Texture-slot assignment goes through the *property* object's
11
+ * `setMap(path)` (defined on `DzNumericProperty`), not through the
12
+ * material. The channel labels in {@link CHANNEL_LABELS} are confirmed
13
+ * against a live DAZ Studio instance -- see
14
+ * `docs/superpowers/specs/2026-08-15-dazpy-materials-design.md` for details.
15
+ */
16
+ import * as fs from "node:fs";
17
+ import * as path from "node:path";
18
+ import { MaterialError } from "./exceptions.js";
19
+ import { ScriptBuilder } from "./scriptBuilder.js";
20
+ // Iray Uber Base shader channel display labels -- confirmed against a live
21
+ // DAZ Studio instance (a prop's default Iray Uber Base material, and a
22
+ // Genesis 9 figure's eye-moisture/tear materials, both of which use the
23
+ // classic Uber Base shader rather than the PBRSkin variant). Note the label
24
+ // ("Metallicity", "Base Bump") can differ from the underlying property name
25
+ // ("Metallic Weight", "Bump Strength") -- findPropertyByLabel() matches on
26
+ // the former.
27
+ const CHANNEL_LABELS = {
28
+ base_color: "Base Color",
29
+ metallic_weight: "Metallicity",
30
+ roughness: "Glossy Roughness",
31
+ glossy_reflectivity: "Glossy Reflectivity",
32
+ cutout_opacity: "Cutout Opacity",
33
+ bump_strength: "Base Bump",
34
+ top_coat_weight: "Top Coat Weight",
35
+ normal: "Normal Map",
36
+ bump: "Base Bump",
37
+ diffuse: "Base Color",
38
+ metallic: "Metallicity",
39
+ };
40
+ function channelLabel(channel) {
41
+ return CHANNEL_LABELS[channel] ?? channel;
42
+ }
43
+ function setChannelValue(material, label, value) {
44
+ return (async () => {
45
+ const serialized = ScriptBuilder.serializeArg(value);
46
+ const script = ScriptBuilder.iife(`
47
+ var m = ${material.getLocator()};
48
+ if (!m) return {"error": "material_not_found"};
49
+ var p = m.findPropertyByLabel(${ScriptBuilder.escapeString(label)});
50
+ if (!p) return {"error": "property_not_found"};
51
+ p.setValue(${serialized});
52
+ return {"success": true};
53
+ `);
54
+ const result = (await material.getClient().execute(script)).value;
55
+ if (!result || result.success !== true) {
56
+ const error = result?.error ?? "unknown_error";
57
+ throw new MaterialError(`Failed to set Iray channel ${JSON.stringify(label)}: ${error}`);
58
+ }
59
+ })();
60
+ }
61
+ async function getChannelValue(material, label) {
62
+ const script = ScriptBuilder.iife(`
63
+ var m = ${material.getLocator()};
64
+ if (!m) return {"error": "material_not_found"};
65
+ var p = m.findPropertyByLabel(${ScriptBuilder.escapeString(label)});
66
+ if (!p) return {"error": "property_not_found"};
67
+ return {"success": true, "value": p.getValue()};
68
+ `);
69
+ const result = (await material.getClient().execute(script)).value;
70
+ if (!result || result.success !== true) {
71
+ const error = result?.error ?? "unknown_error";
72
+ throw new MaterialError(`Failed to read Iray channel ${JSON.stringify(label)}: ${error}`);
73
+ }
74
+ return result.value;
75
+ }
76
+ function validateTexturePath(filePath) {
77
+ if (!path.isAbsolute(filePath)) {
78
+ throw new Error(`Texture map path must be absolute: ${filePath}`);
79
+ }
80
+ if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
81
+ throw new Error(`Texture map not found: ${filePath}`);
82
+ }
83
+ }
84
+ async function setChannelMap(material, label, filePath) {
85
+ validateTexturePath(filePath);
86
+ const script = ScriptBuilder.iife(`
87
+ var m = ${material.getLocator()};
88
+ if (!m) return {"error": "material_not_found"};
89
+ var p = m.findPropertyByLabel(${ScriptBuilder.escapeString(label)});
90
+ if (!p) return {"error": "property_not_found"};
91
+ p.setMap(${ScriptBuilder.escapeString(filePath)});
92
+ return {"success": true};
93
+ `);
94
+ const result = (await material.getClient().execute(script)).value;
95
+ if (!result || result.success !== true) {
96
+ const error = result?.error ?? "unknown_error";
97
+ throw new MaterialError(`Failed to set texture map on channel ${JSON.stringify(label)}: ${error}`);
98
+ }
99
+ }
100
+ /**
101
+ * Assign `texture` to `material`'s corresponding Iray channel.
102
+ *
103
+ * @throws Error If `texture.filePath` is not an absolute path, or does not
104
+ * exist on disk. Checked before any DazScript call is made.
105
+ * @throws MaterialError If the material or the resolved channel property
106
+ * cannot be found on the live material.
107
+ */
108
+ export async function applyTextureMap(material, texture) {
109
+ await setChannelMap(material, channelLabel(texture.channel), texture.filePath);
110
+ }
111
+ /**
112
+ * Return the current value of the named Iray surface property.
113
+ *
114
+ * @throws MaterialError If the material or property cannot be found.
115
+ */
116
+ export async function getSurfaceProperty(material, label) {
117
+ return getChannelValue(material, label);
118
+ }
119
+ /**
120
+ * Set a single named Iray surface property.
121
+ *
122
+ * @throws MaterialError If the material or property cannot be found.
123
+ */
124
+ export async function setSurfaceProperty(material, prop) {
125
+ await setChannelValue(material, prop.label, prop.value);
126
+ }
127
+ const TYPED_FIELDS = [
128
+ ["baseColor", "base_color"],
129
+ ["metallicWeight", "metallic_weight"],
130
+ ["roughness", "roughness"],
131
+ ["glossyReflectivity", "glossy_reflectivity"],
132
+ ["cutoutOpacity", "cutout_opacity"],
133
+ ["bumpStrength", "bump_strength"],
134
+ ["topCoatWeight", "top_coat_weight"],
135
+ ];
136
+ /**
137
+ * Apply `spec` to `material` in typed-fields -> textures -> properties order.
138
+ *
139
+ * `undefined`-valued typed fields are skipped. `spec.properties` is applied
140
+ * last, so it can supersede any typed field or texture set earlier in the
141
+ * same call.
142
+ *
143
+ * @throws Error If any `spec.textures[*].filePath` is not absolute, or does
144
+ * not exist on disk. All texture paths are validated before any DazScript
145
+ * call is made, for the same reason as {@link applyTextureMap}.
146
+ * @throws MaterialError If the material or a resolved channel property
147
+ * cannot be found on the live material.
148
+ */
149
+ export async function applyIrayMaterial(material, spec) {
150
+ for (const texture of spec.textures ?? []) {
151
+ validateTexturePath(texture.filePath);
152
+ }
153
+ for (const [field, channel] of TYPED_FIELDS) {
154
+ const value = spec[field];
155
+ if (value !== undefined) {
156
+ await setChannelValue(material, channelLabel(channel), value);
157
+ }
158
+ }
159
+ for (const texture of spec.textures ?? []) {
160
+ await setChannelMap(material, channelLabel(texture.channel), texture.filePath);
161
+ }
162
+ for (const prop of spec.properties ?? []) {
163
+ await setChannelValue(material, prop.label, prop.value);
164
+ }
165
+ }