Difference between revisions of "iPi Automation Add-on"

From iPi Docs
Jump to: navigation, search
m
Line 480: Line 480:
  
 
''get-devices-state'' returns the state and statistics for all selected devices.
 
''get-devices-state'' returns the state and statistics for all selected devices.
 +
 +
{{Tip|This command is used to check camera status and statistics. You can call it before and after the recording.}}
  
 
<table class="wikitable" style="font-size: smaller; min-width: 50%">
 
<table class="wikitable" style="font-size: smaller; min-width: 50%">
Line 499: Line 501:
 
<tr><td><tt>error</tt></td><td>string</td><td align=center>optional</td><td>Error message string</td>
 
<tr><td><tt>error</tt></td><td>string</td><td align=center>optional</td><td>Error message string</td>
 
<td>Error message if device is in failed status.</td></tr>
 
<td>Error message if device is in failed status.</td></tr>
 +
<tr><td><tt>statistics</tt></td><td>JSON object</td><td><center>optional</center></td><td>
 +
<td>
 +
Camera statistics.
 +
</td></tr>
 +
<tr><td style="padding-left: 40px;"><tt>frameRate</tt></td><td>number</td><td align=center>mandatory
 +
</td><td>Double</td><td>Average frame rate.</td></tr>
 +
<tr><td style="padding-left: 40px;"><tt>frameDropsPerSecond</tt></td><td>number</td><td align=center>mandatory
 +
</td><td>Double</td><td>Average frame drops per second.</td></tr>
 +
<tr><td style="padding-left: 40px;"><tt>badFramesPerSecond</tt></td><td>number</td><td align=center>mandatory
 +
</td><td>Double</td><td>Average bad frames per second.</td></tr>
 +
<tr><td style="padding-left: 40px;"><tt>totalFrameDrops</tt></td><td>number</td><td align=center>mandatory
 +
</td><td>Double</td><td>Total frame drops.</td></tr>
 +
<tr><td style="padding-left: 40px;"><tt>totalBadFrames</tt></td><td>number</td><td align=center>mandatory
 +
</td><td>Double</td><td>Total bad frames.</td></tr>
 
</table>
 
</table>
 
''EXAMPLE''
 
''EXAMPLE''

Revision as of 11:34, 3 December 2015

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:

Note.png
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

  1. Switch to Integration tab.
  2. Press Activate button
  3. Press Start 30-days Free Trial Period or Enter Integration License Key and follow further on-screen instructions
    iPi-Integration-2-1.png
Note.png
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.

Using iPi Integration Add-on

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 NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
No arguments
Result
appNamestringmandatoryiPi Recorder 3 Application name.
appVersionstringmandatoryVersion 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 NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
filePathstringmandatoryValid 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 NameTypeMandatory /
Optional		Allowed ValuesDescription
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 NameTypeMandatory /
Optional		Allowed ValuesDescription
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 NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
No arguments
Result
Array of JSON objects, each representing recording device. Fields of array items:
kindstringmandatorycamera
depth-sensor
microfon		 Device type.
modelstringmandatorySupported device model Device model.
idstringmandatoryUnique string, format depends on device model Unique string that is used to identify recording devices in open-recorder command.
selectedbooleanmandatorytrue
false		 Device selected status.
failedbooleanmandatorytrue
false		 Device filed status.
errorstringoptionalError 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 NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
selectedDevicesstring arraymandatoryList 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.png
Tip: If parameter is not specified in command arguments, current value in user interface will be used.
Parameter NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
durationnumberoptionalInteger number of seconds from 2 to 10

Setting duration of background evaluation.

startDelaynumberoptionalInteger 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
successbooleanmandatorytrue
false		 Success flag. Set to true if background evaluation was completed successfully.
cancelledbooleanmandatorytrue
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
    }
}

start-recording

start-recording starts recording.

Tip.png
Tip: If parameter is not specified in command arguments, current value in user interface will be used.
Parameter NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
filePathstringoptionalValid file path

Full path to destination file for recording.

startDelaynumberoptionalInteger 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
successbooleanmandatorytrue
false		 Success flag. Set to true if background evaluation was completed successfully.
cancelledbooleanmandatorytrue
false		 Cancellation flag. Set to true if background evaluation was cancelled by user or due to error.
filePathstringmandatoryValid file path

Full path to destination file.

fileSizenumbermandatoryNon-negative integer Size of the recorded file in bytes.
durationstringmandatoryTimespan value in format
hh:mm:ss.sssssss

Duration of the recording.

frameCountnumbermandatoryNon-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-recorder command stops recording.

Parameter NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
No arguments
Result
Empty result
Events
recording-stopped event is generated when recording is stopped
successbooleanmandatorytrue
false		 Success flag. Set to true if background evaluation was completed successfully.
cancelledbooleanmandatorytrue
false		 Cancellation flag. Set to true if background evaluation was cancelled by user or due to error.
filePathstringmandatoryValid file path

Full path to destination file.

fileSizenumbermandatoryNon-negative integer Size of the recorded file in bytes.
durationstringmandatoryTimespan value in format
hh:mm:ss.sssssss

Duration of the recording.

