Revision as of 09:48, 29 March 2016

Overview

iPi Integration Add-on allows to control iPi Recorder and iPi Mocap Studio from external application by sending JSON commands via Windows dll. It can be used for:

Using iPi Recorder and iPi Mocap Studio as a part of a third-party solution
Automation of repeatable tasks
Automation of custom workflow

Note: iPi Integration Add-on requires separate license key, which you need to activate in iPi Mocap Studio. 30-days free trial provided.

License and Trial

iPi Integration Add-on requires separate license key, which you need to activate in iPi Mocap Studio. You can order your license here, or activate 30-days free trial. Follow the steps below to start working with iPi Integration Add-on

Select menu item Help > Manage Licenses > Integration Add-on.
Press Start 30-days Free Trial Period or Enter Integration Add-on License Key and follow further on-screen instructions

Note: To use iPi Integration Add-on with iPi Recorder, you have to install iPi Mocap Studio on the same computer and activate iPi Integration Add-on following the instructions above. You do not need to activate any other keys (Main or Biomech Add-on), if you do not plan to perform tracking on this computer.

Using iPi Integration Add-on

Communication Library

In order to enable communication with iPi Recorder and/or iPi Mocap Studio, your program should use the library iPiMocapIntegration.dll.

Redistributable Contents

Redistributable of the library has the following structure:

bin Binary files to redistribute with your program. The library itself accompanied by PDB file, and C runtime library msvcr120.dll.
- x86 32-bit version
- x64 64-bit version
include Header files for the library. May be used directly in C/C++ programs, or as reference for making proper binding to DLL for other programming languages.
lib Static library files for linking with C/C++ programs.
- x86 32-bit version
- x64 64-bit version
samples Samples of library usage. Currently only for Visual C++ 2013.

API

This library provides a general way of communication with supported applications. A client program establishes a connection to an application. Then, using this connection, it sends commands to the application. After executing a command, the application synchronously sends a response to that command back to a client program. Also, through the same connection, the application asynchronously notifies a client program about occurring events, such as the end of a long-running operation.

Each application has its own set of commands and events. Specific commands/events are out of scope of this library and should be handled in code using it.

Connecting and Disconnecting

iPi_Result iPi_ConnectToRecorder(LPCWSTR executablePath, iPi_EventCallback fnEventCallback, LPHANDLE phConnection);
iPi_Result iPi_ConnectToMocapStudio(LPCWSTR executablePath, iPi_EventCallback fnEventCallback, LPHANDLE phConnection);

Parameter	Description
executablePath	Path to executable file of an application. Optional.
fnEventCallback	Pointer to a function which handles events coming from an application. Optional.
phConnection	Receives a connection handle. Required.

Functions iPi_ConnectToRecorder and iPi_ConnectToMocapStudio are used to establish connections to corresponding applications.

First, they try to connect to already running application instance if any. An application will refuse the connection if it already has other connection with some client.

If there are no running instances of the application, or they all refuse connection, then a new instance of the application is launched. If executablePath parameter is specified, then it is used to run the application. Otherwise, the function looks for path to an application in file associations and standard installation directory.

When connection is fully operational, its handle is returned in phConnection parameter. This handle is used in all subsequent calls for this connection.

Parameter fnEventCallback specifies a function to handle asynchronous application events. See the section about events below.

iPi_Result iPi_Disconnect(HANDLE hConnection);

Parameter	Description
hConnection	Connection handle. Required.

iPi_Disconnect closes previously open connection and frees all associated resources.

The function does not close the application itself. To do this, send an exit command specific to the application.

Sending Commands

iPi_Result iPi_ExecuteCommand(HANDLE hConnection, LPCWSTR jsonCommand, LPWSTR* pJsonResponse);

Parameter	Description
hConnection	Connection handle. Required.
jsonCommand	Command string. Required.
pJsonResponse	Receives a response string. Required.

iPi_ExecuteCommand is used to send a command to the application. Parameter jsonCommand contains the command to send.

Response received from the application is placed into pJsonResponse. When not needed anymore, the returned response string should be freed with iPi_Free function.

Consuming Events

To consume asynchronous events coming from the application, client code should specify address of a callback function in fnEventCallback parameter when opening a connection. If callback is not specified, then application events will be discarded. The type of event callback is defined as follows:

typedef void (WINAPI *iPi_EventCallback)(HANDLE hConnection, LPWSTR jsonEvent);

Parameter	Description
hConnection	Connection handle.
jsonEvent	Event string.

Every time an event comes from the application, the library calls this callback function. An event string is passed in jsonEvent parameter. When not needed, this string should be freed with iPi_Free function.

A callback is invoked on a thread from the process's thread pool. Each invocation may be on another thread, and multiple invocations may take place in the same time. So pay attention to proper thread synchronization in code.

Error Codes

Most of API functions has return type iPi_Result, which is enumeration representing error codes. The numeric values of the constants can be found in header file iPiTypes.h.

Constant	Description
IPI_OK	Operation succeeded.
IPI_GENERAL_ERROR	Some error has occurred, for which there is no more specific error code.
IPI_INVALID_PARAM	Invalid parameter value in a call to a function.
IPI_OUT_OF_MEMORY	Not enough memory to complete an operation.
IPI_CONNECTION_BROKEN	Connection to an application has been broken. Should call iPi_Disconnect on this one and establish a new connection if needed.
IPI_CANNOT_START_APP	Application executable file was not found or other problem when starting application.
IPI_CANNOT_CONNECT	Application is not running or does not accept connections. For example, its an old version of the application which does not support connections. Or limit on connections is reached.
IPI_INVALID_DATA	Invalid data read from a connection.

Miscellaneous

BOOL iPi_Free(LPVOID ptr);

Function iPi_Free should be used to free memory blocks that are allocated by the library and passed to client code, when they are not needed anymore. This includes response strings when executing commands and event strings when consuming events.

Command Syntax

Commands are strings based on JSON syntax. Commands are submitted via JSON requests that include command name and may optionally include command arguments.

The response is also JSON string. The response include success flag. In case of error the response include error message. In case of success the response may optionally include result that is JSON object.

Long actions (recording, background evaluation, etc.) initiated by commands generate asynchroneous events on action completion. Event is described by JSON string that include event name and may include optional arguments, depending on type of event.

SYNOPSIS

// Request for command without arguments
{
    "command": "<command_name_string>"
}
 
// Request for command with arguments
{
    "command": "<command_name_string>",
    "arguments": 
    {
        <arguments_list_json_string>
    }
}
 
// Simple response in case of success
{
    "success": true
}
 
// Response including command result field in case of success
{
    "success": true,
    "result":
    {
      <result_json_string>
    } 
}
 
// Response in case of error
{
    "success": false,
    "error": "<error_message_string>"
}
 
// Event without arguments
{
    "event": "<event_name_string>"
}
 
// Event including arguments
{
    "event": "<event_name_string>",
    "arguments": 
    {
        <arguments_list_json_string>
    }
}

iPi Recorder Commands

General Commands

get-app-info

get-app-info command returns the name of application and its version.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
`appName`	string	mandatory	`iPi Recorder 3`	Application name.
`appVersion`	string	mandatory	Version number in the format `XX.XXX.XXX.XXX`	Application version number.

EXAMPLE

// Request
{
    "command": "get-app-info"
}
 
// Response
{
    "success":true,
    "result":
    {
        "appName": "iPi Recorder 3",
        "appVersion": "99.876.543.210"
    }
}

open-studio

open-studio command opens iPi Mocap Studio and creates the project from specified .iPiVideo file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path of .iPiVideo file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-studio",
    "arguments": 
    {
        "filePath": "D:\\iPiMocap\\test_record.iPiVideo"
    }
}
 
// Response
{
    "success": true
}

exit

exit command closes iPi Recorder.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "exit"
}
 
// Response
{
    "success": true
}

Recording Commands

open-home-screen

open-home-screen opens HOME screen of iPi Recorder.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-home-screen"
}
 
