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.pynew file mode 100644index 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.pyindex 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.pynew file mode 100644index 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)