DART Xtra interface docs

• " videoInit string"
  • initialize the video subsystem, but don't open the camera yet.
  • The first parameter is the path the camera calibration data file.
• " videoOpen string"
  • Open the camera, start capturing.
  • The parameter is the camera configuration string.
• " videoReplaySize int, int, int"
  • Set the size of the video that will be fed in when replaying.
  • Not actually used during replay in DART, since we can replay without the xtra, but this is needed to support loading images into texture memory, or running the ARToolkit on them.
  • The parameters are the width, height and depth of the images.
• " videoFOV"
  • get the field of view of the camera.
  • -1.0 on error (camera not open)
• " videoWidth"
  • get the width (in pixels) of the video stream.
  • -1 on error (camera not open)
• " videoHeight"
  • get the height(in pixels) of the video stream.
  • -1 on error (camera not open)
• " videoDepth"
  • get the depth (in bits) of the video stream.
  • -1 on error (camera not open)
• " videoClose"
  • close the video subsystem.
• " videoDistortPoint int, int\n"
  • This method is used to distort the given x,y point using the current camera calibration file.
  • the first parameter is the x value of the (x,y) location for which to perform the undistortion.
  • the second paramter is the y value of the (x,y) location for which to perform the undistortion.
  • the return value is a list [float x, float y] of the resulting un-distorted values.
• " videoUndistortPoint int, int\n"
  • This method is used to undistort the given x,y point using the current camera calibration file.
  • the first parameter is the x value of the (x,y) location for which to perform the undistortion.
  • the second paramter is the y value of the (x,y) location for which to perform the undistortion.
  • the return value is a list [float x, float y] of the resulting un-distorted values.
• " videoSetDataDirectory string\n"
  • Define where on your hard disk the data directory is. All paths to marker pattern files and camera calibration files are relative to this directory.
  • The first parameter is the path.
• " videoMarkerTrackingInit string, int, string, int"
  • Initialize marker tracking on the video stream.
  • the first parameter is the path to the fiducial panel definition file. This file contains a list of all panels to use. You can add additional panels using the loadPanel command below.
  • the second parameter is the ARToolkit threshold value.
  • the third parameter is the lingo callback for marker poses.
    • For each marker panel found, a message will be sent of the form
      • int panelId, int timestamp, [r0c0, r0c1, r0c2, r0c3, r1c0, r1c1, r1c2, r1c3, r2c0, r2c1, r2c2, r2c3] poseMatrix
  • The fourth parameter is a boolean, saying if OpenCV should be used (should always be 1).
  • returns the number of fiducial panels (-1 on error)
• " videoLoadPanel string\n"
  • the first parameter is the path to a single fiducial panel file to be loaded and used. This panel is added to the list of known panels.
  • the panel number for this panel is returned.
• " videoSetThreshold int\n"
  • Set the threshold for the ARToolkit fiducial tracker. The threshold is a number from 0 to 255, which defines the brightness of a pixel above which it should be considered white (pixel brightness below this value are considered black).
• " useMarkerTrackingLite int\n"
  • Says whether to use the "lite" marker tracker (1) or not (0). The lite tracker does not take history into account, and should be used when there is a lot of noice and false recognition (which would cause problems with the history mechanism). When lighting is good, the history will cause the tracker to be smoother and have less drop-outs.
• " videoSetupVideoToTexture"
  • Find the texture to be used for background video. Assumes that the first large texture it finds is the correct one.
  • Returns the integer texture id.
• " videoGetNextFrame"
  • Read the next frame from the camera, saving it in the xtra.
  • Return 0 if there was no video, and the timestamp if there was a video frame.
• " videoFrameToTexture int"
  • Copy the currently saved video frame to the provided texture
• " videoTrackMarkers"
  • Run marker tracking on the saved video frame.
• " videoMarkerCornerRefinement int, int, float\n"
  • Sets the ARtoolkit to refine the corners before using the OpenCV tracker.
  • the first parameter is size, the radius in pixels of the window to look for the best corner in.
  • the second paramter is iterations, the maximum number of iterations to refine the estimate.
  • the third parameter is epsilon. If the pixel moves by less than this distance, stop refining.
  • The correct values depend on many factors (lighting, the distance between markers, etc.). A good start might be (2,4,0.01)
• " videoDebugMarkerTracking int\n"
  • The parameter is a boolean, indicating if debugging of the marker tracker should be turned on or not.
  • If debugging is on, the thresholded image is computed when the marker tracker is run, and small red, blue and green dots are placed in the image. If corner refinement is used, red and green dots show the crude and refined corners. If corner refinement is not used, blue dots show the corners used.
• " videoReplaceWithThresholded\n"
  • If the thresholded image was generated (debugging is on), replace the current video image in the DART xtra with the thresholded image. This can then be copied to an image cast member or loaded into texture memory for viewing.
• " videoFrameToImage object"
  • Copy the saved video frame to the provided image object
• " videoFrameFromImage object"
  • Copy the frame from the image object to become the saved video frame.
  • This only works if the camera has not been openned. The first time this is called, it creates a video frame buffer the size of the passed in image. After that, it checks to make sure each passed in frame is of the same size.
• " videoReleaseFrame"
  • Release the saved video frame. Must be called before videoGetNextFrame is called again after a frame has been saved.

• "vrpnGetCurrentTimestamp"
  • Return the current time using the same timestamps that the vrpn trackers and the marker trackers use
• " vrpnClientInit"
  • Initialize the vrpn subsystem. You should call this before using any other part of the VRPN subsystem.
• " vrpnServerInit string"
  • The first parameter is a string containing a vrpn.cfg file (see VRPN for examples of content), used by the server to create the appropriate tracker server objects. NOTE: if you have invalid trackers in the file, VRPN may try to continutally reinitialize them, which can be a huge performance hit since it happens synchronously. Make sure your vrpn.cfg is correct.
• " vrpnShutdown"
  • Shutdown the vrpn subsystem.
• " vrpnCheckMessages"
  • Check the vrpn system for messages. Send and receive all queued messages. Most likely this is when the vrpn callbacks will happen (although they can happen elsewhere). Call this frequently.

• " vrpnOpenRemoteTracker string, symbol, int"
  • Open a connection to a tracker.
  • The first parameter is of the form "name@host" where the name is the tracker name, and the host is the machine it's running on.
  • The second parameter is the callback to receive updates.
    • The callback takes 2 parameters (int trkId, data)
    • The data is of the form [ report, report, ...]
      • position report: [sensorNum, 1, timestamp, [x,y,z],[q0,q1,q2,q3]]
      • vel or accel report : [sensorNum, 2 or 3, timestamp, [x,y,z],[q0,q1,q2,q3,q4],delta]
  • The third parameter specifies if the tracker reports should be collected into a list before calling the callback (if 0, do not collect, if 1 collect). For fast remote trackers, you MUST set this to 1, as the vrpn subsystem could lock up the xtra reading reports from the tracker if the Lingo callback takes any non-trivial amount of time to return.
  • An integer tracker id is returned.
• " vrpnCloseRemoteTracker int"
  • Close the tracker with the id passed in the first parameter.
• " vrpnSetRemoteTrackerReportTypes int, int, int, int"
  • Set which report types we care about for a remote tracker. There is one parameter which is the tracker id, and then the remaining three are boolean parameters (0 or 1).
  • parameter 2 is for position reports
  • parameter 3 is for velocity reports
  • parameter 4 is for acceleration reports.
  • Note that very few trackers actually generate more than position reports. The default is to accept all 3.
• " vrpnOpenRemoteButton string, symbol, int"
  • Open a connection to a device with buttons on it.
  • The first parameter is of the form "name@host" where the name is the button device name, and the host is the machine it's running on.
  • The second parameter is the callback to receive updates.
    • The callback takes 2 parameters (int buttonId, [[int timestamp, int buttonNum, int buttonVal],...])
    • The buttonId is the id of the button object, returned when the remote button connection is opened.
    • The second parameter is a list of reports, each of which contains 3 values.
      • The timestamp is the time the button state changed.
      • The buttonNum is the button number that changed on that device, and buttonVal is the new state (typically 0 for off and 1 for on).
  • The third parameter specifies if the button reports should be collected into a list before calling the callback (if 0, do not collect, if 1 collect). For rapidly, continuously changing button devices, you should set this to 1, as the vrpn subsystem could lock up the xtra reading reports from the tracker if the Lingo callback takes any non-trivial amount of time to return.
  • An integer button id is returned.
• " vrpnCloseRemoteButton int"
  • Close the button with the id passed in the first parameter.
