                       Realtime TCL Command Reference
                       ------------------------------

APPLICATION COMMANDS
  These commands apply to the application itself, so they are used with
  a leading ".".

  load_parameters

  save_parameters

  load_calibration <path>

  live_source_calibration
    Returns the currently loaded calibration

  live_source_timecode_rate [-raw]
    Returns the current timecode rate. By default it returns a standard
    rate name which is closest to them measured rate, or "unknown" if no
    standard rate is close to the measured rate.  If the -raw option is used,
    then the measured rate is returned.

  live_source_frame_rate
    Returns the current capture rate of the live source.

  set_viewpoint_focal_length <focal length>

  set_viewpoint_film_back <x> <y>

  need_redraw
    The scene will be redrawn the next time realtime is idle.

  current_field
    The current playback frame.

  scripts_dir
    Returns the directory where the realtime Tcl scripts are stored
    (deprecated).

  find_script <filename>
    Find a file with the given filename by looking in the Tcl directories.
    The directories to be searched are specified by the GIANT_TCL environment
    variable.  GIANT_TCL can contain multiple directories separated by
    colons.  GIANT_TCL can also refer to environment variables.  If there is no
    GIANT_TCL environment variable, the default is

      $GIANT_DATA_DIR/tcl:$GIANT_DIR/lib/tcl:<executable path>/lib/tcl

    In addition to the directories specified, subdirectories named "realtime"
    will also be searched.  For example, $GIANT_DATA_DIR/tcl/realtime will
    be checked before $GIANT_DATA_DIR/tcl.  The startup script is executed
    using this command:

      source [.find_script startup.tcl]

  frame_all
    Makes everything visible in the scene.

  delete_last_shape
    Delete the last shape created with the 2D drawing tools.

  open_sdlg
    Opens the secondary dialog.

  start_live_source
    Same as pressing "Start" on the main window.

  stop_live_source
    Same as pressing "Stop" on the main window.

  flush_live_source
    Save as pressing "Flush" on the main window.

  detach_live_source
    Stop receiving tracking data from rttrack

  attach_live_source
    Start receiving tracking data from rttrack

  reload_live_source
    Tell rttrack to reload all files

  snapshot_live_source [-completion_proc <proc>]
    Tell rttrack to make a snapshot

  live_source_is_active
    Returns 1 if the live source is currently active, otherwise 0.

  live_source_stats
    Returns the names and values of the live source statistics. For Example:
      {
        time_per_frame_percent 30
        single_point_count 5
        missing_point_count 3
        average_point_error 0.34
        unidentified_point_count 14
      }

  live_source_current_frame
    Returns the frame number of the latest frame of the live source that was
    tracked.

  live_source_acquired_frame
    Returns the frame number of the latest frame of the live source to have
    been received to track (which may not be tracked yet).

  start_recording
    Same as toggling on "Record" in the main window.

  charmap_project_is_empty
    Returns 1 if there is no target.

  save_charmap_project [-use_stored_vars] <cpj>
    If -use_stored_vars is specified, then the stored variable values will
    be used instead of the current variable values.  The stored variable
    values will contain the values of any curve variables the last time the
    take data was restarted, which occurs when the live source is first
    turned on, when it is flushed, or when it is reloaded.

  load_charmap_project [-no_window] <cpj>
    If -no_window is specified, then the charmapper window will not
    be automatically opened.

  load_charmap [-no_window] <cm>
    If -no_window is specified, then the charmapper window will not
    be automatically opened.

  clear_charmap

  load_charmap_lattice <ffd>
  load_charmap_curve <cdf>

  charmap_lattice_filename

  load_audio <wav>
    Loads the audio of the primary animation.

  clear_audio
    Removes the audio of the primary animation.

  set_full_frame_rate <rate>
    Sets the frame rate of the primary animation.

  load_additional_scalings [<scl> ...]
    Adds additinal scalings for the primary animation.

  set_scaling_weight <scaling number> <weight>
    Sets the weight of the given additional scaling.

  primary_anim
    Returns the anim object for the primary animation.

  secondary_anim
    Returns the anim object for the secondary animation.

  set_upper_overlay_text <text>

  upper_overlay_text

  target_anim
    Returns the anim object for the charmapper target anim

  stop_recording
    Same as toggling off "Record" in the main window.

  probtype
    Returns the current problem name from the live source setup dialog.

  set_field <frame id>
    Changes the current playback frame number to the given value.

  set_probtype <problem name>
    Changes the current problem name in the live source setup dialog.

  load_second_anim <animation filename>
    Loads a secondary animation.

  set_draw_mode (line|circle|angle|none)
    Sets the current 2D drawing tool.

  translate_secondary {<X> <Y> <Z>}
    Translates the secondary animation by the given amounts.  The parameter
    is a list of three real numbers defining the translation vector.

  roty_secondary <angle in degrees>
    Rotates the secondary animation about the Y axis at the origin by the given
    number of degrees.

  add_tool [-shortcut <shortcut>] <menu entry label> <TCL command>
    Adds a new entry to the Tools menu on the main window.  The given TCL
    command will be executed when the user selects that menu item.
    <menu entry label> can be of the form
    <menu1>|<menu2>|...|<name>, in which case
    a cascading menu is created where <name1> is a sub-menu of the Tools
    menu, <name2> is a sub-menu of <menu1>, etc., and finally <name> is
    the actual tool at the lowest level of the menu cascade.

    Example: .add_tool A|B|C my_tool

    This will create a menu A in the Tools menu with a sub-menu B
    that contains the menu item C.  Pressing C will execute my_tool.

    Example: .add_tool -shortcut Ctrl+F1 Test { puts "test" }

  set_live_source_param <param name> <value>
    Sets the given parameter for the current live source problem to the given
    value.

  set_live_source_pattern_tolerance <value>

  set_body_selected_proc [<TCL command>]
    If a TCL command is given as a parameter, the given command will be called
    after a body is selected.  If no TCL command is given, the body selected
    proc is removed.

  set_live_source_stop_proc [<proc>]
    Sets the proc to be called when the live source stops, or clears the proc
    if no proc is given.

  set_live_source_flush_proc [<proc>]
    Sets the proc to be called when the live source is flushed, or clears the
    proc if no proc is given.

  set_live_source_start_proc [<proc>]
    Sets the proc to be called when the live source is started, or clears the
    proc if no proc is given.

  set_live_source_adjust_proc [<TCL command>]
    If a TCL command is given as a parameter, the given command will be called
    after the live source frame has been received, but before it is displayed
    or recorded.  Adjustments can be made to the live source system variable
    values at that time using set_live_source_var_value.  If no TCL command
    is given, then the proc is removed.

  set_live_source_params_changed_proc [<TCL command>]
    If a TCL command is given as a parameter, the given command will be called
    after the live source parameters have changed.  This can happen due
    to a call to .set_probtype, or the user changing a parameter through
    the Edit Parameters window.  If no TCL command is given, then the
    proc is removed.

  add_live_source_param_changed_proc <Tcl command>
    Registers a proc to be called when a live source parameter changes.
    The parameter name and value are passed to the proc.

  remove_live_source_param_changed_proc <Tcl command>
    Removes a previously registered proc from the set of procs to be
    called when a live source parameter changes.

  set_live_source_var_value <system variable id> <value>
    Sets the value of the given system variable in the live source.  If this
    is done inside a live source adjust proc, then this change will take
    effect before the frame is displayed or recorded.

  set_live_source_subject_labels {<subject1 label> <subject2 label> ...}
    Sets the label for each subject.  These labels can be displayed using
    the "Show Subject Labels On Globals" option in Realtime.

  set_live_source_use_optical <bool>
    Enables or disables optical capture.  This can't be changed while live.
    If optical is disabled, an IMU must be enabled that has fixed world
    position and orientation which becomes the master IMU.  The master IMU
    then determines the frame rate for capture.

  live_source_subject_labels
    Returns the subject labels that were last set using
    .set_live_source_subject_labels

  live_source_var_value <system variable id>
    Returns the value of the given system variable for the last received
    live source frame.

  live_source_params
    Returns the current live source parameters as a list of lists.  Each
    sub-list is one parameter name and its value.

  load_anim <anim filename>
    Loads the given animation file as the primary animation.

  load_anim [<options>]
    Loads the given animation components as the primary animation.  The options
    are:
      -current            Use the current value for all components not given.
                          If this option is not given, no value will be used
                          for all components not given explicitly.
      -model <filename>   Use the given graphic model file.
      -map <filename>     Use the given graphic map file.
      -motion <filename>  Use the given motion file.
      -scaling <filename> Use the given graphic scaling file.

  load_target_anim <anm>
    Loads the given animation as the target.

  clear_target_anim

  set_primary_root_scale_factors {[<scale> ...]}
    Sets the scale factors on the roots of primary animation.  This only
    has an effect when using charmapper.

  open_secondary_anim <anm>
    Adds the given animation as a secondary animation.

  export_charmap_branch <body> <path>
    Exports a charmap that just applies to the given target body and its
    descendants.

  set_gssd_mark_received_proc [<proc>]
    Makes it where the given proc will be called when a mark is received,
    or if no proc is given, clears the current proc.

  set_gssd_attachments_changed_proc [<proc>]
    Makes it where the given proc will be changed when the gssd attachments
    are changed, or clears the current proc if no proc is given.

  last_received_gssd_mark_data
    Returns the type, frame, and description of the latest received mark.
    This is useful in combination with set_gssd_mark_received_proc.

  last_gssd_attachments
    Returns the list of attachments for each subject. This is useful in
    combination with set_gssd_attachments_changed_proc.

  set_gssd_attachments {[<attachment> ...]}
    Sets the current attachments.

  set_gssd_property <property name> {[<root value> ...]}
    Sets the given property for each root.

  set_gssd_auto_timecode_rate_property_enabled <bool>
    When enabled, a TCRate property is automatically put on every root,
    and updated whenever the live source timecode rate changes.
    When disabled, the TCRate property is removed.
    This is enabled by default.

  set_gssd_auto_frame_rate_property_enabled <bool>
    When enabled, a FrameRate property is automatically put on every root,
    and updated whenever the live source frame rate changes.
    When disabled, the FrameRate property is removed.
    This is enabled by default.

  set_gssd_timecode_rate_property <value>
    Sets the TCRate property on all roots.
    Auto updating must be disabled before calling this.
    Setting the property to an empty string removes it.

  set_gssd_frame_rate_property <value>
    Sets the FrameRate property on all roots.
    Auto updating must be disabled before calling this.
    Setting the property to an empty string removes it.

  set_gssd_timecode_rate_property_auto_update <bool>
    Turns on or off auto updating of the TCRate property.  If turned off,
    the property remains at its current value until changed explicitly.

  set_gssd_frame_rate_property_auto_update <bool>
    Turns on or off auto updating of the FrameRate property.  If turned off,
    the property remains at its current value until changed explicitly.

  send_gssd_mark <mark name>
    Sends the given mark to all GSSD clients.

  gssd_master_client
    Returns the IP address of the client that is the master.  Returns an
    empty string if there is no master client

  set_gssd_master_client_changed_proc [<TCL command>]
    If a TCL command is given as a parameter, the given command will be called
    when the master client changes.  If no TCL command is given, the callback
    is removed.

  set_gssd_master_client <IP Address>
    Forces the master to be the first client with the given IP address.
    If no client has that address, then an error is returned.
    If <IP Address> is an empty string, then there becomes no forced master
    client; however, this does not prevent clients from being the master.

  gssd_clients
    Returns a list of IP addresses for the GSSD clients which are currently
    connected.

  disconnect_gssd_client <IP Address>
    Disconnects the first client that has the given IP address.  Gives an
    error if there is no client with the given address.

  set_gssd_connect_verify_proc [<proc name>]
    Sets up a proc that will be called whenever a client tries to connect.
    The IP address of the client is passed as the first parameter.  The
    proc should return 1 to allow the client to connect or 0 to disallow it.
    If <proc name> is omitted, then the current proc is removed, and clients
    from any IP address will be allowed to connect again.

  move_viewpoint_to_body <body>
    Moves the viewpoint so that it aligns with the given body.

  playback_range
    Returns the first and last frame of the master range.

  realtime_version
    Returns the version of the application in the form:
      {<major> <minor> <patch>}

