Camera paths

Gaia Sky offers the possibility to record camera paths out of the box and later play them. These camera paths are saved in a .gsc (for Gaia Sky Camera) file in $GS_DATA/camera (see folders).

Camera path file format

The format of the .gsc files is pretty straightforward. It is a comma- or white space-separated text file (both are supported), each row containing the state of the camera and the time for a given frame. The state of the camera consists of 9 double-precision floating point numbers, 3 for the position and 3 for the direction vector and 3 for the up vector. Lines starting with the character ‘#’ are ignored.

The reference system used is explained in the Internal reference system section. The units are .

The format of each row is as follows:

• long integer (8 bytes) – time as defined by the getTime() function of java.util.Date (here). Contains the number of milliseconds since Jan 1, 1970, 00:00:00 GMT.

• 3x double-precision float (8*3 bytes) – [px, py, pz] position of the camera.

• 3x double-precision float (8*3 bytes) – [dx, dy, dz] direction vector of the camera.

• 3x double-precision float (8*3 bytes) – [ux, uy, yz] up vector of the camera.

Recording camera paths

Gaia Sky offers two possibilities as to how to record a camera path: real time recording and keyframes. Keyframes are dealt with in the next sub-section. Here we look at the real time recording of camera paths.

In order to start recording the camera path, click on the REC button next to the Camera section title in the GUI Controls window. The REC button will turn red , which indicates the camera is being recorded.

In order to stop the recording and write the file, click again on the red REC button (). The button will turn grey and a notification will pop up indicating the location of the camera file. Camera files are by default saved in the $GS_DATA/camera directory (see folders).

Hint

Mind the FPS! The camera recording system stores the position of the camera for every frame! It is important that recording and playback are done with the same (stable) frame rate. To set the target recording frame rate, edit the “Target FPS” field in the camcorder settings of the preferences window. That will make sure the camera path is using the right frame rate. In order to play back the camera file at the right frame rate, you can edit the “Maximum frame rate” input in the graphics settings of the preferences window.

Keyframes editor

The keyframe editor offers the possibility to create keyframes at specific positions from which the camera file will be generated. In order start creating a keyframed camera path, click on the REC button in the camera pane of the control panel (marked with a red arrow in the screenshot below). A new window will pop up from which you’ll be able to create and manage the keyframes.

Keyframes file format

Keyframes can be saved and loaded to and from .gkf files using the keyframes file format. These files only contain the information on the keyframes themselves. Once the keyframes have been created, they can be exported to a .gsc camera path file. Both keyframe files and camera path files are stored by default in the $GS_DATA/camera folder (see folders).

The keyframes file format is a text format with comma-separated values. Lines starting with ‘#’ are ignored.. It contains a line for each keyframe. Each line has the following columns:

• double-precision float (8 bytes) – keyframe duration since the last keyframe, in seconds. The duration of the first keyframe must be 0.0.

• long integer (8 bytes) – simulation time of the keyframe, as the number of milliseconds since Jan 1, 1970, 00:00:00 GMT. Times are linearly interpolated between keyframes.

• 3x double-precision float (8*3 bytes) – [px, py, pz] position of the camera in this keyframe.

• 3x double-precision float (8*3 bytes) – [vx, vy, vz] direction of the camera in this keyframe.

• 3x double-precision float (8*3 bytes) – [ux, uy, uz] up vector of the camera in this keyframe.

• OPTIONAL: 3x double-precision float (8*3 bytes) – [tx, ty, tz] position of the camera target, or point of interest, for this keyframe. This vector is only present if the camera was in focus mode when the keyframe was created or modified.

• integer (4 bytes) – seam mark. This is 1 if the keyframe is a seam, and 0 otherwise.

Creating and editing keyframes

Creating a keyframed camera path around Gaia. To the bottom-left, we see the keyframes editor window with some keyframes. The red arrow points to the button used to launch the keyframes editor.

