variable_speed_model: Variable Speed Model

In nicholascarey/loomeR: Looming Animations for Use in Behavioural and Neurological Experiments

Variable Speed Model

Description

Given a viewing distance, this function calculates the on-screen diameters of a hypothetical object of defined size approaching at a user-supplied variable speed profile. This allows a looming animation with precise parameters to be created.

Usage

variable_speed_model(
  x,
  screen_distance = 20,
  frame_rate = 60,
  attacker_diameter = 50
)

Arguments

x	numeric. Vector of speeds (cm/s) of the hypothetical approaching attacker at the same frequency (Hz) as the frame_rate. Length of the vector will thus determine total duration of the resulting animation.
screen_distance	numeric. Distance (cm) from the playback screen to your specimen.
frame_rate	numeric. Frames per second (Hz) you want the resulting animation to be played back at.
attacker_diameter	numeric. Diameter of the hypothetical approaching attacker. This affects the size of the simulation in the final frame of the animation.

Details

Calculates the screen diameters for a modelled object of specified size approaching at a variable speed. The variable speed must be supplied as a vector of speeds (operator x) in cm/s at the same frequency (i.e. same Hz) as the entered frame_rate, which is the frame rate the resulting animation created from this model will be played back at. If the speed profile is in a different frequency than common video frame rates (e.g, 24, 30, 60 fps) it is recommended to interpolate or subsample it to be so. I can't guarantee all playback software will correctly play videos encoded at odd frame rates, though you are free to try.

The output list object can be used to create a looming animation in looming_animation. Unlike constant_speed_model, no starting_distance operator is required: it is assumed the final value in the speeds vector occurs at the point of zero distance between the attacker and observing target. The function uses the speeds to back-calculate distances from this point to the starting entry in speeds. These distances and the attacker_diameter are used to calculate a screen diameter for the simulation in each frame. Obviously, the length of speeds and the frequency determines the total length of the resulting animation.

Required inputs include the intended frame rate at which the subsequent animation will be played, and distance from the screen at which the observing specimen will be located. These details are important in experiments where you want to precisely determine at what time, perceived distance, or perceived velocity of an attack an escape response occurs. Note: if the specimen is closer or further away than the specified screen distance, the animation will be perceived as a different distance and a different velocity.

If you need to create a looming animation simply to elicit a response, and are not concerned with the precise details, see diameter_model.

Inputs should be in cm, speeds in cm/s, and frame rate in Hz or Frames per Second.

Value

List object containing the input parameters and the resulting diameter for each frame in the animation.

Author(s)

Nicholas Carey - [e-mail]

See Also

looming_animation, looming_animation_calib, constant_speed_model diameter_model

Examples

## Create a speeds vector
## Here we create a vector of speeds of an attacker steadily accelerating from
## nearly stationary (1 cm/s) to 500 cm/s by 1 cm/s per frame
x <- seq(1, 500, 1)

## Use the variable speed vector to create the model
loom_model <- variable_speed_model(x, screen_distance = 20, frame_rate = 60, attacker_diameter = 50)

nicholascarey/loomeR documentation built on Jan. 13, 2023, 11:31 a.m.