UsdLayerManager/openspec/changes/viewport-display-usd-data/specs/viewport-camera/spec.md

ADDED Requirements

Requirement: Camera supports orbit, pan, and zoom interaction

The system SHALL provide a turntable-style orbit camera controlled by mouse input within the Viewport panel. Left-drag orbits around a focal point, middle-drag or shift+left-drag pans, and scroll-wheel zooms.

Scenario: Orbit the camera

• WHEN the user holds the left mouse button and drags within the Viewport panel
• THEN the camera orbits around the focal point
• AND the view updates in real-time

Scenario: Pan the camera

• WHEN the user holds the middle mouse button (or shift+left button) and drags within the Viewport panel
• THEN the camera pans horizontally and vertically relative to the view plane
• AND the focal point moves with the camera

Scenario: Zoom the camera

• WHEN the user scrolls the mouse wheel within the Viewport panel
• THEN the camera moves closer to or farther from the focal point
• AND the zoom is proportional to the current distance from the focal point

Requirement: Camera computes view and projection matrices

The system SHALL compute a view matrix from the camera's eye position, focal point, and up vector, and a perspective projection matrix from the field of view, aspect ratio, and near/far clip planes.

Scenario: View matrix from camera parameters

• WHEN the camera parameters (eye, focal point, up) are set or updated
• THEN the system computes a lookAt view matrix

Scenario: Projection matrix matches viewport aspect ratio

• WHEN the FBO dimensions change
• THEN the projection matrix is recomputed with the updated aspect ratio

Requirement: Mouse input is captured only when the viewport is hovered

The system SHALL capture mouse input for camera control only when the ImGui Viewport window is hovered. Mouse events outside the viewport SHALL NOT affect the camera.

Scenario: Mouse input captured in viewport

• WHEN the mouse cursor is over the Viewport panel and the user interacts
• THEN the camera responds to the input

Scenario: Mouse input ignored outside viewport

• WHEN the mouse cursor is outside the Viewport panel
• THEN camera input is not processed

Requirement: Camera frames the scene automatically

The system SHALL compute a default camera position that frames the bounding box of the scene when a stage is first loaded.

Scenario: Camera frames scene on stage load

• WHEN a new USD stage is opened
• THEN the camera position and focal point are set so the entire scene bounding box is visible
• AND the camera distance is adjusted based on the scene size