Skip to content

Action Definitions

Jump to bottom
Andre Antakli edited this page Sep 2, 2021 · 47 revisions

In AJAN, MMUs are executed using the action nodes described in chapter AJAN Actions. For this purpose, two Action Definitions were created as PluginActions and presented below.

To be able to execute a MMU in MOSIM, so-called MInstructions are required. To be able to execute an MInstruction three data are needed in general: a name and a generated ID of this instruction; and to know which MMU is to be executed, the motion type or the ID of the MMU to be used.

But in most cases a MMU needs more context information to create an animation. For this a MInstruction has two more fields or lists. The MInstruction.Properties list contains string-based key-value pairs with required or optional properties. The second list MInstruction.Constraints contains MConstraints. Below is an example shown of the of Locomotion/Walk MMU with its listed properties or parameters and how to create and execute an MInstruction for that MMU in C#:

MMU Input needed to run a Locomotion/Walk MMU

Example execution example in C# for a Locomotion/Walk MMU

MInstruction walkInstruction = new MInstruction(MInstructionFactory.GenerateID(), "Walk", "Locomotion/Walk")
{
     Properties = PropertiesCreator.Create("TargetID", UnitySceneAccess.Instance.GetSceneObjectByName("WalkTarget").ID)
};

this.CoSimulator.AssignInstruction(walkInstruction, currentState);

As can be seen, the Locomotion/Walk MMU needs a defined TargetID or TargetName as property to know to which target the avatar should walk through this MMU. In the shown C# example a MSceneObject with the name "WalkTarget" is read and its ID is passed to the MMU.

In order for AJAN to create and execute an MInstruction with said properties and constraints, the required information must be read out via an SBT Action node as Action Input and is used by an Action Definition to send the CoSimulator the Thrift based MInstruction instruction.


SPARQL-BT MOSIM Async MMU Instruction (Asynchronous)

Implementation: https://github.com/aantakli/AJAN-service/blob/master/pluginsystem/plugins/MOSIMPlugin/src/main/java/de/dfki/asr/ajan/pluginsystem/mosimplugin/extensions/instructions/AsyncMMUInstruction.java

To execute a MMU synchronously in AJAN this Action Definition is needed. Here an MMU is executed and then considered as finished without waiting for a corresponding event (e.g. "end") from the CoSimulator. But this means that AJAN does not notice if a MMU is not executable. The Pose/Idle could be seen as an example for a synchronous execution of a MMU, where AJAN does not have to wait until this is completed, as it must be explicitly terminated.

To execute an AJAN action, whether ServiceAction or PluginAction based, with an Action Definition, an Action Input with said information is required. What information is needed is specified with a Consumable. In the case of this action definition, the following Consumable is used:

Consumable

	actn:consumes [
		a actn:Consumable ;
		actn:sparql """
			PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
			PREFIX mosim: <http://www.dfki.de/mosim-ns#>
			PREFIX actn: <http://www.ajan.de/actn#>
			ASK
			WHERE {
				?instruction rdf:type mosim:MInstruction .
				?instruction mosim:mmu ?mmu .
				OPTIONAL {
					?instruction mosim:actionName ?actionName .
					?instruction mosim:finalEvent ?event .
					?instruction mosim:mmuProperty ?property .
					?instruction mosim:constraint ?constraint .
					?instruction mosim:startCondition ?startCond .
					?instruction mosim:endCondition ?endCond .
				}
				?cosim rdf:type mosim:CoSimulator .
				?cosim mosim:host ?host .
				?cosim mosim:port ?port .
			}"""^^xsd:string ;
	] ;

As shown in the Consumable, basically two pieces of information are needed to execute an MMU with AJAN: (1) a instruction resource ?instruction with a the Motion Type mosim:mmu (xsd:sting); (2) information about the CoSimulator mosim:CoSimulator with its host address mosim:host (<xsd:sting>) and port mosim:port (<xsd:integer>) to be used. Optionally, MInstruction properties mosim:mmuProperty (<URI> whith whole resource description), constraints mosim:constraint (<URI> whith whole resource description), start mosim:startCondition (<xsd:sting>) and end mosim:endCondition (<xsd:sting>) conditions, and an action name mosim:actionName (<xsd:sting>) can be specified. If and which of these data must be defined depends on the MMU to be used.


CoSimulator Resource:

