@bluemoonfoundry/daz-ts 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +377 -2
- package/dist/animation.d.ts +129 -0
- package/dist/animation.js +276 -0
- package/dist/batch.d.ts +118 -0
- package/dist/batch.js +186 -0
- package/dist/bone.d.ts +50 -0
- package/dist/bone.js +66 -0
- package/dist/camera.d.ts +61 -0
- package/dist/camera.js +120 -0
- package/dist/cinematics.d.ts +188 -0
- package/dist/cinematics.js +165 -0
- package/dist/client.d.ts +399 -0
- package/dist/client.js +769 -0
- package/dist/dforce.d.ts +15 -0
- package/dist/dforce.js +36 -0
- package/dist/element.d.ts +51 -0
- package/dist/element.js +141 -0
- package/dist/exceptions.d.ts +124 -0
- package/dist/exceptions.js +173 -0
- package/dist/geometry.d.ts +81 -0
- package/dist/geometry.js +433 -0
- package/dist/index.d.ts +50 -0
- package/dist/index.js +36 -0
- package/dist/light.d.ts +24 -0
- package/dist/light.js +40 -0
- package/dist/lighting.d.ts +120 -0
- package/dist/lighting.js +107 -0
- package/dist/material.d.ts +27 -0
- package/dist/material.js +63 -0
- package/dist/materials.d.ts +107 -0
- package/dist/materials.js +165 -0
- package/dist/math3.d.ts +204 -0
- package/dist/math3.js +502 -0
- package/dist/modifier.d.ts +14 -0
- package/dist/modifier.js +24 -0
- package/dist/morph.d.ts +11 -0
- package/dist/morph.js +24 -0
- package/dist/node.d.ts +196 -0
- package/dist/node.js +447 -0
- package/dist/polling.d.ts +24 -0
- package/dist/polling.js +50 -0
- package/dist/pose.d.ts +82 -0
- package/dist/pose.js +295 -0
- package/dist/poses.d.ts +54 -0
- package/dist/poses.js +40 -0
- package/dist/property.d.ts +64 -0
- package/dist/property.js +125 -0
- package/dist/render.d.ts +242 -0
- package/dist/render.js +811 -0
- package/dist/renderApi.d.ts +124 -0
- package/dist/renderApi.js +235 -0
- package/dist/result.d.ts +15 -0
- package/dist/result.js +1 -0
- package/dist/scene.d.ts +154 -0
- package/dist/scene.js +584 -0
- package/dist/sceneEvents.d.ts +63 -0
- package/dist/sceneEvents.js +102 -0
- package/dist/sceneState.d.ts +167 -0
- package/dist/sceneState.js +430 -0
- package/dist/scriptBuilder.d.ts +41 -0
- package/dist/scriptBuilder.js +72 -0
- package/dist/shotGeometry.d.ts +49 -0
- package/dist/shotGeometry.js +76 -0
- package/dist/skeleton.d.ts +120 -0
- package/dist/skeleton.js +561 -0
- package/dist/timeline.d.ts +24 -0
- package/dist/timeline.js +39 -0
- package/dist/undo.d.ts +24 -0
- package/dist/undo.js +45 -0
- package/dist/version.d.ts +31 -0
- package/dist/version.js +36 -0
- package/dist/viewport.d.ts +58 -0
- package/dist/viewport.js +239 -0
- package/package.json +52 -4
package/dist/bone.js
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { DazNode } from "./node.js";
|
|
2
|
+
import { ScriptBuilder } from "./scriptBuilder.js";
|
|
3
|
+
/**
|
|
4
|
+
* Proxy for a `DzBone` (a single joint within a {@link DazSkeleton}).
|
|
5
|
+
* Extends `DazNode` with bone-specific rotation helpers.
|
|
6
|
+
*
|
|
7
|
+
* Resolution note: only this class's own overrides — `localEuler`,
|
|
8
|
+
* `localRotation`, `setLocalRotation`, `localPosition`, `rotationOrder`, and
|
|
9
|
+
* `getSkeleton` (all routed through the private `nb()` helper) — resolve via
|
|
10
|
+
* the skeleton-relative `locator` passed to {@link fromLocator}. Every method
|
|
11
|
+
* `DazBone` inherits from `DazNode` without overriding (e.g. `position`,
|
|
12
|
+
* `setPosition`, `setRotation`, `label`, `select`, `parent`, `children`,
|
|
13
|
+
* `modifiers`, `materials`, ...) resolves via `this.identifier` instead — a
|
|
14
|
+
* scene-wide `Scene.findNode()`-style lookup that ignores the locator. See
|
|
15
|
+
* the constructor overload doc on `DazNode` for details.
|
|
16
|
+
*/
|
|
17
|
+
export class DazBone extends DazNode {
|
|
18
|
+
constructor(client, identifier, locator) {
|
|
19
|
+
if (locator !== undefined) {
|
|
20
|
+
super(client, identifier, locator);
|
|
21
|
+
}
|
|
22
|
+
else {
|
|
23
|
+
super(client, identifier);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
/** Construct a `DazBone` from a pre-built skeleton-relative locator (see `DazSkeleton`'s bone lookup). */
|
|
27
|
+
static fromLocator(client, locator, name) {
|
|
28
|
+
return new DazBone(client, { value: name, kind: "name" }, locator);
|
|
29
|
+
}
|
|
30
|
+
nb(body) {
|
|
31
|
+
return ScriptBuilder.nodeBodyFromLocator(this.locator, body);
|
|
32
|
+
}
|
|
33
|
+
/** Local-space rotation as `(x, y, z)` Euler degrees; exact inverse of {@link setLocalRotation}. */
|
|
34
|
+
async localEuler() {
|
|
35
|
+
const result = (await this.client.execute(this.nb("return [_node.getXRotControl().getValue(), _node.getYRotControl().getValue(), _node.getZRotControl().getValue()];"))).value;
|
|
36
|
+
if (result === null)
|
|
37
|
+
return null;
|
|
38
|
+
return [result[0], result[1], result[2]];
|
|
39
|
+
}
|
|
40
|
+
/** Local-space rotation as `{x, y, z, w}` quaternion (read-only). */
|
|
41
|
+
async localRotation() {
|
|
42
|
+
return (await this.client.execute(this.nb("var r = _node.getLocalRot(); return {x: r.x, y: r.y, z: r.z, w: r.w};")))
|
|
43
|
+
.value;
|
|
44
|
+
}
|
|
45
|
+
async setLocalRotation(x, y, z) {
|
|
46
|
+
await this.client.execute(this.nb(`_node.getXRotControl().setValue(${ScriptBuilder.serializeArg(x)}); _node.getYRotControl().setValue(${ScriptBuilder.serializeArg(y)}); _node.getZRotControl().setValue(${ScriptBuilder.serializeArg(z)});`));
|
|
47
|
+
}
|
|
48
|
+
/** Local-space position as `{x, y, z}` (read-only). */
|
|
49
|
+
async localPosition() {
|
|
50
|
+
return (await this.client.execute(this.nb("var p = _node.getLocalPos(); return {x: p.x, y: p.y, z: p.z};")))
|
|
51
|
+
.value;
|
|
52
|
+
}
|
|
53
|
+
/** Rotation order string (e.g. `"XYZ"`), or `null`. */
|
|
54
|
+
async rotationOrder() {
|
|
55
|
+
return (await this.client.execute(this.nb("return _node.getRotationOrder();"))).value;
|
|
56
|
+
}
|
|
57
|
+
/** The parent skeleton, or `null`. */
|
|
58
|
+
async getSkeleton() {
|
|
59
|
+
const name = (await this.client.execute(this.nb("var s = _node.getSkeleton(); return s ? s.getName() : null;")))
|
|
60
|
+
.value;
|
|
61
|
+
if (name === null)
|
|
62
|
+
return null;
|
|
63
|
+
const { DazSkeleton } = await import("./skeleton.js");
|
|
64
|
+
return new DazSkeleton(this.client, { value: name, kind: "name" });
|
|
65
|
+
}
|
|
66
|
+
}
|
package/dist/camera.d.ts
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { DazNode } from "./node.js";
|
|
2
|
+
/**
|
|
3
|
+
* Proxy for a `DzCamera` node. Extends `DazNode` with optical and
|
|
4
|
+
* image-sensor properties.
|
|
5
|
+
*/
|
|
6
|
+
export declare class DazCamera extends DazNode {
|
|
7
|
+
/** Focal length in millimetres (read/write, direct `.focalLength` field access). */
|
|
8
|
+
focalLength(): Promise<number | null>;
|
|
9
|
+
setFocalLength(value: number): Promise<void>;
|
|
10
|
+
/** Field of view in degrees (read-only; derived from focal length). */
|
|
11
|
+
fov(): Promise<number | null>;
|
|
12
|
+
/** Whether depth-of-field simulation is enabled (read/write). */
|
|
13
|
+
depthOfField(): Promise<boolean | null>;
|
|
14
|
+
setDepthOfField(value: boolean): Promise<void>;
|
|
15
|
+
/** Horizontal lens shift in millimetres (read/write). */
|
|
16
|
+
lensShiftX(): Promise<number | null>;
|
|
17
|
+
setLensShiftX(value: number): Promise<void>;
|
|
18
|
+
/** Vertical lens shift in millimetres (read/write). */
|
|
19
|
+
lensShiftY(): Promise<number | null>;
|
|
20
|
+
setLensShiftY(value: number): Promise<void>;
|
|
21
|
+
/** Aperture / f-stop — controls depth-of-field blur intensity (read/write). */
|
|
22
|
+
fStop(): Promise<number | null>;
|
|
23
|
+
setFStop(value: number): Promise<void>;
|
|
24
|
+
/** Bokeh blade count (read/write); `0` = circular bokeh, 3+ = polygonal. */
|
|
25
|
+
apertureBlades(): Promise<number | null>;
|
|
26
|
+
setApertureBlades(value: number): Promise<void>;
|
|
27
|
+
/** Bokeh polygon rotation angle in degrees (read/write). */
|
|
28
|
+
apertureBladeRotation(): Promise<number | null>;
|
|
29
|
+
setApertureBladeRotation(value: number): Promise<void>;
|
|
30
|
+
/** Sensor / film-gate width in millimetres (read-only). */
|
|
31
|
+
frameWidth(): Promise<number | null>;
|
|
32
|
+
/** Distance to the focus plane (read/write). */
|
|
33
|
+
focalDistance(): Promise<number | null>;
|
|
34
|
+
setFocalDistance(value: number): Promise<void>;
|
|
35
|
+
/** Render aspect ratio width component (read/write). */
|
|
36
|
+
aspectWidth(): Promise<number | null>;
|
|
37
|
+
setAspectWidth(value: number): Promise<void>;
|
|
38
|
+
/** Render aspect ratio height component (read/write). */
|
|
39
|
+
aspectHeight(): Promise<number | null>;
|
|
40
|
+
setAspectHeight(value: number): Promise<void>;
|
|
41
|
+
/** Render image width in pixels (read/write). */
|
|
42
|
+
pixelsWidth(): Promise<number | null>;
|
|
43
|
+
setPixelsWidth(value: number): Promise<void>;
|
|
44
|
+
/** Render image height in pixels (read/write). */
|
|
45
|
+
pixelsHeight(): Promise<number | null>;
|
|
46
|
+
setPixelsHeight(value: number): Promise<void>;
|
|
47
|
+
/** Near clipping plane distance (read-only). */
|
|
48
|
+
nearClippingPlane(): Promise<number | null>;
|
|
49
|
+
/** Far clipping plane distance (read-only). */
|
|
50
|
+
farClippingPlane(): Promise<number | null>;
|
|
51
|
+
/** Point the camera at a world-space coordinate. */
|
|
52
|
+
aimAt(x: number, y: number, z: number): Promise<void>;
|
|
53
|
+
/** World-space focal point as `{x, y, z}`. */
|
|
54
|
+
focalPoint(): Promise<{
|
|
55
|
+
x: number;
|
|
56
|
+
y: number;
|
|
57
|
+
z: number;
|
|
58
|
+
} | null>;
|
|
59
|
+
/** `true` if this is the active viewport camera. */
|
|
60
|
+
isViewCamera(): Promise<boolean | null>;
|
|
61
|
+
}
|
package/dist/camera.js
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { DazNode } from "./node.js";
|
|
2
|
+
import { ScriptBuilder } from "./scriptBuilder.js";
|
|
3
|
+
/**
|
|
4
|
+
* Proxy for a `DzCamera` node. Extends `DazNode` with optical and
|
|
5
|
+
* image-sensor properties.
|
|
6
|
+
*/
|
|
7
|
+
export class DazCamera extends DazNode {
|
|
8
|
+
/** Focal length in millimetres (read/write, direct `.focalLength` field access). */
|
|
9
|
+
async focalLength() {
|
|
10
|
+
return (await this.client.execute(this.nodeScript("return _node.focalLength;"))).value;
|
|
11
|
+
}
|
|
12
|
+
async setFocalLength(value) {
|
|
13
|
+
await this.client.execute(this.nodeScript(`_node.focalLength = ${ScriptBuilder.serializeArg(value)};`));
|
|
14
|
+
}
|
|
15
|
+
/** Field of view in degrees (read-only; derived from focal length). */
|
|
16
|
+
async fov() {
|
|
17
|
+
return (await this.client.execute(this.nodeScript("return _node.getFieldOfView();"))).value;
|
|
18
|
+
}
|
|
19
|
+
/** Whether depth-of-field simulation is enabled (read/write). */
|
|
20
|
+
async depthOfField() {
|
|
21
|
+
return (await this.getProperty("Depth of Field"));
|
|
22
|
+
}
|
|
23
|
+
async setDepthOfField(value) {
|
|
24
|
+
await this.setProperty("Depth of Field", value);
|
|
25
|
+
}
|
|
26
|
+
/** Horizontal lens shift in millimetres (read/write). */
|
|
27
|
+
async lensShiftX() {
|
|
28
|
+
return (await this.getProperty("Lens Shift X (mm)"));
|
|
29
|
+
}
|
|
30
|
+
async setLensShiftX(value) {
|
|
31
|
+
await this.setProperty("Lens Shift X (mm)", value);
|
|
32
|
+
}
|
|
33
|
+
/** Vertical lens shift in millimetres (read/write). */
|
|
34
|
+
async lensShiftY() {
|
|
35
|
+
return (await this.getProperty("Lens Shift Y (mm)"));
|
|
36
|
+
}
|
|
37
|
+
async setLensShiftY(value) {
|
|
38
|
+
await this.setProperty("Lens Shift Y (mm)", value);
|
|
39
|
+
}
|
|
40
|
+
/** Aperture / f-stop — controls depth-of-field blur intensity (read/write). */
|
|
41
|
+
async fStop() {
|
|
42
|
+
return (await this.getProperty("F/Stop"));
|
|
43
|
+
}
|
|
44
|
+
async setFStop(value) {
|
|
45
|
+
await this.setProperty("F/Stop", value);
|
|
46
|
+
}
|
|
47
|
+
/** Bokeh blade count (read/write); `0` = circular bokeh, 3+ = polygonal. */
|
|
48
|
+
async apertureBlades() {
|
|
49
|
+
return (await this.getProperty("Aperture Blades"));
|
|
50
|
+
}
|
|
51
|
+
async setApertureBlades(value) {
|
|
52
|
+
await this.setProperty("Aperture Blades", Math.trunc(value));
|
|
53
|
+
}
|
|
54
|
+
/** Bokeh polygon rotation angle in degrees (read/write). */
|
|
55
|
+
async apertureBladeRotation() {
|
|
56
|
+
return (await this.getProperty("Aperture Blade Rotation"));
|
|
57
|
+
}
|
|
58
|
+
async setApertureBladeRotation(value) {
|
|
59
|
+
await this.setProperty("Aperture Blade Rotation", value);
|
|
60
|
+
}
|
|
61
|
+
/** Sensor / film-gate width in millimetres (read-only). */
|
|
62
|
+
async frameWidth() {
|
|
63
|
+
return (await this.client.execute(this.nodeScript("return _node.frameWidth;"))).value;
|
|
64
|
+
}
|
|
65
|
+
/** Distance to the focus plane (read/write). */
|
|
66
|
+
async focalDistance() {
|
|
67
|
+
return (await this.client.execute(this.nodeScript("return _node.focalDistance;"))).value;
|
|
68
|
+
}
|
|
69
|
+
async setFocalDistance(value) {
|
|
70
|
+
await this.client.execute(this.nodeScript(`_node.focalDistance = ${ScriptBuilder.serializeArg(value)};`));
|
|
71
|
+
}
|
|
72
|
+
/** Render aspect ratio width component (read/write). */
|
|
73
|
+
async aspectWidth() {
|
|
74
|
+
return (await this.client.execute(this.nodeScript("return _node.aspectWidth;"))).value;
|
|
75
|
+
}
|
|
76
|
+
async setAspectWidth(value) {
|
|
77
|
+
await this.client.execute(this.nodeScript(`_node.aspectWidth = ${ScriptBuilder.serializeArg(value)};`));
|
|
78
|
+
}
|
|
79
|
+
/** Render aspect ratio height component (read/write). */
|
|
80
|
+
async aspectHeight() {
|
|
81
|
+
return (await this.client.execute(this.nodeScript("return _node.aspectHeight;"))).value;
|
|
82
|
+
}
|
|
83
|
+
async setAspectHeight(value) {
|
|
84
|
+
await this.client.execute(this.nodeScript(`_node.aspectHeight = ${ScriptBuilder.serializeArg(value)};`));
|
|
85
|
+
}
|
|
86
|
+
/** Render image width in pixels (read/write). */
|
|
87
|
+
async pixelsWidth() {
|
|
88
|
+
return (await this.client.execute(this.nodeScript("return _node.pixelsWidth;"))).value;
|
|
89
|
+
}
|
|
90
|
+
async setPixelsWidth(value) {
|
|
91
|
+
await this.client.execute(this.nodeScript(`_node.pixelsWidth = ${ScriptBuilder.serializeArg(Math.trunc(value))};`));
|
|
92
|
+
}
|
|
93
|
+
/** Render image height in pixels (read/write). */
|
|
94
|
+
async pixelsHeight() {
|
|
95
|
+
return (await this.client.execute(this.nodeScript("return _node.pixelsHeight;"))).value;
|
|
96
|
+
}
|
|
97
|
+
async setPixelsHeight(value) {
|
|
98
|
+
await this.client.execute(this.nodeScript(`_node.pixelsHeight = ${ScriptBuilder.serializeArg(Math.trunc(value))};`));
|
|
99
|
+
}
|
|
100
|
+
/** Near clipping plane distance (read-only). */
|
|
101
|
+
async nearClippingPlane() {
|
|
102
|
+
return (await this.client.execute(this.nodeScript("return _node.nearClippingPlane;"))).value;
|
|
103
|
+
}
|
|
104
|
+
/** Far clipping plane distance (read-only). */
|
|
105
|
+
async farClippingPlane() {
|
|
106
|
+
return (await this.client.execute(this.nodeScript("return _node.farClippingPlane;"))).value;
|
|
107
|
+
}
|
|
108
|
+
/** Point the camera at a world-space coordinate. */
|
|
109
|
+
async aimAt(x, y, z) {
|
|
110
|
+
await this.client.execute(this.nodeScript(`_node.aimAt(new DzVec3(${ScriptBuilder.serializeArg(x)}, ${ScriptBuilder.serializeArg(y)}, ${ScriptBuilder.serializeArg(z)}));`));
|
|
111
|
+
}
|
|
112
|
+
/** World-space focal point as `{x, y, z}`. */
|
|
113
|
+
async focalPoint() {
|
|
114
|
+
return (await this.client.execute(this.nodeScript("var fp = _node.getFocalPoint(); return {x: fp.x, y: fp.y, z: fp.z};"))).value;
|
|
115
|
+
}
|
|
116
|
+
/** `true` if this is the active viewport camera. */
|
|
117
|
+
async isViewCamera() {
|
|
118
|
+
return (await this.client.execute(this.nodeScript("return _node.isViewCamera();"))).value;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Domain-level camera shot builders built on the DazCamera/DazScene
|
|
3
|
+
* primitives. Mirrors dazpy's `cinematics.py`.
|
|
4
|
+
*
|
|
5
|
+
* Provides {@link applyStaticShot} for a single camera placement/framing,
|
|
6
|
+
* {@link applyOrbitCamera} for a per-frame orbit sweep around a target,
|
|
7
|
+
* {@link applyFrameSubject} for distance-preset framing of a subject, and
|
|
8
|
+
* {@link applyAnimatedShot} for a camera move driven by real DAZ Studio
|
|
9
|
+
* keyframes (`DazNode.setPositionAtFrame`/`setRotationAtFrame`) rather than
|
|
10
|
+
* a per-frame setValue bake -- DAZ Studio interpolates between the given
|
|
11
|
+
* waypoints itself.
|
|
12
|
+
*/
|
|
13
|
+
import { Vec3 } from "./math3.js";
|
|
14
|
+
import type { DazCamera } from "./camera.js";
|
|
15
|
+
import type { DazNode } from "./node.js";
|
|
16
|
+
import type { DazScene } from "./scene.js";
|
|
17
|
+
/** A single camera placement and optics configuration. */
|
|
18
|
+
export interface CinematicStaticShot {
|
|
19
|
+
/** World-space camera position. */
|
|
20
|
+
position: Vec3;
|
|
21
|
+
/**
|
|
22
|
+
* Aim target passed to `DazCamera.aimAt`. A `DazNode` is resolved via its
|
|
23
|
+
* `position()`, raised by `lookAtOffsetCm`. Omitted -> `rotation` (if
|
|
24
|
+
* set) is used instead.
|
|
25
|
+
*/
|
|
26
|
+
lookAt?: Vec3 | DazNode;
|
|
27
|
+
/**
|
|
28
|
+
* Vertical offset (cm) applied when resolving `lookAt` -- see
|
|
29
|
+
* `resolveTarget`. Defaults to `0.0` since this API already takes an
|
|
30
|
+
* explicit `position`/`lookAt` the caller fully controls.
|
|
31
|
+
*/
|
|
32
|
+
lookAtOffsetCm?: number;
|
|
33
|
+
/** Explicit `(x, y, z)` degrees passed to `DazNode.setRotation`. Ignored if `lookAt` is set. */
|
|
34
|
+
rotation?: [number, number, number];
|
|
35
|
+
/** Passed to `DazCamera.setFocalLength`. */
|
|
36
|
+
focalLength?: number;
|
|
37
|
+
/** Passed to `DazCamera.setDepthOfField`. */
|
|
38
|
+
depthOfField?: boolean;
|
|
39
|
+
/** Passed to `DazCamera.setFocalDistance` when set; otherwise DAZ's current value is untouched. */
|
|
40
|
+
focalDistance?: number;
|
|
41
|
+
/** Passed to `DazCamera.setAspectWidth` when set. */
|
|
42
|
+
aspectWidth?: number;
|
|
43
|
+
/** Passed to `DazCamera.setAspectHeight` when set. */
|
|
44
|
+
aspectHeight?: number;
|
|
45
|
+
/** Passed to `DazCamera.setPixelsWidth` when set. */
|
|
46
|
+
pixelsWidth?: number;
|
|
47
|
+
/** Passed to `DazCamera.setPixelsHeight` when set. */
|
|
48
|
+
pixelsHeight?: number;
|
|
49
|
+
}
|
|
50
|
+
/** Options shared by every `apply*Shot`/`applyFrameSubject` call. */
|
|
51
|
+
export interface CameraTargetOptions {
|
|
52
|
+
/** An existing `DazCamera` to reuse/mutate. Omit to create a new one via `scene.createCamera(name)`. */
|
|
53
|
+
camera?: DazCamera;
|
|
54
|
+
/** Optional name for a newly created camera. Ignored when `camera` is given. */
|
|
55
|
+
name?: string;
|
|
56
|
+
}
|
|
57
|
+
/** Place and configure a camera for `shot` in a single HTTP-round-trip set. */
|
|
58
|
+
export declare function applyStaticShot(scene: DazScene, shot: CinematicStaticShot, opts?: CameraTargetOptions): Promise<DazCamera>;
|
|
59
|
+
/**
|
|
60
|
+
* A camera sweeping around a target across a frame range.
|
|
61
|
+
*
|
|
62
|
+
* Writes a static per-frame placement at each timeline frame -- this is
|
|
63
|
+
* **not** a real interpolated keyframe animation (see the module doc
|
|
64
|
+
* comment). Whether the sweep persists as visible motion when scrubbing the
|
|
65
|
+
* timeline afterward depends on DAZ Studio's key/animation mode at call
|
|
66
|
+
* time; that's the caller's responsibility.
|
|
67
|
+
*/
|
|
68
|
+
export interface OrbitCamera {
|
|
69
|
+
/** The point to orbit around, as a `Vec3` world position or a `DazNode` (its `position()`, raised by `targetOffsetCm`, is used). */
|
|
70
|
+
target: Vec3 | DazNode;
|
|
71
|
+
/** Orbit radius from the target, in DAZ Studio units (cm). */
|
|
72
|
+
radius: number;
|
|
73
|
+
/** Constant elevation angle throughout the orbit -- see `sphericalOffset`. Defaults to `15.0`. */
|
|
74
|
+
elevationDeg?: number;
|
|
75
|
+
/** Azimuth at `frameStart`. Defaults to `0.0`. */
|
|
76
|
+
startAzimuthDeg?: number;
|
|
77
|
+
/**
|
|
78
|
+
* Azimuth at `frameEnd`. Azimuth is linearly interpolated between the two
|
|
79
|
+
* across the frame range. Defaults to `360.0`, which gives `frameStart`
|
|
80
|
+
* and `frameEnd` the same azimuth (a duplicate endpoint) -- callers
|
|
81
|
+
* wanting a seamless loop should use e.g. `endAzimuthDeg: 356.0` or
|
|
82
|
+
* `frameEnd: frameStart + 89` instead of a full 360.
|
|
83
|
+
*/
|
|
84
|
+
endAzimuthDeg?: number;
|
|
85
|
+
/** First timeline frame (inclusive). Defaults to `0`. */
|
|
86
|
+
frameStart?: number;
|
|
87
|
+
/** Last timeline frame (inclusive). Must be `>=` `frameStart`. Defaults to `90`. */
|
|
88
|
+
frameEnd?: number;
|
|
89
|
+
/** Passed to `DazCamera.setFocalLength` once, before the per-frame sweep. Defaults to `50.0`. */
|
|
90
|
+
focalLength?: number;
|
|
91
|
+
/**
|
|
92
|
+
* Vertical offset (cm) applied when resolving `target` -- see
|
|
93
|
+
* `resolveTarget`. Defaults to `25.0` (chest height) since a figure's
|
|
94
|
+
* resolved position is generally its root/hip joint and a close orbit
|
|
95
|
+
* radius aimed straight at it risks clipping the head.
|
|
96
|
+
*/
|
|
97
|
+
targetOffsetCm?: number;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Sweep a camera around `orbit.target` across its frame range.
|
|
101
|
+
*
|
|
102
|
+
* Side effects: this widens/sets the scene's animation range to
|
|
103
|
+
* `[orbit.frameStart, orbit.frameEnd]` via `DazScene.setAnimRange` --
|
|
104
|
+
* without this, DAZ Studio's `Scene.setFrame()` clamps to the scene's
|
|
105
|
+
* existing animation range (typically 0-30 on a fresh scene), silently
|
|
106
|
+
* overwriting later frames onto the clamped one. The scene's timeline frame
|
|
107
|
+
* is also left parked at `orbit.frameEnd` when this function returns -- it
|
|
108
|
+
* is not restored to whatever frame was current beforehand.
|
|
109
|
+
*
|
|
110
|
+
* @throws Error If `orbit.frameEnd` is less than `orbit.frameStart`.
|
|
111
|
+
*/
|
|
112
|
+
export declare function applyOrbitCamera(scene: DazScene, orbit: OrbitCamera, opts?: CameraTargetOptions): Promise<DazCamera>;
|
|
113
|
+
/** A camera framing a subject at a named shot distance. */
|
|
114
|
+
export interface FrameSubject {
|
|
115
|
+
/** The point to frame, as a `Vec3` world position or a `DazNode` (its `position()`, raised by `targetOffsetCm`, is used). */
|
|
116
|
+
subject: Vec3 | DazNode;
|
|
117
|
+
/** One of `"close_up"`, `"medium"`, `"full_body"` -- maps to a preset distance via a module-level table. Defaults to `"medium"`. */
|
|
118
|
+
shotType?: "close_up" | "medium" | "full_body";
|
|
119
|
+
/** Camera azimuth around the subject -- see `sphericalOffset`. Defaults to `0.0`. */
|
|
120
|
+
azimuthDeg?: number;
|
|
121
|
+
/** Camera elevation around the subject. Defaults to `10.0`. */
|
|
122
|
+
elevationDeg?: number;
|
|
123
|
+
/** Passed to `DazCamera.setFocalLength`. Defaults to `50.0`. */
|
|
124
|
+
focalLength?: number;
|
|
125
|
+
/**
|
|
126
|
+
* Vertical offset (cm) applied when resolving `subject` -- see
|
|
127
|
+
* `resolveTarget`. Omitted -> uses `shotType`'s entry in the target-offset
|
|
128
|
+
* table (tighter shots aim higher, to compensate for a figure's resolved
|
|
129
|
+
* position being its root/hip joint rather than chest/head height).
|
|
130
|
+
*/
|
|
131
|
+
targetOffsetCm?: number;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Place and aim a camera to frame `frame.subject` at its shot distance.
|
|
135
|
+
*
|
|
136
|
+
* @throws Error If `frame.shotType` is not one of `"close_up"`, `"medium"`, `"full_body"`.
|
|
137
|
+
*/
|
|
138
|
+
export declare function applyFrameSubject(scene: DazScene, frame: FrameSubject, opts?: CameraTargetOptions): Promise<DazCamera>;
|
|
139
|
+
/** A single waypoint in an animated camera move (see {@link CinematicAnimatedShot}). */
|
|
140
|
+
export interface CameraKeyframe {
|
|
141
|
+
/** Timeline frame number for this waypoint. */
|
|
142
|
+
frame: number;
|
|
143
|
+
/** World-space camera position at `frame`. */
|
|
144
|
+
position: Vec3;
|
|
145
|
+
/** Aim target at `frame`, resolved the same way as `CinematicStaticShot.lookAt`. Omitted -> `rotation` (if set) is used instead. */
|
|
146
|
+
lookAt?: Vec3 | DazNode;
|
|
147
|
+
/** Vertical offset (cm) applied when resolving `lookAt` -- see `resolveTarget`. */
|
|
148
|
+
lookAtOffsetCm?: number;
|
|
149
|
+
/** Explicit `(x, y, z)` degrees for this waypoint. Ignored if `lookAt` is set. */
|
|
150
|
+
rotation?: [number, number, number];
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* A camera move driven by real DAZ Studio keyframes.
|
|
154
|
+
*
|
|
155
|
+
* Unlike {@link OrbitCamera} (which bakes a value on every timeline frame),
|
|
156
|
+
* this writes one keyframe per {@link CameraKeyframe} waypoint and lets DAZ
|
|
157
|
+
* Studio interpolate the frames in between via its own animation curves.
|
|
158
|
+
*/
|
|
159
|
+
export interface CinematicAnimatedShot {
|
|
160
|
+
/**
|
|
161
|
+
* The waypoints, in ascending, unique `frame` order (at least two). Either
|
|
162
|
+
* every waypoint must specify an orientation (`lookAt` or `rotation`) or
|
|
163
|
+
* none must -- a partial mix would leave the rotation curve keyed at only
|
|
164
|
+
* some waypoints, holding a stale orientation between them.
|
|
165
|
+
*/
|
|
166
|
+
keyframes: CameraKeyframe[];
|
|
167
|
+
/** Passed to `DazCamera.setFocalLength` once, before the keyframes are written. Defaults to `50.0`. */
|
|
168
|
+
focalLength?: number;
|
|
169
|
+
/** Passed to `DazCamera.setDepthOfField` once. Defaults to `false`. */
|
|
170
|
+
depthOfField?: boolean;
|
|
171
|
+
/** Passed to `DazCamera.setFocalDistance` once, when set; otherwise DAZ's current value is untouched. */
|
|
172
|
+
focalDistance?: number;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Write `shot.keyframes` as real DAZ Studio keyframes on a camera.
|
|
176
|
+
*
|
|
177
|
+
* Side effects: clears any existing keys on the camera's position controls
|
|
178
|
+
* (via `DazNode.clearPositionKeys`) before writing the new curve -- a
|
|
179
|
+
* freshly created camera can already carry a default key from creation
|
|
180
|
+
* time, which would otherwise distort interpolation/extrapolation around
|
|
181
|
+
* the new keyframes. Rotation controls are cleared the same way, but only
|
|
182
|
+
* if at least one keyframe specifies an orientation.
|
|
183
|
+
*
|
|
184
|
+
* @throws Error If fewer than two keyframes are given, if their `frame`
|
|
185
|
+
* values are not strictly ascending, or if only some keyframes specify an
|
|
186
|
+
* orientation (`lookAt`/`rotation`).
|
|
187
|
+
*/
|
|
188
|
+
export declare function applyAnimatedShot(scene: DazScene, shot: CinematicAnimatedShot, opts?: CameraTargetOptions): Promise<DazCamera>;
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Domain-level camera shot builders built on the DazCamera/DazScene
|
|
3
|
+
* primitives. Mirrors dazpy's `cinematics.py`.
|
|
4
|
+
*
|
|
5
|
+
* Provides {@link applyStaticShot} for a single camera placement/framing,
|
|
6
|
+
* {@link applyOrbitCamera} for a per-frame orbit sweep around a target,
|
|
7
|
+
* {@link applyFrameSubject} for distance-preset framing of a subject, and
|
|
8
|
+
* {@link applyAnimatedShot} for a camera move driven by real DAZ Studio
|
|
9
|
+
* keyframes (`DazNode.setPositionAtFrame`/`setRotationAtFrame`) rather than
|
|
10
|
+
* a per-frame setValue bake -- DAZ Studio interpolates between the given
|
|
11
|
+
* waypoints itself.
|
|
12
|
+
*/
|
|
13
|
+
import { lookAtEuler, resolveTarget, sphericalOffset } from "./shotGeometry.js";
|
|
14
|
+
async function resolveCamera(scene, camera, name) {
|
|
15
|
+
if (camera !== undefined) {
|
|
16
|
+
return camera;
|
|
17
|
+
}
|
|
18
|
+
return scene.createCamera(name);
|
|
19
|
+
}
|
|
20
|
+
/** Place and configure a camera for `shot` in a single HTTP-round-trip set. */
|
|
21
|
+
export async function applyStaticShot(scene, shot, opts = {}) {
|
|
22
|
+
const cam = await resolveCamera(scene, opts.camera, opts.name);
|
|
23
|
+
await cam.setPosition(shot.position.x, shot.position.y, shot.position.z);
|
|
24
|
+
if (shot.lookAt !== undefined) {
|
|
25
|
+
const target = await resolveTarget(shot.lookAt, shot.lookAtOffsetCm ?? 0.0);
|
|
26
|
+
await cam.aimAt(target.x, target.y, target.z);
|
|
27
|
+
}
|
|
28
|
+
else if (shot.rotation !== undefined) {
|
|
29
|
+
await cam.setRotation(...shot.rotation);
|
|
30
|
+
}
|
|
31
|
+
await cam.setFocalLength(shot.focalLength ?? 50.0);
|
|
32
|
+
await cam.setDepthOfField(shot.depthOfField ?? false);
|
|
33
|
+
if (shot.focalDistance !== undefined) {
|
|
34
|
+
await cam.setFocalDistance(shot.focalDistance);
|
|
35
|
+
}
|
|
36
|
+
if (shot.aspectWidth !== undefined) {
|
|
37
|
+
await cam.setAspectWidth(shot.aspectWidth);
|
|
38
|
+
}
|
|
39
|
+
if (shot.aspectHeight !== undefined) {
|
|
40
|
+
await cam.setAspectHeight(shot.aspectHeight);
|
|
41
|
+
}
|
|
42
|
+
if (shot.pixelsWidth !== undefined) {
|
|
43
|
+
await cam.setPixelsWidth(shot.pixelsWidth);
|
|
44
|
+
}
|
|
45
|
+
if (shot.pixelsHeight !== undefined) {
|
|
46
|
+
await cam.setPixelsHeight(shot.pixelsHeight);
|
|
47
|
+
}
|
|
48
|
+
return cam;
|
|
49
|
+
}
|
|
50
|
+
function lerp(start, end, t) {
|
|
51
|
+
return start + (end - start) * t;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Sweep a camera around `orbit.target` across its frame range.
|
|
55
|
+
*
|
|
56
|
+
* Side effects: this widens/sets the scene's animation range to
|
|
57
|
+
* `[orbit.frameStart, orbit.frameEnd]` via `DazScene.setAnimRange` --
|
|
58
|
+
* without this, DAZ Studio's `Scene.setFrame()` clamps to the scene's
|
|
59
|
+
* existing animation range (typically 0-30 on a fresh scene), silently
|
|
60
|
+
* overwriting later frames onto the clamped one. The scene's timeline frame
|
|
61
|
+
* is also left parked at `orbit.frameEnd` when this function returns -- it
|
|
62
|
+
* is not restored to whatever frame was current beforehand.
|
|
63
|
+
*
|
|
64
|
+
* @throws Error If `orbit.frameEnd` is less than `orbit.frameStart`.
|
|
65
|
+
*/
|
|
66
|
+
export async function applyOrbitCamera(scene, orbit, opts = {}) {
|
|
67
|
+
const frameStart = orbit.frameStart ?? 0;
|
|
68
|
+
const frameEnd = orbit.frameEnd ?? 90;
|
|
69
|
+
const elevationDeg = orbit.elevationDeg ?? 15.0;
|
|
70
|
+
const startAzimuthDeg = orbit.startAzimuthDeg ?? 0.0;
|
|
71
|
+
const endAzimuthDeg = orbit.endAzimuthDeg ?? 360.0;
|
|
72
|
+
const focalLength = orbit.focalLength ?? 50.0;
|
|
73
|
+
const targetOffsetCm = orbit.targetOffsetCm ?? 25.0;
|
|
74
|
+
if (frameEnd < frameStart) {
|
|
75
|
+
throw new Error(`OrbitCamera.frameEnd (${frameEnd}) must be >= frameStart (${frameStart})`);
|
|
76
|
+
}
|
|
77
|
+
const cam = await resolveCamera(scene, opts.camera, opts.name);
|
|
78
|
+
await scene.setAnimRange(frameStart, frameEnd);
|
|
79
|
+
const target = await resolveTarget(orbit.target, targetOffsetCm);
|
|
80
|
+
await cam.setFocalLength(focalLength);
|
|
81
|
+
const frameCount = frameEnd - frameStart;
|
|
82
|
+
for (let frame = frameStart; frame <= frameEnd; frame++) {
|
|
83
|
+
const t = frameCount > 0 ? (frame - frameStart) / frameCount : 0.0;
|
|
84
|
+
const azimuth = lerp(startAzimuthDeg, endAzimuthDeg, t);
|
|
85
|
+
const pos = sphericalOffset(target, azimuth, elevationDeg, orbit.radius);
|
|
86
|
+
await scene.setFrame(frame);
|
|
87
|
+
await cam.setPosition(pos.x, pos.y, pos.z);
|
|
88
|
+
await cam.aimAt(target.x, target.y, target.z);
|
|
89
|
+
}
|
|
90
|
+
return cam;
|
|
91
|
+
}
|
|
92
|
+
const SHOT_DISTANCES = { close_up: 60.0, medium: 150.0, full_body: 300.0 };
|
|
93
|
+
const SHOT_TARGET_OFFSETS_CM = { close_up: 45.0, medium: 25.0, full_body: 0.0 };
|
|
94
|
+
/**
|
|
95
|
+
* Place and aim a camera to frame `frame.subject` at its shot distance.
|
|
96
|
+
*
|
|
97
|
+
* @throws Error If `frame.shotType` is not one of `"close_up"`, `"medium"`, `"full_body"`.
|
|
98
|
+
*/
|
|
99
|
+
export async function applyFrameSubject(scene, frame, opts = {}) {
|
|
100
|
+
const shotType = frame.shotType ?? "medium";
|
|
101
|
+
if (!(shotType in SHOT_DISTANCES)) {
|
|
102
|
+
throw new Error(`Invalid FrameSubject.shotType ${JSON.stringify(shotType)}; must be one of ${JSON.stringify(Object.keys(SHOT_DISTANCES).sort())}`);
|
|
103
|
+
}
|
|
104
|
+
const cam = await resolveCamera(scene, opts.camera, opts.name);
|
|
105
|
+
const offset = frame.targetOffsetCm !== undefined ? frame.targetOffsetCm : SHOT_TARGET_OFFSETS_CM[shotType];
|
|
106
|
+
const target = await resolveTarget(frame.subject, offset);
|
|
107
|
+
const pos = sphericalOffset(target, frame.azimuthDeg ?? 0.0, frame.elevationDeg ?? 10.0, SHOT_DISTANCES[shotType]);
|
|
108
|
+
await cam.setPosition(pos.x, pos.y, pos.z);
|
|
109
|
+
await cam.aimAt(target.x, target.y, target.z);
|
|
110
|
+
await cam.setFocalLength(frame.focalLength ?? 50.0);
|
|
111
|
+
return cam;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Write `shot.keyframes` as real DAZ Studio keyframes on a camera.
|
|
115
|
+
*
|
|
116
|
+
* Side effects: clears any existing keys on the camera's position controls
|
|
117
|
+
* (via `DazNode.clearPositionKeys`) before writing the new curve -- a
|
|
118
|
+
* freshly created camera can already carry a default key from creation
|
|
119
|
+
* time, which would otherwise distort interpolation/extrapolation around
|
|
120
|
+
* the new keyframes. Rotation controls are cleared the same way, but only
|
|
121
|
+
* if at least one keyframe specifies an orientation.
|
|
122
|
+
*
|
|
123
|
+
* @throws Error If fewer than two keyframes are given, if their `frame`
|
|
124
|
+
* values are not strictly ascending, or if only some keyframes specify an
|
|
125
|
+
* orientation (`lookAt`/`rotation`).
|
|
126
|
+
*/
|
|
127
|
+
export async function applyAnimatedShot(scene, shot, opts = {}) {
|
|
128
|
+
if (shot.keyframes.length < 2) {
|
|
129
|
+
throw new Error("CinematicAnimatedShot.keyframes needs at least two waypoints");
|
|
130
|
+
}
|
|
131
|
+
const frames = shot.keyframes.map((kf) => kf.frame);
|
|
132
|
+
const sorted = [...frames].sort((a, b) => a - b);
|
|
133
|
+
const isStrictlyAscendingUnique = frames.every((f, i) => f === sorted[i]) && new Set(frames).size === frames.length;
|
|
134
|
+
if (!isStrictlyAscendingUnique) {
|
|
135
|
+
throw new Error("CinematicAnimatedShot.keyframes must have strictly ascending, unique frame numbers");
|
|
136
|
+
}
|
|
137
|
+
const hasOrientation = shot.keyframes.map((kf) => kf.lookAt !== undefined || kf.rotation !== undefined);
|
|
138
|
+
const anyOriented = hasOrientation.some(Boolean);
|
|
139
|
+
const allOriented = hasOrientation.every(Boolean);
|
|
140
|
+
if (anyOriented && !allOriented) {
|
|
141
|
+
throw new Error("CinematicAnimatedShot.keyframes must either all specify an orientation (lookAt/rotation) or none of them should");
|
|
142
|
+
}
|
|
143
|
+
const cam = await resolveCamera(scene, opts.camera, opts.name);
|
|
144
|
+
await cam.setFocalLength(shot.focalLength ?? 50.0);
|
|
145
|
+
await cam.setDepthOfField(shot.depthOfField ?? false);
|
|
146
|
+
if (shot.focalDistance !== undefined) {
|
|
147
|
+
await cam.setFocalDistance(shot.focalDistance);
|
|
148
|
+
}
|
|
149
|
+
await cam.clearPositionKeys();
|
|
150
|
+
if (anyOriented) {
|
|
151
|
+
await cam.clearRotationKeys();
|
|
152
|
+
}
|
|
153
|
+
for (const kf of shot.keyframes) {
|
|
154
|
+
await cam.setPositionAtFrame(kf.frame, kf.position.x, kf.position.y, kf.position.z);
|
|
155
|
+
if (kf.lookAt !== undefined) {
|
|
156
|
+
const target = await resolveTarget(kf.lookAt, kf.lookAtOffsetCm ?? 0.0);
|
|
157
|
+
const [x, y, z] = lookAtEuler(kf.position, target);
|
|
158
|
+
await cam.setRotationAtFrame(kf.frame, x, y, z);
|
|
159
|
+
}
|
|
160
|
+
else if (kf.rotation !== undefined) {
|
|
161
|
+
await cam.setRotationAtFrame(kf.frame, ...kf.rotation);
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
return cam;
|
|
165
|
+
}
|