// Response
{
    "success": true
}

refresh-device-list

refresh-device-list returns the list of available devices.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Array of JSON objects, each representing recording device. Fields of array items:
`kind`	string	mandatory	`camera` `depth-sensor` `microphone`	Device type.
`model`	string	mandatory	Supported device model	Device model.
`id`	string	mandatory	Unique string, format depends on device model	Unique string that is used to identify recording devices in open-recorder command.
`selected`	boolean	mandatory	`true false`	Device selected status.
`failed`	boolean	mandatory	`true false`	Device failed status.
`error`	string	optional	Error message string	Error message if device is in failed status.

EXAMPLE

// Request
{
    "command": "refresh-device-list"
}
 
// Response
{
    "success":true,
    "result":
    [
        {
            "kind": "camera",
            "model": "PlayStation Eye",
            "id": "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&2ed872d7&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}",
            "selected": false,
            "failed": false
        },
        {
            "kind": "depth-sensor",
            "model": "Kinect 2 for Windows",
            "id": "Default Kinect 2",
            "selected": true,
            "failed": true,
            "error": "Is not available"
        },    
        {
            "kind": "microphone",
            "model": "USB Camera-B4.04.27.1",
            "id": "Microphone (USB Camera-B4.04.27 [VID=-1; PID=-1; Driver=256; Channels=2; Supports=WAVE_FORMAT_11M08, ...]",
            "selected": false,
            "failed": false
        }
    ]
}

open-recorder

open-recorder selects devices for recording and switches to SETUP stage.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`selectedDevices`	string array	mandatory	List of device id strings	Selecting devices for recording. Device ids are returned by refresh-device-list command.
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-recorder"
    "arguments":
    {
        "selectedDevices":
        [
            "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&2ed872d7&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}",
            "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&1c1ec232&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}"
        ]
    }    
 
}
 
// Response
{
    "success":true
}

evaluate-background

evaluate-background runs background evaluation.

Tip: If parameter is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`duration`	number	optional	Integer number of seconds from 2 to 10	Setting duration of background evaluation.
`startDelay`	number	optional	Integer number of seconds from 0 to 30	Setting start delay for background evaluation.
Result
Empty result
Events
background-evaluation-stopped event is generated when background evaluation is competed or cancelled
`success`	boolean	mandatory	`true false`	Success flag. Set to `true` if background evaluation was completed successfully.
`cancelled`	boolean	mandatory	`true false`	Cancellation flag. Set to `true` if background evaluation was cancelled by user or due to error.

EXAMPLE

// Request
{
    "command": "evaluate-backgorund",
    "arguments": 
    {
        "duration": 3,
        "startDelay": 1
    }
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "background-evaluation-stopped",
    "arguments":
    {
        "success": true,
        "cancelled": false
    }
}

open-record-screen

open-record-screen opens RECORD screen of iPi Recorder.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-record-screen"
}
 
// Response
{
    "success": true
}

start-recording

start-recording starts recording.

Tip: If parameter is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	optional	Valid file path	Full path to destination file for recording.
`startDelay`	number	optional	Integer number of seconds from 0 to 60	Setting start delay for recording.
Result
Empty result
Events
recording-stopped event is generated when recording is stopped
`success`	boolean	mandatory	`true false`	Success flag. Set to `true` if background evaluation was completed successfully.
`cancelled`	boolean	mandatory	`true false`	Cancellation flag. Set to `true` if background evaluation was cancelled by user or due to error.
`filePath`	string	mandatory	Valid file path	Full path to destination file.
`fileSize`	number	mandatory	Non-negative integer	Size of the recorded file in bytes.
`duration`	string	mandatory	Timespan value in format `hh:mm:ss.sssssss`	Duration of the recording.
`frameCount`	number	mandatory	Non-negative integer	Number of the recorded frames.

EXAMPLE

// Request
{
    "command": "start-recording",
    "arguments": 
    {
        "filePath": "D:\\iPiMocap\\test_record.iPiVideo",
        "startDelay": 1
    }
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "recording-stopped",
    "arguments":
    {
        "success": true,
        "cancelled": false,
        "filePath": "D:\\iPiMocap\\test_record.iPiVideo",
        "fileSize": 39975560,
        "duration": "00:00:04.0155425",
        "frameCount": 197
    }
}

stop-recording

stop-recording command stops recording.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
recording-stopped event is generated when recording is stopped
`success`	boolean	mandatory	`true false`	Success flag. Set to `true` if background evaluation was completed successfully.
`cancelled`	boolean	mandatory	`true false`	Cancellation flag. Set to `true` if background evaluation was cancelled by user or due to error.
`filePath`	string	mandatory	Valid file path	Full path to destination file.
`fileSize`	number	mandatory	Non-negative integer	Size of the recorded file in bytes.
`duration`	string	mandatory	Timespan value in format `hh:mm:ss.sssssss`	Duration of the recording.
`frameCount`	number	mandatory	Non-negative integer	Number of the recorded frames.

EXAMPLE

// Request
{
    "command": "stop-recording"
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "recording-stopped",
    "arguments":
    {
        "success": true,
        "cancelled": false,
        "filePath": "D:\\iPiMocap\\test_record.iPiVideo",
        "fileSize": 39975560,
        "duration": "00:00:04.0155425",
        "frameCount": 197
    }
}

get-devices-state

get-devices-state returns the state and statistics for all selected devices.

Tip: This command is used to make sure recording process is ok. You can use it before and after recording.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Array of JSON objects, each representing selected device. Fields of array items:
`kind`	string	mandatory	`camera` `depth-sensor` `microphone`	Device type.
`model`	string	mandatory	Supported device model	Device model.
`id`	string	mandatory	Unique string, format depends on device model	Unique string that is used to identify recording devices in open-recorder command.
`selected`	boolean	mandatory	`true false`	Device selected status.
`failed`	boolean	mandatory	`true false`	Device failed status.
`error`	string	optional	Error message string	Error message if device is in failed status.
`statistics`	JSON object	optional		Camera statistics.
`frameRate`	number	mandatory	Double	Average frame rate.
`frameDropsPerSecond`	number	mandatory	Double	Average frame drops per second.
`badFramesPerSecond`	number	mandatory	Double	Average bad frames per second.
`totalFrameDrops`	number	mandatory	Integer	Total frame drops.
`totalBadFrames`	number	mandatory	Integer	Total bad frames.

EXAMPLE

// Request
{
    "command": "refresh-device-list"
}
 
// Response
{
    "success":true,
    "result":
    [
        {
            "kind": "camera",
            "model": "PlayStation Eye",
            "id": "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&2ed872d7&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}",
            "selected": true,
            "failed": false,
            "statistics":
            {
                "frameRate": 50.0,
                "frameDropsPerSecond": 0.0,
                "badFramesPerSecond": 0.0,
                "totalFrameDrops": 0,
                "totalBadFrames": 0
            }        
        },
        {
            "kind": "microphone",
            "model": "USB Camera-B4.04.27.1",
            "id": "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&1c1ec232&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}",
            "selected": true,
            "failed": false,
            "statistics":
            {
                "frameRate": 50.0,
                "frameDropsPerSecond": 0.0,
                "badFramesPerSecond": 0.0,
                "totalFrameDrops": 0,
                "totalBadFrames": 0
            }        
        }
    ]
}

get-recorder-props