A visual representation of keyframes is displayed in the 3D world (see screenshot above) as lines (splines, orientations, etc.) and points (keyframe locations). The colors are as following:

• Yellow lines – linear interpolation paths between keyframes.

• Green lines – spline paths (either B-Splines or Catmull-Rom splines) between keyframes. They represent the true camera position. If the position interpolation is set to linear in the keyframes settings, the green lines coincide with the yellow lines. If the position interpolation is set to Catmull-Rom splines, the green line should hit every keyframe position perfectly. If the position interpolation is set to B-splines, the green line should only hit perfectly the path start and end points.

• Red lines – for each keyframe, the red line represents the camera direction vector.

• Blue lines – for each keyframe, the blue line represents the camera up vector.

• Green points – represent keyframe locations for keyframes which are not currently selected.

• Magenta points – represent the keyframe that is currently selected and acts as a camera focus, if any.

The keyframe visual representation is only displayed when the visibility of keyframes in enabled, so make sure that the visibility of Keyframes is on (you can use the Keframe visuals button in the keyframes editor directly).

Keyframes can be selected and dragged with the right mouse button. The currently selected keyframe is highlighted in the keyframes list and also in the scene, using a magenta color. Here are the basic controls:

• Right mouse – select keyframes (click) and move them around (drag).

• Shift + Right mouse – drag to rotate the keyframe orientation around the up vector (in blue).

• Ctrl + Right mouse – drag to rotate the keyframe orientation around the direction vector (in red).

• Alt + Right mouse – drag to rotate the keyframe orientation around the perpendicular to the up and the direction vector (not represented in the scene).

Adding keyframes

In order to add a new keyframe, click on the Add keyframe at the end button. The new keyframe will be created after the current one (if any), and with the current camera state (position, orientation). If the camera is in focus mode, the keyframe name will appear in yellow, and the keyframe will have a target, or point of interest. See the OptFlowCam export section for more information.

The keyframe is also created with as many seconds after the previous keyframe as stated in the Seconds after prev. text field, and with the name given in the Name (optional) text field. If no name is entered, the default name of “Keyframe x” is used, where x is a monotonically increasing integer.

Keyframes list

To the right of the keyframes editor is the keyframes list. It is a list of keyframes with their properties, along with some buttons to perform some actions. The list is sorted top-to-bottom in the same order as they are in the path. Each entry in the list has the following elements, in order, left to right:

• – move the keyframe up in the list. This moves the keyframe one position to the left in the path.

• – move the keyframe down in the list. This moves the keyframe one position to the right in the path.

• Keyframe time – the time of the keyframe relative to the first one, in seconds. The first keyframe in the list always has the time 000.00. By default, keyframes are created 1.0 seconds after the previous one. Left click on the green keyframe time label to edit it on the fly. Once the edition is done, press Enter to persist.

• (Frame number) – the frame number relative to the first keyframe. This is just the keyframe time times the target FPS (defined in the keyframe preferences).

• – hover over this icon to see the simulation time attached to this keyframe.

• – when this icon and the keyframe name are in yellow color, the keyframe has a target position (also referred to as ‘point of interest’). A keyframe has a target only when it was created when the camera was in focus mode. In that case, the keyframe target is the position of the camera focus object at the time. Targets are used only by the OptFlowCam export function. Refer to that section for more information.

• Keyframe name – the name of the keyframe. By default, this will be “keyframe x”, where x is a monotonically increasing integer number in the keyframes list, starting at 1. Left click on the keyframe name label to edit it on the fly. As with the target icon, the keyframe name appears in yellow if the keyframe has a target position (point of interest). Targets are used only by the OptFlowCam export function. Refer to that section for more information.

• – go to the keyframe. Puts the camera in the state specified by the keyframe.

• – set keyframe to the current camera state. This allows to modify the given keyframe by setting it to the current state of the camera (including position, orientation and target, if any).

• – mark the keyframe as seam. In case the spline interpolation method is chosen, this will break the spline path.

