Automation Control Protocol
The SOS Automation Interface (also known as the show floor control protocol) is available via a TCP connection to the main SOS system. This interface allows extensive control of the operation of SOS by an external computer, as a coordinated part of a larger exhibit. For example, SOS could be synchronized with films or PowerPoint display programs, controlled by an interactive kiosk, or run on an automatic daily schedule of timed presentations.
Establishing and Using a Connection
Permalink to Establishing and Using a ConnectionTo use the SOS Automation Interface, establish a TCP connection to socket 2468 on the main SOS host. The SOS Automation Interface uses an ASCII line-oriented protocol. Each command is a single line of text. Every command will result in a response from the SOS system. After establishing the TCP connection, it may be kept open and used for multiple commands, but the very first command must be the word “enable”. This is neither an actionable command nor a real password, but is used as a simple-minded way to avoid dealing with random socket probes and scans.
Command responses are also ASCII and line-oriented. The error response is the letter “E” (for Error) followed by a two-digit error code, all on a single line. Future error codes may be more precise, but at present this is almost always the string “E04”.
The default successful command response is the letter “R” (for Ready) on a single line. This indicates successful completion of commands that have no return value (e.g. stop). It also indicates success and the end of the list for commands that return more than one line (e.g. get_clip_info *). Commands that always return a single line of information (e.g. get_frame_count) return only that line of information in the successful case, and don’t return an “R” character.
Dataset Commands
Permalink to Dataset Commandsaudio
Permalink to audioThe audio command controls aspects of the optional audio track associated with the current dataset loaded on the sphere. These are the available subcommands:
volume
Permalink to volumeReturns the current volume, for example 75.0.
mute
Permalink to muteMutes the audio track.
unmute
Permalink to unmuteUnmutes the audio track.
toggle
Permalink to toggleMutes 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.
down
Permalink to downDecreases the volume of the audio track by a system-dependent amount, down to a minimum value.
[0 … 100]
Permalink to [0 … 100]Sets the volume to a percentage of the current system volume. The value is an integer in the range 0-100.
get_animating
Permalink to get_animatingThe get_animating
command returns “1” if the current clip is animating, or “0” if it is paused or no clip is loaded.
get_frame_count
Permalink to get_frame_countThe get_frame_count
command returns the total number of frames in the current clip, or 0 if no clip is loaded.
get_frame_number
Permalink to get_frame_numberThe 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.
get_frame_rate
Permalink to get_frame_rateThe 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
This example shows the default values for frame rate and dwells.
get_tilt
Permalink to get_tiltThe 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.
kml
Permalink to kmlThe 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:
legendXoffset
Permalink to legendXoffsetkml legendXoffset [dx]
Offsets the longitude of the legend by dx degrees.
legendYoffset
Permalink to legendYoffsetkml legendYoffset [dy]
Offsets the latitude of the legend by dy degrees.
legendoffset
Permalink to legendoffsetkml legendoffset [dx] [dy]
Offsets the longitude of the legend by dx degrees and the latitude by dy degrees.
pipscale
Permalink to pipscalekml 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
Permalink to orientorient [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.
pause
Permalink to pauseThe pause
command stops animating the current clip (the opposite of play
).
pic_mute
Permalink to pic_muteThe 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
Permalink to pippip [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
Permalink to pipalphapipalpha [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
Permalink to pipcoordspipcoords [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
Permalink to pipdelaypipdelay [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
Permalink to pipdeletepipdelete [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
Permalink to pipfadeinpipfadein [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
Permalink to pipfadeoutpipfadeout [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
Permalink to pipfpspipfps [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
Permalink to pipheightpipheight [height]
The pipheight
command specifies the height of the selected PIP, in degrees latitude.
piphorizontal
Permalink to piphorizontalpiphorizontal [value]
The piphorizontal
command specifies the horizontal placement of the selected PIP. The value is in degrees east latitude.
pipimage
Permalink to pipimagepipimage [filename]
The pipimage
command loads a new image file which will replace the window contents of the selected pip.
pipname
Permalink to pipnamepipname [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
Permalink to pipstylepipstyle [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.
projector
Permalink to projectorDuplicates the PIP four times around the sphere, in front of the traditional projector positions. The locations are unaffected by the set_tilt
command.
globe
Permalink to globeVisually attaches the PIP to the globe data set, so the PIP moves when the sphere spins or is moved with the set_tilt
command.
room
Permalink to roomKeeps the PIP stationary on the sphere surface (relative to the room) as the global data set moves.
pipselect
Permalink to pipselectpipselect [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
Permalink to piptimerpiptimer [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
Permalink to pipverticalpipvertical [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
Permalink to pipwidthpipwidth [width]
The pipwidth
command specifies the width of the selected PIP, in degrees longitude.
play
Permalink to playplay [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
Permalink to set_frame_rateset_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
Sets the frame rate to 29.97 frames per second (the historic American TV standard frame rate).
set_frame_rate 30 1000 500
Sets the frame rate to 30 frames per second (the SOS default), and dwells an additional second on the first frame, and half-second on the last frame.
set_tilt
Permalink to set_tiltset_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
Permalink to skipskip [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
Jumps to the beginning of the current clip.
skip 99
If there are 100 frames in the current clip, this jumps to the last frame of the clip.
skip 999999999
Jumps to the end of the current clip. 999999999 is larger than any reasonably-sized clip, and is rounded down to the last frame.
step
Permalink to stepstep [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
If there are 100 frames loaded, and SOS is on frame number 10, this command jumps to frame number 20.
step 1
If there are 3600 frames loaded, and SOS is paused on frame number 3599 (the last frame in the clip), this command jumps to frame 0 (the first frame in the clip).
stop
Permalink to stopThe stop
command clears the sphere. It unloads any data that is currently loaded.
zrotationangle
Permalink to zrotationanglezrotationangle [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
This set of commands make the sphere act like a jumpy second hand on a watch, jumping by 6 degrees every second, so the sphere makes one complete rotation around the room every minute.
zfps 30 zrotationangle 0.1 zrotationenable 1
This set of commands turn on Z rotation with the same settings as the default value. Since the rotation angle is being updated 30 times per second, the result is a smooth rotation around the room. With a rotation angle of 0.1 degree being incremented 30 times per second, the sphere rotates 3 degrees every second, so it completely rotates around the room every 2 minutes (since 360 degrees / 3 degrees per second = 120 seconds).
zfps
Permalink to zfpszfps [fps]
The zfps
command sets the number of times per second that the rotation angle is updated. The default value is 30.
zrotationenable
Permalink to zrotationenablezrotationenable [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.
zrotationtoggle
Permalink to zrotationtoggleThe zrotationtoggle
command toggles the status of Z Rotation, turning it on if it is off, and vice versa.
Playlist and Library Commands
Permalink to Playlist and Library CommandsWhile most SOS automation commands apply to the current clip, those in this section apply to the playlist as a whole. An SOS playlist is a set of clips, numbered from one through the number of clips in the playlist.
fadein
Permalink to fadeinfadein [fade_duration]
The fadein
command fades the sphere in from black. The fade_duration
parameter specifies the number of seconds over which to fade in from black. If the fade_duration
is not specified, the default fadein
duration is used. This command is called automatically after a clip is loaded.
fadeout
Permalink to fadeoutfadeout [fade_duration]
The fadeout
command fades the sphere to black. The fade_duration
parameter specifies the number of seconds over which to fade to black. If the fade_duration
is not specified, the default fadeout
duration is used. This command is called automatically before a clip is unloaded.
get_all_name_value_pairs
Permalink to get_all_name_value_pairsget_all_name_value_pairs [clip_number]
The get_all_name_value_pairs
command returns a list of name-value pairs for all the parameters specified for the given clip_number
in the currently loaded playlist. The syntax of the returned list is derived from the Tcl scripting language, and is a single line containing a set of space delimited name-value pairs. Each name-value pair is also space delimited. If the value contains internal spaces, it is enclosed in curly braces. If the value itself contains curly braces, they and other special characters may be further escaped with backward slashes.
Once a clip is loaded, many of the clip attributes can be modified by the automation interface. The get_all_name_value_pairs
command returns the initial values of those attributes as recorded in the playlist, even if they have changed since the clip was loaded.
get_clip_count
Permalink to get_clip_countThe get_clip_count
command returns the total number of clips in the currently loaded playlist.
get_clip_info
Permalink to get_clip_infoget_clip_info [clip_number | * clip_parameter]
The get_clip_info
command returns information about a clip as specified within the currently loaded playlist.
The first command argument is required, and is the clip number, or an asterisk for all clips.
The second command argument is optional, and is the name of the clip parameter as specified in the playlist. The default parameter is the name of the clip.
Once a clip is loaded, many of the clip attributes can be modified by the automation interface. The get_clip_info
command returns the initial values of those attributes as recorded in the playlist, even if they have changed since the clip was loaded.
The value returned by the get_clip_info
command has a different format depending on whether a specific clip number was requested, or the asterisk was used to request all clips. If a specific clip number was given, the return value is one line, with the value of the requested parameter (or an empty line if the parameter was not specified for this clip). If the asterisk was used to request all clips, the return value is a set of lines, one per clip, with a final line consisting of the character “R” to indicate the end of the list. The line for each clip in this case is the clip number followed by a space character, optionally followed by the parameter value for that clip (if specified in the playlist).
get_clip_list_from_file
Permalink to get_clip_list_from_fileget_clip_list_from_file [filename]
The get_clip_list_from_file
command returns an unsorted list of all the name-value pairs of each clip found in the filename
, where filename
is the absolute path to a .sos playlist file. The syntax of the returned list is derived from the Tcl scripting language, and is a single line containing a set of space delimited name-value pairs (see the get_all_name_value_pairs
command for more information on the Tcl syntax).
Each name tag in a name-value pair is prepended by the clip’s sequential number in the playlist file (for example: 2,category, where category is the name tag).
Note that there are two extra name-value pairs always included in the return list:
0,animate value
(where value is 0 or 1)size value
(where value is the number of clips in the playlist)
In addition, there is one extra name-value pair for each clip that is always included in the return list, but is not present in the clip’s .sos file:
#,valid value
(where # is a clip number in the playlist, and value is 0 or 1)
get_clip_list_from_file "~/sosrc/myplaylist.sos" 1,opengl true 1,publisher NOAA size 2 0,animate 0 1,category land 2,publisher {NASA GSFC} 1,fps 40 2,fps 30 2,name {Helium Sun} 2,pipcount 0 1,tiltx 23.5 2,category astronomy 0,valid 1 1,valid 1 1,creator NASA 2,creator {NASA GSFC} 2,valid 1 1,name {Blue Marble (23 degree tilt)} 1,datadir /shared/sos/media/land/blue_marble/blue_marble/4096.jpg 2,datadir /shared/sos/media/astronomy/helium_sun/helium_sun_2048.mp4 1,pipcount 0
In this examples, the SOS playlist myplaylist.sos
points to two clips, Blue Marble (23 degree tilt) and Helium Sun.
get_clip_number
Permalink to get_clip_numberThe get_clip_number
command returns the number of the currently playing clip. Clips in the playlist are numbered from one to the total number of clips in the playlist.
If the currently playing clip is not part of the current playlist, get_clip_number
returns 0. This happens when a new playlist is loaded while a clip continues to play.
If no clip is currently playing, get_clip_number
returns -1.
get_playlist_name
Permalink to get_playlist_nameThe get_playlist_name
command returns the filename of the current presentation playlist. If no presentation playlist is currently loaded, it returns an empty line.
load
Permalink to loadload [filename | dirname]
The load
command loads an individual global image file (or directory of files) without the context of a playlist. Ordinarily, data sets are viewed as defined by a clip within a playlist, but this command allows loading an image file without editing a playlist. A temporary clip, number 0, is created when this command is used.
next_clip
Permalink to next_clipThe next_clip
command stops any currently playing clip, clears the sphere, and plays the next clip sequentially in the playlist. If the last clip was playing, it jumps to the first clip.
open_clip_list
Permalink to open_clip_listopen_clip_list [clip_list]
The open_clip_list
command clears the currently loaded playlist and loads and opens a new temporary playlist in SOS Stream GUI containing all the clips in clip_list
. clip_list
is a Tcl list of name-value pairs for a set of clips (for example, a list that is in the format returned by the get_clip_list_from_file
command).
open_playlist
Permalink to open_playlistopen_playlist [playlist_file]
The open_playlist
command loads a new playlist file. If the playlist_file
name starts with a forward slash character, it specifies an absolute path name. Otherwise, it specifies a file relative to ~/sosrc (the sosrc directory in the user’s home directory). Any currently playing clip continues to play after a new playlist is loaded.
open_playlist /shared/sos/media/land/blue_marble/blue_marble/playlist.sos
This example opens the library playlist for the blue marble clip, within the SOS media tree.
open_playlist normal-demo.sos
This example opens the default SOS playlist ~/sosrc/normal-demo.sos
.
overlay
Permalink to overlayoverlay [filename | dirname | clip_number]
The overlay
command creates a new layer on top of any existing global data, and loads the specified global image file or directory of files to the new layer. The new layer is created with default attributes which can then be changed with the layer command. When an integer clip_number
is specified, the global image layers of that clip are loaded as new layers on top of any existing global data.
playlist_delete
Permalink to playlist_deleteplaylist_delete [playlist_file]
The playlist_delete
command deletes the specified presentation playlist file, which is required to use a relative path under the presentation playlist directory ~/sosrc.
playlist_delete mysubdir/playlist.sos
Deletes the the file ~/sosrc/mysubdir/playlist.sos
.
playlist_exists
Permalink to playlist_existsplaylist_exists [playlist_file]
The playlist_exists
command checks to see if the specified playlist file exists. The playlist is required to use a relative path under the presentation playlist directory ~/sosrc or a full path under a NOAA dataset directory (i.e., under /shared/sos/media or /shared/sos/rt/noaa).
playlist_exists /shared/sos/media/site-custom/mysubdir/myplaylist.sos
Checks to see if mysubdir/myplaylist.sos
exists in the site-custom folder.
playlist_read
Permalink to playlist_readplaylist_read [playlist_file]
The playlist_read
command opens and reads the contents of the specified playlist file, which is returned as a string. The playlist is required to use a relative path under the presentation playlist directory ~/sosrc or a full path under the NOAA dataset directory (i.e., under /shared/sos/media or /shared/sos/rt/noaa).
playlist_read /shared/sos/media/site-custom/mysubdir/myplaylist.sos
Returns the contents of myplaylist.sos
.
playlist_rename
Permalink to playlist_renameplaylist_rename [from_playlist_file] [to_playlist_file]
The playlist_rename
command renames (i.e., moves) the specified playlist file to a new name. Both the “from” and “to” playlist_files
are required to use a relative path under the presentation playlist directory ~/sosrc and the “to” playlist_file
cannot be for an existing file. Existing subdirectories within ~/sosrc may be specified, but new subdirectories are not created by this command.
playlist_rename myplaylist.sos mysubdir/myplaylist2.sos
Moves myplaylist.sos
to mysubdir/myplaylist2.sos
. The subdirectory mysubdir/
must already exist.
playlist_write
Permalink to playlist_writeplaylist_write [playlist_file] [playlist_text]
The playlist_write
command writes a playlist-formated text string into the specified playlist file, creating it, if necessary. Ends of lines in the text are indicated by “\n”. The playlist is required to use a relative path under the presentation playlist directory ~/sosrc. Existing subdirectories within ~/sosrc may be specified, but new subdirectories are not created by this command.
playlist_write myplaylist.sos “# comment\ninclude=/shared/sos/media/site-custom/playlist.sos\n#> presenter note\n”
Writes the playlist data to myplaylist.sos
.
prev_clip
Permalink to prev_clipThe prev_clip
command stops any currently playing clip, clears the sphere, and plays the previous clip sequentially in the playlist. If the first clip was playing, it jumps to the last clip.
search_clip_list
Permalink to search_clip_listsearch_clip_list [search_term] [clip_list list_of_tags]
The search_clip_list
command is identical to the search_clip_list_from_file
command (see below). The only difference is the second parameter, clip_list. clip_list is a Tcl list of name-value pairs for a set of clips (for example, a list that is in the format returned by the get_clip_list_from_file
command).
search_clip_list_from_file
Permalink to search_clip_list_from_filesearch_clip_list_from_file [search_term] [playlist_file] [list_of_tags]
The search_clip_list_from_file
command searches through the name-value pairs of each clip in the playlist_file
and returns all of the name-value pairs of only those clips where each of the search terms were present somewhere in the clip’s values.
The first command argument is the term or terms to be searched for. Multiple search terms should be enclosed in quotation marks (ex. “carbon aerosol”).
The second command argument is the absolute path to a .sos playlist file.
The third command argument, list_of_tags, selects a specific name tag to search in the clip’s sos playlist file. There are three options:
name
Permalink to nameSearch only the values paired with the name tag.
keywords
Permalink to keywordsSearch only the values paired with the keywords tag.
The empty string means search all tags specified for the clip.
Multiple tags may be specified by enclosing them in quotation marks (ex. “name keywords”). Note that at least on of the above options must be specified.
In the return list of search results, each name tag in a name-value pair is prepended by the clip’s number in the playlist file (for example: 2,category
, where category is the name tag).
Note that there is one extra name-value pair for each clip that is always included in the list that is not found in the clip’s .sos file: 0,valid value
(where value is 0 or 1).
search_clip_list_from_file "helium sun" "~/sosrc/__library__/all.sos" name 196,publisher {NASA GSFC} 196,datadir /shared/sos/media/astronomy/helium_sun/helium_sun_2048.mp4 196,valid 1 196,name {Helium Sun} 196,pipcount 0 196,category astronomy 196,fps 30 196,creator {NASA GSFC}
Example: Searching the all.sos
playlist for the text “helium sun”.
set_auto_presentation_mode
Permalink to set_auto_presentation_modeset_auto_presentation_mode [0 | 1]
The set_auto_presentation_mode
turns on or off (0 = off, 1 = on) the auto presentation (or auto run) mode of SOS. While in auto presentation mode, the system automatically advances from one clip to the next. The system plays each clip the number of seconds that are specified by the timer value for that clip in the current playlist. If no timer value is specified for the clip, a system default time is used (typically 2 or 3 minutes per clip).
set_fadeout_duration
Permalink to set_fadeout_durationset_fadeout_duration [seconds]
The set_fadeout_duration
command sets the default duration in seconds for subsequent fadeouts.
set_fadein_duration
Permalink to set_fadein_durationset_fadein_duration [seconds]
The set_fadein_duration
command sets the default duration in seconds for subsequent fadeins.
Interactive commands
Permalink to Interactive commandsalignment
Permalink to alignmentalignment [alignment_subcommand]
Note: The alignment subcommands are reserved for use by SOS software to align the sphere. It is not recommended that third-party software make use of these commands, as they may change with any future SOS software release. They are documented here for informational purposes only.
annotation help
Permalink to annotation helpThis command describes the annotation command options.
annotation
Permalink to annotationannotation [subcommand]
The annotation command is used for interactive drawing on the sphere. The subcommand is a list of one or more of the following:
clear
Permalink to clearClears the annotation.
drawline
Permalink to drawlineannotation drawline [lat1,lon1,lat2,lon2,width,red,green,blue]
Draw a line based on the parameters that are provided for position, width and color. Parameters lat1,lon1 specify the starting latitude and longitude coordinate of the line, while lat2,lon2 specify the ending latitude and longitude coordinate. Parameter width specifies the width of the line in pixels. Parameters red, green, and blue specify the color of the line and the values of each RGB component may be from 0 to 255. The position of the drawn line is dependent on the current orientation and is not draw exactly to the latlon specified.
drawlineAbsolute
Permalink to drawlineAbsoluteannotation drawlineAbsolute [lat1,lon1,lat2,lon2,width,red,green,blue]
Draw a line based on the parameters that are provided for position, width and color. Parameters lat1,lon1 specify the starting latitude and longitude coordinate of the line, while lat2,lon2 specify the ending latitude and longitude coordinate. Parameter width specifies the width of the line in pixels. Parameters red, green, and blue specify the color of the line and the values of each RGB component may be from 0 to 255. The position of the drawn line is will be drawn to the latlon coordinates specified, regardless of sphere orientation.
labelvisible
Permalink to labelvisiblelabelvisible [1 | 0 | on | off]
This command turns the label text on (1) or off (0). New in SOS 5.3.
layer help
Permalink to layer helpThis command describes the layer command options
layer info
Permalink to layer infoThis command gives you information about layers in the currently loaded dataset, including PIPs and labels.
layer
Permalink to layerlayer [index] [subcommands]
This command lets you modify the existing layers. The index value can be top (the top layer), pip or label, or an integer layer index (zero-based). You can get this information by first issuing the layer info
command. The subcommands available are:
[name]
Permalink to [name]Renames the layer to the provided name.
Turns the layer off.
off
Permalink to offTurns the layer on alpha [0.0-1.0] ~ adjusts the transparency.
minzoom
Permalink to minzoomlayer [index] minzoom [float]
Adjusts the minimum zoom level.
maxzoom
Permalink to maxzoomlayer [index] maxzoom [float]
Adjusts the maximum zoom level.
east
Permalink to eastlayer [index] east [float]
Sets the east boundary of the layer.
west
Permalink to westlayer [index] west [float]
Sets the west boundary of the layer.
north
Permalink to northlayer [index] north [float]
Sets the north boundary of the layer.
south
Permalink to southlayer [index] south [float]
Sets the south boundary of the layer.
delete
Permalink to deleteDeletes the layer.
pointer
Permalink to pointerpointer [subcommand]
The pointer command takes multiple arguments for manipulating the state of the associate sphere image.
Turns on the pointer, making it visible on the sphere.
off
Permalink to offTurns off the pointer, making it disappear from the sphere.
red
Permalink to redMakes the pointer image a red simulated laser pointer.
green
Permalink to greenMakes the pointer image a green simulated laser pointer.
grab
Permalink to grabMakes the sphere “stick” to the pointer, so the sphere data set moves as the pointer is moved.
ungrab
Permalink to ungrabReleases the sphere after a pointer grab, so the sphere no longer moves with the pointer.
[lat,lon]
Permalink to [lat,lon]Moves the pointer to an absolute position specified by latitude,longitude. No white space is allowed in lat,lon.
[Dlat,lon]
Permalink to [Dlat,lon]Moves the pointer by an incremental “delta” latitude,longitude. No white space is allowed in Dlat,lon.
pointerimage
Permalink to pointerimagepointerimage [filename]
The pointerimage
command gives the name of an image file to use as the pointer image. This allows other types of pointers than the default red or green simulated laser pointer. This should be a png file with a transparent background.
pointersize
Permalink to pointersizepointersize [degrees]
The pointersize
command specifies the diameter of the simulated laser pointer image. The argument is the width and height of the underlying image, in degrees at the equator.
splitter help
Permalink to splitter helpThis command describes the splitter command options.
splitter info
Permalink to splitter infoThis command lists all the information about the current state of the splitter.
splitter
Permalink to splittersplitter [subcommands]
The splitter
command controls an interactive feature to split the sphere into 2-4 slices and replicate the section of data currently being displayed on the sphere at the center of the User Position (the red dot by default, or latlon below). The subcommands that are available are:
Turns the splitter on.
off
Permalink to offTurns the splitter off.
latlon
Permalink to latlonsplitter latlon [float,float]
Defines where the splitter should be centered.
slices
Permalink to slicessplitter slices [int]
Sets the number of slices.
write
Permalink to writeDisplays the splitter with the current settings.
zoom help
Permalink to zoom helpThis command describes the zoom command options.
zoom
Permalink to zoomzoom [subcommand]
The zoom
command sets and displays attributes of the virtual magnifying glass, which is used to zoom in on global sphere data. The subcommands that are available are:
Turns the zoom on.
off
Permalink to offTurns the zoom off.
factor
Permalink to factorzoom factor [float]
Defines the level of zoom.
winsize
Permalink to winsizezoom winsize [float]
Sets the size of the zoom window.
latlon
Permalink to latlonzoom latlon [float,float]
Set the position of the zoom window.
pips
Permalink to pipspips [on|off]
Show (on) or hide (off) the pips under the magnifying glass. Pips are not shown be default. If you would like them to be shown by default, set the environment variable SOS_MAGNIFY_PIPS to “on” or “off” in ~/sos_stream_control.config.
System Commands
Permalink to System Commandsbottommask
Permalink to bottommaskbottommask [on | off | lolat,hilat]
The bottommask
command turns the bottom sphere mask on or off, or specifies the latitude range over which the masking transitions from no masking to fully masked. It is used to provide a faded transition to the “black hole” at the bottom of the sphere where the projectors are not able to illuminate the sphere. It can help reduce rough edges and moire patterns, at the cost of decreasing the overall size of the illuminated sphere area.
exit
Permalink to exitThe exit
command closes the current client connection to the SOS system.
get_version_number
Permalink to get_version_numberThe get_version_number
command returns a string identifying the running version of SOS.
get_database_date
Permalink to get_database_dateThe get_database_date
command returns a string containing the timestamp of the SQLite database containing the SOS Data Catalog (the file path is /shared/sos/database/sos_sqlite.db). An example of the timestamp format is 2015-03-05 17:27:47.087217857 -0700, which corresponds to March 5, 2015, slightly after 5:27:47 PM in the Mountain Daylight Time zone (7 hours before GMT).
get_filenames_in_directory
Permalink to get_filenames_in_directoryget_filenames_in_directory [directory_name]
The get_filenames_in_directory
command returns a list of the files in the specified directory on the SOS system.
get_playlist_names_in_directory
Permalink to get_playlist_names_in_directoryget_playlist_names_in_directory [directory_name]
The get_playlist_names_in_directory
command returns a list of the playlist files in the specified directory on the SOS system. If directory_name
is not specified, the default playlist directory is used (~/sosrc). Note: Use of the directory_name
argument is currently not supported.
get_state
Permalink to get_stateget_state [timestamp]
This command returns a list of the SOS state variables that have changed since the specified timestamp. It is intended to provide a simple and efficient polled interface for updating a user interface to SOS. It returns a list of {name value} pairs. Each pair is enclosed in curly braces, and the individual pairs are delimited by spaces. One of the pairs is a timestamp that can be used for future calls.
To use get_state
in a polling loop, first call it with a timestamp value of 0. It returns the current value for all the available state variables, including the timestamp. Then when the returned time stamp is used in a future call, only values that have changed are returned (including a new timestamp).
help
Permalink to helpThe help
command returns a brief summary of all the automation control interface commands.
identify
Permalink to identifyidentify [on | off]
Note: This command is very likely to be discontinued.
The identify
command displays information on the sphere to identify the individual projectors by name: P1, P2, P3, or P4.
shutdown
Permalink to shutdownThe shutdown
command shuts down the running SOS software on the system.
topmask
Permalink to topmasktopmask [on | off | lolat,hilat]
The topmask
command turns the top sphere mask on or off, or specifies the latitude range over which the masking transitions from no masking to fully masked. It is used to provide a faded transition to the “black hole” at the top of the sphere where the projectors are not able to illuminate the sphere. It can help reduce rough edges and moire patterns, at the cost of decreasing the overall size of the illuminated sphere area.
Example
Permalink to ExampleHere is a trivial example of the automation interface, using telnet to establish an interactive session. Commands typed by the user are shown in bold.
[email protected]:~$ telnet localhost 2468 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. enable R get_clip_info * 1 Blue Marble - Hi-Res 2 Hurricane Season - 2005 3 Sea Surface Currents 4 Sea Surface Temperature NOAA Model (black land) 5 Sun: X-Ray - 2003 6 Mars 7 Tsunami Wave Propagation: Indian Ocean - December 26, 2004 8 Aerosols: Black Carbon and Sulfate 9 Climate Model: Temperature Change (GFDL a1b) - 1870 - 2100 10 Nighttime Lights 11 Air Traffic 12 NOAA Logo 13 Fossil Fuel: CO2 Release - 2011-2012 14 Surface Temperature R get_clip_number 1 get_frame_count 3600 get_frame_number 179 get_frame_number 504 exit Connection closed by foreign host. [email protected]:~$