Module, Parameter und Services¶
Die Softwaremodule des rc_visard heißen in der REST-API Nodes und vereinen jeweils bestimmte algorithmische Funktionen. Über folgenden Befehl lassen sich alle Softwaremodule der REST-API mit ihren jeweiligen Services und Parametern auflisten:
curl -X GET http://<host>/api/v1/nodes
Informationen zu einem bestimmten Modul (z.B. rc_stereocamera
) lassen sich mit folgendem Befehl abrufen:
curl -X GET http://<host>/api/v1/nodes/rc_stereocamera
- Status:
Während der Laufzeit stellt jedes Modul Informationen zu seinem aktuellen Status bereit. Dies umfasst nicht nur den aktuellen Verarbeitungsstatus des Moduls (z.B.
running
oderstale
), sondern die meisten Module melden auch Laufzeitstatistiken oder schreibgeschützte Parameter, sogenannte Statuswerte. Die Statuswerte desrc_stereocamera
-Moduls lassen sich beispielsweise wie folgt abrufen:curl -X GET http://<host>/api/v1/nodes/rc_stereocamera/status
Bemerkung
Die zurückgegebenen Statuswerte sind modulspezifisch und werden im jeweiligen Softwaremodul dokumentiert.
Bemerkung
Statuswerte werden nur gemeldet, wenn sich das jeweilige Modul im Zustand
running
befindet.
- Parameter:
Die meisten Module stellen Parameter über die REST-API des rc_visard zur Verfügung, damit ihr Laufzeitverhalten an den Anwendungskontext oder die Anforderungen angepasst werden kann. Die REST-API ermöglicht es, den Wert eines Parameters zu setzen und abzufragen. Darüber hinaus stellt sie weitere Angaben, wie z.B. den jeweiligen Standardwert und zulässige Minimal- bzw. Maximalwerte von Parametern, zur Verfügung.
Die
rc_stereomatching
-Parameter lassen sich beispielsweise wie folgt abrufen:curl -X GET http://<host>/api/v1/nodes/rc_stereomatching/parameters
Der
quality
-Parameter dieses Moduls könnte wie folgt auf den WertFull
gesetzt werden:curl -X PUT http://<host>/api/v1/nodes/rc_stereomatching/parameters?quality=Full
oder äquivalent
curl -X PUT --header 'Content-Type: application/json' -d '{ "value": "Full" }' http://<host>/api/v1/nodes/rc_stereomatching/parameters/quality
Bemerkung
Laufzeitparameter sind modulspezifisch und werden in dem jeweiligen Softwaremodul dokumentiert.
Bemerkung
Die meisten Parameter, die die Module über die REST-API anbieten, lassen sich auch über die benutzerfreundliche Web GUI des rc_visard erkunden und austesten.
Bemerkung
Einige der Parameter, die über die REST-API des rc_visard bereitgestellt werden, sind auch über die GigE Vision 2.0/GenICam-Schnittstelle zugänglich. Die Einstellung dieser Parameter über die REST-API und die Web GUI ist verboten, solange ein GenICam-Client verbunden ist.
Zudem bietet jedes Modul, das Laufzeitparameter bereitstellt, auch Services, um die aktuellen Parametereinstellungen zu speichern oder um die Werkseinstellungen aller Parameter wiederherzustellen.
- Services:
Einige Module bieten auch Services, die sich über die REST-API aufrufen lassen. Hierzu gehört beispielsweise das oben bereits genannte Speichern und Wiederherstellen von Parametern oder auch das Starten und Stoppen von Modulen. Die Services des Moduls zur Hand-Auge-Kalibrierung lassen sich beispielsweise wie folgt aufrufen:
curl -X GET http://<host>/api/v1/nodes/rc_hand_eye_calibration/services
Um einen Service eines Moduls aufzurufen, wird eine
PUT
-Anfrage mit servicespezifischen Argumenten für die jeweilige Ressource gestellt (siehe das"args"
-Feld des Service-Datenmodells). Beispielsweise lässt sich folgendermaßen eine Bildaufnahme mit dem Stereo-Matching-Modul auslösen:curl -X PUT --header 'Content-Type: application/json' -d '{ "args": {} }' http://<host>/api/v1/nodes/rc_stereomatching/services/acquisition_trigger
Bemerkung
Die Services und zugehörigen Argumente sind modulspezifisch und werden im jeweiligen Softwaremodul dokumentiert.
Die folgende Liste enthält alle REST-API-Anfragen zum Status des Moduls und seinen Parametern und Services:
-
GET
/nodes
¶ Abruf einer Liste aller verfügbaren Module.
Musteranfrage
GET /api/v1/nodes HTTP/1.1
Musterantwort
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" } ]
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: NodeInfo-Array)
Referenzierte Datenmodelle:
-
GET
/nodes/{node}
¶ Abruf von Informationen zu einem einzelnen Modul.
Musteranfrage
GET /api/v1/nodes/<node> HTTP/1.1
Musterantwort
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" }
Parameter: - node (string) – Modulname (obligatorisch)
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: NodeInfo)
- 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
-
GET
/nodes/{node}/parameters
¶ Abruf von Parametern eines Moduls.
Musteranfrage
GET /api/v1/nodes/<node>/parameters?name=<name> HTTP/1.1
Musterantwort
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 } ]
Parameter: - node (string) – Modulname (obligatorisch)
Anfrageparameter: - name (string) – Schränkt Ergebnisse auf Parameter mit diesem Namen ein (optional).
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter-Array)
- 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
-
PUT
/nodes/{node}/parameters
¶ Aktualisierung mehrerer Parameter.
Musteranfrage
PUT /api/v1/nodes/<node>/parameters HTTP/1.1 Accept: application/json [ { "name": "string", "value": {} } ]
Musterantwort
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 } ]
Parameter: - node (string) – Modulname (obligatorisch)
JSON-Objekt-Array zur Anfrage: - parameters (ParameterNameValue) – Liste von Parametern (obligatorisch)
Anfrage-Header: - Accept – application/json
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter-Array)
- 400 Bad Request – Ungültiger Parameterwert
- 403 Forbidden – Aktualisierung des Parameters verboten, z.B. weil er aufgrund einer laufenden GigE Vision-Anwendung gesperrt ist oder keine valide Lizenz für dieses Modul vorliegt.
- 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
-
GET
/nodes/{node}/parameters/{param}
¶ Abruf eines bestimmten Parameters eines Moduls.
Musteranfrage
GET /api/v1/nodes/<node>/parameters/<param> HTTP/1.1
Musterantwort
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" }
Parameter: - node (string) – Modulname (obligatorisch)
- param (string) – Name des Parameters (obligatorisch)
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter)
- 404 Not Found – Modul oder Parameter nicht gefunden
Referenzierte Datenmodelle:
-
PUT
/nodes/{node}/parameters/{param}
¶ Aktualisierung eines bestimmten Parameters eines Moduls.
Musteranfrage
PUT /api/v1/nodes/<node>/parameters/<param> HTTP/1.1 Accept: application/json { "value": {} }
Musterantwort
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" }
Parameter: - node (string) – Modulname (obligatorisch)
- param (string) – Name des Parameters (obligatorisch)
JSON-Objekt zur Anfrage: - parameter (ParameterValue) – zu aktualisierender Parameter als JSON-Objekt (obligatorisch)
Anfrage-Header: - Accept – application/json
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter)
- 400 Bad Request – Ungültiger Parameterwert
- 403 Forbidden – Aktualisierung des Parameters verboten, z.B. weil er aufgrund einer laufenden GigE Vision-Anwendung gesperrt ist oder keine valide Lizenz für dieses Modul vorliegt.
- 404 Not Found – Modul oder Parameter nicht gefunden
Referenzierte Datenmodelle:
-
GET
/nodes/{node}/services
¶ Abruf von Beschreibungen aller von einem Modul angebotenen Services.
Musteranfrage
GET /api/v1/nodes/<node>/services HTTP/1.1
Musterantwort
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" } } ]
Parameter: - node (string) – Modulname (obligatorisch)
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Service-Array)
- 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
-
GET
/nodes/{node}/services/{service}
¶ Abruf der Beschreibung eines modulspezifischen Services.
Musteranfrage
GET /api/v1/nodes/<node>/services/<service> HTTP/1.1
Musterantwort
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" } }
Parameter: - node (string) – Modulname (obligatorisch)
- service (string) – Name des Service (obligatorisch)
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Funktion)
- 404 Not Found – Modul oder Service nicht gefunden
Referenzierte Datenmodelle:
-
PUT
/nodes/{node}/services/{service}
¶ Aufruf des Services eines Moduls: Die benötigten Argumente und die zugehörige Antwort hängt vom Modul und vom Service ab.
Musteranfrage
PUT /api/v1/nodes/<node>/services/<service> HTTP/1.1 Accept: application/json { "args": {} }
Musterantwort
HTTP/1.1 200 OK Content-Type: application/json { "name": "set_pose", "response": { "message": "Grid detected, pose stored.", "status": 1, "success": true } }
Parameter: - node (string) – Modulname (obligatorisch)
- service (string) – Name des Service (obligatorisch)
JSON-Objekt zur Anfrage: - service args (Service) – Beispielargumente (obligatorisch)
Anfrage-Header: - Accept – application/json
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Serviceaufruf erledigt (returns Service)
- 403 Forbidden – Service-Aufruf verboten, z.B. weil keine valide Lizenz für dieses Modul vorliegt.
- 404 Not Found – Modul oder Service nicht gefunden
Referenzierte Datenmodelle:
-
GET
/nodes/{node}/status
¶ Abruf des Status eines Moduls.
Musteranfrage
GET /api/v1/nodes/<node>/status HTTP/1.1
Musterantwort
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" } }
Parameter: - node (string) – Modulname (obligatorisch)
Antwort-Headers: - Content-Type – application/json
Statuscodes: - 200 OK – Erfolgreiche Verarbeitung (Rückgabe: NodeStatus)
- 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle: