Class InteractiveCameraModule

java.lang.Object

gaiasky.script.v2.impl.APIModule

gaiasky.script.v2.impl.InteractiveCameraModule

All Implemented Interfaces:

InteractiveCameraAPI

public class InteractiveCameraModule
extends APIModule
implements InteractiveCameraAPI

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.

Field Summary

Fields inherited from class APIModule

api, em, logger, me, name

Modifier and Type	Field	Description
protected final APIv2	api	Reference to API object.
protected final EventManager	em	Reference to event manager.
protected final Logger.Log	logger
protected final APIModule	me	Reference to self.
protected final String	name	Module name.

Constructor Summary

Constructors

Constructor	Description
InteractiveCameraModule(EventManager em, APIv2 api, String name)	Create a new module with the given attributes.

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_forward(long value)
void	add_pitch(double amount)	Add a pitch to the camera.
void	add_pitch(long amount)
void	add_roll(double value)	Add a roll force to the camera.
void	add_roll(long roll)
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_rotation(double deltaX, long deltaY)
void	add_rotation(long deltaX, double deltaY)
void	add_turn(double dx, double dy)	Add a turn force to the camera (yaw and/or pitch).
void	add_turn(double deltaX, long deltaY)
void	add_turn(long deltaX, double deltaY)
void	add_turn(long deltaX, long deltaY)
void	add_yaw(double amount)	Add a yaw to the camera.
void	cameraYaw(long amount)
void	dispose()	Method called whenever the module is disposed.
double	get_speed()	Get the current physical speed of the camera in km/h.
void	go_to_object(com.badlogic.ashley.core.Entity object, double solidAngle, int waitTimeSeconds, AtomicBoolean stop)	Version of go_to_object(Entity, double, float, AtomicBoolean) that gets the waitTimeSeconds as an integer instead of a float.
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	go_to_object(String name, double solidAngle, int waitTimeSeconds)	Same as go_to_object(String, double, float), but using an integer for waitTimeSeconds.
void	go_to_object(String name, double solidAngle, int waitTimeSeconds, AtomicBoolean stop)	Version of go_to_object(String, double, int) that gets an optional AtomicBoolean that enables stopping the execution of the call when its value changes.
void	go_to_object(String name, long solidAngle, float waitTimeSeconds)	Same as go_to_object(String, double, float), but using a long for solidAngle.
void	go_to_object(String name, long solidAngle, int waitTimeSeconds)	Same as go_to_object(String, double, float), but using an integer for waitTimeSeconds, and a long for solidAngle.
void	land_at_location(com.badlogic.ashley.core.Entity entity, double longitude, double latitude, AtomicBoolean stop)
void	land_at_location(com.badlogic.ashley.core.Entity object, String locationName, AtomicBoolean stop)
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_at_location(String name, String locationName, AtomicBoolean stop)
void	land_on(com.badlogic.ashley.core.Entity object, AtomicBoolean stop)
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	rotation_speed_setting(int speed)
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	speed_setting(int speed)
void	turning_speed_setting(float speed)	Change the turning speed multiplier of the camera.
void	turning_speed_setting(int speed)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

InteractiveCameraModule

public InteractiveCameraModule(EventManager em,
 APIv2 api,
 String name)

Create a new module with the given attributes.

Parameters:

api - Reference to the API class.

name - Name of the module.

Method Details

set_cinematic

public void set_cinematic(boolean cinematic)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

set_cinematic in interface InteractiveCameraAPI

Parameters:

cinematic - Whether to enable or disable the cinematic mode.

go_to_object

public void go_to_object(String name)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

go_to_object in interface InteractiveCameraAPI

Parameters:

name - The name or id (HIP, TYC, sourceId) of the object.

go_to_object

public void go_to_object(String name,
 double sa)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

go_to_object in interface InteractiveCameraAPI

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

public void go_to_object(String name,
 double sa,
 float wait)

Description copied from interface: InteractiveCameraAPI

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 InteractiveCameraAPI.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.

Specified by:

go_to_object in interface InteractiveCameraAPI

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.

go_to_object

public void go_to_object(String name,
 double solidAngle,
 int waitTimeSeconds)

Same as go_to_object(String, double, float), but using an integer for waitTimeSeconds.

go_to_object

public void go_to_object(String name,
 long solidAngle,
 int waitTimeSeconds)

Same as go_to_object(String, double, float), but using an integer for waitTimeSeconds, and a long for solidAngle.

go_to_object

public void go_to_object(String name,
 long solidAngle,
 float waitTimeSeconds)

Same as go_to_object(String, double, float), but using a long for solidAngle.

go_to_object

public void go_to_object(String name,
 double solidAngle,
 int waitTimeSeconds,
 AtomicBoolean stop)

Version of go_to_object(String, double, int) that gets an optional AtomicBoolean that enables stopping the execution of the call when its value changes.

go_to_object

public void go_to_object(com.badlogic.ashley.core.Entity object,
 double solidAngle,
 int waitTimeSeconds,
 AtomicBoolean stop)