get-recorder-props command gets current properties for setup, background and recording stages specified in user interface.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Properties for SETUP Stage:
`videoMode`	string	mandatory	Available modes depend on camera model.	Selected RGB video mode.
`videoModeList`	string array	mandatory	List of available modes depend on camera model.	Possible `videoMode` values.
`audioMode`	string	optional	Available modes depend on microphone model.	Selected audio mode. This field is included into the response, if microphone is selected.
`audeoModeList`	string array	optional	List of available modes depend on microphone model.	Possible `audioMode` values. This field is included into the response, if microphone selected.
`globalDeviceProps`	JSON object	optional		Device-specific list of properties visible in “SHARED SETTINGS” section of SETUP stage.
`PlayStation Eye: Darkening for Calibration`	string	optional	`"None"` `"Darkening"` `"Extra Darkening"`	Selected darkening mode for Sony PS3 Eye cameras. This field is included into the response, if Sony PS3 Eye camera is selected.
`PlayStation Eye: Darkening for Calibration/List`	string array	optional	List of available modes	Available darkening modes for Sony PS3 Eye cameras. This field is included into the response, if Sony PS3 Eye camera is selected.
`screensInRow`	number	mandatory	Integer from 1 to number of cameras	Selected number of screens in a row for multiple camera video view.
`screenLayout`	string	mandatory	For RGB cameras: `"Color"` For depth sensors: `"Depth"` `"Picture in picture"` `"Side by side"`	Selected screen layout.
`screenLayoutList`	string array	mandatory	Available screenLayout modes.	Available screen layout modes. Depend on type of selected cameras.
Properties for BACKGROUND Stage:
`backgroundEvaluationDuration`	number	mandatory	Integer number of seconds from 2 to 10	Selected duration of background evaluation.
`backgroundEvaluationStartDelay`	number	mandatory	Integer number of seconds from 0 to 30	Selected start delay for background evaluation.
`showEvaluatedBackground`	boolean	mandatory	`true false`	Selected show background mode.
Properties for RECORD Stage:
`recordingStartDelay`	number	mandatory	Integer number of seconds from 0 to 60	Selected start delay for recording.
`hideBackgroundWhenRecording`	boolean	mandatory	`true false`	Selected hide background mode.
`destinationFilePath`	string	mandatory	Valid file path	Selected full path to destination file for recording.
`colorCompression`	string	mandatory	`"None"` `"Background subtraction"` `"JPEG"`	Selected RGB video compression mode.
`jpegQuality`	number	mandatory	integer from 0 to 100	Selected JPEG quality for JPEG compression.
`depthCompression`	string	mandatory	`"None"` `"Background subtraction"`	Selected depth compression mode.
Result
Empty result

EXAMPLE

// Request
{
    "command": "get-recorder-props"
}
 
// Response
{
    "success": true,
    "result":
    {
        "videoMode": "640x480 color @ 50Hz",
        "videoModeList":
        [
            "640x480 color @ 60Hz",
            "640x480 color @ 50Hz",
            "640x480 color @ 40Hz",
            "640x480 color @ 30Hz",
            "640x480 color @ 25Hz",
            "320x240 color @ 60Hz",
            "320x240 color @ 50Hz",
            "320x240 color @ 37Hz",
            "320x240 color @ 30Hz"
        ],
        "screensInRow": 1,
        "screenLayout": "Color",
        "screenLayoutList":
        [
            "Color"
        ],
        "globalDeviceProps":
        {
            "PlayStation Eye: Darkening for Calibration": "None",
            "PlayStation Eye: Darkening for Calibration/List":
            [
                "None",
                "Darkening",
                "Extra Darkening"
            ]
        },
        "backgroundEvaluationStartDelay": 5,
        "backgroundEvaluationDuration": 2,
        "showEvaluatedBackground": false,
        "recordingStartDelay": 1,
        "hideBackgroundWhenRecording": true,
        "destinationFilePath": "D:\\iPiMocap\\<time stamp>.iPiVideo",
        "colorCompression": "Jpeg",
        "jpegQuality": 100,
        "depthCompression": "BackgroundSubtraction"
    }
 
}

set-recorder-props

set-recorder-props command sets properties for setup, background and recording stages.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
Properties for SETUP Stage:
`videoMode`	string	optional	Available modes depend on camera model.	Setting RGB video mode. You can see available modes in "Video Mode" combobox at SETUP stage, or get it in the result of get-recorder-props command.
`audioMode`	string	optional	Available modes depend on microphone model.	Setting audio mode. You can see available modes in "Audio Mode" combobox at SETUP stage, or get it in the result of get-recorder-props command.
`globalDeviceProps`	JSON object	optional		Device-specific list of properties visible in “SHARED SETTINGS” section of SETUP stage.
`PlayStation Eye: Darkening for Calibration`	string	optional	`"None"` `"Darkening"` `"Extra Darkening"`	Darkening mode for Sony PS3 Eye cameras
`screensInRow`	number	optional	Integer from 1 to number of cameras	Setting number of screens in a row for multiple camera video view.
`screenLayout`	string	optional	For RGB cameras: `"Color"` For depth sensors: `"Depth"` `"Picture in picture"` `"Side by side"`	Setting screen layout.
Properties for BACKGROUND Stage:
`backgroundEvaluationDuration`	number	optional	Integer number of seconds from 2 to 10	Setting duration of background evaluation.
`backgroundEvaluationStartDelay`	number	optional	Integer number of seconds from 0 to 30	Setting start delay for background evaluation.
`showEvaluatedBackground`	boolean	optional	`true false`	Show background mode on / off.
Properties for RECORD Stage:
`recordingStartDelay`	number	optional	Integer number of seconds from 0 to 60	Setting start delay for recording.
`hideBackgroundWhenRecording`	boolean	optional	`true false`	Show hide background mode on / off.
`destinationFilePath`	string	optional	Valid file path	Full path to destination file for recording.
`colorCompression`	string	optional	`"None"` `"Background subtraction"` `"JPEG"`	Setting RGB video compression mode.
`jpegQuality`	number	optional	integer from 0 to 100	JPEG quality for JPEG compression.
`depthCompression`	string	optional	`"None"` `"Background subtraction"`	Setting depth compression mode.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-recorder-props",
    "arguments":
    {
        "colorCompression": "jpeg",
	"globalDeviceProps":
        {
	    "PlayStation Eye: Darkening for calibration":"None"
        },
    "hideBackgroundWhenRecording": true,
    "recordingStartDelay": 0,
    "videoMode": "640x480 color @ 50Hz"
    }
}
 
// Response
{
    "success": true
}

Player Commands

set-player-props

set-player-props command sets properties for player.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`screensInRow`	number	optional	Integer from 1 to number of cameras	Setting number of screens in a row for multiple camera video view.
`hideBackground`	boolean	optional	`true false`	Turn hide background mode on / off.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-player-props",
    "arguments":
    {
        "screensInRow": 2,
	"hideBackground": true
    }
}
 
// Response
{
    "success": true
}

open-player

open-player command opens .iPiVideo file in player.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path to file to be opened in player.
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-player",
    "arguments": 
    {
        "filePath": "D:\\iPiMocap\\test_record.iPiVideo"
    }
}
 
// Response
{
    "success": true
}

play-forward

play-forward starts playing video forward starting from the current frame. If current frame is the last frame playing starts from the first frame.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
playing-stopped event is generated when playing is competed (reached the last frame) or stopped by user
No event arguments

EXAMPLE

// Request
{
    "command": "play-forward"
}
 
// Response
{
    "success": true
}

play-backward

play-backward starts playing video backward starting from the current frame. If current frame is the first frame playing starts from the last frame.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events

EXAMPLE

// Request
{
    "command": "play-backward"
}
 
// Response
{
    "success": true
}

frame-forward

frame-forward steps one frame forward. If current frame is the last frame error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "frame-forward"
}
 
// Response
{
    "success": true,
    "error": "Last frame reached"
}

frame-backward

frame-backward steps one frame backward. If current frame is the first frame error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "frame-backward"
}
 
// Response
{
    "success": true,
    "error": "First frame reached"
}

go-to-frame

go-to-frame command selects current frame. If case of invalid frame index error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`frameIndex`	number	mandatory	Non-negative integer	Frame index. The first frame index is 0, the last frame index is <total_number_of_frames> - 1.
Result
Empty result

EXAMPLE

// Request
{
    "command": "go-to-frame",
    "arguments": 
    {
        "frameIndex": 27
    }
}
 
