All Known Implementing Classes:: InteractiveCameraModule

public interface InteractiveCameraAPI

API definition for the interactive camera module, InteractiveCameraModule.

The interactive camera module contains calls and methods that modify the camera using the interactive mode. In this mode, the camera is modified through events that mimic inputs from different devices such as the mouse or the keyboard. This mode produces good results when running scripts interactively (i.e. using the REST server, or the in-app console), but those results are not reproducible, as they typically are affected by external factors such as the current frame rate, the computer clock, or the pre-existing camera momentum and location.

If you need reproducible results, we recommend the following:

Use the transitions API—see CameraAPI.transition(double[], double[], double[], double) and others in the same family of calls, prefixed by "transition", with the form transition[...]().
Manipulate the internal camera state directly with CameraAPI.set_position(double[]), CameraAPI.set_direction(double[]), and CameraAPI.set_up(double[]). In this case, you need to implement your camera logic in your script.
Use camera paths (see CamcorderAPI).
Use key-framed camera paths TODO.

Method Summary

Modifier and Type

Method

Description

void

add_forward(double value)

Add a forward movement to the camera with the given value.

void

add_pitch(double amount)

Add a pitch to the camera.

void

add_roll(double roll)

Add a roll force to the camera.

void

add_rotation(double dx, double dy)

Add a rotation movement to the camera around the current focus, or a pitch/yaw if in free mode.

void

add_turn(double dx, double dy)

Add a turn force to the camera (yaw and/or pitch).

void

add_yaw(double amount)

Add a yaw to the camera.

double

get_speed()

Get the current physical speed of the camera in km/h.

void

go_to_object(String name)

Run a seamless trip to the object with the name focusName until the object view angle is 20 degrees.

void

go_to_object(String name, double sa)

Run a seamless trip to the object with the name focusName until the object view angle viewAngle is met.

void

go_to_object(String name, double sa, float wait)

Run a seamless trip to the object with the name focusName until the object view angle viewAngle is met.

void

land_at_location(String name, double longitude, double latitude)

Land on the object with the given name, if it is a planet or moon, at the location specified in by [latitude, longitude], in degrees.

void

land_at_location(String name, String location)

Land on the object with the given name, if it is a planet or moon, at the location with the given name, if it exists.

void

land_on(String name)

Land on the object with the given name, if it is a planet or moon.

void

rotation_speed_setting(float speed)

Change the speed of the camera when it rotates around a focus.

void

set_cinematic(boolean cinematic)

Enable/disable the cinematic camera mode.

void

speed_setting(float speed)

Change the speed multiplier of the camera and its acceleration.

void

turning_speed_setting(float speed)

Change the turning speed multiplier of the camera.

Method Details
- set_cinematic
  
  void set_cinematic(boolean cinematic)
  
  Enable/disable the cinematic camera mode. The cinematic camera mode makes the camera use acceleration and momentum, leading to very smooth transitions and movements. This is the ideal camera to use when recording camera paths or presenting to an audience.
  
  Parameters:
  
  cinematic - Whether to enable or disable the cinematic mode.
- go_to_object
  
  void go_to_object(String name)
  
  Run a seamless trip to the object with the name focusName until the object view angle is 20 degrees.
  Warning: This method is not deterministic. It is implemented as a loop that sends 'camera forward' events to the main thread, running in a separate thread. If you need total synchronization and reproducibility, look into the BaseModule.park_runnable(String, Runnable) family of calls.
  
  Parameters:
  
  name - The name or id (HIP, TYC, sourceId) of the object.
- go_to_object
  
  void go_to_object(String name, double sa)
  
  Run a seamless trip to the object with the name focusName until the object view angle viewAngle is met. If angle is negative, the default angle is 20 degrees.
  Warning: This method is not deterministic. It is implemented as a loop that sends 'camera forward' events to the main thread, running in a separate thread. If you need total synchronization and reproducibility, look into the BaseModule.park_runnable(String, Runnable) family of calls.
  
  Parameters:
  
  name - The name or id (HIP, TYC, sourceId) of the object.
  
  sa - The target solid angle of the object, in degrees. The angle gets larger and larger as we approach the object.
- go_to_object
  
  void go_to_object(String name, double sa, float wait)
  
  Run a seamless trip to the object with the name focusName until the object view angle viewAngle is met. If angle is negative, the default angle is 20 degrees. If waitTimeSeconds is positive, it indicates the number of seconds to wait (block the function) for the camera to face the focus before starting the forward movement. This very much depends on the turn velocity of the camera. See turning_speed_setting(float).
  Warning: This method is not deterministic. It is implemented as a loop that sends 'camera forward' events to the main thread, running in a separate thread. If you need total synchronization and reproducibility, look into the BaseModule.park_runnable(String, Runnable) family of calls.
  
  Parameters:
  
  name - The name or id (HIP, TYC, sourceId) of the object.
  
  sa - The target solid angle of the object, in degrees. The angle gets larger and larger as we approach the object.
  
  wait - The seconds to wait for the camera direction vector and the vector from the camera position to the target object to be aligned.
