View source for AI Scenery objects

{{Non-stable}}

{{infobox subsystem
|name = AI Scenery Objects
|started= 07/2018
|description = Providing a way for controlling scenery objects from the scenery objects database by the AI subsystem 
|status = Under active development as of 07/2018
|developers =  ThomasS (since 07/2018) 
<!--
|topic-fg= 
-->
}}

== Objective ==
{{See also|Howto:Animated jetways}}
<!--
{{WIP}}
-->

The currently preferred way for defining animated jetways for an airport is putting the definitions into a ICAO.jetways.xml file and let someone with commit access upload the file to the scenery server for sharing it by TerraSync. But using a single file per airport has a few drawbacks:

* Its difficult to maintain and to evolve the jetways step by step without always modifying the complete file
* It bypasses parts of the well established process for adding objects to the scenery and always requires some manual intervention by a core developer for committing it.
* Temporary runtime model files are created on demand for each airport.

After some discussion on the developer mailing list  <ref>{{cite web
  |url    =  https://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/CAMcJc7oP_AuXaNDQOF1pTYtSM4pskCDWg1gXpxkKtXaF4LVfLg%40mail.gmail.com/#msg36378569
  |title  =  <nowiki> Mailing list discussion </nowiki> 
  |author =  <nowiki> ThomasS </nowiki> 
  |date   =  July, 2018 
  |script_version = 0.40 
  }}</ref> the original idea scetched above broadened to a more generic solution, that not only disposes icao.jetways.xml, so the name "AI Scenery Object" arose. So an animated jetway is just one type of an AI Scenery Object. Cranes or bridges might be other types.

This page is about a proof of concept for an alternative way for maintaining animated jetways by uploading animated jetways as AI scenery Object to the scenery object database similar to other scenery objects and have these controlled by the AI subsystem and a Nasal module  <ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?f=5&t=34461&sid=4be4c415b0b814080102d632310b3297#p334260 
  |title  =  <nowiki> Animated Jetways: Type 1 or 2? </nowiki> 
  |author =  <nowiki> ThomasS </nowiki> 
  |date   =  Jul 20th, 2018 
  |added  =  Jul 20th, 2018
  |script_version = 0.40 
  }}</ref>.

== Specification ==

=== System Load (FPS) ===
Users not interested in animated objects (jetways) should not be affected. 

=== STG ===
A new STG token OBJECT_AI is added for defining an AI scenery object. There is no need for providing a shared option as these models are highly location specific. Such a line looks like

OBJECT_AI <object-properties-path> <flags> <longitude> <latitude>...

This complies to other object definitions except for the file referenced. This will not by a model file but just a property list file defining the AI object (see below).

ReaderWriterSTG decides depending on a global switch 
"ai-scenery-objects-enabled" to either:
* ignore these lines 
* load a static scenery object if available (supplied and defined by the scenery designer), otherwise the animated model is used. This provides the option to the scenery designer to define a less complex model for reducing frame rate drawbacks. 
* create a PagedLOD node to display a static object (jetway) until the range reaches a defined threhold (might be 100m for jetways), and then loads an animated object (jetway). Pass the model information to AIManager for creating an instance of  FGAISceneryObject and load the object-properties-path into the AI/models subtree. The object-properties-path will be the file containing jetway location specific data. 

"flags" will just be a placeholder for future use for hopefully avoiding 
a change to the file specification for upcoming requirements. The exact 
implementation ReaderWriterSTG works however might change. 

=== object properties ===
The object properties file is a regular PropertyList file defining the characteristics of the scenery objects like
* the animated model file
* optionally a more simple static model file

=== controlling objects ===
The AI subsystem just takes care of hooking the model animation properties into the "/ai/models" subtree. Main control is performed by a Nasal module by triggering model animations.

== Outline ==
The existing solution in jetways.nas for controlling jetways will be retained. For not affecting readability and increaing the complexity of jetways.nas, the core jetway funtionality will be extracted into a separate module/addon that supports the new jetway definition.

The existing jetway solution by ICAO.jetways.xml will not be affected.

== Status as of January 2019 ==
Due to the overall complexity and the number of involved components a few sub projects are isolated. These sub projects are intended to be just generic multi purpose extensions to FlightGear, which might later be combined for achieving the "big jetway solution". The sub projects are:

1)  {{Progressbar|100}} {{done}} An additional FG-Command interface to the AI subsystem (AIManager aso.). This provides a way to let the AI subsystem create a new object by just executing a FG-Command. The object built uses a PagedLOD and respects two level of degree, if a low res model file is provided. By using FG-Command this interface will be available from several components like Nasal, ReaderWriterSTG, Websockets, telnet, aso. If the model loaded contains animations, the animation properties will be located below the node in /ai/models/. AIManager will tranform these objects like other AI objects, ie. adjust its position/orientation from the corresponding properties. Removing an object will also be triggered by an FG-Command.

This can be tested from Nasal console with
<syntaxhighlight>
    var position = geo.aircraft_position();
    var course = getprop("/orientation/heading-deg");
    position.apply_course_distance(course,300);
    var info = geodinfo(position.lat(), position.lon());    
    var alt = num(info[0]);
      
    fgcommand("add-aiobject", props.Node.new({
        "type": "static",
        "model":"Models/Airport/Jetway/j_generic_s.xml",
        "model-lowres":"Models/Buildings/silo.ac",
        "latitude": position.lat(),
        "longitude": position.lon(),        
        "altitude": alt*M2FT,
        "search-order": "DATA_ONLY"
    }));
</syntaxhighlight>
The original idea of using a property tree based interface inspired by ModelMgr has been dismissed.

2) {{pending}} A property tree based interface to the AI subsystem (AIManager) that lets drive AIManager animation properties in its update() routine depending on the tpf value. By using the property tree this interface will be available from several components like Nasal, Websockets, telnet, aso. This feature is especially useful for avoiding update loops in Nasal.

3) {{pending}} A new keyword OBJECT_AI (or similar) for STG files to let ReaderSTG use the above feature no 1) for placing objects.

4) {{pending}} An extended interface to the scenery database.

== References ==
{{Appendix}}