Cinematic Camera Controls

The cinematic camera API exposes Unreal Engine’s physical camera model to UnrealCV clients. It applies a shared filmback, lens, focus, crop, near-clipping, and physical-exposure configuration to the capture sensors that belong to a camera.

Activation and compatibility

The cinematic camera path is disabled by default. While it is disabled, the camera retains the established UnrealCV field-of-view and capture behavior.

Reading cinematic camera state does not enable the feature. Any cinematic vset command other than explicitly disabling the feature enables the cinematic camera path for that camera. Use the following command to return to the legacy camera path:

vset /camera/0/cine/enabled 0

Disabling the feature restores the projection and post-process state that was active before the cinematic camera path was enabled. Cinematic settings are runtime state and are not persisted across application restarts.

State queries

vget /camera/[id]/cine: Return the complete cinematic camera state as JSON. The response contains enabled, filmback, lens, focus, crop, exposure, near_clip, horizontal_fov_degrees, and vertical_fov_degrees.
vget /camera/[id]/cine/enabled: Return 1 when the cinematic camera path is enabled, or 0 when the legacy camera path is active.
vget /camera/[id]/cine/intrinsics: Return the active image dimensions, pinhole intrinsics fx, fy, cx, and cy in pixels, horizontal and vertical fields of view in degrees, the two-element off-center projection_offset, and the row-major 4x4 projection_matrix as JSON. The matrix is returned as a flat array of 16 values.

Configuration commands

vset /camera/[id]/cine/enabled [enabled]: Enable or disable the cinematic camera path. 0 disables it; any nonzero integer enables it.
vset /camera/[id]/cine/filmback [width_mm] [height_mm] [offset_x_mm] [offset_y_mm]: Set the sensor width, sensor height, horizontal sensor offset, and vertical sensor offset in millimeters.
vset /camera/[id]/cine/lens [focal_length_mm] [aperture_fstop]: Set the current physical focal length in millimeters and the aperture in f-stops.
vset /camera/[id]/cine/lens_settings [min_focal_mm] [max_focal_mm] [min_fstop] [max_fstop] [min_focus_mm] [squeeze] [blades]: Set the lens limits, minimum focus distance, anamorphic squeeze factor, and diaphragm blade count. Focal lengths and the minimum focus distance use millimeters. blades is an integer.
vset /camera/[id]/cine/focus [distance_cm]: Set the manual focus distance in centimeters.
vset /camera/[id]/cine/focus_mode [mode] [smooth] [smoothing_speed] [offset_cm]: Set the focus method and focus interpolation settings. Supported modes are manual, tracking, disable, none, and do_not_override. smooth uses 0 or 1; offset_cm is the focus-plane offset in centimeters.
vset /camera/[id]/cine/focus_tracking [actor] [offset_x_cm] [offset_y_cm] [offset_z_cm]: Track an actor by UnrealCV object name and apply a relative focus offset in centimeters. The command returns an error if the actor cannot be found.
vset /camera/[id]/cine/crop [aspect_ratio] [overscan] [crop_overscan] [scale_resolution]: Set the crop aspect ratio and overscan, and control whether overscan is cropped and whether output resolution scales with overscan. The final two arguments use 0 or 1.
vset /camera/[id]/cine/near_clip [enabled] [distance_cm]: Enable or disable the custom near clipping plane and set its distance in centimeters.
vset /camera/[id]/cine/exposure [iso] [shutter_reciprocal] [physical_exposure]: Set ISO, shutter speed, and whether physical camera exposure is applied. Shutter speed is expressed as a reciprocal value: 60 means 1/60 s. physical_exposure uses 0 or 1.

Example

The following sequence configures a 50 mm lens and manual focus, then reads the derived intrinsics:

vset /camera/0/cine/filmback 24.89 18.67 0 0
vset /camera/0/cine/lens_settings 18 135 1.4 22 15 1 9
vset /camera/0/cine/lens 50 2.8
vset /camera/0/cine/focus_mode manual 0 8 0
vset /camera/0/cine/focus 250
vset /camera/0/cine/exposure 100 60 1
vget /camera/0/cine/intrinsics

The first vset command automatically enables the cinematic camera path.

Focal-length terminology

vset /camera/[id]/focal [distance] [region] is the legacy depth-of-field command. Its arguments control focal distance and focal region; they do not set physical lens focal length in millimeters. Use vset /camera/[id]/cine/lens for the physical lens model.