SCENE COMMANDS
  The commands apply to the scene manipulator.  All of these commands are
  preceded by ".scene_manip."

  center_view_on_rot_axes
    Translates the view so that the rotation axes are in the center of the
    screen.

  redraw
    Forces an immediate redraw of the scene.

  draw_all_axes
    Displays the local axes for all bodies.

  clear_all_axes
    Turns off the display of local axes for all bodies.

  label_all_axes
    Turns on axis labelling.

  body_is_selected
    Returns a boolean indicating if a body is selected.

  clear_selected_bodies
    Makes there be no selected body.

  hide_selected_body
    Hides the currently selected body.

  selected_body
    Returns the currently selected body.

  selected_animation
    Returns the animation of the currently selected body.

  hide_all_but_selected_body
    Hides all bodies except the selected body.

  hide_selected_body_to_root
    Hides the selected body and all its ancestor bodies.

  unhide_selected_body
    Unhides the selected body.

  hide_selected_body_all
    Hides all bodies that share the same root as the selected body.

  hide_selected_body_with_desc
    hides the selected body and all descendant bodies (bodies that have
    the selected body as an ancestor).

  unhide_all_bodies
    Makes no body be hidden.

  field_of_view
    Returns the current field of view.

  rotx <angle in degrees>
    Performs a relative X rotation of the scene.

  roty <angle in degrees>
    Performs a relative Y rotation of the scene.

  unhide_anim_bodies <animation>
    Unhides all bodies in the given animation.

  aim_at_anim_point {<X> <Y> <Z>}
    Translate the view so that the given point in the scene is in the
    center of the screen.  The parameter is a list of three numbers giving the
    coordinates.

  set_field_of_view <angle in degrees>
    Changes the field of view to the given value.

  select_body <anim> <body id>
    Selects the given body.

  unhide_body <anim> <body id>
    Unhides the given body.

  move_rot_axes_to <anim> <body id>
    Moves the rotation axes to the origin of the given body.

  set_far_clip <distance>
    Changes the distance of the far clipping plane.

  set_near_clip <distance>
    Changes the distance of the near clipping plane.