// Response
{
    "success": true
}

iPi Mocap Studio Commands

General Commands

get-app-info

get-app-info command returns the name of application and its version.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
`appName`	string	mandatory	`iPi Mocap Studio 3`	Application name.
`appVersion`	string	mandatory	Version number in the format `XX.XXX.XXX.XXX`	Application version number.

EXAMPLE

// Request
{
    "command": "get-app-info"
}
 
// Response
{
    "success":true,
    "result":
    {
        "appName": "iPi Mocap Studio 3",
        "appVersion": "99.876.543.210"
    }
}

exit

exit command closes iPi Mocap Studio.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "exit"
}
 
// Response
{
    "success": true
}

Project Commands

create-project

create-project creates new project from specified .iPiVideo file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`videoFilePath`	string	mandatory	Valid file path	Full path of .iPiVideo file.
`projectType`	string	mandatory	`action calibration`	Type of the project.
`sceneFilePath`	string	mandatory	Valid file path	Scene file path or project file path to take calibration information from. Mandatory for action projects. No needed for calibration projects.
`actors`	string array	mandatory	List of valid .iPiActor file paths	Array of .iPiActor file paths to read actor parameters from. Mandatory for action projects. No needed for calibration projects.
`actors`	JSON objects array	mandatory		Array of actor parameters objects. Alternative way to specify actors' parameters. Mandatory for action projects. No needed for calibration projects.
`gender`	string	mandatory	`female male`	Gender of actor.
`height`	number	mandatory	Double	Height of actor.
`clothingModel`	string	optional	`longsleeveshirt tshirt tshirtoverlongsleeveshirt`	Actor clothing model. Requred for projects recorded with RGB cameras.
`cameraFov`	number	optional	Double	Required for calibration projects recorded with RGB cameras. Camera diagonal field of view in degrees.
`autoAdjustFov`	boolean	optional	`true false`	Required for calibration projects recorded with RGB cameras. Turns on auto detection of camera field of view.
`autoDetectInitialCameraPositions`	boolean	optional	`true false`	Required for calibration projects recorded with RGB cameras. Turns on auto detection of initial camera positions.
Result
Empty result

EXAMPLE

// Request
{
    "command": "create-project",
    "arguments": 
    {
        "videoFilePath": "D:\\iPiMocap\\test_project.iPiVideo"
        "projectType": "action"
        "sceneFilePath": "D:\\iPiMocap\\test_project.iPiScene"
        "actors":["D:\\iPiMocap\\test_actor.iPiActor"]
    }
}

open-project

open-project command opens existing project from specified .iPiMotion file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path of .iPiMotion file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-project",
    "arguments": 
    {
        "filePath": "D:\\iPiMocap\\test_project.iPiMotion"
    }
}
 
// Response
{
    "success": true
}

save-project

save-project command saves current project to file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	optional	Valid file path	Full path of .iPiMotion file. You do not need to specify file path if you save previously opened project to the same file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "save-project",
    "arguments": 
    {
        "filePath": "D:\\iPiMocap\\test_project.iPiMotion"
    }
}
 
// Response
{
    "success": true
}

close-project

close-project command closes project curretnly opened in iPi Mocap Studio.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "close-project"
}
 
// Response
{
    "success": true
}

get-project-info

get-project-info command returns current project information.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
`projectType`	string	mandatory	`action calibration dummy`	Type of the project. Dummy stands for empty project.
`camerasType`	string	mandatory	`Depth RGB`	Type of the cameras.
`camerasCount`	number	mandatory	Non-negative integer	Number of cameras.

EXAMPLE

// Request
{
    "command": "get-project-info"
}
 
// Response
{
    "success":true,
    "result":
    {
        "projectType": "action",
        "camerasType": "RGB",
        "camerasCount": 6
    }
}

Project Properties Commands

get-timeline-props

get-timeline-props command returns timeline properties of the current project.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
`timeline`	TimelineClip JSON object	mandatory		Whole timeline properties.
`regionOfInterest`	TimelineClip JSON object	mandatory		Region of Interest (ROI) properties.
`takes`	TimelineClip JSON objects array	mandatory		List of takes.
TimelineClip JSON objects properties:
`beginFrame`	number	mandatory	Non-negative integer	Begin frame index (first frame is 0).
`framesCount`	number	mandatory	Positive integer	Number of frames.
`secondsPerFrame`	number	mandatory	Double	Seconds per frame.
`durationInSeconds`	number	mandatory	Double	Duration in seconds.
`description`	string	optional	string	Description.

EXAMPLE

// Request
{
    "command": "get-timeline-props"
}
 
// Response
{
    "success": true,
    "result":
    {
        "timeline":
        {
            "beginFrame": 0,
            "framesCount": 758,
            "secondsPerFrame": 0.02,
            "durationInSeconds": 15.1399
        },
        "regionOfInterest":
        {
            "beginFrame": 0,
            "framesCount": 758,
            "secondsPerFrame": 0.02,
            "durationInSeconds": 15.1399,
            "description": "Region of Interest"
        },
        "takes":
        [
            {
                "beginFrame": 0,
                "framesCount": 758,
                "secondsPerFrame": 0.02,
                "durationInSeconds": 15.1399,
                "description": "Take 1"
            }
        ]
    }
}

set-timeline-props

set-timeline-props command sets timeline properties of the current project.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`regionOfInterest`	TimelineClip JSON object	mandatory		Region of Interest (ROI) properties.
`takes`	TimelineClip JSON objects array	mandatory		List of takes.
TimelineClip JSON objects properties:
`beginFrame`	number	mandatory	Non-negative integer	Begin frame index (first frame is 0).
`framesCount`	number	mandatory	Positive integer	Number of frames.
`description`	string	optional	string	Description.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-timeline-props"
    "arguments":
    {
        "regionOfInterest":
        {
            "beginFrame": 10,
            "framesCount": 558,
        },
        "takes":
        [
            {
                "beginFrame": 10,
                "framesCount": 158,
                "description": "Take 1"
            },
            {
                "beginFrame": 200,
                "framesCount": 558,
                "description": "Take 2"
            }
        ]
    }
}
 
// Response
{
    "success": true
}

get-view-props

get-view-props command gets current view properties specified via View menu.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
General view properties
`skin`	boolean	mandatory	`true false`	Show skin flag value.
`skinOpacity`	numeric	mandatory	Double from 0 to 1	Skin opacity value.
`bones`	boolean	mandatory	`true false`	Show bones flag value.
`viewportBackgroundColor`	string	mandatory	Valid html color value	Viewport background color.
`cameras`	boolean	mandatory	`true false`	Show cameras flag value.
`currentCamera`	numeric	mandatory	Non-negative integer	Selected camera index starting from 0.
`groundPlane`	boolean	mandatory	`true false`	Show ground plane flag value.
`viewBackground`	boolean	mandatory	`true false`	Show background flag value.
Action projects view properties
`currentActor`	numeric	mandatory	Non-negative integer	Selected actor index starting from 0.
`trajectories`	boolean	mandatory	`true false`	Show trajectories flag value.
`skeletonStrobe`	boolean	mandatory	`true false`	Show skeleton strobe flag value.
`extraSkeletonStrobe`	boolean	mandatory	`true false`	Show extra skeleton strobe flag value.
`collisionObjects`	boolean	mandatory	`true false`	Show collision objects flag value.
`massObjects`	boolean	mandatory	`true false`	Show mass objects flag value.
`poseMismatch`	boolean	mandatory	`true false`	Show pose mismatch flag value.
View properties of projects containing RGB information
`video`	boolean	mandatory	`true false`	Show video flag value.
`videoOpacity`	numeric	mandatory	Double from 0 to 1	Video opacity value.
`videoThumbnails`	boolean	mandatory	`true false`	Show video thumbnails flag value.
`lightSource`	boolean	mandatory	`true false`	Show light source flag value.
View properties of projects containing depth information
`depth`	boolean	mandatory	`true false`	Show depth flag value.
`depthOpacity`	numeric	mandatory	Double from 0 to 1	Depth opacity value.
`hideBackground`	boolean	mandatory	`true false`	Hide background flag value.
`depthFromAllSensors`	boolean	mandatory	`true false`	Show depth from all sensors flag value.
View properties of projects containing RGB and depth information
`alignColorVideoToDepth`	boolean	mandatory	`true false`	Align color video to depth flag value.
`colorPointCloudWithRgbData`	boolean	mandatory	`true false`	Color point cloud with RGB data flag value.