frameCountnumbermandatoryNon-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.png
Tip: This command is used to check camera status and statistics. You can call it before and after the recording.
Parameter NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
No arguments
Result
Array of JSON objects, each representing selected device. Fields of array items:
kindstringmandatorycamera
depth-sensor
microfon		 Device type.
modelstringmandatorySupported device model Device model.
idstringmandatoryUnique string, format depends on device model Unique string that is used to identify recording devices in open-recorder command.
selectedbooleanmandatorytrue
false		 Device selected status.
failedbooleanmandatorytrue
false		 Device failed status.
errorstringoptionalError message string Error message if device is in failed status.
statisticsJSON object
optional

Camera statistics.

frameRatenumbermandatory DoubleAverage frame rate.
frameDropsPerSecondnumbermandatory DoubleAverage frame drops per second.
badFramesPerSecondnumbermandatory DoubleAverage bad frames per second.
totalFrameDropsnumbermandatory DoubleTotal frame drops.
totalBadFramesnumbermandatory DoubleTotal 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": false,
            "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": "Microphone (USB Camera-B4.04.27 [VID=-1; PID=-1; Driver=256; Channels=2; Supports=WAVE_FORMAT_11M08, ...]",
            "selected": false,
            "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 NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
No arguments
Result
Properties for SETUP Stage:
videoModestringmandatory

Available modes depend on camera model.

Selected RGB video mode.

videoModeListstring arraymandatory

List of available modes depend on camera model.

Possible videoMode values.

audioModestringoptional

Available modes depend on microphone model.

Selected audio mode. This field is included into the response, if microphone selected.

audeoModeListstring arrayoptional

List of available modes depend on camera model.

Possible audioMode values. This field is included into the response, if microphone selected.

globalDevicePropsJSON object
optional

Device-specific list of properties visible in “SHARED SETTINGS” section of SETUP stage.

PlayStation Eye: Darkening for Calibrationstringoptional "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/Liststring arrayoptional 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.

screensInRownumbermandatoryInteger from 1 to number of cameras

Selected number of screens in a row for multiple camera video view.

screenLayoutstringmandatory

For RGB cameras:
"Color"

For depth sensors:
"Depth"
"Picture in picture"
"Side by side"

Selected screen layout.

screenLayoutListstring arraymandatory Available screenLayout modes.Available screen layout modes. Depend on type of selected cameras.
Properties for BACKGROUND Stage:
backgroundEvaluationDurationnumbermandatoryInteger number of seconds from 2 to 10

Selected duration of background evaluation.

backgroundEvaluationStartDelaynumbermandatoryInteger number of seconds from 0 to 30

Selected start delay for background evaluation.

showEvaluatedBackgroundbooleanmandatorytrue
false

Selected show background mode.

Properties for RECORD Stage:
recordingStartDelaynumbermandatoryInteger number of seconds from 0 to 60

Selected start delay for recording.

hideBackgroundWhenRecordingbooleanmandatorytrue
false

Selected hide background mode.

destinationFilePathstringmandatory

Valid file path

Selected full path to destination file for recording.

colorCompressionstringmandatory

"None"
"Background subtraction"
"JPEG"

Selected RGB video compression mode.

jpegQualitynumbermandatoryinteger from 0 to 100

Selected JPEG quality for JPEG compression.

depthCompressionstringmandatory"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.png
Tip: If property is not specified in command arguments, current value in user interface will be used.
Parameter NameTypeMandatory /
Optional		Allowed ValuesDescription
Arguments
Properties for SETUP Stage:
videoModestringoptional

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.

audioModestringoptional

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.

globalDevicePropsJSON object
optional

Device-specific list of properties visible in “SHARED SETTINGS” section of SETUP stage.

PlayStation Eye: Darkening for Calibrationstringoptional "None"
"Darkening"
"Extra Darkening"

Darkening mode for Sony PS3 Eye cameras

screensInRownumberoptionalInteger from 1 to number of cameras

Setting number of screens in a row for multiple camera video view.

screenLayoutstringoptional

For RGB cameras:
"Color"

For depth sensors:
"Depth"
"Picture in picture"
"Side by side"

Setting screen layout.

Properties for BACKGROUND Stage:
backgroundEvaluationDurationnumberoptionalInteger number of seconds from 2 to 10

Setting duration of background evaluation.

backgroundEvaluationStartDelaynumberoptionalInteger number of seconds from 0 to 30

Setting start delay for background evaluation.

showEvaluatedBackgroundbooleanoptionaltrue
false

Show background mode on / off.

Properties for RECORD Stage:
recordingStartDelaynumberoptionalInteger number of seconds from 0 to 60

Setting start delay for recording.

hideBackgroundWhenRecordingbooleanoptionaltrue
false

Show hide background mode on / off.

destinationFilePathstringoptional

Valid file path

Full path to destination file for recording.

colorCompressionstringoptional

"None"
"Background subtraction"
"JPEG"

Setting RGB video compression mode.

jpegQualitynumberoptionalinteger from 0 to 100

JPEG quality for JPEG compression.

depthCompressionstringoptional"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

Retrieved from "http://docs.ipisoft.com/index.php?title=iPi_Automation_Add-on&oldid=1106"