• – add a new keyframe after this one, interpolating position, orientation and time with the next one. If the two keyframes have a target, the target position is also interpolated.

• – remove the keyframe.

Since 3.5.3

Playback controls

Below the keyframes list is a series of playback controls and a timeline slider. The slider is annotated with the current frame, and can be used to position the camera at any location in the path in real time. No need to export the camera path.

• Beginning – Move to the beginning of the timeline.

• Step back – Step one frame backward.

• Play/pause – Play or pause the camera path.

• Step forward – Step one frame forward.

• End – Move to the end of the timeline.

Export keyframes to camera paths

To the top of the keyframes window there are a few buttons to load, export and save keyframes projects.

• Open… – load a new .gkf keyframes file. The button opens a file picker in the default camera directory ($GS_DATA/camera, see system directories).

• Save… – save the current keyframes to a keyframes file .gkf in $GS_DATA/camera. You can choose the file name, but not the directory. If another file with the same name exists, a unique file name is generated from the given one.

• Export… – export the current project to a camera path file .gsc. Optionally, the OptFlowCam method can be used to export. The export process uses the settings defined in the kefyrame preferences. You can choose the file name, but not the directory. If another file with the same name exists, a unique file name is generated from the given one.

• Normalize – recompute all keyframe times so that speed is constant. The total length and distance are unaltered.

• Preferences – see next section, Keyframes preferences.

Keyframes preferences

The Preferences button (lower right in the Keyframes window) opens a window which contains some settings related to the keyframes system:

• Target FPS – the target frame rate to use when generating the camera file from the keyframes.

• Interpolation type – method used to interpolate between positions (orientations are always interpolated using quaternion interpolation). The time is always interpolated linearly to prevent unwanted speed-ups and slow-downs. Two types of interpolation are available:

  • Catmull-Rom splines – produce smoothed paths which hit every keyframe. In this mode, keyframes can be seams . Seam keyframes break up the path into two sections, so that two splines will be used ending and beginning at the keyframe.

  • B-splines – produce smoothed paths which do not hit every keyframe. In this mode, keyframes can be seams . Seam keyframes break up the path into two sections, so that two splines will be used ending and beginning at the keyframe.

  • Linear interpolation – keyframe positions are joined by straight lines. In this mode, the yellow and green lines above are the same.

Export keyframes with OptFlowCam

Gaia Sky includes the option to use the OptFlowCam method to export the keyframes to camera path files. This method works very well in smoothing paths which span over long distance ranges and extremely varying scales.

The keyframes export window contains a check box to activate the OptFlowCam post-processing.

A few caveats need to be taken into account to use this functionality:

• The OptFlowCam processing is implemented as an external Python script, so a local installation of Python 3.x must be in place and accessible via the operating system. NumPy is also required. Typically, once Python is installed, you can install NumPy by running pip3 install numpy in a terminal. In some cases, if the Python environment is externally managed, you may need to install it via your package manager (for instance, in Arch Linux you would do pacman -S python-numpy). The Flatpak version of Gaia Sky already includes Python and NumPy.

  • Install Python on Windows.

  • Install Python on macOS.

  • Install Python on Linux: use the package manager provided by your distribution.

• The technique works best if every keyframe has a target or point of interest (see sections above for more information), so make sure that all your keyframes are created when the camera is in focus mode. Otherwise, a default distance-to-target of 500.000 Km is assumed.

• Note that the green line visually indicating the camera path is not respected in this mode. Only the keyframes themselves are guaranteed to be hit, but not so the interpolated positions between them.

• Following up on the previous point, the method is not interactive, and only kicks in at export time. Do not use the visual path lines for guidance, as they are not updated with this method in real time.

Playing camera paths

In order to play a camera file, click on the PLAY icon next to the REC icon. This will prompt a list of available camera files in the $GS_DATA/camera folder (see folders).

You can also combine the camera file playback with the frame output system to save each frame to a JPEG image during playback. To do so, enable the Activate frame output automatically checkbox in the preferences dialog as described in the Camrecorder section.