EXAMPLE

// Request
{
    "command": "get-view-props"
}
 
// Response
{
    "success": true,
    "result":
    {
        "skin": true,
        "skinOpacity": 0.7,
        "bones": true,
        "viewportBackgroundColor": "#7D90A3",
        "cameras": true,
        "currentCamera": 0,
        "groundPlane": true,
        "viewBackground": false,
        "currentActor": 0,
        "trajectories": false,
        "skeletonStrobe": false,
        "extraSkeletonStrobe": false,
        "collisionObjects": false,
        "massObjects": false,
        "poseMismatch": false,
        "video": true,
        "videoOpacity": 0.7,
        "videoThumbnails": true,
        "lightSource": true    
    }
 
}

set-view-props

set-view-props command sets view properties specified via View menu.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
General view properties
`skin`	boolean	optional	`true false`	Show skin flag value.
`skinOpacity`	numeric	optional	Double from 0 to 1	Skin opacity value.
`bones`	boolean	optional	`true false`	Show bones flag value.
`viewportBackgroundColor`	string	optional	Valid html color value	Viewport background color.
`cameras`	boolean	optional	`true false`	Show cameras flag value.
`currentCamera`	numeric	optional	Non-negative integer	Selected camera index starting from 0.
`groundPlane`	boolean	optional	`true false`	Show ground plane flag value.
`viewBackground`	boolean	optional	`true false`	Show background flag value.
Action projects view properties
`currentActor`	numeric	optional	Non-negative integer	Selected actor index starting from 0.
`trajectories`	boolean	optional	`true false`	Show trajectories flag value.
`skeletonStrobe`	boolean	optional	`true false`	Show skeleton strobe flag value.
`extraSkeletonStrobe`	boolean	optional	`true false`	Show extra skeleton strobe flag value.
`collisionObjects`	boolean	optional	`true false`	Show collision objects flag value.
`massObjects`	boolean	optional	`true false`	Show mass objects flag value.
`poseMismatch`	boolean	optional	`true false`	Show pose mismatch flag value.
View properties of projects containing RGB information
`video`	boolean	optional	`true false`	Show video flag value.
`videoOpacity`	numeric	optional	Double from 0 to 1	Video opacity value.
`videoThumbnails`	boolean	optional	`true false`	Show video thumbnails flag value.
`lightSource`	boolean	optional	`true false`	Show light source flag value.
View properties of projects containing depth information
`depth`	boolean	optional	`true false`	Show depth flag value.
`depthOpacity`	numeric	optional	Double from 0 to 1	Depth opacity value.
`hideBackground`	boolean	optional	`true false`	Hide background flag value.
`depthFromAllSensors`	boolean	optional	`true false`	Show depth from all sensors flag value.
View properties of projects containing RGB and depth information
`alignColorVideoToDepth`	boolean	optional	`true false`	Align color video to depth flag value.
`colorPointCloudWithRgbData`	boolean	optional	`true false`	Color point cloud with RGB data flag value.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-view-props"
}
 
// Response
{
    "success": true,
    "result":
    {
        "skin": false,
        "skinOpacity": 0.5,
        "bones": true,
        "viewportBackgroundColor": "#7D90A3",
        "cameras": true,
        "currentCamera": 2,
        "groundPlane": true,
        "videoOpacity": 0.6,
        "videoThumbnails": false,
        "lightSource": true    
    }
 
}

load-scene

load-scene loads scene and light information from .iPiScene, .iPiCalib or .iPiMotion file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path to file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "load-scene",
    "arguments": 
    {
        "filePath": "D:\\iPiMocap\\test.iPiMotion"
    }
}
 
// Response
{
    "success": true
}

save-scene

save-scene saves scene and light information (if available) to .iPiScene file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path to file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "save-scene",
    "arguments": 
    {
        "filePath": "D:\\iPiMocap\\test.iPiScene"
    }
}
 
// Response
{
    "success": true
}

Actor Commands

load-actor

load-actor loads actor properties from .iPiActor file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`actorIndex`	number	mandatory	Non-negative integer	Actor index starting from 0.
`filePath`	string	mandatory	Valid file path	Full path to file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "load-actor",
    "arguments": 
    {
        "actorIndex": 0,
        "filePath": "D:\\iPiMocap\\test.iPiActor"
    }
}
 
// Response
{
    "success": true
}

save-actor

save-actor saves actor properties to .iPiActor file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`actorIndex`	number	mandatory	Non-negative integer	Actor index starting from 0.
`filePath`	string	mandatory	Valid file path	Full path to file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "save-actor",
    "arguments": 
    {
        "actorIndex": 0,
        "filePath": "D:\\iPiMocap\\test.iPiActor"
    }
}
 
// Response
{
    "success": true
}

detect-actor-colors

detect-actor-colors runs auto-detection of actor colors.

</td></tr>

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`handsColorSameAsFace`	boolean	optional	`true false`	Setting "Hands are the Same Color as Face" flag value.
Result
Empty result
Events
detect-actor-colors-finished event is generated when operation is competed or stopped by user
`shirtColor`	string	mandatory	Valid html color value	Shirt color.
`pantsColor`	string	mandatory	Valid html color value	Pants color.
`handsColor`	string	mandatory	Valid html color value	Hands color.
`faceColor`	string	mandatory	Valid html color value	Face color.
`shoesColor`	string	mandatory	Valid html color value	Shoes color.
`shoeSolesColor`	string	mandatory	Valid html color value	Shoe soles color.
`hairColor`	string	mandatory	Valid html color value	Hair color.
`sleevesColor`	string	mandatory	Valid html color value	Sleeves color.

EXAMPLE

// Request
{
    "command": "detect-actor-colors",
    "arguments": 
    {
        "handsColorSameAsFace": false
    }
}
 
// Response
{
    "success": true
}
 
// Event
{
    "event": "detect-actor-colors-finished",
    "arguments":  
    {
        "shirtColor":"#384662",
        "pantsColor":"#1F2431",
        "handsColor":"#9A9DA6",
        "faceColor":"#7A7077",
        "shoesColor":"#504C4C",
        "shoeSolesColor":"#504C4C",
        "hairColor":"#57555E",
        "sleevesColor":"#384662"
    }
}

Playing Commands

play-forward

play-forward starts playing forward starting from the current frame. If current frame is the last frame playing starts from the first frame.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
playing-stopped event is generated when playing is competed (reached the last frame) or stopped by user
No event arguments

EXAMPLE

// Request
{
    "command": "play-forward"
}
 
// Response
{
    "success": true
}

play-backward

play-backward starts playing backward starting from the current frame. If current frame is the first frame playing starts from the last frame.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "play-backward"
}
 
// Response
{
    "success": true
}

frame-forward

frame-forward steps one frame forward. If current frame is the last frame error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "frame-forward"
}
 
// Response
{
    "success": false,
    "error": "Frame index exceeds total frames count"
}

frame-backward

frame-backward steps one frame backward. If current frame is the first frame error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "frame-backward"
}
 
// Response
{
    "success": true
}

go-to-frame

go-to-frame command selects current frame. If case of invalid frame index error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`frameIndex`	number	mandatory	Non-negative integer	Frame index. The first frame index is 0, the last frame index is <total_number_of_frames> - 1.
Result
Empty result

EXAMPLE

// Request
{
    "command": "go-to-frame",
    "arguments": 
    {
        "frameIndex": 27
    }
}
 
