Dataset Commands

The audio command controls aspects of the optional audio track associated with the current dataset loaded on the sphere. These are the available subcommands:

Returns the current volume, for example 75.0.

Mutes the audio track.

Unmutes the audio track.

Mutes the audio track if it is playing, and turns it back on if it is muted.

Increases the volume of the audio track by a system-dependent amount, up to a maximum value.

Decreases the volume of the audio track by a system-dependent amount, down to a minimum value.

Sets the volume to a percentage of the current system volume. The value is an integer in the range 0-100.

The get_animating command returns “1” if the current clip is animating, or “0” if it is paused or no clip is loaded.

The get_frame_count command returns the total number of frames in the current clip, or 0 if no clip is loaded.

The get_frame_number command returns the frame number that is currently being displayed within the current clip. Frames are numbered from 0 to one less than the total number of frames. If no clip is loaded, the frame number is zero.

The get_frame_rate command returns the frame rate and dwell times at which the current clip is now playing. If no clip is loaded, the value is not valid or useful.

The return value is a line with three space-separated numbers: fps first_dwell_ms last_dwell_ms.

The value fps is the current number of frames per second. It is a floating point number, and fractional values are allowed.

The values first_dwell_ms and last_dwell_ms give the integer dwell times for the first and last frames of the current clip, in milliseconds. They specify an additional amount of time that the system lingers on the first and last frames. This is particularly useful for animations through time, to help the viewer adjust to the time discontinuity as the clip wraps around the end.

get_frame_rate
30.000000 0 0

The get_tilt command returns the current position of the sphere display in terms of three defining Euler angles. The angles are specified in degrees. In the SOS display software, the sphere image is first rotated around the y-axis, then the x-axis, and finally the z-axis. The result is a set of three numbers that can describe any possible rotational position of the sphere.

The kml command controls the placement of KML features. By default KML legends and ancillary graphics are placed at 180 degrees longitude. These are the available subcommands:

kml legendXoffset [dx]

Offsets the longitude of the legend by dx degrees.

kml legendYoffset [dy]

Offsets the latitude of the legend by dy degrees.

kml legendoffset [dx] [dy]

Offsets the longitude of the legend by dx degrees and the latitude by dy degrees.

kml pipscale [sf]

Scales all image placemarks in the KML file using sf. For example, an sf of 1.5 would increase the size by 50%.

orient [globe_lat,globe_lon] [room_lat,room_lon]

The orient command positions the sphere display in terms of two (latitude, longitude) pairs. The intent is to provide a more intuitive way to position the sphere than the basic Euler angles specified for the set_tilt command. The idea is to move a particular position on the global data set (globe coordinates) to a particular position on the physical sphere (room coordinates). The global data set is further adjusted so that North is up at the specified point.

In the default SOS position (set_tilt 0 0 0) the two coordinate systems (globe and room) are identical ways of specifying a position on the sphere surface. As the sphere display orientation is changed, the room coordinate system by definition remains in the original position, and the globe coordinate system shifts around to describe the data orientation as displayed on the sphere.

The pause command stops animating the current clip (the opposite of play).

The pic_mute command toggles the sos video display, turning it off if it is visible, and vice versa. When muted, the clip continues to play, but is not visible on the sphere.

pip [filename]