Basically, the needed CoSimulator resource (represented in the example with ?cosim) from RDF type mosim:CoSimulator (where mosim: is the @prefix of http://www.ajan.de/mosim-ns#) has the following parameters:

  • rdf:type <URI> (mosim:CoSimulator)
  • mosim:host <xsd:string> (e.g. "http://localhost")
  • mosim:port <xsd:integer> (e.g. 9011)

RDF Example

@prefix mosim: <http://www.dfki.de/mosim-ns#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

_:cosim rdf:type mosim:CoSimulator .
_:cosim mosim:host "http://localhost" .
_:cosim mosim:port 9011 .

Instruction Resource:

Basically, the needed MInstruction resource (represented in the example with ?instruction) from RDF type mosim:MInstruction (where mosim: is the @prefix of http://www.ajan.de/mosim-ns#) has the following parameters:

  • rdf:type <URI> (mosim:MInstruction)
  • mosim:mmu <xsd:string> (e.g. "Locomotion/Walk")

Optional Action Name: AJAN specific and only used, if a instruction needs to be accessed via its "Name" later in the SBT.

  • mosim:actionName <xsd:string> (e.g. "WalkX")

Optional Final Event: An additional MMU-based event that AJAN listens for, to recognize an AsyncMMUInstruction-based action as completed. This event overwrites the standard CoSimulator based event "end".

  • mosim:finalEvent <xsd:string> (e.g. "PositioningFinished")

Optional MInstruction.Properties<string,string>:

  • mosim:mmuProperty <URI_Pr> (single Property<string,string>; multiple properties can be defined)
  • <URI_Pr> rdf:type <URI> (mosim:MProperty)
  • <URI_Pr> mosim:key <xsd:string> (e.g. "TargetID")
  • <URI_Pr> mosim:value <xsd:string> (e.g. "12")

Optional MInstruction.Constraints:

  • mosim:constraint <URI_Cs> (single MConstraint; multiple constraints can be defined)
  • <URI_Cs> rdf:type <URI> (mosim:MConstraint)
  • <URI_Cs> mosim:object <xsd:string> (Base64 data, e.g. "fsdfsdf845njksnfi2348hjsdv...")

Optional Start/End Conditions:

  • mosim:startCondition <xsd:string>
  • mosim:endCondition <xsd:string>

RDF Example

@prefix mosim: <http://www.dfki.de/mosim-ns#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

test:Instruction mosim:mmu "Locomotion/Walk" .
test:Instruction mosim:actionName "WalkX" .
test:Instruction mosim:mmuProperty test:TargetProperty .
test:Instruction mosim:constraint test:Constraint .

test:TargetProperty rdf:type mosim:MProperty .
test:TargetProperty mosim:key "TargetID" .
test:TargetProperty mosim:value "12" .

test:Constraint rdf:type mosim:MConstraint .
test:Constraint mosim:object ?object .

Producible

	actn:produces [
		a actn:Producible ;
		actn:sparql """
			ASK
			WHERE {
				?s ?p ?o .
			}"""^^xsd:string ;
	] ;

Since MMUs strictly speaking do not have a return value and only emit an event, this PluginAction independently generates an ActionResult and stores it in the agent's knowledge base. For this reason, this Producible only checks whether an RDF record was created. The structure of the output or the ActionResult is explained in the chapter MOSIM Plugin Instruction.


Action Input example to run a Locomotion/Walk MMU in [Turtle/RDF] (comments strat with: #)

@prefix mosim: <http://www.dfki.de/mosim-ns#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix test: <http://test/> .

test:Instruction mosim:mmu "Locomotion/Walk" .
test:Instruction mosim:actionName "WalkX" .
test:Instruction mosim:mmuProperty test:TargetProperty .
	
test:TargetProperty rdf:type mosim:MProperty .
test:TargetProperty mosim:key "TargetID" .
test:TargetProperty mosim:value "12" .

_:cosim rdf:type mosim:CoSimulator .
_:cosim mosim:host "http://localhost" .
_:cosim mosim:port 9011 .

SPARQL-BT MOSIM Async MMU Instruction (Synchronous)

Implementation: https://github.com/aantakli/AJAN-service/blob/master/pluginsystem/plugins/MOSIMPlugin/src/main/java/de/dfki/asr/ajan/pluginsystem/mosimplugin/extensions/instructions/MMUInstruction.java

To execute a MMU synchronously in AJAN this Action Definition is needed. Here an MMU is executed and then considered as finished without waiting for a corresponding event (e.g. "end") from the CoSimulator. But this means that AJAN does not notice if a MMU is not executable. The Pose/Idle could be seen as an example for a synchronous execution of a MMU, where AJAN does not have to wait until this is completed, as it must be explicitly terminated.

Since the not waiting for an event is the only difference between the MMUInstruction presented here and the AsyncMMUInstruction described earlier, this Action Definition will not be discussed further below.

mosim:finalEvent

Consumable

	actn:consumes [
		a actn:Consumable ;
		actn:sparql """
			PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
			PREFIX mosim: <http://www.dfki.de/mosim-ns#>
			PREFIX actn: <http://www.ajan.de/actn#>
			ASK
			WHERE {
				?instruction mosim:mmu ?mmu .
				OPTIONAL {
					?instruction mosim:actionName ?actionName .
					?instruction mosim:mmuProperty ?property .
					?instruction mosim:constraint ?constraint .
					?instruction mosim:startCondition ?startCond .
					?instruction mosim:endCondition ?endCond .
				}
				?cosim rdf:type mosim:CoSimulator .
				?cosim mosim:host ?host .
				?cosim mosim:port ?port .
			}"""^^xsd:string ;
	] ;

Producible

	actn:produces [
		a actn:Producible ;
		actn:sparql """
			ASK
			WHERE {
				?s ?p ?o .
			}"""^^xsd:string ;
	] ;

Clone this wiki locally