// Response
{
    "success": true
}

pause-play

pause-play pauses playing.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "pause-play"
}
 
// Response
{
    "success": true
}

Tracking Commands

get-tracking-props

get-tracking-props command gets current tracking properties specified in Tracking tab.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
`enableFootTracking`	boolean	mandatory	`true false`	Foot tracking enabled flag value.
`enableGroundCollisions`	boolean	mandatory	`true false`	Ground collisions enabled flag value.
`enableHeadTracking`	boolean	mandatory	`true false`	Head tracking enabled flag value.
`shouldersTrackingMode`	number	mandatory	Integer index of selected Shoulders combobox item. `0` - Calculated from arm position `1` - Tracked from video	Selected shoulder tracking mode.
`spineTrackingMode`	number	mandatory	Integer index of selected Spine combobox item. `0` - Stiff Lower Spine `1` - Flexible Lower Spine `2` - Very Flexible Lower Spine	Selected spine tracking mode.
`trackingResolution`	number	mandatory	Integer index of selected Tracking resolution combobox item. `0` - High `1` - Low	Selected tracking resolution.
`jitterRemovalOptions`	number array	mandatory	Array containing 6 integers each in the range from 0 to 5. `Item 0` - value for Torso `Item 1` - value for Left arm `Item 2` - value for Right arm `Item 3` - value for Left leg `Item 4` - value for Right leg `Item 5` - value for Head	Selected jitter removal options.
`trajectoryFilter`	number	mandatory	Integers in the range from 0 to 5.	Selected trajectory filter value.

EXAMPLE

// Request
{
    "command": "get-tracking-props"
}
 
// Response
{
    "success": true,
    "result":
    {
        "enableFootTracking": true,
        "enableGroundCollisions": true,
        "enableHeadTracking": true,
        "shouldersTrackingMode": 1,
        "spineTrackingMode": 0,
        "trackingResolution": 0,
        "jitterRemovalOptions": [2, 2, 2, 2, 2, 2],
        "trajectoryFilter": 2
    }
 
}

set-tracking-props

set-tracking-props command sets tracking properties in Tracking tab.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`enableFootTracking`	boolean	optional	`true false`	Foot tracking enabled flag value.
`enableGroundCollisions`	boolean	optional	`true false`	Ground collisions enabled flag value.
`enableHeadTracking`	boolean	optional	`true false`	Head tracking enabled flag value.
`shouldersTrackingMode`	number	optional	Integer index of selected Shoulders combobox item. `0` - Calculated from arm position `1` - Tracked from video	Selected shoulder tracking mode.
`spineTrackingMode`	number	optional	Integer index of selected Spine combobox item. `0` - Stiff Lower Spine `1` - Flexible Lower Spine `2` - Very Flexible Lower Spine	Selected spine tracking mode.
`trackingResolution`	number	optional	Integer index of selected Tracking resolution combobox item. `0` - High `1` - Low	Selected tracking resolution.
`jitterRemovalOptions`	number array	optional	Array containing 6 integers each in the range from 0 to 5. `Item 0` - value for Torso `Item 1` - value for Left arm `Item 2` - value for Right arm `Item 3` - value for Left leg `Item 4` - value for Right leg `Item 5` - value for Head	Selected jitter removal options.
`trajectoryFilter`	number	optional	Integers in the range from 0 to 5.	Selected trajectory filter value.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-tracking-props"
    "arguments":
    {
        "enableFootTracking": true,
        "enableGroundCollisions": false,
        "enableHeadTracking": false,
        "shouldersTrackingMode": 0,
        "spineTrackingMode": 2,
        "trackingResolution": 0,
        "jitterRemovalOptions": [5, 4, 3, 2, 1, 0],
        "trajectoryFilter": 3
    }
}
 
// Response
{
    "success": true,
}

refit-pose

refit-pause starts Refit Pose operation.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
refit-pose-finished event is generated when operation is competed or stopped by user
`mismatch`	Number	mandatory	Double	Pose mismatch value.
`translation`	JSON object	mandatory		Coordinates of root bone translation.
`x`	number	Double		x cooordinate.
`y`	number	Double		y cooordinate.
`z`	number	Double		z cooordinate.
`joints`	JSON objects array	mandatory		List of joints rotations.
`name`	string	string		Name of joint.
`rotation`	JSON object	mandatory		Quaternion coordinates of joint rotation relative to parent joint.
`w`	number	Double		w cooordinate.
`x`	number	Double		x cooordinate.
`y`	number	Double		y cooordinate.
`z`	number	Double		z cooordinate.

EXAMPLE

// Request
{
    "command": "play-forward"
}
 
// Response
{
    "success": true
}
 
// Event
{
    "event": "refit-pose-finished",
    "arguments":
    {
        "mismatch": -0.0346799499867484,
        "translation":
        {
            "x": 0.20735317468643188,
            "y": 0.93647444248199463,
            "z": 0.1268109530210495
        },
        "joints":
        [
            {
                "name": "Hip",
                "rotation":
                {
                    "w": 0.99089264869689941,
                    "x": -0.024765072390437126,
                    "y": -0.13141168653964996,
                    "z": -0.015792140737175941
                }
            },
            {
                "name": "LowerSpine",
                "rotation":
                {
                    "w": 0.9960486888885498,
                    "x": 0.028381859883666039,
                    "y": -0.083706416189670563,
                    "z": -0.008648967370390892
                }
            },
            {
                "name": "MiddleSpine",
                "rotation":
                {
                    "w": 0.9960486888885498,
                    "x": 0.028381859883666039,
                    "y": -0.083706416189670563,
                    "z": -0.008648967370390892
                }
            },
            {
                "name": "Chest",
                "rotation":
                {
                    "w": 0.9960486888885498,
                    "x": 0.028381859883666039,
                    "y": -0.083706416189670563,
                    "z": -0.008648967370390892
                }
            },
            {
                "name": "Neck",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "Head",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "EffectorHead",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "LClavicle",
                "rotation":
                {
                    "w": 0.99793654680252075,
                    "x": 0.0059945755638182163,
                    "y": 0.046108484268188477,
                    "z": 0.044281467795372009
                }
            },
            {
                "name": "LShoulder",
                "rotation":
                {
                    "w": 0.9549943208694458,
                    "x": -0.034553475677967072,
                    "y": 0.29447850584983826,
                    "z": 0.0086394213140010834
                }
            },
            {
                "name": "LForearm",
                "rotation":
                {
                    "w": 0.91743868589401245,
                    "x": -0.036340668797492981,
                    "y": -0.39591813087463379,
                    "z": 0.015319216065108776
                }
             },
             {
                "name": "LHand",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "RClavicle",
                "rotation":
                {
                    "w": 0.995156466960907,
                    "x": -0.040068801492452621,
                    "y": -0.048379208892583847,
                    "z": 0.075615249574184418
                }
            },
            {
                "name": "RShoulder",
                "rotation":
                {
                    "w": 0.965262770652771,
                    "x": -0.0052053602412343025,
                    "y": 0.26098120212554932,
                    "z": -0.011395715177059174
                }
            },
            {
                "name": "RForearm",
                "rotation":
                {
                    "w": 0.99951714277267456,
                    "x": -0.020441532135009766,
                    "y": -0.0027645230293273926,
                    "z": -0.023236606270074844
                }
            },
            {
                "name": "RHand",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "RThigh",
                "rotation":
                {
                    "w": 0.79308795928955078,
                    "x": 0.068257540464401245,
                    "y": 0.60094189643859863,
                    "z": 0.072259068489074707
                }
            },
            {
                "name": "RShin",
                "rotation":
                {
                    "w": 0.79541802406311035,
                    "x": 0.053630385547876358,
                    "y": 0.60230922698974609,
                    "z": -0.040715586394071579
                }
            },
            {
                "name": "RFoot",
                "rotation":
                {
                    "w": 0.99298214912414551,
                    "x": -0.11810562759637833,
                    "y": -0.00553984334692359,
                    "z": -0.0026492751203477383
                }
            },
            {
                "name": "RToe",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "EffectorRToe",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "LThigh",
                "rotation":
                {
                    "w": 0.99825394153594971,
                    "x": -0.0010303414892405272,
                    "y": 0.021972890943288803,
                    "z": 0.054818056523799896
                }
            },
            {
                "name": "LShin",
                "rotation":
                {
                    "w": 0.99794912338256836,
                    "x": 0.059693548828363419,
                    "y": 0.023080151528120041,
                    "z": -0.0013148610014468431
                }
            },
            {
                "name": "LFoot",
                "rotation":
                {
                    "w": 0.98020839691162109,
                    "x": -0.18852591514587402,
                    "y": -0.054500121623277664,
                    "z": -0.026062563061714172
                }
            },
            {
                "name": "LToe",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            },
            {
                "name": "EffectorLToe",
                "rotation":
                {
                    "w": 1.0,
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0
                }
            }
        ]
    }
}

