KSCONVERT - The Kinect Studio Clip Conversion Tool

  • Article

The Kinect Studio Clip Conversion tool (ksconvert.exe) is a command-line tool that is used to convert eXtended Raw Files (XRF) and eXtended Event Files (XEF). Uses of this tool include:

  • Converting raw data (XRF) into processed data (XEF)
  • Upgrading data from an older format to the current format
  • Transforming, decoding, or archiving/unarchiving data.

Clips that contain raw data captured directly from the sensor array are not directly usable by applications, whereas clips that contain processed data are usable by applications.

  • Syntax
  • Command Line Options
  • Usage Examples
  • Best Practices

Syntax

Run the conversion tool from the command line using the following syntax.

KSConvert.exe [options] source destination

Command Line Options

KSConvert.exe supports the following command-line options.

Option Description
/? Displays usage information.
/nologo Suppresses copyright messages.
/c Continues conversion in a batch even if an error is encountered while converting a file.
/s Searches the specified directory and all subdirectories for source files for conversion.
/archive Prepares clips for archival purposes by compressing the data at the individual stream-level. Some compression techniques are domain specific to maximize compression, thus yielding a much smaller file.
/unarchive Removes data compression of streams within a file, which will return the file to a playable state.
/DecodeColor Decodes a compressed color stream into an uncompressed color stream.
/StripColor Does not copy the color stream to the result file. Removing color can significantly decrease the size of the result file.
/pii Copies metadata marked as ‘personally identifiable information’ to the result file. All other metadata will be copied by default.
source Specifies a file to convert, either a raw capture (XRF) or a previously processed clip (XEF). This file may be located on the computer.
destination Specifies a name for the converted file.

Usage Examples

  • Convert a raw XRF into a processed XEF:

    ksconvert raw.xrf processed.xef

  • Convert an older, existing XEF into an upgraded, processed XEF:

    ksconvert existing.xef processed.xef

  • Compress a raw XRF on the computer and write the result file to a network share:

    ksconvert /compress d:\clips\rawIR.xrf \\myshare\compressedIR.xrf

  • Unarchive a raw XRF on a network share and strip color from the result file:

    ksconvert /unarchive /StripColor \\myshare\compressedIRColor.xrf \\myshare\RawIRNoColor.xrf

Best Practices

KSConvert.exe can perform the following operations:

  • Converting raw data (IR) into processed data (depth, IR, body).
  • Updating raw data (depth, IR, and body if the user was tracked) or a processed file (body if the user was tracked) to the latest data format.

The KSConvert.exe tool is updated periodically to work with the latest version of Kinect runtime. Use the tool to convert input data (either raw or processed) to data that matches the latest version of the Kinect runtime. This allows you to preserve your investment in capture clips. Perform the following steps:

  1. Record sensor data. E.g. Capture gestures and save them in a XRF/XEF file.
  2. Upgrade your computer to the latest SDK.
  3. Run KSConvert.exe on your existing XRF/XEF file. Any new SDK improvements are also added to the XEF file.
  4. Use the updated XEF file with the rest of the SDK tools.

Processed data files are significantly smaller than raw data files, but they are limited in the amount of Kinect data that can be regenerated. Be sure to save your raw data as you can use this tool to update them to the latest data format.

If long-term storage capacity is limited, be sure to archive the raw files before committing them to storage.