ANIMATION COMMANDS
  The follow commands apply to animations, so they are preceded by the
  animation object and a ".".   (ex.  .top_anim.anim1.command)

  add_sub_anim
    Adds an empty sub-animation to the animation.

  num_anims
    Returns the number of sub-animations of the animation.

  transformation
    Returns the transformation of the animation relative to its parent
    animation.

  load_model <filename>
    Loads the given graphic model into the animation.

  save_model <filename>
    Saves the model with the given filename.

  save_mapping <filename>
    Saves the mapping with the given filename.

  save_scaling <filename>
    Saves the scaling with the given filename.

  load_mapping <filename>
    Loads the given graphic mapping into the animation.

  load_motion <filename>
    Loads the given motion into the animation.

  hide_body <body id>
    Hides the body with the given id in the animation.

  unhide_body <body id>
    Unhides the body with the given id in the animation.

  set_transformation <matrix>
    Sets the transformation matrix of this animation relative to its parent
    animation.  The matrix is given as a list of lists.  The first list
    is the top row of the matrix, defining the X axis of this animation
    in its parent's coordinate system.  The second and third rows define
    the Y and Z axis.  The last row defines the translation of the
    origin of this animation in the parent animation's coordinate system.

  body_center_coordinates <body> <frame id>
    Gives the global coordinates of the center of the bounding box of the
    given body at the given frame.

  set_body_draw_axes <body id> <bool>
    Turns on/off local axis drawing for the body with the given id in the
    animation.

  local_to_global [-field <field id>] [-body <body>] <point>
    Returns the global coordinates of the given point given in coordinates
    local to the given body on the given field.  If no body is given, the
    selected body is used.  If no field is given, the current field is used.
    A field id of 0 can be used to indicate the reference position.

  model_filename

  mapping_filename

  motion_filename

  scaling_filename

  set_model_filename <mdl>
    If <mdl> is "", then the model will be considered unsaved.

  set_mapping_filename <dof>
    If <dof> is "", then the mapping will be considered unsaved.

  set_motion_filename <bmo>

  set_scaling_filename <scl>
    If <scl> is "", then the scaling will be considered unsaved.

  playback_range
    Returns the first and last frame of the given animation.

  sync_offset

  sync_ratio

  media_type

  open <anm>
    Replaces the animation with the one given.

  save <path>
    Saves the animation to the given path.

  set_casts_shadows (on|off|default)


MODEL COMMANDS
  The following commands apply to models and are preceded by the model object
  and a "." (ex. .top_anim.anim1.model.command)

  num_bodies
    Returns the number of bodies in the model.

  bodies
    Returns a list of all body objects in the model.

  body_ids
    Returns the list of ids of all the bodies in the model.


BODY COMMANDS
  The following commands apply to bodies and are preceded by the body object
  and a "." (ex. .top_anim.anim1.body5.command)

  name
    Returns the name of the body

  center_coordinates
    Returns the coordinates for the center of the bounding box of the body.
    The return value is a list of three numbers given the X,Y,and Z
    coordinates.

  id
    Returns the body id.

  children
    Returns a list of the child bodies

  descendants_ids
    Returns a list of all the body ids for all descendants of the body.

FLOOR COMMANDS
  The following commands apply to the floor of a scene, and are preced by
  ".scene_manip.floor." (ex. .scene_manip.floor.command)

  set_draw_surface <boolean>
    Turns on or off the drawing of the floor surface.

  set_draw_grid <boolean>
    Turns on or off the drawing of the floor grid.