• " vrpnOpenRemoteAnalog string, symbol, int"
  • Open a connection to a device with analog sensors on it.
  • The first parameter is of the form "name@host" where the name is the analog device name, and the host is the machine it's running on.
  • The second parameter is the callback to receive updates.
    • The callback takes 2 parameters (int analogId, [[int timestamp, [float sensorVal, float sensorVal, ...],...])
    • The analogId is the id of the analog object, returned when the remote analog connection is opened.
    • The second parameter is a list of reports, each of which contains 2 values.
      • The timestamp is the time the analog state changed.
      • The second element is a list of floating point values, between -1.0 and 1.0, one for each analog sensor the device has. A new report is generated when any sensor changes.
  • The third parameter specifies if the analog reports should be collected into a list before calling the callback (if 0, do not collect, if 1 collect). For rapidly, continuously changing analog devices, you should set this to 1, as the vrpn subsystem could lock up the xtra reading reports from the device if the Lingo callback takes any non-trivial amount of time to return.
  • An integer analog id is returned.
• " vrpnCloseRemoteAnalog int"
  • Close the analog with the id passed in the first parameter.

• " vrpnCreateManualTracker int, string"
  • Create a tracker server that we will manually feed reports to.
  • The first parameter is the the number of sensors.
  • The second parameter is the name of the tracker.
  • An integer tracker id is returned.
• " vrpnCloseManualTracker int"
  • Close a manual tracker, with the id specified in the parameter.
• " vrpnAddManualTrackerReport int, list"
  • Add a report to the manual tracker.
  • Parameters: int trackerId, list data
  • data: list of list of reports formatted as below:
    • [ [report], [report], ... ]
    • formatting of each report:
    • 1: position report
      • [sensorid, 1, timestamp, [pos,pos,pos],[quat,quat,quat,quat]],
    • 2: velocity report
      • [sensorid, 2, timestamp, [vel,vel,vel], [quat, quat, quat, quat], delta]
    • 4: acceleration report
      • [sensorid, 4, timestamp, [acc,acc,acc], [quat, quat, quat, quat], delta]
  • The timestamp is an integer, and is appoximately the milliseconds since Director was opened. This is the scale of time that is used by the callbacks with other tracker reports, and by the callbacks for the marker tracking pose estimates. If timestamp is 0, the current time is used.

• " vrpnCreateSharedInteger string, int, symbol"
  • Create a shared integer object server.
  • parameter 1 is the name of the object
  • parameter 2 is the initial value
  • parameter 3 is the callback function for updates
    • the function takes 2 parameters (int objectId, int newValue)
  • returns the integer id for the object
• " vrpnCreateSharedFloat string, float, symbol"
  • Create a shared float object server.
  • parameter 1 is the name of the object
  • parameter 2 is the initial value
  • parameter 3 is the callback function for updates
    • the function takes 2 parameters (int objectId, float newValue)
  • returns the integer id for the object
• " vrpnCreateSharedString string, string, symbol"
  • Create a shared string object server. Strings can have at most 1000 characters.
  • parameter 1 is the name of the object
  • parameter 2 is the initial value
  • parameter 3 is the callback function for updates
    • the function takes 2 parameters (int objectId, string newValue)
  • returns the integer id for the object
• " vrpnOpenRemoteSharedInteger string, symbol"
  • Create a connection to a remote shared integer object.
  • parameter 1 is the name of the object and the host, "name@host"
  • parameter 2 is the callback function for updates
    • the function takes 2 parameters (int objectId, int newValue)
  • returns the integer id for the object
• " vrpnOpenRemoteSharedFloat string, symbol"
  • Create a connection to a remote shared float object.
  • parameter 1 is the name of the object and the host, "name@host"
  • parameter 2 is the callback function for updates
    • the function takes 2 parameters (int objectId, float newValue)
  • returns the integer id for the object
• " vrpnOpenRemoteSharedString string, symbol"
  • Create a connection to a remote shared string object. Strings can have at most 1000 characters.
  • parameter 1 is the name of the object and the host, "name@host"
  • parameter 2 is the callback function for updates
    • the function takes 2 parameters (int objectId, string newValue)
  • returns the integer id for the object
• " vrpnCloseSharedObject int"
  • close the object with the id in the parameter
• " vrpnSetSharedObjectValue int, any"
  • Set the value of a shared object (server or remote).
  • parameter 1 is the object id
  • parameter 2 is the new object value
• " vrpn_asin float"
  • convenience function. return the arc sin of the parameter.
• " vrpn_acos float"
  • convenience function. return the arc cos of the parameter.
• " vrpn_atan float"
  • convenience function. return the arc tan of the parameter.
• " vrpn_atan2 float,float"
  • convenience function. return the arc tan of the 2 parameters.
• " vrpn_quat_to_euler list"
  • convenience function. return the 3 euler angles corresponding to the quaternion passed in.
• "vrpn_quat_to_matrix list\n"
  • convenience function. convert a [x,y,z,w] quaternion to a 16 element list containing the elements of a column-major rotation matrix.
• "vrpn_matrix_to_quat list\n"
  • convenience function. convert a 16 element list containing the elements of a column-major rotation matrix to a [x,y,z,w] quaternion.
• "vrpn_quat_slerp list, list, float\n"
  • Do a quaternion slerp (interpolation).
  • The first parameter is the first quaterion [x,y,z,w]
  • The second parameter is the second quaternion [x,y,z,w]
  • The third parameter is the interpolation amount of 0 (param 1) to 1 (param 2).
  • The return value is the interpolated quaternion [x,y,z,w]
• "vrpn_lla_to_utm list\n"
  • Calculate the UTM coordinates for a given LLA coordinate set
  • The first parameter is LLA, a list [long,lat,alt] of three floats.
  • The return value is the UTM coordinates in a list of 5 values: [float utmX, float utmY, float alt, int xZone, string Yzone].
• "vrpn_utm_to_lla list\n"
  • Calculate the LLA coordinates for a given UTM coordinate set
  • The first parameter is the UTM coordinates in a list of 5 values: [float utmX, float utmY, float alt, int xZone, string Yzone].
  • The return value is LLA, a list [long,lat,alt] of three floats.