delete-pose

delete-pose deleted pose in current frame.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "delete-pose"
}
 
// Response
{
    "success": true
}

track-forward

track-forward starts tracking forward.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
tracking-operation-finished event is generated when tracking is competed or cancelled
`framesProcessed`	number	mandatory	Non-negative integer	Number of frames processed. In case of successful completion equal to Region-of-Interest number of frames.
`elapsedTime`	number	mandatory	Double	Total processing time in seconds.
`fps`	number	mandatory	Double	Average processing speed in frames per second.

EXAMPLE

// Request
{
    "command": "track-forward"
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "tracking-operation-finished",
    "arguments":
    {
        "framesProcessed": 253,
        "elapsedTime": 62.321,
        "fps": 4.05963,
    }
}

track-backward

track-backward starts tracking backward.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
tracking-operation-finished event is generated when tracking is competed or cancelled
`framesProcessed`	number	mandatory	Non-negative integer	Number of frames processed. In case of successful completion equal to Region-of-Interest number of frames.
`elapsedTime`	number	mandatory	Double	Total processing time in seconds.
`fps`	number	mandatory	Double	Average processing speed in frames per second.

EXAMPLE

// Request
{
    "command": "track-backward"
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "tracking-operation-finished",
    "arguments":
    {
        "framesProcessed": 253,
        "elapsedTime": 62.321,
        "fps": 4.05963,
    }
}

refine-forward

refine-forward starts refine forward.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
tracking-operation-finished event is generated when tracking is competed or cancelled
`framesProcessed`	number	mandatory	Non-negative integer	Number of frames processed. In case of successful completion equal to Region-of-Interest number of frames.
`elapsedTime`	number	mandatory	Double	Total processing time in seconds.
`fps`	number	mandatory	Double	Average processing speed in frames per second.

EXAMPLE

// Request
{
    "command": "refine-forward"
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "tracking-operation-finished",
    "arguments":
    {
        "framesProcessed": 253,
        "elapsedTime": 62.321,
        "fps": 4.05963,
    }
}

refine-backward

refine-backward starts refine backward.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
tracking-operation-finished event is generated when tracking is competed or cancelled
`framesProcessed`	number	mandatory	Non-negative integer	Number of frames processed. In case of successful completion equal to Region-of-Interest number of frames.
`elapsedTime`	number	mandatory	Double	Total processing time in seconds.
`fps`	number	mandatory	Double	Average processing speed in frames per second.

EXAMPLE

// Request
{
    "command": "refine-backward"
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "tracking-operation-finished",
    "arguments":
    {
        "framesProcessed": 253,
        "elapsedTime": 62.321,
        "fps": 4.05963,
    }
}

pause-tracking

pause-tracking stops tracking or refine operation.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "pause-tracking"
}
 
// Response
{
    "success": true
}

remove-jitter

remove-jitter starts jitter removal.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
tracking-operation-finished event is generated when jitter removal is competed or cancelled
`framesProcessed`	number	mandatory	Non-negative integer	Number of frames processed. In case of successful completion equal to Region-of-Interest number of frames.
`elapsedTime`	number	mandatory	Double	Total processing time in seconds.
`fps`	number	mandatory	Double	Average processing speed in frames per second.

EXAMPLE

// Request
{
    "command": "remove-jitter"
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "tracking-operation-finished",
    "arguments":
    {
        "framesProcessed": 253,
        "elapsedTime": 62.321,
        "fps": 4.05963,
    }
}

Biomech Commands

load-biomech-profile

load-biomech-profile loads biomech profile from .iPiBiomech file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`profilePath`	string	mandatory	Valid file path	Full path to file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "load-biomech-profile",
    "arguments": 
    {
        "profilePath": "D:\\iPiMocap\\test.iPiBiomech"
    }
}
 
// Response
{
    "success": true
}

plot-biomech-data

plot-biomech-data plots biomech data.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "plot-biomech-data"
}
 
// Response
{
    "success": true
}

export-biomech-data

export-biomech-data exports bones motion data to file or copies to clipboard.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`format`	string	mandatory	`text matlab clipboard`	Export format.
`filePath`	string	optional	Valid file path	Full path to file. Not needed in case of copying to clipboard.
Result
Empty result
Events
biomech-data-export-completed event is generated when export is competed
No event arguments

EXAMPLE

// Request
{
    "command": "export-biomech-data",
    "arguments": 
    {
        "format": "text",
        "filePath": "D:\\iPiMocap\\test.txt"
    }
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "biomech-data-export-completed",
    "arguments":
    {
        "success": true
    }
}

export-point-cloud

export-point-cloud exports point cloud data to file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`format`	string	mandatory	`pcd obj matlab ply pts prt xyz`	Export format.
`folderPath`	string	mandatory	Valid folder path	Full path to folder to export to.
`fileName`	string	mandatory	File name	File name (does not include path to folder but includes extension).
`subtractBackground`	boolean	optional	`true false`	Subtract background flag value.
`subtractBackgroundThreshold`	numeric	optional	Double from -4 to 5	Background subtraction threshold. Bigger value means more points will be subtracted.
`exportRGB`	boolean	optional	`true false`	Export RGB information flag value.
`currentFrameOnly`	boolean	optional	`true false`	If `true`, only current frame will be exported. If `false`, all frames of Region-of-Interest will be exported.
`cameraIndises`	numeric array	optional		Array of camera indicese (starting from 0) to include in export. If not set, all cameras will be exported.
Result
Empty result
Events
point-cloud-export-finished event is generated when point cloud export is competed or cancelled
`framesProcessed`	number	mandatory	Non-negative integer	Number of frames processed. In case of successful completion equal to Region-of-Interest number of frames.
`elapsedTime`	number	mandatory	Double	Total processing time in seconds.
`fps`	number	mandatory	Double	Average processing speed in frames per second.

EXAMPLE

// Request
{
    "command": "export-point-cloud",
    "arguments": 
    {
        "format": "pcd",
        "folderPath": "D:\\iPiMocap",
        "fileName": "test.pcd",
        "subtractBackground": true,
        "exportRGB": true
    }
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "point-cloud-export-finished",
    "arguments":
    {
        "framesProcessed": 253,
        "elapsedTime": 62.321,
        "fps": 4.05963,
    }
}

Calibration Commands

run-calibration

