Interface miMod(Model) – step 0031 – January 2010

1 Introduction

There are several types of SrrTrains Models

Intrinsic Models
Static Models
Vehicle Models

Remark: SrrTrains does not pose any requirements on Non-SrrTrains Models, that might be used in SrrTrains model railroad layouts, too.

Intrinsic models are implemented as part of a module, using SRR objects directly. Such models do NOT provide the miMod(Model) interface.

Static models are provided as X3D prototypes, providing the miMod(Model) interface to be loaded and initialized by a module statically.

Vehicle models, providing the miMod(Model) interface to be loaded and initialized by the SRR Controller – TMM.

2 Static Models – Definition of miMod(Model)

Static models use SRR objects to implement (a part of) their functionality.

Furthermore they may use the SrrTracer prototype to output diagnostic information.

Both options require to have an object ID (objId) and to be initialized with the module parameters (modParam).

Therefore SrrTrains requires the following minimum interface from a static model:

The static model shall be implemented as a <ProtoDeclare> node in an external file.
The model author shall document how to reach the prototype file (URL).
The model author shall document the origin and orientation of the local coordinate system in relation to the model (enabling the module author to create a surrounding <Transform> node with the right values of translation and rotation).
Alternatively, the model author shall provide and document some fields at the interface, that allow to set position and orientation of the model.
The prototype defined in the <ProtoDeclare> shall provide at least the following interface.

The prototype shall use the objId and the modParam to initialize all contained SRR objects and an optional SrrTracer instance.

3 Vehicle Models – Definition of miMod(Model)

Vehicle models are loaded by the SRR Controller – TMM. The convention is, that the file, that is referenced by an URL, must create one or more X3D nodes, when being loaded with Browser.createVrmlFromURL().

The second node will be taken as the model's instance.

After having loaded the model, the SRR Controller will

set standalone to false
set the quasiModule field to the quasi-module-name that has to be used instead of a module name in trace output and network sensor IDs
set the objId of the instance of the model
initialize the model with the modParam parameter
wait, until the model outputs initialized != null (success case) or initialized = null (failure case)

When unloading a model, the SRR Controller will

set the enabled parameter of the model to false.

Hence, SrrTrains requires the following minimum interface from a vehicle model

The vehicle model shall be implemented in an external file, accessible by a URL.
When loading the file with Browser.createVrmlFromUrl(), the second node of the created scene shall represent the instance of the vehicle.
This vehicle shall be instrumented by SRR objects (a so-called specific vehicle prototype).
The instance of the vehicle shall offer at least following fields

<field accessType='inputOutput' name='objId' type='SFString'/>
<field accessType='inputOutput' name='quasiModule' type='SFString'/>
<field accessType='inputOutput' name='modParam' type='SFNode'/>
<field accessType='inputOutput' name='standalone' type='SFBool' value="true"/>
<field accessType='outputOnly' name='initialized' type='SFNode'/>
<field accessType='inputOutput' name='enabled' type='SFBool' value='true'/>
objId, quasiModule and modParam shall be used to initialize the contained specific vehicle prototype and to initialize an optional instance of SrrTracer. The value of objId will be set by the SRR Controller – TMM.
The value of standalone shall be forwarded to the specific vehicle prototype, SRR Controller – TMM will set this value to false, after having loaded the vehicle.
The value of enabled shall be forwarded to the specific vehicle prototype and it shall be used to enable/disable all other time sensors / network sensors etc. of the model.
When the specific vehicle prototype reports initialized, the vehicle model shall forward this value to the user (SRR Controller – TMM).

4 Example of a Vehicle Model