From 1f795218c00effcdcd03474dd77339988b25f214 Mon Sep 17 00:00:00 2001 From: Terry Jia Date: Thu, 10 Sep 2026 20:35:18 -0400 Subject: [PATCH 1/4] feat: add CameraAngle node with camera_info and shot prompt outputs --- comfy_extras/nodes_camera_angle.py | 123 ++++++++++++++++++ nodes.py | 1 + .../comfy_extras_test/camera_angle_test.py | 76 +++++++++++ 3 files changed, 200 insertions(+) create mode 100644 comfy_extras/nodes_camera_angle.py create mode 100644 tests-unit/comfy_extras_test/camera_angle_test.py diff --git a/comfy_extras/nodes_camera_angle.py b/comfy_extras/nodes_camera_angle.py new file mode 100644 index 00000000000..cd203610a00 --- /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 stands on the ground plane, so the camera orbits its centre. +SUBJECT_CENTER = (0.0, 0.5, 0.0) +CAMERA_FOV = 35.0 +MIN_DISTANCE = 3.2 +MAX_DISTANCE = 6.0 + +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_distance(zoom: float) -> float: + return MAX_DISTANCE - (MAX_DISTANCE - MIN_DISTANCE) * (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) + distance = zoom_to_distance(zoom) + cx, cy, cz = SUBJECT_CENTER + return { + "position": { + "x": cx + distance * math.cos(pitch) * math.sin(yaw), + "y": cy + distance * math.sin(pitch), + "z": cz + distance * math.cos(pitch) * math.cos(yaw), + }, + "target": {"x": cx, "y": cy, "z": cz}, + "zoom": 1.0, + "cameraType": "perspective", + "fov": CAMERA_FOV, + } + + +class CameraAngle(IO.ComfyNode): + @classmethod + def define_schema(cls): + return IO.Schema( + node_id="CameraAngle", + display_name="Camera Angle", + 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="How close the camera is: 0 is a wide shot, 10 a close-up."), + 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 813095f8c53..49de5a35bdc 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 00000000000..149a3374637 --- /dev/null +++ b/tests-unit/comfy_extras_test/camera_angle_test.py @@ -0,0 +1,76 @@ +import math + +import pytest + +from comfy_extras.nodes_camera_angle import ( + CameraAngle, + MAX_DISTANCE, + MIN_DISTANCE, + SUBJECT_CENTER, + build_camera_info, + describe_camera_angle, + horizontal_term, + zoom_to_distance, +) + + +@pytest.mark.parametrize( + "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 + + +@pytest.mark.parametrize( + "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_between_wide_and_close_distances(): + assert zoom_to_distance(0) == MAX_DISTANCE + assert zoom_to_distance(10) == MIN_DISTANCE + assert zoom_to_distance(5) == pytest.approx((MAX_DISTANCE + MIN_DISTANCE) / 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": SUBJECT_CENTER[1], "z": MAX_DISTANCE}) + assert info["target"] == {"x": 0.0, "y": SUBJECT_CENTER[1], "z": 0.0} + assert info["cameraType"] == "perspective" + assert info["zoom"] == 1.0 + + +def test_orbit_position_follows_yaw_and_pitch(): + info = build_camera_info(90, 30, 10) + position = info["position"] + assert position["x"] == pytest.approx(MIN_DISTANCE * math.cos(math.radians(30))) + assert position["y"] == pytest.approx(SUBJECT_CENTER[1] + MIN_DISTANCE * math.sin(math.radians(30))) + assert position["z"] == pytest.approx(0.0, abs=1e-9) + + +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) From 49b3703294d4bf06f4f8ca9aae0e7dfaaa381b13 Mon Sep 17 00:00:00 2001 From: Terry Jia Date: Sun, 13 Sep 2026 09:54:54 -0400 Subject: [PATCH 2/4] fix: carry CameraAngle zoom into camera_info.zoom --- comfy_extras/nodes_camera_angle.py | 20 ++++++++-------- .../comfy_extras_test/camera_angle_test.py | 24 ++++++++++--------- 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/comfy_extras/nodes_camera_angle.py b/comfy_extras/nodes_camera_angle.py index cd203610a00..139c5f12802 100644 --- a/comfy_extras/nodes_camera_angle.py +++ b/comfy_extras/nodes_camera_angle.py @@ -8,8 +8,9 @@ # a unit subject cube stands on the ground plane, so the camera orbits its centre. SUBJECT_CENTER = (0.0, 0.5, 0.0) CAMERA_FOV = 35.0 -MIN_DISTANCE = 3.2 -MAX_DISTANCE = 6.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 @@ -53,22 +54,21 @@ def describe_camera_angle(horizontal_angle: float, vertical_angle: float, zoom: return f"{horizontal_term(horizontal_angle)} {vertical_term(vertical_angle)} {distance_term(zoom)}" -def zoom_to_distance(zoom: float) -> float: - return MAX_DISTANCE - (MAX_DISTANCE - MIN_DISTANCE) * (zoom / ZOOM_MAX) +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) - distance = zoom_to_distance(zoom) cx, cy, cz = SUBJECT_CENTER return { "position": { - "x": cx + distance * math.cos(pitch) * math.sin(yaw), - "y": cy + distance * math.sin(pitch), - "z": cz + distance * math.cos(pitch) * math.cos(yaw), + "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": 1.0, + "zoom": zoom_to_factor(zoom), "cameraType": "perspective", "fov": CAMERA_FOV, } @@ -90,7 +90,7 @@ def define_schema(cls): 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="How close the camera is: 0 is a wide shot, 10 a close-up."), + 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, diff --git a/tests-unit/comfy_extras_test/camera_angle_test.py b/tests-unit/comfy_extras_test/camera_angle_test.py index 149a3374637..f017d38c9f3 100644 --- a/tests-unit/comfy_extras_test/camera_angle_test.py +++ b/tests-unit/comfy_extras_test/camera_angle_test.py @@ -4,13 +4,14 @@ from comfy_extras.nodes_camera_angle import ( CameraAngle, - MAX_DISTANCE, - MIN_DISTANCE, + MAX_ZOOM_FACTOR, + MIN_ZOOM_FACTOR, SUBJECT_CENTER, + SUBJECT_DISTANCE, build_camera_info, describe_camera_angle, horizontal_term, - zoom_to_distance, + zoom_to_factor, ) @@ -47,26 +48,27 @@ def test_describe_camera_angle_joins_vertical_and_distance_terms(vertical, zoom, assert describe_camera_angle(0, vertical, zoom) == expected -def test_zoom_maps_linearly_between_wide_and_close_distances(): - assert zoom_to_distance(0) == MAX_DISTANCE - assert zoom_to_distance(10) == MIN_DISTANCE - assert zoom_to_distance(5) == pytest.approx((MAX_DISTANCE + MIN_DISTANCE) / 2) +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": SUBJECT_CENTER[1], "z": MAX_DISTANCE}) + assert info["position"] == pytest.approx({"x": 0.0, "y": SUBJECT_CENTER[1], "z": SUBJECT_DISTANCE}) assert info["target"] == {"x": 0.0, "y": SUBJECT_CENTER[1], "z": 0.0} assert info["cameraType"] == "perspective" assert info["zoom"] == 1.0 -def test_orbit_position_follows_yaw_and_pitch(): +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(MIN_DISTANCE * math.cos(math.radians(30))) - assert position["y"] == pytest.approx(SUBJECT_CENTER[1] + MIN_DISTANCE * math.sin(math.radians(30))) + 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(): From 025c2e33239f69868feabeff37fbdc18611f7830 Mon Sep 17 00:00:00 2001 From: Terry Jia Date: Sun, 13 Sep 2026 20:57:56 -0400 Subject: [PATCH 3/4] fix: orbit CameraAngle around the world origin --- comfy_extras/nodes_camera_angle.py | 4 ++-- tests-unit/comfy_extras_test/camera_angle_test.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/comfy_extras/nodes_camera_angle.py b/comfy_extras/nodes_camera_angle.py index 139c5f12802..d396f9825c5 100644 --- a/comfy_extras/nodes_camera_angle.py +++ b/comfy_extras/nodes_camera_angle.py @@ -5,8 +5,8 @@ from comfy_api.latest import ComfyExtension, IO # Scene layout shared with the frontend preview (src/extensions/core/cameraAngle/types.ts): -# a unit subject cube stands on the ground plane, so the camera orbits its centre. -SUBJECT_CENTER = (0.0, 0.5, 0.0) +# 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 diff --git a/tests-unit/comfy_extras_test/camera_angle_test.py b/tests-unit/comfy_extras_test/camera_angle_test.py index f017d38c9f3..6adb046f0c2 100644 --- a/tests-unit/comfy_extras_test/camera_angle_test.py +++ b/tests-unit/comfy_extras_test/camera_angle_test.py @@ -56,8 +56,8 @@ def test_zoom_maps_linearly_onto_the_lens_zoom_factor(): 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": SUBJECT_CENTER[1], "z": SUBJECT_DISTANCE}) - assert info["target"] == {"x": 0.0, "y": SUBJECT_CENTER[1], "z": 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 From 3417e02aaa096b50c5acd0858c184ec335672f91 Mon Sep 17 00:00:00 2001 From: Terry Jia Date: Mon, 5 Oct 2026 23:27:53 -0400 Subject: [PATCH 4/4] fix: rename CameraAngle display name to Compose Camera Angle Prompt --- comfy_extras/nodes_camera_angle.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/comfy_extras/nodes_camera_angle.py b/comfy_extras/nodes_camera_angle.py index d396f9825c5..654939beb72 100644 --- a/comfy_extras/nodes_camera_angle.py +++ b/comfy_extras/nodes_camera_angle.py @@ -79,7 +79,7 @@ class CameraAngle(IO.ComfyNode): def define_schema(cls): return IO.Schema( node_id="CameraAngle", - display_name="Camera Angle", + 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 "