run-calibration starts calibration.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`markerSpotSize`	string	optional	`small medium large`	Marker spot size on video setting.
`autoDetectInitialCameraPositions`	boolean	optional	`true false`	Auto detect initial camera positions flag value. RGB projects only.
`autoAdjustFov`	boolean	optional	`true false`	Auto adjust FOV flag value. RGB projects only.
`calibrationMode`	string	optional	`fast normal extended extreme`	Calibration mode. RGB projects only.
Result
Empty result
Events
calibration-finished event is generated when point cloud export is competed or canceled
`elapsedTime`	number	mandatory	Double	Total processing time in seconds.
`canceled`	boolean	mandatory	`true false`	Set to `true` if calibration was canceled by user.
`rgbCalibrationStat`	JSON objects array	optional		List of calibration statistics per camera for RBG projects.
`quality`	string	mandatory	`failed good perfect unknown`	Camera calibration quality.
`reprojectionError`	number	mandatory	Double	Camera reprojection error.
`mistetects`	number	mandatory	Double	Camera misdetects percent.
`depthMarkerCalibrationStat`	JSON object	optional		Calibration statistics for depth projects calibrated with flashlight.
`quality`	string	mandatory	`failed good perfect unknown`	Camera calibration quality.
`goodFramesCount`	number	mandatory	Non-negative integer	Number of good frames.
`averagePositionError`	number	mandatory	Double	Average position error.
`markerCloudMinSize`	number	mandatory	Double	Marker point cloud minimum size.
`occlusionPercent`	number	mandatory	Double	Occlusion percent.
`depthBoardCalibrationStat`	JSON object	optional		Calibration statistics for depth projects calibrated with board.
`quality`	string	mandatory	`failed good perfect unknown`	Camera calibration quality.
`goodFramesCount`	number	mandatory	Non-negative integer	Number of good frames.
`averageAngleError`	number	mandatory	Double	Average angle error.
`averagePositionError`	number	mandatory	Double	Average position error.

EXAMPLE

// Request
{
    "command": "run-calibration",
    "arguments": 
    {
        "markerSpotSize": "large",
        "calibrationMode": "fast"
    }
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "calibration-finished",
    "arguments":
    {
        "elapsedTime": 49.0548727,
        "canceled": false,
        "rgbCalibrationStat":
        [
            {
                "quality": "perfect",
                "reprojectionError": 0.8999624,
                "misdetects": 0.36743924
            },
            {
                "quality": "perfect",
                "reprojectionError": 0.5540145,
                "misdetects": 0.328137815
            },
            {
                "quality": "perfect",
                "reprojectionError": 0.8146306,
                "misdetects": 0.5209761
            },
            {
                "quality": "perfect",
                "reprojectionError": 0.567752242,
                "misdetects": 1.13636363
            }
        ]    
    }
}

mark-ground-points

mark-ground-points marks ground points.

Parameter Name	Type	Mandatory / Optional	Description
Arguments
`frames`	numeric array	mandatory	List of frame indices to be marked as ground
Result
Empty result

EXAMPLE

// Request
{
    "command": "mark-ground-points",
    "arguments": 
    {
        "frames": [28, 304, 504, 1123]
    }
}
 
// Response
{
    "success": true
}

ummark-ground-points

unmark-ground-points unmarks ground points.

Parameter Name	Type	Mandatory / Optional	Description
Arguments
`frames`	numeric array	optional	List of ground points frame indices to be unmarked. Unmarks all ground points if empty.
Result
Empty result

EXAMPLE

// Request
{
    "command": "unmark-ground-points",
    "arguments": 
    {
        "frames": [28, 304, 504, 1123]
    }
}
 
// Response
{
    "success": true
}

Animation Export Commands

load-target-character

load-target-character loads target character from file or selects from predefined characters list.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`rigName`	string	optional	`default motionbuilder 3dsmax endorphin iclone blender`	Name of predefined rig.
`filePath`	string	optional	Valid file path	Full path to character file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "load-target-character",
    "arguments": 
    {
        "rigName": "3dsmax"
    }
}
 
// Response
{
    "success": true
}

load-motion-transfer-profile

load-motion-transfer-profile loads motion transfer profile from .iPiTransfer file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`profilePath`	string	mandatory	Valid file path	Full path to file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "load-motion-transfer-profile",
    "arguments": 
    {
        "profilePath": "D:\\iPiMocap\\test.iPiTransfer"
    }
}
 
// Response
{
    "success": true
}

get-export-props

get-export-props command gets export properties.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
`advancedMotionTransfer`	boolean	mandatory	`true false`	Advanced motion transfer flag value.
`recenterCoordinateSystemOnCharacter`	boolean	mandatory	`true false`	Recenter coordinate system on character flag value.
`exportTPoseInFirstFrame`	boolean	mandatory	`true false`	Export T-Pose in first frame flag value.

EXAMPLE

// Request
{
    "command": "get-export-props"
}
 
// Response
{
    "success": true,
    "result":
    {
	"advancedMotionTransfer": true,
	"recenterCoordinateSystemOnCharacter": false,
	"exportTPoseInFirstFrame": true,
    }
}

set-export-props

set-export-props command sets export properties.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`advancedMotionTransfer`	boolean	optional	`true false`	Advanced motion transfer flag value.
`recenterCoordinateSystemOnCharacter`	boolean	optional	`true false`	Recenter coordinate system on character flag value.
`exportTPoseInFirstFrame`	boolean	optional	`true false`	Export T-Pose in first frame flag value.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-export-props",
    "arguments":
    {
	"advancedMotionTransfer": true,
	"recenterCoordinateSystemOnCharacter": false,
	"exportTPoseInFirstFrame": true,
    }
}
 
// Response
{
    "success": true
}

export-animation

export-animation exports animation to file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path to file. Animation format is defined by file extension.
`fbxIsBinary`	string	optional	`true false`	Fbx binary format flag for FBX format. If `false` or not set, ASCII format is used.
`fbxVersion`	string	optional	`2014 2013 2012 2011 2010`	Fbx version for FBX format.
Result
Empty result

EXAMPLE

// Request
{
    "command": "export-animation",
    "arguments": 
    {
        "profilePath": "D:\\iPiMocap\\test.bvh"
    }
}
 
// Response
{
    "success": true
}

@@ Line 468: / Line 468: @@
          "cancelled": false
      }
+}
+</syntaxhighlight>
+==== open-record-screen ====
+''open-record-screen'' opens RECORD screen of [[iPi Recorder]].
+<table class="wikitable" style="font-size: smaller; min-width: 50%">
+<tr><th>Parameter Name</th><th>Type</th><th>Mandatory /<br>Optional</th><th>Allowed Values</th><th>Description</th></tr>
+<tr><td colspan="5" style="background-color: white;">'''Arguments'''</td></tr>
+<tr><td colspan="5">''No arguments''</td></tr>
+<tr><td colspan="5" style="background-color: white;">'''Result'''</td></tr>
+<tr><td colspan="5">''Empty result''</td></tr>
+</table>
+''EXAMPLE''
+<syntaxhighlight lang=javascript>
+// Request
+{
+    "command": "open-record-screen"
+}
+// Response
+{
+    "success": true
 }
 </syntaxhighlight>

Difference between revisions of "iPi Automation Add-on"

Revision as of 09:48, 29 March 2016

Contents

Overview

License and Trial

Using iPi Integration Add-on

Communication Library

Redistributable Contents

API

Connecting and Disconnecting

Sending Commands

Consuming Events

Error Codes

Miscellaneous

Command Syntax

iPi Recorder Commands

General Commands

get-app-info

open-studio

exit

Recording Commands

open-home-screen

refresh-device-list

open-recorder

evaluate-background

open-record-screen

start-recording

stop-recording

get-devices-state

get-recorder-props

set-recorder-props

Player Commands

set-player-props

open-player

play-forward

play-backward

frame-forward

frame-backward

go-to-frame

iPi Mocap Studio Commands

General Commands

get-app-info

exit

Project Commands

create-project

open-project

save-project

close-project

get-project-info

Project Properties Commands

get-timeline-props

set-timeline-props

get-view-props

set-view-props

load-scene

save-scene

Actor Commands

load-actor

save-actor

detect-actor-colors

Playing Commands

play-forward

play-backward

frame-forward

frame-backward

go-to-frame

pause-play

Tracking Commands

get-tracking-props

set-tracking-props

refit-pose

delete-pose

track-forward

track-backward

refine-forward

refine-backward

pause-tracking

remove-jitter

Biomech Commands

load-biomech-profile