- get_speed
  
  double get_speed()
  
  Get the current physical speed of the camera in km/h.
  
  Returns:
  
  The current speed of the camera in km/h.
- speed_setting
  
  void speed_setting(float speed)
  
  Change the speed multiplier of the camera and its acceleration. This setting affects the camera speed in interactive mode, and all the functions that move the camera forward or backward in this module.
  
  Parameters:
  
  speed - The new speed, from 0 to 100.
- rotation_speed_setting
  
  void rotation_speed_setting(float speed)
  
  Change the speed of the camera when it rotates around a focus. This setting affects the rotation speed of the camera in interactive mode, and the function add_rotation(double, double).
  
  Parameters:
  
  speed - The new rotation speed in [0,100]
- turning_speed_setting
  
  void turning_speed_setting(float speed)
  
  Change the turning speed multiplier of the camera. This setting affects the turning speed in interactive mode, and the functions add_turn(double, double), add_pitch(double), add_yaw(double), and add_roll(double).
  
  Parameters:
  
  speed - The new turning speed, from 1 to 100.
- add_forward
  
  void add_forward(double value)
  
  Add a forward movement to the camera with the given value. If value is negative the movement is backwards.
  This gets a unitless parameter in [-1, 1] to mimic the mouse scroll movement up and down.
  
  Parameters:
  
  value - The magnitude of the movement, between -1 and 1.
- add_rotation
  
  void add_rotation(double dx, double dy)
  
  Add a rotation movement to the camera around the current focus, or a pitch/yaw if in free mode.
  If the camera is not using the cinematic behaviour (set_cinematic(boolean), the rotation movement will not be permanent. Use the cinematic behaviour to have the camera continue to rotate around the focus.
  This method gets two unitless parameters in [0, 1], deltaX and deltaY, which mimic the delta, in pixels, of the mouse cursor being dragged.
  
  Parameters:
  
  dx - The x component, between 0 and 1. Positive is right and negative is left.
  
  dy - The y component, between 0 and 1. Positive is up and negative is down.
- add_roll
  
  void add_roll(double roll)
  
  Add a roll force to the camera.
  
  Parameters:
  
  roll - The intensity of the roll.
- add_turn
  
  void add_turn(double dx, double dy)
  
  Add a turn force to the camera (yaw and/or pitch). If the camera is in focus mode, it permanently deviates the line of sight from the focus until centered again.
  If the camera is not using the cinematic behaviour (set_cinematic(boolean), the turn will not be permanent. Use the cinematic behaviour to have the turn persist in time.
  
  Parameters:
  
  dx - The x component, between 0 and 1. Positive is right and negative is left.
  
  dy - The y component, between 0 and 1. Positive is up and negative is down.
- add_yaw
  
  void add_yaw(double amount)
  
  Add a yaw to the camera. Same as add_turn(double, double) with deltaY set to zero.
  
  Parameters:
  
  amount - The amount.
- add_pitch
  
  void add_pitch(double amount)
  
  Add a pitch to the camera. Same as add_turn(double, double) with deltaX set to zero.
  
  Parameters:
  
  amount - The amount.
- land_on
  
  void land_on(String name)
  
  Land on the object with the given name, if it is a planet or moon. The land location is determined by the line of sight from the current position of the camera to the object.
  
  Parameters:
  
  name - The proper name of the object.
- land_at_location
  
  void land_at_location(String name, String location)
  
  Land on the object with the given name, if it is a planet or moon, at the location with the given name, if it exists.
  
  Parameters:
  
  name - The proper name of the object.
  
  location - The name of the location to land on
- land_at_location
  
  void land_at_location(String name, double longitude, double latitude)
  
  Land on the object with the given name, if it is a planet or moon, at the location specified in by [latitude, longitude], in degrees.
  
  Parameters:
  
  name - The proper name of the object.
  
  longitude - The location longitude, in degrees.
  
  latitude - The location latitude, in degrees.

Interface InteractiveCameraAPI

Method Summary

Method Details

set_cinematic

go_to_object

go_to_object

go_to_object

get_speed

speed_setting

rotation_speed_setting

turning_speed_setting

add_forward

add_rotation

add_roll

add_turn

add_yaw

add_pitch

land_on

land_at_location

land_at_location