Skip to content

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

feat: add CameraAngle node with camera_info and shot prompt outputs (#16251)

Terry Jia7a5dad695fe1
diff --git a/comfy_extras/nodes_camera_angle.py b/comfy_extras/nodes_camera_angle.py
new file mode 100644
index 000000000..654939beb
--- /dev/null
+++ b/comfy_extras/nodes_camera_angle.py
@@ -0,0 +1,123 @@
+import math
+
+from typing_extensions import override
+
+from comfy_api.latest import ComfyExtension, IO
+
+# Scene layout shared with the frontend preview (src/extensions/core/cameraAngle/types.ts):
+# a unit subject cube sits at the world origin, where downstream 3D nodes centre their models.
+SUBJECT_CENTER = (0.0, 0.0, 0.0)
+CAMERA_FOV = 35.0
+SUBJECT_DISTANCE = 6.0
+MIN_ZOOM_FACTOR = 1.0
+MAX_ZOOM_FACTOR = 1.875
+
+HORIZONTAL_MIN, HORIZONTAL_MAX = 0, 360
+VERTICAL_MIN, VERTICAL_MAX = -30, 60
+ZOOM_MIN, ZOOM_MAX = 0.0, 10.0
+
+HORIZONTAL_TERMS = (
+ "front view",
+ "front-right quarter view",
+ "right side view",
+ "back-right quarter view",
+ "back view",
+ "back-left quarter view",
+ "left side view",
+ "front-left quarter view",
+)
+VERTICAL_TERMS = ((-15, "low-angle shot"), (15, "eye-level shot"), (45, "elevated shot"), (None, "high-angle shot"))
+DISTANCE_TERMS = ((2, "wide shot"), (6, "medium shot"), (None, "close-up"))
+
+
+def _bucket(value: float, terms) -> str:
+ for upper, term in terms:
+ if upper is None or value < upper:
+ return term
+ return terms[-1][1]
+
+
+def horizontal_term(angle: float) -> str:
+ sector = int(((angle % 360) + 22.5) // 45) % len(HORIZONTAL_TERMS)
+ return HORIZONTAL_TERMS[sector]
+
+
+def vertical_term(angle: float) -> str:
+ return _bucket(angle, VERTICAL_TERMS)
+
+
+def distance_term(zoom: float) -> str:
+ return _bucket(zoom, DISTANCE_TERMS)
+
+
+def describe_camera_angle(horizontal_angle: float, vertical_angle: float, zoom: float) -> str:
+ return f"{horizontal_term(horizontal_angle)} {vertical_term(vertical_angle)} {distance_term(zoom)}"
+
+
+def zoom_to_factor(zoom: float) -> float:
+ return MIN_ZOOM_FACTOR + (MAX_ZOOM_FACTOR - MIN_ZOOM_FACTOR) * (zoom / ZOOM_MAX)
+
+
+def build_camera_info(horizontal_angle: float, vertical_angle: float, zoom: float) -> dict:
+ yaw, pitch = math.radians(horizontal_angle), math.radians(vertical_angle)
+ cx, cy, cz = SUBJECT_CENTER
+ return {
+ "position": {
+ "x": cx + SUBJECT_DISTANCE * math.cos(pitch) * math.sin(yaw),
+ "y": cy + SUBJECT_DISTANCE * math.sin(pitch),
+ "z": cz + SUBJECT_DISTANCE * math.cos(pitch) * math.cos(yaw),
+ },
+ "target": {"x": cx, "y": cy, "z": cz},
+ "zoom": zoom_to_factor(zoom),
+ "cameraType": "perspective",
+ "fov": CAMERA_FOV,
+ }
+
+
+class CameraAngle(IO.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="CameraAngle",
+ display_name="Compose Camera Angle Prompt",
+ search_aliases=["multi angle", "camera view", "orbit camera", "shot angle", "camera prompt"],
+ category="3d",
+ description="Pick a camera angle around a subject with a 3D preview. Outputs a camera_info "
+ "for 3D nodes and a plain-English shot description for prompts.",
+ inputs=[
+ IO.Int.Input("horizontal_angle", default=0, min=HORIZONTAL_MIN, max=HORIZONTAL_MAX, step=1,
+ tooltip="Azimuth around the subject in degrees. 0 is the front, 90 the right side, 180 the back."),
+ IO.Int.Input("vertical_angle", default=0, min=VERTICAL_MIN, max=VERTICAL_MAX, step=1,
+ tooltip="Elevation in degrees. Negative looks up from below, positive looks down from above."),
+ IO.Float.Input("zoom", default=5.0, min=ZOOM_MIN, max=ZOOM_MAX, step=0.1,
+ tooltip="Lens zoom on the subject: 0 is a wide shot, 10 a close-up. Carried into camera_info.zoom."),
+ IO.Image.Input("image", optional=True,
+ tooltip="Optional reference image shown on the front of the subject cube in the 3D preview."),
+ IO.String.Input("view", default="", optional=True, socketless=True,
+ extra_dict={"widgetType": "CAMERA_ANGLE_VIEW"}),
+ ],
+ outputs=[
+ IO.Load3DCamera.Output(display_name="camera_info"),
+ IO.String.Output(display_name="prompt"),
+ ],
+ )
+
+ @classmethod
+ def execute(cls, horizontal_angle, vertical_angle, zoom, image=None, view=None) -> IO.NodeOutput:
+ horizontal_angle = max(HORIZONTAL_MIN, min(HORIZONTAL_MAX, int(horizontal_angle)))
+ vertical_angle = max(VERTICAL_MIN, min(VERTICAL_MAX, int(vertical_angle)))
+ zoom = max(ZOOM_MIN, min(ZOOM_MAX, float(zoom)))
+ return IO.NodeOutput(
+ build_camera_info(horizontal_angle, vertical_angle, zoom),
+ describe_camera_angle(horizontal_angle, vertical_angle, zoom),
+ )
+
+
+class CameraAngleExtension(ComfyExtension):
+ @override
+ async def get_node_list(self) -> list[type[IO.ComfyNode]]:
+ return [CameraAngle]
+
+
+async def comfy_entrypoint() -> CameraAngleExtension:
+ return CameraAngleExtension()
diff --git a/nodes.py b/nodes.py
index 813095f8c..49de5a35b 100644
--- a/nodes.py
+++ b/nodes.py
@@ -2545,6 +2545,7 @@ async def init_builtin_extra_nodes():
"nodes_mediapipe.py",
"nodes_gaussian_splat.py",
"nodes_camera.py",
+ "nodes_camera_angle.py",
"nodes_triposplat.py",
"nodes_depth_anything_3.py",
"nodes_seed.py",
diff --git a/tests-unit/comfy_extras_test/camera_angle_test.py b/tests-unit/comfy_extras_test/camera_angle_test.py
new file mode 100644
index 000000000..6adb046f0
--- /dev/null
+++ b/tests-unit/comfy_extras_test/camera_angle_test.py
@@ -0,0 +1,78 @@
+import math
+
+import pytest
+
+from comfy_extras.nodes_camera_angle import (
+ CameraAngle,
+ MAX_ZOOM_FACTOR,
+ MIN_ZOOM_FACTOR,
+ SUBJECT_CENTER,
+ SUBJECT_DISTANCE,
+ build_camera_info,
+ describe_camera_angle,
+ horizontal_term,
+ zoom_to_factor,
+)
+
+
+ "angle, term",
+ [
+ (0, "front view"),
+ (22, "front view"),
+ (23, "front-right quarter view"),
+ (90, "right side view"),
+ (135, "back-right quarter view"),
+ (180, "back view"),
+ (225, "back-left quarter view"),
+ (270, "left side view"),
+ (315, "front-left quarter view"),
+ (338, "front view"),
+ (360, "front view"),
+ ],
+)
+def test_horizontal_term_buckets_by_45_degree_sector(angle, term):
+ assert horizontal_term(angle) == term
+
+
+ "vertical, zoom, expected",
+ [
+ (-30, 0, "front view low-angle shot wide shot"),
+ (-15, 2, "front view eye-level shot medium shot"),
+ (15, 6, "front view elevated shot close-up"),
+ (45, 10, "front view high-angle shot close-up"),
+ ],
+)
+def test_describe_camera_angle_joins_vertical_and_distance_terms(vertical, zoom, expected):
+ assert describe_camera_angle(0, vertical, zoom) == expected
+
+
+def test_zoom_maps_linearly_onto_the_lens_zoom_factor():
+ assert zoom_to_factor(0) == MIN_ZOOM_FACTOR
+ assert zoom_to_factor(10) == MAX_ZOOM_FACTOR
+ assert zoom_to_factor(5) == pytest.approx((MIN_ZOOM_FACTOR + MAX_ZOOM_FACTOR) / 2)
+
+
+def test_front_view_places_camera_on_positive_z_looking_at_subject_centre():
+ info = build_camera_info(0, 0, 0)
+ assert info["position"] == pytest.approx({"x": 0.0, "y": 0.0, "z": SUBJECT_DISTANCE})
+ assert info["target"] == {"x": 0.0, "y": 0.0, "z": 0.0}
+ assert info["cameraType"] == "perspective"
+ assert info["zoom"] == 1.0
+
+
+def test_orbit_position_follows_yaw_and_pitch_while_zoom_only_changes_the_lens():
+ info = build_camera_info(90, 30, 10)
+ position = info["position"]
+ assert position["x"] == pytest.approx(SUBJECT_DISTANCE * math.cos(math.radians(30)))
+ assert position["y"] == pytest.approx(SUBJECT_CENTER[1] + SUBJECT_DISTANCE * math.sin(math.radians(30)))
+ assert position["z"] == pytest.approx(0.0, abs=1e-9)
+ assert info["zoom"] == MAX_ZOOM_FACTOR
+
+
+def test_execute_clamps_inputs_and_returns_camera_info_and_prompt():
+ result = CameraAngle.execute(horizontal_angle=400, vertical_angle=-90, zoom=99)
+ camera_info, prompt = result.args
+ assert prompt == "front view low-angle shot close-up"
+ assert camera_info == build_camera_info(360, -30, 10)