Version of go_to_object(Entity, double, float, AtomicBoolean) that gets the waitTimeSeconds as an integer instead of a float.

add_forward

public void add_forward(double value)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

add_forward in interface InteractiveCameraAPI

Parameters:

value - The magnitude of the movement, between -1 and 1.

add_forward

public void add_forward(long value)

add_rotation

public void add_rotation(double dx,
 double dy)

Description copied from interface: InteractiveCameraAPI

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 (InteractiveCameraAPI.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.

Specified by:

add_rotation in interface InteractiveCameraAPI

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_rotation

public void add_rotation(double deltaX,
 long deltaY)

add_rotation

public void add_rotation(long deltaX,
 double deltaY)

add_roll

public void add_roll(double value)

Description copied from interface: InteractiveCameraAPI

Add a roll force to the camera.

Specified by:

add_roll in interface InteractiveCameraAPI

Parameters:

value - The intensity of the roll.

add_roll

public void add_roll(long roll)

add_turn

public void add_turn(double dx,
 double dy)

Description copied from interface: InteractiveCameraAPI

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 (InteractiveCameraAPI.set_cinematic(boolean), the turn will not be permanent. Use the cinematic behaviour to have the turn persist in time.

Specified by:

add_turn in interface InteractiveCameraAPI

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_turn

public void add_turn(double deltaX,
 long deltaY)

add_turn

public void add_turn(long deltaX,
 double deltaY)

add_turn

public void add_turn(long deltaX,
 long deltaY)

add_yaw

public void add_yaw(double amount)

Description copied from interface: InteractiveCameraAPI

Add a yaw to the camera. Same as InteractiveCameraAPI.add_turn(double, double) with deltaY set to zero.

Specified by:

add_yaw in interface InteractiveCameraAPI

Parameters:

amount - The amount.

cameraYaw

public void cameraYaw(long amount)

add_pitch

public void add_pitch(double amount)

Description copied from interface: InteractiveCameraAPI

Add a pitch to the camera. Same as InteractiveCameraAPI.add_turn(double, double) with deltaX set to zero.

Specified by:

add_pitch in interface InteractiveCameraAPI

Parameters:

amount - The amount.

add_pitch

public void add_pitch(long amount)

get_speed

public double get_speed()

Description copied from interface: InteractiveCameraAPI

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

Specified by:

get_speed in interface InteractiveCameraAPI

Returns:

The current speed of the camera in km/h.

speed_setting

public void speed_setting(float speed)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

speed_setting in interface InteractiveCameraAPI

Parameters:

speed - The new speed, from 0 to 100.

speed_setting

public void speed_setting(int speed)

rotation_speed_setting

public void rotation_speed_setting(float speed)

Description copied from interface: InteractiveCameraAPI

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 InteractiveCameraAPI.add_rotation(double, double).

Specified by:

rotation_speed_setting in interface InteractiveCameraAPI

Parameters:

speed - The new rotation speed in [0,100]

rotation_speed_setting

public void rotation_speed_setting(int speed)

turning_speed_setting

public void turning_speed_setting(float speed)

Description copied from interface: InteractiveCameraAPI

Change the turning speed multiplier of the camera. This setting affects the turning speed in interactive mode, and the functions InteractiveCameraAPI.add_turn(double, double), InteractiveCameraAPI.add_pitch(double), InteractiveCameraAPI.add_yaw(double), and InteractiveCameraAPI.add_roll(double).

Specified by:

turning_speed_setting in interface InteractiveCameraAPI

Parameters:

speed - The new turning speed, from 1 to 100.

turning_speed_setting

public void turning_speed_setting(int speed)

land_on

public void land_on(String name)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

land_on in interface InteractiveCameraAPI

Parameters:

name - The proper name of the object.

land_on

public void land_on(com.badlogic.ashley.core.Entity object,
 AtomicBoolean stop)

land_at_location

public void land_at_location(String name,
 String location)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

land_at_location in interface InteractiveCameraAPI

Parameters:

name - The proper name of the object.

location - The name of the location to land on

land_at_location

public void land_at_location(String name,
 String locationName,
 AtomicBoolean stop)

land_at_location

public void land_at_location(com.badlogic.ashley.core.Entity object,
 String locationName,
 AtomicBoolean stop)

land_at_location

public void land_at_location(String name,
 double longitude,
 double latitude)

Description copied from interface: InteractiveCameraAPI

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.

Specified by:

land_at_location in interface InteractiveCameraAPI

Parameters:

name - The proper name of the object.

longitude - The location longitude, in degrees.

latitude - The location latitude, in degrees.

land_at_location

public void land_at_location(com.badlogic.ashley.core.Entity entity,
 double longitude,
 double latitude,
 AtomicBoolean stop)

dispose

public void dispose()

Description copied from class: APIModule

Method called whenever the module is disposed. To be overwritten if necessary.

Overrides:

dispose in class APIModule