Managing the Active Camera (Using APIs)
Managing the Active Camera
When using the Threekit Player, you may wish to alter a user’s camera controls or view based on the current state of the scene. For instance, a camera can change its view restrictions when an object changes size/location. Or, a camera animation of some type may be used to take a user’s view from one location to another. This document will outline the tools available for such actions.
Sources of Information
Camera API
This API will get and change the position of the camera. The Camera API controls basic camera functionality, including getting and setting the location/orientation (translation/quaternion) of the camera. If need be, you can also frame the camera’s view around its target.
Camera Controller
This API will get the active camera’s information:
playerApi.player.cameraController.getActiveCamera()
With the active camera’s information, you can look up information about the camera in the scenegraph.
Scenegraph (Player API’s Scene module)
This API will get and change the behavior of the camera.
After acquiring the camera’s ID from the Camera Controller, querying the camera’s asset instance using the following call
playerApi.scene.get({from: playerApi.instanceId, id: cameraInstanceId});
The return from this scene API call will be a scene node object. Within that object, access camera information at object.plugs.Camera[0]
The information found here includes the following properties. Those marked with an asterisk (*) indicate editing via playerApi.scene.set() will update the camera’s view/behavior instantly:
- constraintDistanceOffsetMax* - Maximum zoom out from the camera’s position at the time when user assumes control of the camera
- constraintDistanceOffsetMin* - Maximum zoom in from the camera’s position at the time when user assumes control of the camera
- constraintLatitudeMax* - Maximum upward orbit (in degrees) that a user can perform with the camera from the camera’s position at the time when user assumes control of the camera
- constraintLatitudeMin* - Maximum downward orbit (in degrees) that a user can perform with the camera from the camera’s position at the time when user assumes control of the camera
- constraintLatitudeMode* - When = 1, the Latitude constraints will impact camera movement. When = 0, the Latitude constraints will not impact camera movement
- constraintLongitudeMax* - Maximum right orbit (in degrees) that a user can perform with the camera from the camera’s position at the time when user assumes control of the camera
- constraintLongitudeMin* - Maximum left orbit (in degrees) that a user can perform with the camera from the camera’s position at the time when user assumes control of the camera
- constraintLongitudeMode* - When = 1, the Longitude constraints will impact camera movement. When = 0, the Longitude constraints will not impact camera movement
- fieldOfView - Angle (in degrees) of the cone of visibility for the camera
- orthoZoom - Distance the camera is from it’s Target Node (assuming no right-click panning)
- targetNode - The ID of the instance of the scenegraph node that the camera orbits around