Nodes, parameters, and services

Nodes represent the rc_visard’s software components , each bundling a certain algorithmic functionality. All available REST-API nodes can be listed with their service calls and parameters using

curl -X GET http://<host>/api/v1/nodes

Information about a specific node (e.g., rc_stereocamera) can be retrieved using

curl -X GET http://<host>/api/v1/nodes/rc_stereocamera
Status:

During run-time, each node offers information about its current status. This includes not only the current processing status of the component (e.g., running or stale), but most nodes also offer run-time statistics or read-only parameters, so-called status values. As an example, the rc_stereocamera values can be retrieved using

curl -X GET http://<host>/api/v1/nodes/rc_stereocamera/status

Note

The returned status values are specific to individual nodes and are documented in the respective software component .

Note

The status values are only reported when the respective node is in the running state.

Parameters:

Most nodes expose parameters via the rc_visard’s REST-API to allow their run-time behaviors to be changed according to application context or requirements. The REST-API permits to read and write a parameter’s value, but also provides further information such as minimum, maximum, and default values.

As an example, the rc_stereomatching parameters can be retrieved using

curl -X GET http://<host>/api/v1/nodes/rc_stereomatching/parameters

Its quality parameter could be set to Full using

curl -X PUT http://<host>/api/v1/nodes/rc_stereomatching/parameters?quality=Full

or equivalently

curl -X PUT --header 'Content-Type: application/json' -d '{ "value": "Full" }' http://<host>/api/v1/nodes/rc_stereomatching/parameters/quality

Note

Run-time parameters are specific to individual nodes and are documented in the respective software component .

Note

Most of the parameters that nodes offer via the REST-API can be explored and tested via the rc_visard’s user-friendly Web GUI .

Note

Some parameters exposed via the rc_visard’s REST-API are also available from the GigE Vision 2.0/GenICam image interface . Please note that setting those parameters via the REST-API or Web GUI is prohibited if a GenICam client is connected.

In addition, each node that offers run-time parameters also features services to save, i.e., persist, the current parameter setting, or to restore the default values for all of its parameters.

Services:

Some nodes also offer services that can be called via REST-API, e.g., to save and restore parameters as discussed above, or to start and stop nodes. As an example, the services of the hand-eye calibration component could be listed using

curl -X GET http://<host>/api/v1/nodes/rc_hand_eye_calibration/services

A node’s service is called by issuing a PUT request for the respective resource and providing the service-specific arguments (see the "args" field of the Service data model). As an example, the stereo matching component can be triggered to do an acquisition by:

curl -X PUT --header 'Content-Type: application/json' -d '{ "args": {} }' http://<host>/api/v1/nodes/rc_stereomatching/services/acquisition_trigger

Note

The services and corresponding argument data models are specific to individual nodes and are documented in the respective software component .

The following list includes all REST-API requests regarding the node’s status, parameters, and services calls:

GET /nodes

Get list of all available nodes.

Template request

GET /api/v1/nodes HTTP/1.1

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "rc_stereocalib",
    "parameters": [
      "grid_width",
      "grid_height",
      "snap"
    ],
    "services": [
      "save_parameters",
      "reset_defaults",
      "change_state"
    ],
    "status": "stale"
  },
  {
    "name": "rc_stereocamera",
    "parameters": [
      "fps",
      "exp_auto",
      "exp_value",
      "exp_max"
    ],
    "services": [
      "save_parameters",
      "reset_defaults"
    ],
    "status": "running"
  },
  {
    "name": "rc_hand_eye_calibration",
    "parameters": [
      "grid_width",
      "grid_height",
      "robot_mounted"
    ],
    "services": [
      "save_parameters",
      "reset_defaults",
      "set_pose",
      "reset",
      "save",
      "calibrate",
      "get_calibration"
    ],
    "status": "stale"
  },
  {
    "name": "rc_stereo_ins",
    "parameters": [],
    "services": [],
    "status": "stale"
  },
  {
    "name": "rc_stereomatching",
    "parameters": [
      "quality",
      "seg",
      "fill",
      "minconf",
      "mindepth",
      "maxdepth",
      "maxdeptherr"
    ],
    "services": [
      "save_parameters",
      "reset_defaults"
    ],
    "status": "running"
  },
  {
    "name": "rc_stereovisodo",
    "parameters": [
      "disprange",
      "nkey",
      "ncorner",
      "nfeature"
    ],
    "services": [
      "save_parameters",
      "reset_defaults"
    ],
    "status": "stale"
  }
]
Response Headers:
 
