Files
effectcraft/crates/engine/src/cmd/three_d.rs
T
vangel76andClaude Opus 5.5 d04ccd5234 Render: sampleImage and text fonts note the files they read
EvalCtx carries the render's read log. A sampleImage render records its footage
reads, keeps them with its per-thread cached buffer and notes them in the
evaluating render's log on every use. Text notes the font files it is drawn with,
with the identity their bytes were read with; a family that isn't installed, a
fallback or missing glyph, or a font from memory leaves the list incomplete.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 01:58:15 +01:00

797 lines
36 KiB
Rust

//! 3D: cameras (Layer ▸ New ▸ Camera, Camera Settings), lights (Layer ▸ New ▸ Light, Light
//! Settings), the viewer's 3D views (View ▸ Switch 3D View, Reset 3D View) and the camera tools
//! (Orbit, Pan, Dolly) acting on the current 3D view.
use effectcraft_geom::{Mat4, Vec3, vec3};
use effectcraft_keyframe::Value as KV;
use effectcraft_project::build;
use effectcraft_project::{AutoOrient, Comp, ItemId, Layer, LayerId, LayerSource, LightKind};
use effectcraft_render::EvalCtx;
use effectcraft_render::three_d::camera::{self, PRESETS, Rig, View3D, ViewCam, Views3D, orientation_for, zoom_for_focal};
use effectcraft_time::Tick;
use serde_json::{Value, json};
use super::layer::{color_p, insert_layer};
use super::model3d::{report_switch, use_advanced_3d};
use super::{CommandSpec, b_p, bad, comp_id, f_p, has_comp, layer_mut, layer_p, merge_p, str_p, time_p};
use crate::{EngineError, Result, Session, cmd, query};
fn v3_p(p: &Value, k: &str) -> Option<[f64; 3]> {
let a = p.get(k)?.as_array()?;
let g = |i: usize| a.get(i).and_then(Value::as_f64);
Some([g(0)?, g(1)?, g(2).unwrap_or(0.0)])
}
/// Set a property at comp time `t` (adds a key when it is animated).
fn set_at(l: &mut Layer, path: &str, t: Tick, v: KV) {
let lt = l.layer_time(t);
if let Some(pr) = l.props.prop_mut(path) {
pr.set_value_at(lt, v);
}
}
fn get_at(l: &Layer, path: &str, t: Tick) -> Option<KV> {
l.props.prop(path).map(|pr| pr.value_at(l.layer_time(t)))
}
// ---------------------------------------------------------------- cameras
/// Parse a camera type: `oneNode`/`twoNode` (or "One-Node Camera"…). Some(true) = two-node.
fn two_node_p(p: &Value) -> Option<bool> {
let t = str_p(p, "type")?.to_ascii_lowercase().replace(['-', ' ', '_'], "");
if t.starts_with("one") {
Some(false)
} else if t.starts_with("two") {
Some(true)
} else {
None
}
}
/// Zoom from `zoom`, `preset` ("50mm"), `focalLength` (mm) or `angleOfView` (degrees).
fn zoom_p(p: &Value, comp_w: f64) -> Result<Option<f64>> {
if let Some(z) = f_p(p, "zoom") {
return Ok(Some(z.max(0.1)));
}
if let Some(pr) = p.get("preset") {
let focal = match pr {
Value::Number(n) => n.as_f64(),
Value::String(s) => {
let k = s.trim().to_ascii_lowercase();
PRESETS.iter().find(|(n, _)| n.eq_ignore_ascii_case(&k)).map(|(_, f)| *f).or_else(|| k.trim_end_matches("mm").trim().parse().ok())
}
_ => None,
}
.ok_or_else(|| bad("layer.newCamera", format!("unknown preset {pr}; use one of 15mm, 20mm, 24mm, 28mm, 35mm, 50mm, 80mm, 135mm, 200mm")))?;
return Ok(Some(zoom_for_focal(comp_w, focal)));
}
if let Some(f) = f_p(p, "focalLength") {
return Ok(Some(zoom_for_focal(comp_w, f)));
}
if let Some(a) = f_p(p, "angleOfView") {
return Ok(Some(comp_w * 0.5 / (a.clamp(0.1, 179.0).to_radians() * 0.5).tan()));
}
Ok(None)
}
/// Apply Camera Settings parameters to a camera layer at comp time `t`.
fn apply_camera(l: &mut Layer, comp: &Comp, p: &Value, t: Tick, cmd: &str) -> Result<()> {
let w = comp.width as f64;
if let Some(z) = zoom_p(p, w)? {
set_at(l, "cameraOptions/zoom", t, KV::Scalar(z));
// "Lock to Zoom" (default): the focus distance follows the zoom unless one is given.
if b_p(p, "lockToZoom").unwrap_or(true) && f_p(p, "focusDistance").is_none() {
set_at(l, "cameraOptions/focusDistance", t, KV::Scalar(z));
}
}
if let Some(v) = b_p(p, "dof").or_else(|| b_p(p, "depthOfField")) {
set_at(l, "cameraOptions/dof", t, KV::Bool(v));
}
for (k, path) in [("focusDistance", "cameraOptions/focusDistance"), ("aperture", "cameraOptions/aperture"), ("blurLevel", "cameraOptions/blurLevel")] {
if let Some(v) = f_p(p, k) {
set_at(l, path, t, KV::Scalar(v.max(0.0)));
}
}
if let Some(fs) = f_p(p, "fStop") {
// F-Stop = focal length / aperture, apertures in mm scaled like the presets (25.3 mm at 1920 px).
let z = get_at(l, "cameraOptions/zoom", t).map(|v| v.as_f64()).unwrap_or(1000.0);
let focal = camera::focal_for_zoom(w, z);
set_at(l, "cameraOptions/aperture", t, KV::Scalar(focal / fs.max(0.01) * w / 1920.0));
}
if let Some(pos) = v3_p(p, "position") {
set_at(l, "transform/position", t, KV::Vec3(pos));
}
if let Some(poi) = v3_p(p, "poi").or_else(|| v3_p(p, "pointOfInterest")) {
set_at(l, "transform/poi", t, KV::Vec3(poi));
}
if let Some(two) = two_node_p(p) {
let was = l.auto_orient == AutoOrient::TowardsPointOfInterest;
if two != was {
let pos = Vec3::from(get_at(l, "transform/position", t).map(|v| v.as_vec3()).unwrap_or([0.0; 3]));
let zoom = get_at(l, "cameraOptions/zoom", t).map(|v| v.as_f64()).unwrap_or(1000.0);
if two {
// Keep the view: put the POI where the camera looks, clear the orientation.
let o = get_at(l, "transform/orientation", t).map(|v| v.as_vec3()).unwrap_or([0.0; 3]);
let fwd = Mat4::orientation(Vec3::from(o)).apply_vec(vec3(0.0, 0.0, 1.0));
let poi = pos + fwd * zoom;
set_at(l, "transform/poi", t, KV::Vec3([poi.x, poi.y, poi.z]));
set_at(l, "transform/orientation", t, KV::Vec3([0.0; 3]));
l.auto_orient = AutoOrient::TowardsPointOfInterest;
} else {
let poi = Vec3::from(get_at(l, "transform/poi", t).map(|v| v.as_vec3()).unwrap_or([0.0; 3]));
set_at(l, "transform/orientation", t, KV::Vec3(orientation_for(poi - pos)));
l.auto_orient = AutoOrient::Off;
}
}
} else if p.get("type").is_some() {
return Err(bad(cmd, "type: oneNode|twoNode"));
}
Ok(())
}
fn new_camera(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let name = str_p(p, "name").unwrap_or("Camera 1").to_string();
let t = time_p(s, p, Some(&comp));
let id = s.edit("New Camera", None, |proj, st| {
let mut l = build::layer(proj, &comp, &name, LayerSource::Camera, (comp.width, comp.height), None);
apply_camera(&mut l, &comp, p, t, "layer.newCamera")?;
insert_layer(proj, st, cid, l)
})?;
Ok(json!({"layer": id.0}))
}
/// The camera or light layer a settings command targets.
fn target(s: &Session, p: &Value, cmd: &str, want_camera: bool) -> Result<(ItemId, LayerId)> {
let (cid, lid) = layer_p(s, p, cmd)?;
let l = s.project.comp(cid).and_then(|c| c.layer(lid)).ok_or(EngineError::NoComp)?;
let ok = if want_camera { l.is_camera() } else { l.is_light() };
if !ok {
return Err(bad(cmd, format!("layer `{}` is not a {}", l.name, if want_camera { "camera" } else { "light" })));
}
Ok((cid, lid))
}
fn camera_settings(s: &mut Session, p: &Value) -> Result<Value> {
let (cid, lid) = target(s, p, "layer.cameraSettings", true)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let t = time_p(s, p, Some(&comp));
let name = str_p(p, "name").map(str::to_string);
s.edit("Camera Settings", None, |proj, _| {
let l = layer_mut(proj, cid, lid)?;
if let Some(n) = &name {
l.name = n.clone();
}
apply_camera(l, &comp, p, t, "layer.cameraSettings")
})?;
Ok(Value::Null)
}
// ---------------------------------------------------------------- lights
fn light_kind_p(p: &Value, k: &str) -> Option<LightKind> {
let v = str_p(p, k)?;
LightKind::ALL.into_iter().find(|l| l.label().eq_ignore_ascii_case(v.trim()))
}
fn apply_light(l: &mut Layer, p: &Value, t: Tick, cmd: &str) -> Result<()> {
if let Some(c) = color_p(p, "color") {
set_at(l, "lightOptions/color", t, KV::Color([c[0] as f64, c[1] as f64, c[2] as f64, 1.0]));
}
for k in ["intensity", "coneAngle", "coneFeather", "radius", "falloffDistance", "shadowDarkness", "shadowDiffusion"] {
if let Some(v) = f_p(p, k) {
set_at(l, &format!("lightOptions/{k}"), t, KV::Scalar(v));
}
}
if let Some(v) = b_p(p, "castsShadows") {
set_at(l, "lightOptions/castsShadows", t, KV::Bool(v));
}
if let Some(f) = p.get("falloff") {
let i = match f {
Value::Number(n) => n.as_u64().map(|v| v as u32),
Value::String(s) => {
let k = s.to_ascii_lowercase();
if k.starts_with("none") {
Some(0)
} else if k.starts_with("smooth") {
Some(1)
} else if k.starts_with("inverse") {
Some(2)
} else {
None
}
}
_ => None,
}
.filter(|i| *i <= 2)
.ok_or_else(|| bad(cmd, "falloff: None|Smooth|Inverse Square Clamped"))?;
set_at(l, "lightOptions/falloff", t, KV::Enum(i));
}
if let Some(pos) = v3_p(p, "position") {
set_at(l, "transform/position", t, KV::Vec3(pos));
}
if let Some(poi) = v3_p(p, "poi").or_else(|| v3_p(p, "pointOfInterest")) {
set_at(l, "transform/poi", t, KV::Vec3(poi));
}
Ok(())
}
fn new_light(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let kind = match p.get("kind").or_else(|| p.get("type")) {
Some(_) => {
light_kind_p(p, "kind").or_else(|| light_kind_p(p, "type")).ok_or_else(|| bad("layer.newLight", "kind: Parallel|Spot|Point|Ambient|Environment"))?
}
None => LightKind::Spot,
};
let name = str_p(p, "name").unwrap_or("Light 1").to_string();
let t = time_p(s, p, Some(&comp));
// Only the Advanced 3D renderer lights with Environment lights, so adding one switches a
// Classic 3D comp to it, like After Effects (inside the adding edit: one undo step).
let env = kind == LightKind::Environment;
let (id, switched) = s.edit("New Light", None, |proj, st| {
let mut l = build::layer(proj, &comp, &name, LayerSource::Light { kind }, (comp.width, comp.height), None);
apply_light(&mut l, p, t, "layer.newLight")?;
let id = insert_layer(proj, st, cid, l)?;
Ok((id, if env { use_advanced_3d(proj, cid)? } else { false }))
})?;
report_switch(s, cid, switched, "which Environment lights need to light the scene");
Ok(json!({"layer": id.0, "advanced3d": env}))
}
fn light_settings(s: &mut Session, p: &Value) -> Result<Value> {
let (cid, lid) = target(s, p, "layer.lightSettings", false)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let t = time_p(s, p, Some(&comp));
let name = str_p(p, "name").map(str::to_string);
let kind = match p.get("kind").or_else(|| p.get("type")) {
Some(_) => Some(
light_kind_p(p, "kind")
.or_else(|| light_kind_p(p, "type"))
.ok_or_else(|| bad("layer.lightSettings", "kind: Parallel|Spot|Point|Ambient|Environment"))?,
),
None => None,
};
let switched = s.edit("Light Settings", None, |proj, _| {
let old = proj.comp(cid).and_then(|c| c.layer(lid)).cloned().ok_or(EngineError::NoComp)?;
let mut l = old.clone();
if let Some(k) = kind
&& old.source != (LayerSource::Light { kind: k })
{
// Light Type change: rebuild the light's groups, carrying over shared values.
let fresh = build::layer(proj, &comp, &old.name, LayerSource::Light { kind: k }, (comp.width, comp.height), None);
l.source = fresh.source.clone();
l.auto_orient = fresh.auto_orient;
l.props = fresh.props;
for path in [
"transform/position",
"transform/poi",
"transform/orientation",
"transform/rotationX",
"transform/rotationY",
"transform/rotation",
"lightOptions/intensity",
"lightOptions/color",
"lightOptions/coneAngle",
"lightOptions/coneFeather",
"lightOptions/falloff",
"lightOptions/radius",
"lightOptions/falloffDistance",
"lightOptions/castsShadows",
"lightOptions/shadowDarkness",
"lightOptions/shadowDiffusion",
] {
if let (Some(src), Some(dst)) = (old.props.prop(path), l.props.prop_mut(path)) {
dst.value = src.value.clone();
dst.keys = src.keys.clone();
dst.expr = src.expr.clone();
}
}
}
if let Some(n) = &name {
l.name = n.clone();
}
apply_light(&mut l, p, t, "layer.lightSettings")?;
// A light that becomes an Environment light switches a Classic 3D comp to Advanced 3D,
// like adding one does; editing one that already is leaves the renderer to the user.
let was_env = matches!(old.source, LayerSource::Light { kind: LightKind::Environment });
let is_env = matches!(l.source, LayerSource::Light { kind: LightKind::Environment });
*layer_mut(proj, cid, lid)? = l;
Ok(if !was_env && is_env { use_advanced_3d(proj, cid)? } else { false })
})?;
report_switch(s, cid, switched, "which Environment lights need to light the scene");
Ok(Value::Null)
}
// ---------------------------------------------------------------- 3D views
fn views(s: &mut Session, cid: ItemId) -> &mut Views3D {
s.state.views3d.entry(cid).or_default()
}
fn view_p(p: &Value, cmd: &str) -> Result<View3D> {
let v = str_p(p, "view").ok_or_else(|| bad(cmd, "missing `view` (activeCamera|default|front|left|top|back|right|bottom|custom1|custom2|custom3)"))?;
View3D::from_id(v).ok_or_else(|| bad(cmd, format!("unknown view `{v}`")))
}
fn switch_view(s: &mut Session, cid: ItemId, v: View3D) -> Value {
let vs = views(s, cid);
if vs.current != v {
vs.last = vs.current;
vs.current = v;
}
json!({"view": v.id()})
}
fn set_3d_view(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let v = view_p(p, "view.set3DView")?;
Ok(switch_view(s, cid, v))
}
/// The view of one pane of the View Layout: pane 0 is the main view (the same as Switch 3D View),
/// panes 1 to 3 are the extra views of a 2- or 4-view layout. UI state, not part of the project.
fn set_pane_view(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let v = view_p(p, "view.setPaneView")?;
let pane = p.get("pane").and_then(Value::as_u64).filter(|n| *n <= 3).ok_or_else(|| bad("view.setPaneView", "pane: 0 (main view) to 3"))? as usize;
if pane == 0 {
switch_view(s, cid, v);
} else {
views(s, cid).set_pane(pane - 1, v);
}
let vs = views(s, cid);
Ok(json!({"pane": pane, "view": v.id(), "views": [vs.current.id(), vs.pane(0).id(), vs.pane(1).id(), vs.pane(2).id()]}))
}
macro_rules! view_cmd {
($f:ident, $v:expr) => {
fn $f(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
Ok(switch_view(s, cid, $v))
}
};
}
view_cmd!(view_active, View3D::ActiveCamera);
view_cmd!(view_front, View3D::Front);
view_cmd!(view_left, View3D::Left);
view_cmd!(view_top, View3D::Top);
view_cmd!(view_back, View3D::Back);
view_cmd!(view_right, View3D::Right);
view_cmd!(view_bottom, View3D::Bottom);
view_cmd!(view_custom1, View3D::Custom1);
view_cmd!(view_custom2, View3D::Custom2);
view_cmd!(view_custom3, View3D::Custom3);
view_cmd!(view_default, View3D::Default);
fn last_view(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let last = views(s, cid).last;
Ok(switch_view(s, cid, last))
}
fn reset_view(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let cur = views(s, cid).current;
if cur != View3D::ActiveCamera {
views(s, cid).cams.remove(&cur);
return Ok(json!({"view": cur.id()}));
}
// Active camera: back to the default framing (50 mm-style distance, looking at the centre).
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let t = s.state.times.get(&cid).copied().unwrap_or(Tick::ZERO);
let cam = comp.active_camera(t).map(|l| l.id).ok_or_else(|| bad("view.reset3DView", "the comp has no camera layer"))?;
let (w, h) = (comp.width as f64, comp.height as f64);
s.edit("Reset 3D View", None, |proj, _| {
let l = layer_mut(proj, cid, cam)?;
let zoom = get_at(l, "cameraOptions/zoom", t).map(|v| v.as_f64()).unwrap_or(effectcraft_geom::default_camera_zoom(w));
set_at(l, "transform/position", t, KV::Vec3([w / 2.0, h / 2.0, -zoom]));
set_at(l, "transform/poi", t, KV::Vec3([w / 2.0, h / 2.0, 0.0]));
set_at(l, "transform/orientation", t, KV::Vec3([0.0; 3]));
Ok(())
})?;
Ok(json!({"view": "activeCamera"}))
}
fn set_view_camera(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let v = view_p(p, "view.set3DViewCamera")?;
if v == View3D::ActiveCamera {
return Err(bad("view.set3DViewCamera", "edit the camera layer for the active camera view"));
}
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?;
let (w, h) = (comp.width as f64, comp.height as f64);
let vs = views(s, cid);
let mut c = vs.cam(v, w, h);
if let Some(e) = v3_p(p, "eye") {
c.eye = e;
}
if let Some(e) = v3_p(p, "poi") {
c.poi = e;
}
if let Some(z) = f_p(p, "zoom") {
c.zoom = z.max(1e-3);
}
vs.cams.insert(v, c);
Ok(json!({"view": v.id()}))
}
fn get_3d(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?;
let (w, h) = (comp.width as f64, comp.height as f64);
let vs = s.state.views3d.get(&cid).cloned().unwrap_or_default();
let t = s.state.times.get(&cid).copied().unwrap_or(Tick::ZERO);
let ctx = EvalCtx {
project: &s.project,
comp_id: cid,
comp,
time: t,
expr: s.expr.as_deref(),
footage: None,
property_overrides: &[],
media_overrides: &[],
reads: None,
};
let cam = vs.override_camera(w, h).unwrap_or_else(|| camera::active_camera(&ctx));
let f = cam.forward();
let lights: Vec<Value> = comp
.layers
.iter()
.filter_map(|l| match l.source {
LayerSource::Light { kind } => Some(json!({"id": l.id.0, "name": l.name, "kind": kind.label()})),
_ => None,
})
.collect();
let active = comp.active_camera(t).map(|l| json!({"id": l.id.0, "name": l.name, "twoNode": camera::is_two_node(l)}));
Ok(json!({
"view": vs.current.id(),
"label": vs.current.label(),
"views": View3D::ALL.iter().map(|v| v.id()).collect::<Vec<_>>(),
"camera": {"eye": [cam.eye.x, cam.eye.y, cam.eye.z], "forward": [f.x, f.y, f.z], "zoom": cam.zoom, "ortho": cam.ortho},
"activeCameraLayer": active,
"lights": lights,
}))
}
// ---------------------------------------------------------------- camera tools
enum ToolOp {
Orbit(f64, f64),
Pan(f64, f64),
Dolly(f64),
}
fn camera_tool(s: &mut Session, p: &Value, op: ToolOp, cmd: &str, label: &str) -> Result<Value> {
let cid = comp_id(s, p)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let (w, h) = (comp.width as f64, comp.height as f64);
let cur = s.state.views3d.get(&cid).map(|v| v.current).unwrap_or_default();
let apply = |r: &mut Rig, layer: bool| match op {
ToolOp::Orbit(yaw, pitch) => r.orbit(yaw, pitch),
ToolOp::Pan(dx, dy) => r.pan(dx, dy),
ToolOp::Dolly(a) => r.dolly(a, layer),
};
if cur != View3D::ActiveCamera {
let vs = views(s, cid);
let vc = vs.cam(cur, w, h);
let mut r = Rig::from_view(&vc);
apply(&mut r, false);
let nc = ViewCam { eye: camera::arr(r.eye), poi: camera::arr(r.poi), zoom: r.zoom, ..vc };
vs.cams.insert(cur, nc);
return Ok(json!({"view": cur.id(), "eye": nc.eye, "poi": nc.poi, "zoom": nc.zoom}));
}
let t = s.state.times.get(&cid).copied().unwrap_or(Tick::ZERO);
let cam = match p.get("layer") {
Some(v) => super::resolve_layer(&comp, v).filter(|id| comp.layer(*id).is_some_and(|l| l.is_camera())),
None => comp.active_camera(t).map(|l| l.id),
}
.ok_or_else(|| bad(cmd, "the comp has no active camera layer (Layer ▸ New ▸ Camera), or switch to a custom 3D view"))?;
let merge = merge_p(p).map(str::to_string);
let r = s.edit(label, merge.as_deref(), |proj, _| {
let l = layer_mut(proj, cid, cam)?;
let pos = Vec3::from(get_at(l, "transform/position", t).map(|v| v.as_vec3()).unwrap_or([w / 2.0, h / 2.0, -1000.0]));
let zoom = get_at(l, "cameraOptions/zoom", t).map(|v| v.as_f64()).unwrap_or(1000.0);
let two = camera::is_two_node(l);
let o = get_at(l, "transform/orientation", t).map(|v| v.as_vec3()).unwrap_or([0.0; 3]);
let rx = get_at(l, "transform/rotationX", t).map(|v| v.as_f64()).unwrap_or(0.0);
let ry = get_at(l, "transform/rotationY", t).map(|v| v.as_f64()).unwrap_or(0.0);
let poi = if two {
Vec3::from(get_at(l, "transform/poi", t).map(|v| v.as_vec3()).unwrap_or([w / 2.0, h / 2.0, 0.0]))
} else {
let fwd = (Mat4::orientation(Vec3::from(o)) * Mat4::rotate_y(ry) * Mat4::rotate_x(rx)).apply_vec(vec3(0.0, 0.0, 1.0));
pos + fwd * zoom
};
let mut rig = Rig { eye: pos, poi, zoom, ortho: false };
apply(&mut rig, true);
set_at(l, "transform/position", t, KV::Vec3(camera::arr(rig.eye)));
if two {
set_at(l, "transform/poi", t, KV::Vec3(camera::arr(rig.poi)));
} else {
set_at(l, "transform/orientation", t, KV::Vec3(orientation_for(rig.poi - rig.eye)));
set_at(l, "transform/rotationX", t, KV::Scalar(0.0));
set_at(l, "transform/rotationY", t, KV::Scalar(0.0));
}
Ok(json!({"layer": cam.0, "position": camera::arr(rig.eye), "poi": camera::arr(rig.poi)}))
})?;
Ok(r)
}
fn orbit(s: &mut Session, p: &Value) -> Result<Value> {
camera_tool(
s,
p,
ToolOp::Orbit(f_p(p, "yaw").or_else(|| f_p(p, "dx")).unwrap_or(0.0), f_p(p, "pitch").or_else(|| f_p(p, "dy")).unwrap_or(0.0)),
"camera.orbit",
"Orbit Camera",
)
}
fn pan(s: &mut Session, p: &Value) -> Result<Value> {
camera_tool(s, p, ToolOp::Pan(f_p(p, "dx").unwrap_or(0.0), f_p(p, "dy").unwrap_or(0.0)), "camera.pan", "Pan Camera")
}
fn dolly(s: &mut Session, p: &Value) -> Result<Value> {
camera_tool(s, p, ToolOp::Dolly(f_p(p, "amount").or_else(|| f_p(p, "dz")).unwrap_or(0.0)), "camera.dolly", "Dolly Camera")
}
/// Layer ▸ Transform ▸ Auto-Orient: off | alongPath | towardsCamera (3D layers) |
/// towardsPointOfInterest (cameras and spot/parallel lights).
fn auto_orient(s: &mut Session, p: &Value) -> Result<Value> {
let (cid, ids) = super::layers_p(s, p)?;
if ids.is_empty() {
return Err(bad("layer.autoOrient", "select a layer first"));
}
let raw = str_p(p, "mode").ok_or_else(|| bad("layer.autoOrient", "missing `mode` (off|alongPath|towardsCamera|towardsPointOfInterest)"))?;
let k = raw.to_ascii_lowercase().replace([' ', '-', '_'], "");
let mode = match k.as_str() {
"off" => AutoOrient::Off,
"alongpath" | "orientalongpath" => AutoOrient::AlongPath,
"towardscamera" | "orienttowardscamera" => AutoOrient::TowardsCamera,
"towardspointofinterest" | "towardspoi" | "orienttowardspointofinterest" => AutoOrient::TowardsPointOfInterest,
_ => return Err(bad("layer.autoOrient", format!("unknown mode `{raw}`"))),
};
s.edit("Auto-Orient", None, |proj, _| {
let comp = proj.comp_mut(cid).ok_or(EngineError::NoComp)?;
for l in comp.layers.iter_mut_where(|l| ids.contains(&l.id)) {
let rig = l.is_camera() || l.is_light();
let ok = match mode {
AutoOrient::Off | AutoOrient::AlongPath => true,
AutoOrient::TowardsCamera => !rig,
AutoOrient::TowardsPointOfInterest => rig && l.transform().is_some_and(|t| t.get("poi").is_some()),
};
if !ok {
return Err(bad("layer.autoOrient", format!("`{raw}` is not available for layer `{}`", l.name)));
}
l.auto_orient = mode;
}
Ok(())
})?;
Ok(Value::Null)
}
// ---------------------------------------------------------------- look at / camera from view
/// World-space points spanning the layers' content at comp time `t` (content-box corners
/// through each layer's world matrix; cameras and lights contribute their position).
fn layer_points(s: &Session, cid: ItemId, ids: &[LayerId], t: Tick) -> Vec<Vec3> {
let Some(comp) = s.project.comp(cid) else { return vec![] };
let ctx = EvalCtx {
project: &s.project,
comp_id: cid,
comp,
time: t,
expr: s.expr.as_deref(),
footage: None,
property_overrides: &[],
media_overrides: &[],
reads: None,
};
let mut out = vec![];
for l in comp.layers.iter().filter(|l| ids.contains(&l.id)) {
let m = ctx.world_matrix(l);
match effectcraft_render::content_bounds(&ctx, l) {
Some([x0, y0, x1, y1]) => {
for (x, y) in [(x0, y0), (x1, y0), (x1, y1), (x0, y1)] {
out.push(m.apply(vec3(x, y, 0.0)));
}
}
None => out.push(m.apply(Vec3::ZERO)),
}
}
out
}
fn look_at(s: &mut Session, p: &Value, all: bool) -> Result<Value> {
let cmd = if all { "view.lookAtAll" } else { "view.lookAtSelected" };
let cid = comp_id(s, p)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let t = s.state.times.get(&cid).copied().unwrap_or(Tick::ZERO);
let ids: Vec<LayerId> = if all {
comp.layers.iter().filter(|l| l.is_active_at(t) && !l.is_camera() && !l.is_light()).map(|l| l.id).collect()
} else {
let (_, sel) = super::layers_p(s, p)?;
sel
};
if ids.is_empty() {
return Err(bad(cmd, if all { "the composition has no visible layers" } else { "select layers first" }));
}
let pts = layer_points(s, cid, &ids, t);
let (mut lo, mut hi) = (vec3(f64::MAX, f64::MAX, f64::MAX), vec3(f64::MIN, f64::MIN, f64::MIN));
for q in &pts {
lo = vec3(lo.x.min(q.x), lo.y.min(q.y), lo.z.min(q.z));
hi = vec3(hi.x.max(q.x), hi.y.max(q.y), hi.z.max(q.z));
}
let c = (lo + hi) * 0.5;
let r = ((hi - lo).length() * 0.5).max(1.0);
let (w, h) = (comp.width as f64, comp.height as f64);
let fit = w.min(h);
let cur = s.state.views3d.get(&cid).map(|v| v.current).unwrap_or_default();
if !comp.has_3d() {
// 2D: frame the layers in the viewer (zoom and pan to their comp-space bounds).
let rect = [lo.x, lo.y, hi.x, hi.y];
super::frontend(s, "view.lookAt", &json!({"rect": rect}))?;
return Ok(json!({"rect": rect}));
}
if cur != View3D::ActiveCamera {
let vs = views(s, cid);
let mut vc = vs.cam(cur, w, h);
let fwd = (Vec3::from(vc.poi) - Vec3::from(vc.eye)).normalize();
if vc.ortho {
vc.zoom = fit / (2.2 * r);
vc.eye = camera::arr(c - fwd * 10_000.0);
} else {
vc.eye = camera::arr(c - fwd * (vc.zoom * r * 2.2 / fit));
}
vc.poi = camera::arr(c);
vs.cams.insert(cur, vc);
return Ok(json!({"view": cur.id(), "eye": vc.eye, "poi": vc.poi, "zoom": vc.zoom}));
}
let cam = comp.active_camera(t).map(|l| l.id).ok_or_else(|| bad(cmd, "the comp has no camera layer: switch to a 3D view (View ▸ Switch 3D View)"))?;
s.edit(if all { "Look at All Layers" } else { "Look at Selected Layers" }, None, |proj, _| {
let l = layer_mut(proj, cid, cam)?;
let lt = l.layer_time(t);
let pos = Vec3::from(get_at(l, "transform/position", lt).map(|v| v.as_vec3()).unwrap_or([w / 2.0, h / 2.0, -1000.0]));
let zoom = get_at(l, "cameraOptions/zoom", lt).map(|v| v.as_f64()).unwrap_or(1000.0);
let two = camera::is_two_node(l);
let fwd = if two {
let poi = Vec3::from(get_at(l, "transform/poi", lt).map(|v| v.as_vec3()).unwrap_or([w / 2.0, h / 2.0, 0.0]));
(poi - pos).normalize()
} else {
let o = get_at(l, "transform/orientation", lt).map(|v| v.as_vec3()).unwrap_or([0.0; 3]);
Mat4::orientation(Vec3::from(o)).apply_vec(vec3(0.0, 0.0, 1.0)).normalize()
};
let eye = c - fwd * (zoom * r * 2.2 / fit);
set_at(l, "transform/position", lt, KV::Vec3(camera::arr(eye)));
if two {
set_at(l, "transform/poi", lt, KV::Vec3(camera::arr(c)));
}
Ok(json!({"layer": cam.0, "position": camera::arr(eye), "poi": camera::arr(c)}))
})
}
/// Layer ▸ Camera ▸ Create Camera from 3D View: a two-node camera matching the current 3D view.
fn camera_from_view(s: &mut Session, p: &Value) -> Result<Value> {
let cid = comp_id(s, p)?;
let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone();
let (w, h) = (comp.width as f64, comp.height as f64);
let cur = s.state.views3d.get(&cid).map(|v| v.current).unwrap_or_default();
if cur == View3D::ActiveCamera {
return Err(bad("camera.fromView", "switch to a 3D view first (View ▸ Switch 3D View)"));
}
let vc = s.state.views3d.get(&cid).cloned().unwrap_or_default().cam(cur, w, h);
let poi = Vec3::from(vc.poi);
let fwd = (poi - Vec3::from(vc.eye)).normalize();
let zoom = if vc.ortho { effectcraft_geom::default_camera_zoom(w) } else { vc.zoom };
let eye = if vc.ortho { poi - fwd * zoom } else { Vec3::from(vc.eye) };
let t = s.state.times.get(&cid).copied().unwrap_or(Tick::ZERO);
let name = comp.unique_layer_name("Camera 1");
let params = json!({"position": camera::arr(eye), "poi": camera::arr(poi), "zoom": zoom});
let id = s.edit("Create Camera from 3D View", None, |proj, st| {
let mut l = build::layer(proj, &comp, &name, LayerSource::Camera, (comp.width, comp.height), None);
apply_camera(&mut l, &comp, &params, t, "camera.fromView")?;
insert_layer(proj, st, cid, l)
})?;
switch_view(s, cid, View3D::ActiveCamera);
Ok(json!({"layer": id.0, "from": cur.id()}))
}
pub fn specs() -> Vec<CommandSpec> {
vec![
cmd!(
"layer.autoOrient",
"Auto-Orient...",
["Layer", "Transform"],
Some("Cmd+Alt+O"),
"{mode: off|alongPath|towardsCamera|towardsPointOfInterest, layers?}",
super::has_layers,
auto_orient
),
cmd!(
"layer.newLight",
"Light...",
["Layer", "New"],
Some("Cmd+Alt+Shift+L"),
"{kind?: Parallel|Spot|Point|Ambient|Environment (default Spot; Environment lights and reflects from an equirectangular image layer: prop.set its lightOptions/source to that layer's id, or leave it empty for the comp's Environment Layer or a flat default environment of its colour and intensity, see layer.environment; an Environment light switches a Classic 3D comp to Advanced 3D), name?, color?, intensity?, coneAngle?, coneFeather?, falloff?: None|Smooth|Inverse Square Clamped, radius?, falloffDistance?, castsShadows?, shadowDarkness?, shadowDiffusion?, position? [x,y,z], poi? [x,y,z]}",
has_comp,
new_light
),
cmd!(
"layer.newCamera",
"Camera...",
["Layer", "New"],
Some("Cmd+Alt+Shift+C"),
"{name?, type?: oneNode|twoNode (default twoNode), preset?: 15mm|20mm|24mm|28mm|35mm|50mm|80mm|135mm|200mm, zoom?, focalLength? mm, angleOfView? deg, dof?, focusDistance?, aperture?, fStop?, blurLevel?, lockToZoom?, position? [x,y,z], poi? [x,y,z]}",
has_comp,
new_camera
),
cmd!(
"layer.cameraSettings",
"Camera Settings...",
["Layer", "Camera"],
None,
"{layer?, name?, type?, preset?, zoom?, focalLength?, angleOfView?, dof?, focusDistance?, aperture?, fStop?, blurLevel?, position?, poi?}",
has_comp,
camera_settings
),
cmd!(
"layer.lightSettings",
"Light Settings...",
[],
None,
"{layer?, name?, kind?: Parallel|Spot|Point|Ambient|Environment (changing to Environment switches a Classic 3D comp to Advanced 3D), color?, intensity?, coneAngle?, coneFeather?, falloff?, radius?, falloffDistance?, castsShadows?, shadowDarkness?, shadowDiffusion?, position?, poi?}",
has_comp,
light_settings
),
cmd!(
"view.set3DView",
"Switch 3D View",
[],
None,
"{view: activeCamera|default|front|left|top|back|right|bottom|custom1|custom2|custom3, comp?}",
has_comp,
set_3d_view
),
cmd!(
"view.setPaneView",
"Set View of Pane",
[],
None,
"{pane: 0 (main) | 1 | 2 | 3, view: activeCamera|default|front|left|top|back|right|bottom|custom1|custom2|custom3, comp?}",
has_comp,
set_pane_view
),
cmd!("view.3d.activeCamera", "Active Camera", ["View", "Switch 3D View"], Some("F12"), "{comp?}", has_comp, view_active),
cmd!("view.3d.default", "Default", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_default),
cmd!("view.3d.front", "Front", ["View", "Switch 3D View"], Some("F10"), "{comp?}", has_comp, view_front),
cmd!("view.3d.left", "Left", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_left),
cmd!("view.3d.top", "Top", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_top),
cmd!("view.3d.back", "Back", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_back),
cmd!("view.3d.right", "Right", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_right),
cmd!("view.3d.bottom", "Bottom", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_bottom),
cmd!("view.3d.custom1", "Custom View 1", ["View", "Switch 3D View"], Some("F11"), "{comp?}", has_comp, view_custom1),
cmd!("view.3d.custom2", "Custom View 2", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_custom2),
cmd!("view.3d.custom3", "Custom View 3", ["View", "Switch 3D View"], None, "{comp?}", has_comp, view_custom3),
cmd!("view.3d.last", "Switch to Last 3D View", ["View"], None, "{comp?}", has_comp, last_view),
cmd!("view.lookAtSelected", "Look at Selected Layers", ["View"], Some("Cmd+Alt+Shift+\\"), "{comp?, layers?}", super::has_layers, |s, p| look_at(
s, p, false
)),
cmd!("view.lookAtAll", "Look at All Layers", ["View"], None, "{comp?}", has_comp, |s, p| look_at(s, p, true)),
cmd!("camera.fromView", "Create Camera from 3D View", ["Layer", "Camera"], None, "{comp?}", has_comp, camera_from_view),
cmd!("view.reset3DView", "Reset 3D View", ["View"], None, "{comp?}", has_comp, reset_view),
cmd!("view.set3DViewCamera", "Set 3D View Camera", [], None, "{view, eye? [x,y,z], poi? [x,y,z], zoom?}", has_comp, set_view_camera),
cmd!(
"camera.orbit",
"Orbit Camera",
[],
None,
"{yaw|dx deg, pitch|dy deg, layer?, merge?} — current 3D view (camera layer in Active Camera)",
has_comp,
orbit
),
cmd!("camera.pan", "Pan Camera", [], None, "{dx, dy (comp px), layer?, merge?}", has_comp, pan),
cmd!("camera.dolly", "Dolly Camera", [], None, "{amount (px, + = forward), layer?, merge?}", has_comp, dolly),
query!("view.get3D", "3D View State", "{comp?} → current 3D view, view camera, active camera layer, lights", get_3d),
]
}