The pip command creates a new PIP window and loads the specified image filename into the window. (Note that filename can also be a url image, as in http://example.com/image.jpg, or an rtsp stream, as in http://server_name/stream_name.sdp) The PIP becomes the selected PIP, to which the following PIP commands apply.

pipalpha [0 to 1]

The pipalpha command specifies the opacity of the selected PIP. A value of 0 makes the PIP fully transparent (invisible). A value of 1 makes the PIP fully opaque. Values between 0 and 1 make the PIP translucent.

pipcoords [lat,lon]

The pipcoords command positions the center of the selected PIP at a particular latitude and longitude. Unlike the pipvertical command, the PIP shape doesn’t change as the latitude increases. A different transformation is used in each case, so it is recommended to use either pipvertical or pipcoords, but not both.

pipdelay [seconds]

The pipdelay command specifies the offset in seconds from the start of the current clip where the selected PIP first appears. If not specified, the PIP is visible from the start of the clip.

pipdelete [name]

The pipdelete command deletes the with the user-specified name. Once deleted, the PIP disappears from the sphere, and is no longer available to be manipulated by other PIP commands.

pipfadein [seconds]

The pipfadein command specifies the number of seconds it takes the selected PIP to fade in when the PIP first appears (per the pipdelay command).

pipfadeout [seconds]

The pipfadeout command specifies the number of seconds it takes the selected PIP to fade out when the PIP disappears (per the piptimer command).

pipfps [value]

The pipfps command specifies the animation rate of the selected PIP in frames per second for animated pips. The default animation rate of the PIP is read from the PIP movie file. If not specified in the file, it plays at 30 fps.

pipheight [height] 

The pipheight command specifies the height of the selected PIP, in degrees latitude.

piphorizontal [value]

The piphorizontal command specifies the horizontal placement of the selected PIP. The value is in degrees east latitude.

pipimage [filename]

The pipimage command loads a new image file which will replace the window contents of the selected pip.

pipname [name]

The pipname command assigns a user-specified name to the selected PIP, so that it may be selected by that name for future manipulation. If this command is not used, the name of the clip is that of the filename specified when it was created.

pipstyle [projector|globe|room]

The pipstyle command specifies where the selected PIP appears, and how it is affected as the sphere data is reoriented via the set_tilt command.

Duplicates the PIP four times around the sphere, in front of the traditional projector positions. The locations are unaffected by the set_tilt command.

Visually attaches the PIP to the globe data set, so the PIP moves when the sphere spins or is moved with the set_tilt command.

Keeps the PIP stationary on the sphere surface (relative to the room) as the global data set moves.

pipselect [name]

The pipselect command selects a PIP (or multiple PIPs) with a user-specified name. The name is either specified via the pipname command, or is the filename specified originally by the pip command. Most commands then apply to the selected PIP (or PIPs).

piptimer [seconds]

The piptimer command sets the length of time that the selected PIP remains visible on the sphere. If not specified, the PIP is always visible after it first appears.

pipvertical [value]

The pipvertical command specifies the vertical placement of the center of the selected PIP. The value is in degrees north latitude. Shifting the PIP with this command changes its shape, since the edges of the PIP remain aligned with lines of longitude, which converge towards the north and south poles.

pipwidth [width]

The pipwidth command specifies the width of the selected PIP, in degrees longitude.

play [clip_number]

The play command with the clip_number specified clears the sphere, then loads and plays the given clip_number. The first clip in the playlist is clip_number 1. For example, play 2 loads and plays the second clip in the current playlist. A clip number that is greater than the last clip in the current playlist plays the last clip.

The play command with no arguments does one of two things, depending on whether or not a clip is currently loaded. If the sphere is clear (nothing loaded), play loads and plays the first clip in the current playlist (identical to play 1). If a clip is already loaded, play starts animating the clip (the opposite of pause). If the clip is already animating, play has no effect.

set_frame_rate [fps] ([first_dwell_ms last_dwell_ms])

The set_frame_rate command sets the playback speed of the currently loaded clip. The fps argument is required, and specifies the speed of animation in frames per second. If not specified, the default animation rate is 30 frames per second. The fps value is a floating point number, and fractional values are allowed.

The optional arguments first_dwell_ms and last_dwell_ms specify the dwell times for the first and last frames of the current clip, in milliseconds. They specify an additional amount of time to linger on the first and last frames. This is particularly useful for animations through time, to help the viewer adjust to the time discontinuity as the clip wraps around the end.

Note: The SOS system does not attempt to impose a maximum frame rate, because it depends on the particulars of the computer and the clip being played. Most clips will eventually fail to play correctly as the frame rate is increased, due to exhaustion of computer system resources.

set_frame_rate 29.97

set_frame_rate 30 1000 500

set_tilt [x] [y] [z]

The set_tilt command positions the sphere display in terms of three defining Euler angles. The angles are specified in degrees. In the SOS display software, the sphere image is first rotated around the y-axis, then the x-axis, and finally the z-axis. The result is a set of three numbers that can describe any possible rotational position of the sphere.

skip [frame_number]

The skip command stops animation, then jumps to the specified absolute frame number within the current clip. The first frame of the clip is number 0. Values of frame_number less than zero are rounded up to zero. Values of frame_number past the last frame are rounded down to the last frame.

skip 0

skip 99

skip 999999999

step [n_frames]

The step command stops animation, then increments the current frame number by n_frames, and jumps to the new frame. If n_frames is negative, the command steps backward. The command argument is the number of frames to jump relative to the current frame number. The step command wraps smoothly around the first or last frame of the clip as needed.

step 10

step 1

The stop command clears the sphere. It unloads any data that is currently loaded.

zrotationangle [angle]

The zrotationangle command sets the increment angle for Z Rotation, in degrees. Every time the rotation angle is updated (at a rate determined by zfps), it is incremented by this amount. The default is 0.1 degrees.

zfps 1
zrotationangle 6
zrotationenable 1

zfps 30
zrotationangle 0.1
zrotationenable 1

zfps [fps]

The zfps command sets the number of times per second that the rotation angle is updated. The default value is 30.

zrotationenable [0 | 1]

The zrotationenable command turns Z Rotation on or off. A command argument of 0 or 1 is required: 1 to turn Z Rotation on and 0 to turn it off.

The zrotationtoggle command toggles the status of Z Rotation, turning it on if it is off, and vice versa.