Status Codes:
  • 200 OK – successful operation (returns array of NodeInfo)
Referenced Data Models:
 
GET /nodes/{node}

Get info on a single node.

Template request

GET /api/v1/nodes/<node> HTTP/1.1

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "rc_stereocamera",
  "parameters": [
    "fps",
    "exp_auto",
    "exp_value",
    "exp_max"
  ],
  "services": [
    "save_parameters",
    "reset_defaults"
  ],
  "status": "running"
}
Parameters:
  • node (string) – name of the node (required)
Response Headers:
 
Status Codes:
Referenced Data Models:
 
GET /nodes/{node}/parameters

Get parameters of a node.

Template request

GET /api/v1/nodes/<node>/parameters?name=<name> HTTP/1.1

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "default": 25,
    "description": "Frames per second in Hz",
    "max": 25,
    "min": 1,
    "name": "fps",
    "type": "float64",
    "value": 25
  },
  {
    "default": true,
    "description": "Switching between auto and manual exposure",
    "max": true,
    "min": false,
    "name": "exp_auto",
    "type": "bool",
    "value": true
  },
  {
    "default": 0.007,
    "description": "Maximum exposure time in s if exp_auto is true",
    "max": 0.018,
    "min": 6.6e-05,
    "name": "exp_max",
    "type": "float64",
    "value": 0.007
  }
]
Parameters:
  • node (string) – name of the node (required)
Query Parameters:
 
  • name (string) – limit result to parameters with name (optional)
Response Headers:
 
Status Codes:
  • 200 OK – successful operation (returns array of Parameter)
  • 404 Not Found – node not found
Referenced Data Models:
 
PUT /nodes/{node}/parameters

Update multiple parameters.

Template request

PUT /api/v1/nodes/<node>/parameters HTTP/1.1
Accept: application/json

[
  {
    "name": "string",
    "value": {}
  }
]

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "default": 25,
    "description": "Frames per second in Hz",
    "max": 25,
    "min": 1,
    "name": "fps",
    "type": "float64",
    "value": 10
  },
  {
    "default": true,
    "description": "Switching between auto and manual exposure",
    "max": true,
    "min": false,
    "name": "exp_auto",
    "type": "bool",
    "value": false
  },
  {
    "default": 0.005,
    "description": "Manual exposure time in s if exp_auto is false",
    "max": 0.018,
    "min": 6.6e-05,
    "name": "exp_value",
    "type": "float64",
    "value": 0.005
  }
]
Parameters:
  • node (string) – name of the node (required)
Request JSON Array of Objects:
 
  • parameters (ParameterNameValue) – array of parameters (required)
Request Headers:
 
Response Headers:
 
Status Codes:
  • 200 OK – successful operation (returns array of Parameter)
  • 400 Bad Request – invalid parameter value
  • 403 Forbidden – Parameter update forbidden, e.g. because they are locked by a running GigE Vision application or there is no valid license for this component.
  • 404 Not Found – node not found
Referenced Data Models:
 
GET /nodes/{node}/parameters/{param}

Get a specific parameter of a node.

Template request

GET /api/v1/nodes/<node>/parameters/<param> HTTP/1.1

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "default": "H",
  "description": "Quality, i.e. H, M or L",
  "max": "",
  "min": "",
  "name": "quality",
  "type": "string",
  "value": "H"
}
Parameters:
  • node (string) – name of the node (required)
  • param (string) – name of the parameter (required)
Response Headers:
 
Status Codes:
  • 200 OK – successful operation (returns Parameter)
  • 404 Not Found – node or parameter not found
Referenced Data Models:
 
PUT /nodes/{node}/parameters/{param}

Update a specific parameter of a node.

Template request

PUT /api/v1/nodes/<node>/parameters/<param> HTTP/1.1
Accept: application/json

{
  "value": {}
}

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "default": "H",
  "description": "Quality, i.e. H, M or L",
  "max": "",
  "min": "",
  "name": "quality",
  "type": "string",
  "value": "M"
}
Parameters:
  • node (string) – name of the node (required)
  • param (string) – name of the parameter (required)
Request JSON Object:
 
  • parameter (ParameterValue) – parameter to be updated as JSON object (required)
Request Headers:
 
Response Headers:
 
Status Codes:
  • 200 OK – successful operation (returns Parameter)
  • 400 Bad Request – invalid parameter value
  • 403 Forbidden – Parameter update forbidden, e.g. because they are locked by a running GigE Vision application or there is no valid license for this component.
  • 404 Not Found – node or parameter not found
Referenced Data Models:
 
GET /nodes/{node}/services

Get descriptions of all services a node offers.

Template request

GET /api/v1/nodes/<node>/services HTTP/1.1

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "args": {},
    "description": "Restarts the component.",
    "name": "restart",
    "response": {
      "accepted": "bool",
      "current_state": "string"
    }
  },
  {
    "args": {},
    "description": "Starts the component.",
    "name": "start",
    "response": {
      "accepted": "bool",
      "current_state": "string"
    }
  },
  {
    "args": {},
    "description": "Stops the component.",
    "name": "stop",
    "response": {
      "accepted": "bool",
      "current_state": "string"
    }
  }
]
Parameters:
  • node (string) – name of the node (required)
Response Headers:
 
Status Codes:
Referenced Data Models:
 
GET /nodes/{node}/services/{service}

Get description of a node’s specific service.

Template request

GET /api/v1/nodes/<node>/services/<service> HTTP/1.1

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "args": {
    "pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "slot": "int32"
  },
  "description": "Save a pose (grid or gripper) for later calibration.",
  "name": "set_pose",
  "response": {
    "message": "string",
    "status": "int32",
    "success": "bool"
  }
}
Parameters:
  • node (string) – name of the node (required)
  • service (string) – name of the service (required)
Response Headers:
 
Status Codes:
  • 200 OK – successful operation (returns Service)
  • 404 Not Found – node or service not found
Referenced Data Models:
 
PUT /nodes/{node}/services/{service}

Call a service of a node. The required args and resulting response depend on the specific node and service.

Template request

PUT /api/v1/nodes/<node>/services/<service> HTTP/1.1
Accept: application/json

{
  "args": {}
}

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "set_pose",
  "response": {
    "message": "Grid detected, pose stored.",
    "status": 1,
    "success": true
  }
}
Parameters:
  • node (string) – name of the node (required)
  • service (string) – name of the service (required)
Request JSON Object:
 
  • service args (Service) – example args (required)
Request Headers:
 
Response Headers:
 
Status Codes:
  • 200 OK – Service call completed (returns Service)
  • 403 Forbidden – Service call forbidden, e.g. because there is no valid license for this component.
  • 404 Not Found – node or service not found
Referenced Data Models:
 
GET /nodes/{node}/status

Get status of a node.

Template request

GET /api/v1/nodes/<node>/status HTTP/1.1

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "running",
  "timestamp": 1503075030.2335997,
  "values": {
    "baseline": "0.0650542",
    "color": "0",
    "exp": "0.00426667",
    "focal": "0.844893",
    "fps": "25.1352",
    "gain": "12.0412",
    "height": "960",
    "temp_left": "39.6",
    "temp_right": "38.2",
    "time": "0.00406513",
    "width": "1280"
  }
}
Parameters:
  • node (string) – name of the node (required)
Response Headers:
 
Status Codes:
Referenced Data Models: