Using JavaProp to generate JSBSim propeller coefficients

2023-07-03T16:54:20Z

TheEagle: Created page

This is a tutorial on how to generate thrust and power coefficients for a JSBSim propeller using JavaProp.
[[Category:JSBSim]]
{{DEFAULTSORT:Using JavaProp to generate JSBSim propeller coefficients}}

Pax transport addon

2023-05-12T17:36:05Z

TheEagle:

{{Infobox addon|name=Pax transport|started=May 2023|contributors=TheFGFSEagle|status=Alpha|desc=This add-on allows you to transport cargo and persons between places}}

This add-on allows you to transport cargo and persons between places.

Template:Infobox addon

2023-05-12T17:34:13Z

TheEagle:

{{infobox subsystem
| name = {{{name|noname}}}
| started = {{{started|started-in}}}
| description = {{{desc|description}}}
| developers = {{{contributors|none}}}
| status = {{{status|unknown}}}
| coderepo = {{{url|none}}}
}}<includeonly>{{main other|[[Category:FlightGear addons]]}}{{howto other|[[Category:FlightGear addons]]}}</includeonly><noinclude>
{{-}}
{{Informative template|1=
__NOTOC__
== Goal ==

This template can be placed on articles about FlightGear [[addon]]s.

Adding this template to a page will automatically add [[:Category:FlightGear addons]] to that page.

== Usage ==
{{obr}}'''infobox addon'''
{{!}} ''name'' =
{{!}} ''started'' =
{{!}} ''desc'' =
{{!}} ''contributors'' =
{{!}} ''status'' =
{{!}} "coderepo" =
{{cbr}}
All parameters are optional.

; name: The name of the addon. Defaults to '''noname'''.
; started: When development started. Defaults to '''started-in'''.
; description: A short description of the addon. Defaults to '''description'''.
; status: The status of the addon. Defaults to '''unknown'''.
; developers: The developers of the addon. Defaults to '''none'''.
; coderepo: URL of a Git repo containing the code for the addon

== Examples ==
{{obr}}infobox addon{{cbr}}
{{infobox addon}}
{{-}}
{{obr}}infobox addon
{{!}} name = MoonWalker
{{!}} started = August 2005
{{!}} desc = Modifies the walker to simulate moon gravity.
{{!}} contributors =
* Joe Jumper
* Jittery Jim
{{!}} status = Concept
{{!}} coderepo = https://github.com/JoeJumper/MoonWalker
{{cbr}}
{{infobox addon
| name = MoonWalker
| started = August 2005
| desc = Modifies the walker to simulate moon gravity.
| contributors =
* Joe Jumper
* Jittery Jim
| status = Concept
| coderepo = https://github.com/JoeJumper/MoonWalker
}}
{{-}}
}}
[[Category:Infobox templates]]
</noinclude>

2023-04-14T00:57:50Z

TheEagle: Some small corrections, added documentation about commit 51149bf: Support expressions in material animations

The real world is full of motion. To simulate this in [[FlightGear]], '''models must be animated'''.

FlightGear allows you to animate models in response to property changes: for example, the propellers can spin when the engine is on and the elevators can move up and down with your controller. There is no fixed limit on what parts can be animated: the only requirements are that the part is named in the 3D model file, and that there is a property in the main tree that you can use to get the positioning information.

This document provides basic information for all kind of animations. When animating your model, it is very helpful to find an aircraft with parts similar to yours and use it as an example. Cut and paste the code into your wrapper file and then edit to suit.

== Notes ==
=== File name of main model and animation XML file ===
{{main article|Aircraft-set.xml#Not used for loading multiplayer aircraft}}
The file name of the main model and animation XML file, or the .ac file if there is no XML file, (in essence the property <code>/sim/model/path</code>) will be the name of the aircraft that is transmitted when using [[multiplayer]] and will also be used for loading multiplayer aircraft.

There is also a mechanism to substitute a full aircraft model with a simpler AI aircraft model if one is available at the same file path (including for example <code>Models/Boeing-797-800.xml</code>), but in <code>[[$FG_ROOT]]/'''AI'''/Aircraft/</code> instead of <code>$FG_ROOT/Aircraft/</code>.

=== .ac files ===
{{Main article|AC files: Understanding and changing .ac code#Identifying an object}}

When referring to an .ac file in your xml animation, it is important that the <code><object-name></code> exactly matches the object named in the .ac file (this includes cases!).

'''Note for SketchUp users:''' The spatial reference X/Y/Z used in animation to locate an object or a point are different from the ones in AC3D ie X values are the same in both but Y in animation must be matched to AC3D's -Z (Z value but opposite sign) and Z value in animation must be matched to AC3D's Y value.

'''Note for SketchUp users:''' when exporting to AC3D in Sketchup, the .ac file will name the objects in your model to "blah" by default. You need to amend the relevant object names in your .ac file using text edit, so that the xml will work.

=== Animation order ===
Animations are executed by FlightGear in the order that they are read in the model's .xml file. Therefore, it is very important to pay attention to the order, especially when multiple animations are applied to the same object(s). Wrong ordering of animations might cause [[Howto:Animate models#Timed|timed]] animations (used to create flashing lights) to not work. For further details see this [https://sourceforge.net/p/flightgear/mailman/message/37090714/ thread] on the development mailing list. Updated [https://scenery.flightgear.org/app.php?c=Models&a=browse&shared=18 shared Effects models] will be available very soon.

Similar problems can be encountered with the dist-scale instead of the timed animation.
== Tags used in most animations ==
=== Name ===
With a name animation, you can group multiple objects.

<source>
<animation>
<name>Collection1</name>
<object-name>Object1</object-name>
<object-name>Object2</object-name>
<object-name>Object3</object-name>
</animation>
</source>

The example above creates a "virtual object" with the name Collection1. In animation, we can animate this group of objects, by using:

<source>
<object-name>Collection1</object-name>
</source>

=== Object-name ===
These names are set in the 3D model. Each single object has a unique name; for easy identification it is advised to use descriptive names (LeftElevator, Rudder etc.). Animations are only applied to those objects that are mentioned in an object-name line (one object per line!). Animations lacking those, will be applied to the entire model.

=== Property ===
Each animation must be associated with exactly one property from the main FlightGear property tree (remember that the properties in the wrapper file are not part of the main tree), using <code><property></code> to provide the property path:

<source>
<animation>
<type>rotate</type>
<object-name>Rudder</object-name>
<property>controls/rudder</property>
</animation>
</source>

Note the omission of the leading slash '/' when referring to the property. This assures that when the model is used for AI or multiplayer traffic the animations will follow that of the AI controller instead of that of the user.

=== Axis ===
An axis part is required in every animation that involves a rotating or moving thing.

<source>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</source>

The axis are similar to the ones of the 3D model. There is a difference between rotation and translation:
* In rotation animations, the axis part defines around what axis the object rotates. Negative/positive values make the difference between counterclockwise and clockwise rotations.
* In translate animations, the part defines along what axis the object moves. If the x-axis is poiting backwards, an x-value of -1 will result in forward motion.

You could also define two points, between which FlightGear will calculate the correct axis. This makes the use of a [[#Center|<nowiki><center></nowiki>]] tag redundant! Such coordinates are extremely useful for animating control surfaces (rudder, elevators etc.).

<source>
<axis>
<x1-m> 4.9</x1-m>
<y1-m> 7.1</y1-m>
<z1-m>-1.0</z1-m>
<x2-m> 5.9</x2-m>
<y2-m>11.2</y2-m>
<z2-m>-0.5</z2-m>
</axis>
</source>

=== Center ===
Various animations ([[#Rotate|rotate]], [[#Spin|spin]], [[#Scale|scale]]) move around a center point.

<source>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
</source>

The axis are similar to the ones of the 3D model, so finding coordinates is easily done in 3D modeling software.

=== Using a geometry object for axis and centre (2017.2) ===

Added in V2017.2 is support to allow a geometry object (a line segment with two vertices) that is used to define both the centre and the axis for an animation. This will work with rotate, spin, translate and knob animations.

{{Note|Since SimGear commit 6ca9141083e62be1161d0ca2d1e3b918494dd6ad on next, this feature can also be used for slider (usage equivalent to that for a translate animation) and for any of the <*-center> / <*-axis> tags of a locked-track animation.}}

When used for translate animations, the axis line should be normalized (i.e. be 1 meter long) as its length acts as a factor for the translation distance.

The XML syntax for this is:

<source>
<axis>
<object-name>some-object</object-name>
</axis>
</source>

If the <code><axis>...</axis></code> section is omitted entirely, <code>{object-name}-axis</code> will be used by default, where <code>{object-name}</code> is the name of the object being animated (if we are animating more than one object, the first object is used). In the earlier example this would be <code>Rudder-axis</code>.

In the '''.ac''' file, specify a SURF with type (bottom 4 bits, 0=polygon, 1=closedline, 2=line) set to 2, and two vertices that define the axis. For example:

OBJECT poly
name "aileron.l-axis"
numvert 2
3.2077502191170844 0.18160835055097943 4.055616960642423
2.6758650763079 0.28024033462188946 6.477876098622225
numsurf 1
SURF 0x12
mat 0
refs 2
0 0 0
1 0 0
kids 0

Once the object-name used for the axis has been processed the geometry object will be hidden. This also allows a visual check for any axis objects that are not yet assigned.

It is possible to reuse the same object definition multiple times within a single XML file.

[[File:Canopy-animation-axis-object.png|small|Illustration of where an axis object (2017.2) can be placed for a canopy]]

[[File:Gauges-knobs-animation-axis-object.png|small|Illustration of where an axis object (2017.2) can be placed for cockpit elements]]

== Additional tags that can be used in most animations ==
=== Conditions ===
Multiple animations can make use of a conditional. Check <tt>$FGDATA/Docs/README.conditions</tt> for some more details.

* '''equals:''' property value (or second property) is equal to value/(first)property.
* '''greater-than:''' property value (or second property) is larger than value/(first)property.
* '''greater-than-equals:''' property value (or second property) is greater than or equal to value/(first)property.
* '''less-than:''' property value (or second property) is smaller than value/(first)property.
* '''less-than-equals:''' property value (or second property) is smaller than or equal to value/(first)property.

The example below is true when n1 has a value greater than 25.
<source>
<condition>
<greater-than>
<property>engines/engine[1]/n1</property>
<value>25</value>
</greater-than>
</condition>
</source>

Then there are some special tags:

* '''and:'''
* '''not:'''
* '''or:'''

In the example below, the condition is true when either n1 is greater than 25% or equal to 0%.
<source>
<condition>
<or>
<greater-than>
<property>engines/engine[1]/n1</property>
<value>25</value>
</greater-than>
<equals>
<property>engines/engine[1]/n1</property>
<value>0</value>
</equals>
</or>
</condition>
</source>

An example of implementation into an animation looks as follows:

<source>
<animation>
<object-name>Object</object-name>
<type>rotate</type>
<property>suface-positions/left-aileron-pos-norm</property>
<factor>25</factor>
<condition>
<greater-than>
<property>suface-positions/left-aileron-pos-norm</property>
<value>10</value>
</greater-than>
</condition>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

=== Interpolation ===
For non-fixed factors, an interpolation "table" can be created.

<source>
<interpolation>
<entry>
<ind> 0.0</ind>
<dep> 0.0</dep>
</entry>
<entry>
<ind> 0.667</ind>
<dep> 0.0</dep>
</entry>
<entry>
<ind> 1.0</ind>
<dep> 0.5</dep>
</entry>
</interpolation>
</source>

The lines above represent the following table:

{|
!Input
!Output
|-
|0.0
|0.0
|-
|0.667
|0.0
|-
|1.0
|0.5
|}

You can add as many entries as you need. Interpolation tables are often used for gear animations (eg. to open doors during gear-movements and close them again once the gear is either retracted or fully extended).

=== Expressions ===
For some animations it is possible to define complex animations by using [[Expressions|Expressions]]. This even allows to drive the animation from multiple properties without the need for additional Nasal scripts. Here is an example for a translate animation depending on two properties and the cosine function:
<syntaxhighlight lang="xml">
<animation>
<type>translate</type>
<expression>
<product>
<property>/my/factor-property</property>
<cos>
<deg2rad>
<property>/my/angular-property</property>
</deg2rad>
</cos>
</product>
</expression>
[..]more elements[..]
</animation>
</syntaxhighlight>

Animations which can utilize [[Expressions|Expressions]] are:
* [[Howto:Animate_models#Translate|Translate]]
* [[Howto:Animate_models#Rotate|Rotate]]
* [[Howto:Animate_models#Scale|Scale]]
* [[Howto:Animate_models#Range|Range]]
* [[Howto:Animate_models#Blend|Blend]]

See more detailed info at [[Expressions|Expressions]]

== Lights ==
As of January 2021 FlightGear supports multiple light sources just like Project Rembrandt has always done.
[[Compositor#Lights|Adding lights to a model]]

== Object animations ==
=== Alpha-test ===
<source>
<animation>
<type>alpha-test</type>
<object-name>Object</object-name>
<alpha-factor>0.01</alpha-factor>
</animation>
</source>
This "animation" is a way to set an alpha test on a model branch. The effect is to avoid depth buffer writing of pixel that are not seen because they are transparent. This is particulary useful when modeling a metallic structure or a tree with a billboard. The threshold of transparency is set with the <alpha-factor> element. See also [[Pixel testing in effects]].

=== Blend ===
Blends an object with the surrounding. Comparable to a translucency animation. A value of 0 corresponds to no transparency, i.e. and ordinary solid object, and a value of 1 makes the object fully transparent, i.e., not visible at all.

<source>
<animation>
<type>blend</type>
<property>/velocities/airspeed-kt</property>
<factor>0.00025</factor>
<min>0.2</min>
<max>0.7</max>
</animation>
</source>

* '''property:'''
* '''factor:'''
* '''min:'''
* '''max:'''
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

Note that when using the Project Rembrandt renderer, all transparent and translucent objects must be registered to display properly. [[Project_Rembrandt#Registering_all_translucent_surfaces|More information here.]]

=== Billboard ===
This faces an object towards the viewer. Often used on 2D objects, like clouds, trees and lights.

<source>
<animation>
<type>billboard</type>
<object-name>Object</object-name>
<spherical type="bool">true</spherical>
</animation>
</source>

* '''spherical:'''

=== Dist-scale ===
Used to scale an object, based on the distance to the viewer. <code><nowiki><ind></nowiki></code> and <code><nowiki><dep></nowiki></code> (independent and dependent) are the distance in meters and the scale at that distance.

<source>
<animation>
<type>dist-scale</type>
<object-name>Object</object-name>
<interpolation>
<entry>
<ind>0</ind>
<dep>1</dep>
</entry>
<entry>
<ind>300</ind>
<dep>4</dep>
</entry>
<entry>
<ind>1500</ind>
<dep>8</dep>
</entry>
</interpolation>
</animation>
</source>

You can optionally add [[#Center|<center>]] coordinates, to scale the object around that point.

=== Flash ===

Used to scale an object based on the cosine of the angle between the axis provided in the animation and the view vector.

<source>
<animation>
<type>flash</type>
<object-name>Object</object-name>
<offset>0.0</offset>
<factor>1.0</factor>
<power>2</power>
<two-sides type="bool">false</two-sides>
<min>0.0</min>
<max>1.0</max>
<center>
<x-m>0.0</x-m>
<y-m>0.0</y-m>
<z-m>0.0</z-m>
</center>
<axis>
<x>0.0</x>
<y>-1</y>
<z>0.1</z>
</axis>
</animation>
</source>

* '''offset:'''
* '''factor:'''
* '''power:'''
* '''two-sides:''' if false, nothing is drawn if the cosine is negative.
* '''min:'''
* '''max:'''

scale = factor * pow( cosine, power ) + offset

scale is then clamped between min and max.

and this scale factor is applied to the object, from the center specified. It works best if scale is less than 1. Otherwise, there will be clipping issues.

=== Noshadow ===
This animation is used to make sure an object will cast no shadow.

<source>
<animation>
<type>noshadow</type>
<object-name>Object</object-name>
</animation>
</source>

=== Range ===
: ''See also [[Modeling - Getting Started#Level of Detail (LOD)]].''

To prevent objects -like instruments- being drawn when the aircraft is actually too far away for them to be seen anyway, a range animation is used.

<syntaxhighlight lang="xml">
<animation>
<type>range</type>
<min-m>0</min-m>
<max-m>30</max-m>
</animation>
</syntaxhighlight>

* '''min-m:''' the shortest distance (in meters) from the object center at which it is visible.
* '''max-m:''' the largest distance (in meters) from the object center at which it is visible.

You could also use the generic level of detail (LOD) properties, which can be set by the user through View > Adjust LOD rangers:
{| class="wikitable"
! Property
! Description
! Default value
|-
|<tt>/sim/rendering/static-lod/bare</tt>
| only a rough exterior model
| 30,000 m
|-
|<tt>/sim/rendering/static-lod/rough</tt>
| most should be visible
| 9,000 m
|-
|<tt>/sim/rendering/static-lod/detailed</tt>
| all details should be visible
| 1,500 m
|}

The animation code will look like this:
<syntaxhighlight lang="xml">
<animation>
<type>range</type>
<min-m>0</min-m>
<max-property>sim/rendering/static-lod/bare</max-property>
</animation>
</syntaxhighlight>

You can have both ranges (max and min) bound to a property, or just one of them.
* '''min-property:'''
* '''max-property:'''
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

=== Rotate ===
One of the most important and frequently used animations of all. It rotates an object to an absolute position in degrees, as provided by the property-value.

<source>
<animation>
<object-name>Object</object-name>
<type>rotate</type>
<property>surface-positions/left-aileron-pos-norm</property>
<factor>25</factor>
<offset-deg>25</offset-deg>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

* '''factor:''' is optional.
* '''offset-deg:''' is optional. Offset in degrees.
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

=== Scale ===
A scale animation scales (resizes) an object. This can be either property-value dependant (first example) or a fixed scale (second example).

<source>
<animation>
<type>scale</type>
<object-name>Object</object-name>
<property>sim/time/sun-angle-rad</property>
<x-min>1.0</x-min>
<y-min>1.0</y-min>
<z-min>1.0</z-min>
<x-factor>1.4</x-factor>
<y-factor>1.4</y-factor>
<z-factor>2.0</z-factor>
</animation>
</source>

* ?-min: the mimimum scale factor for each axis. If the property value would result in a smaller factor than this setting, the scale animation will hold.
* ?-factor: the scale factor for each axis (factor*property=scale factor).

<source>
<animation>
<type>scale</type>
<x-offset>0.5</x-offset>
<y-offset>0.5</y-offset>
<z-offset>0.5</z-offset>
</animation>
</source>

* x.offset: the scale factor.
* Add [[#Center|<center>]] coordinates, to scale the object around that point.
* '''You can optionally use an [[Howto:Animate_models#Expressions|expression]] in the <factor> or <offset> inputs.''' For more details see [[Expressions|Expressions]]

=== Select ===
This animation selects (or unselects) objects when certain conditions are true (or false). The example below shows the object when the n1 of engine[1] is higher than 25%.

<source>
<animation>
<object-name>Object</object-name>
<type>select</type>
<condition>
<greater-than>
<property>engines/engine[0]/n1</property>
<value>25</value>
</greater-than>
</condition>
</animation>
</source>

=== Shader ===
<source>
<animation>
<type>shader</type>
<shader>chrome</shader>
<texture>chrome2.png</texture>
<object-name>Object</object-name>
</animation>
</source>

* '''shader:'''
* '''texture:''' path to the texture used by the shader.

=== Spin ===
Very similar to [[#Rotate|rotate]], but the property provides a value in revolutions per minute (RPM) rather than an absolute position in degrees, and offset cannot be used.

<source>
<animation>
<object-name>Object</object-name>
<type>spin</type>
<property>engines/engine[0]/n1</property>
<factor>25</factor>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

* '''factor:''' is optional.

=== Timed ===
Swtiches between objects at specified intervals. This example switches between a lights-on model and a lights-off model. Lights on are shown 0.2 seconds, while lights off are displayed for 0.8 seconds.

<source>
<animation>
<type>timed</type>
<object-name>BacklightOn</object-name>
<object-name>BacklightOff</object-name>
<use-personality type="bool">true</use-personality>
<branch-duration-sec>0.8</branch-duration-sec>
<branch-duration-sec>0.2</branch-duration-sec>
</animation>
</source>

=== Tracking ===
A ''locked-track animation'' can do exactly the same thing as the [https://docs.blender.org/manual/en/latest/animation/constraints/tracking/locked_track.html Locked Track constraint] available in Blender and can also be used to simulate simple inverse kinematic systems consisting of two bones connected with a revolute joint (aka hinge). For details see: [[Howto:Animate gear scissors using the tracking animation]]

=== Translate ===
This animation moves an object along an axis (not to be confused with the <code>textranslate</code> animation which only moves the texture on the UV map, not the geometry). The example below will move an object in the Y direction:

{| class="wikitable" border="0" cellspacing="0"
!Property value
!Output
|-
| -1
| -2.5
|-
| 0
| 2.5
|-
| 1
| 7.5
|}

<source>
<animation>
<type>translate</type>
<object-name>Object</object-name>
<property>controls/seat/pilot/position-norm</property>
<factor>5</factor>
<offset-m>2.5</offset-m>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

When using interpolation tables such as:
<source>
<interpolation>
<entry><ind>0.0</ind><dep> 0</dep></entry>
<entry><ind>0.666</ind><dep>0.18</dep></entry>
<entry><ind>1.0</ind><dep>0.27</dep></entry>
</interpolation>
</source>
The first figure (<code><ind></code>) refers to the value of the property associated with the object and the second figure (<code><dep></code>) refers to the amount that the object moves in metres. For example, in this case, the object moves 18cm when the value reads 0.66 and 27cm when the value is 1.

'''IF used WTIHOUT property''' : The object is placed at some (Value of Offset) meters away from its original position, along the virtual axis formed by said original position and the point with coordinates x/y/z defined in the <axis> tag.
Mathematically, assuming the Object to translate is (in the model space) placed at point A (x1, y1, z1) and you want to relocate it to point B (x2, y2, z2) then x2,y2,z2 are the values in the <axis> tag of the Translate animation and <offset> can be computed as SQRT((x2-x1)^2+(y2-y1)^2+(z2-z1)^2)

* '''factor:''' is optional.
* '''offset-m:''' is optional. Offset in meters.
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

== Material animation ==
Animate the material properties of an object, such as it's texture, shininess or color.

<source lang="xml">
<animation>
<type>material</type>
<object-name>Object</object-name>
<property-base>sim/model/c172p/material</property-base>
...
lines as mentioned below
...
</animation>
</source>

'''Optional:'''
* '''property-base:''' All other properties of this animation will be relative to this property node.

'''Notes:'''
* Numbers are clamped to 0.0 - 1.0, except <code>shininess</code>, which is clamped to 0 - 128.
* By appending <tt>-prop</tt> each of the material properties can read its value from another property.
* '''New since SimGear commit <code>51149bf</code>''': For each of the color components (<code>ambient</code>, <code>diffuse</code>, <code>emission</code> and <code>specular</code>), the <code>red</code>, <code>green</code>, <code>blue</code>, <code>factor</code> and <code>offset</code> tags can each contain an [[Expressions|expression]] instead of a value.

=== Ambient ===
<source>
<ambient>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</ambient>
</source>

=== Diffuse ===
<source>
<diffuse>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</diffuse>
</source>

=== Emission ===
{{Main article|Howto: Illuminate faces}}
<source>
<emission>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
<factor-prop>controls/lighting/panel-norm</factor-prop>
</emission>
</source>

Emission colors are multiplied by the factor-prop value. 1 is maximum color intensity, while 0 is the minimum. Colors are calculated according to the [http://en.wikipedia.org/wiki/RGB_color_model RGB color model].

=== Specular ===
<source>
<specular>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</specular>
</source>

=== Transparency ===
<source>
<transparency>
<alpha-prop>rotors/tail/rpm</alpha-prop>
<factor>-0.0015</factor>
<offset>1</offset>
</transparency>
</source>

=== Shininess ===
Shininess is clamped to 0-128.
<source>
<shininess>105</shininess>
</source>

=== Threshold ===
<source>
<threshold>0.001</threshold>
</source>

=== Texture ===
Used for the [[Livery over MP]] system.

<source>
<property-base>sim/model/livery</property-base>
<texture-prop>engine</texture-prop>
<texture>KLM.png</texture>
</source>

== Texture Animations ==
Applying different matrix transformations to the textures of an object.

=== Textranslate ===
A very important animation for cockpits! This animation moves textures over a surface.

<source>
<animation>
<type>textranslate</type>
<object-name>Object</object-name>
<property>autopilot/settings/target-speed-kt</property>
<bias>0.0001</bias>
<factor>0.001</factor>
<step>100</step>
<axis>
<x>0</x>
<y>1</y>
</axis>
</animation>
</source>

* '''bias:''' Adds an offset to the property before factor/step. A small value is needed to compensate for [http://en.wikipedia.org/wiki/Floating_point#Accuracy_problems floating point accuracy].
* '''factor:''' property * factor * texture width/height = the amount of pixels that the texture should be translated. If your texture is 256 pixels, an textranslate of 0.1 will result in the texture moving with 26 pixels, into the direction specified by the axis settings.
* '''step:''' the step size at which the texture is translated. If this is set to 0.1, the texture will only be translated at 0.1, 0.2, 0.3 etc.
* '''axis:''' the direction in which the texture is translated. Y is up/down, while X is left/right.

=== Texrotate ===

<source>
<animation>
<object-name>Object</object-name>
<type>texrotate</type>
<property>some/property/path</property>
<factor>25</factor>
<offset-deg>25</offset-deg>
<center>
<x>0.5</x>
<y>0.5</y>
<z>0</z>
</center>
<axis>
<x>0</x>
<y>0</y>
<z>1</z>
</axis>
</animation>
</source>

=== Textrapezoid ===

<source>
<animation>
<type>textrapezoid</type>
<object-name>HUD.l.canvas</object-name>
<property>/hud/trapezoid-correction</property>
<side>bottom</side>
</animation>
</source>

* '''side''': side of quad which should be scaled (''top'' (default)/''right''/''bottom''/''left'')

=== Texmultiple ===

Only one texture matrix can be applied to each object. With ''textmultiple'' multiple texture animations can be combined into a single matrix, applied to the specified object.

<source>
<animation>
<type>texmultiple</type>
<object-name>HUD.l.canvas</object-name>
<transform>
<subtype>textranslate</subtype>
<property>/hud/offset-x</property>
<axis>
<x>1</x>
<y>0</y>
<z>0</z>
</axis>
</transform>
<transform>
<subtype>textranslate</subtype>
<property>/hud/offset-y</property>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</transform>
<transform>
<subtype>textrapezoid</subtype>
<property>/hud/trapezoid-correction</property>
</transform>
</animation>
</source>

== Object interaction animations ==
=== Enable-hot ===
Scenery objects are automatically defined as solid by FlightGear, meaning that an aircraft can taxi on them and/or crash when touching. For certain objects (groundmarkings, beacon light-beams etc.) this might be an unwanted feature. The solidness can be disabled with the following animation:

<source>
<animation>
<object-name>Object</object-name>
<enable-hot type="bool">false</enable-hot>
</animation>
</source>

* '''enable-hot:''' can be either true or false. Remember that objects are automatically solid, so it should not be necessary to set this at all when wanting solidness.

=== Interactions ===
<source>
<animation>
<type>interaction</type>
<object-name>Object</object-name>
<interaction-type>carrier-wire</interaction-type>
</animation>
</source>

* '''interaction-type:''' can have the following values:
**'''carrier-catapult:'''
** '''carrier-wire:''' makes the object act as an arresting wire, as used on [[aircraft carrier]]s.

== Direct manipulation animations ==
=== Knob / slider (v. 2.11-) ===
{{Main article|Knob / slider animation}}

=== Pick ===
{{Main article|Howto: Make a clickable panel#Pick}}

=== Touch ===

The touch animation provides the normalized coordinates of a touch (or click) event on a 2d surface. The coordinates are passed in the argument and can be accessed using cmdarg() in Nasal.

* Touch animation is designed to work with a quad that is being used as a Canvas placement (display).
* The touch animation must not be combined with a pick animation on the same object.
* More info here: [[Touch Animation]]

==== touch example ====

<animation>
<type>touch</type>
<visible>true</visible>
<object-name>CanvasPlacement</object-name>
<action>
<touch>0</touch>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>print("touch input (",cmdarg().getNode("x").getValue(),",",cmdarg().getNode("y").getValue())</script>
</binding>
</action>
</animation>

== Shadow Handling ==
There exist several possibilites for handling of shadows. <br />
See '''[[ALS_technical_notes|ALS Technical Notes]]''' and more specific '''[[ALS_technical_notes#ALS_fuselage_shadow_effect|Fuselage Shadow Effect with ALS]]''' for a relatively simple shadow handling.<br />
See '''[[Project Rembrandt]]''' which - amongst other functionality - implements a very realistic shadow mapping.
As of January 2021 Project Rembrandt was replaced by the '''[[Compositor]]''' renderer which combines both Project Rembrandt and ALS in a single rendering engine. This also means that the Fuselage Shadow Effect with ALS is now deprecated.

== References ==
{{Appendix|all|
* {{cite web |url=http://www.opensubscriber.com/message/flightgear-devel@flightgear.org/958955.html |title="material" animation (and the bo105 as an example) |first=Melchior |last=Franz |date=22 March 2005 |work=FlightGear-devel mailinglist }}
* {{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg01546.html |title=flash animation |first=Frederic |last=Bouvier |date=22 Feb 2006 |work=FlightGear-devel mailinglist }}
}}

== Related content ==
=== Wiki articles ===
* [[MP Fallback models]]
* [[Howto:Animate gear scissors]]
* [[Howto:Animate helicopters]]
* [[Howto:Creating 3D instruments]]

=== Forum topics ===
* {{forum link|t=37353|title=3d models, how to produce them in an understandable way}} (April 2020-) - Touches on the subject of not using LOD range animations in scenery models.
* {{forum link|t=36545|title=speedo Drum settings}} (November 2019) - Animating a mechanical multi-digit drum counter

[[Category:Aircraft enhancement|Animate models]]
[[Category:Howto|Animate models]]
[[Category:Modeling|Animate models]]
[[Category:Scenery enhancement|Animate models]]

2022-12-28T07:31:07Z

TheEagle: Created page with " <noinclude> <templatedata> { "params": { "description": { "label": "Description", "description": "A description of the function / method being documented.", "type..."

Template:Canvas Widget Matrix

2022-12-27T17:27:11Z

TheEagle:

Howto:Animate models

2022-11-12T01:57:22Z

TheEagle: Add note about added axis-object support for slider and locked-track animations on Git next.

The real world is full of motion. To simulate this in [[FlightGear]], '''models must be animated'''.

FlightGear allows you to animate models in response to property changes: for example, the propellers can spin when the engine is on and the elevators can move up and down with your controller. There is no fixed limit on what parts can be animated: the only requirements are that the part is named in the 3D model file, and that there is a property in the main tree that you can use to get the positioning information.

This document provides basic information for all kind of animations. When animating your model, it is very helpful to find an aircraft with parts similar to yours and use it as an example. Cut and paste the code into your wrapper file and then edit to suit.

== Notes ==
=== File name of main model and animation XML file ===
{{main article|Aircraft-set.xml#Not used for loading multiplayer aircraft}}
The file name of the main model and animation XML file, or the .ac file if there is no XML file, (in essence the property <code>/sim/model/path</code>) will be the name of the aircraft that is transmitted when using [[multiplayer]] and will also be used for loading multiplayer aircraft.

There is also a mechanism to substitute a full aircraft model with a simpler AI aircraft model if one is available at the same file path (including for example <code>Models/Boeing-797-800.xml</code>), but in <code>[[$FG_ROOT]]/'''AI'''/Aircraft/</code> instead of <code>$FG_ROOT/Aircraft/</code>.

=== .ac files ===
{{Main article|AC files: Understanding and changing .ac code#Identifying an object}}

When referring to an .ac file in your xml animation, it is important that the <code><object-name></code> exactly matches the object named in the .ac file (this includes cases!).

'''Note for SketchUp users:''' The spatial reference X/Y/Z used in animation to locate an object or a point are different from the ones in AC3D ie X values are the same in both but Y in animation must be matched to AC3D's -Z (Z value but opposite sign) and Z value in animation must be matched to AC3D's Y value.

'''Note for SketchUp users:''' when exporting to AC3D in Sketchup, the .ac file will name the objects in your model to "blah" by default. You need to amend the relevant object names in your .ac file using text edit, so that the xml will work.

=== Animation order ===
Animations are executed by FlightGear in the order that they are read in the model's .xml file. Therefore, it is very important to pay attention to the order, especially when multiple animations are applied to the same object(s). Wrong ordering of animations might cause [[Howto:Animate models#Timed|timed]] animations (used to create flashing lights) to not work. For further details see this [https://sourceforge.net/p/flightgear/mailman/message/37090714/ thread] on the development mailing list. Updated [https://scenery.flightgear.org/app.php?c=Models&a=browse&shared=18 shared Effects models] will be available very soon.

Similar problems can be encountered with the dist-scale instead of the timed animation.
== Tags used in most animations ==
=== Name ===
With a name animation, you can group multiple objects.

<source>
<animation>
<name>Collection1</name>
<object-name>Object1</object-name>
<object-name>Object2</object-name>
<object-name>Object3</object-name>
</animation>
</source>

The example above creates a "virtual object" with the name Collection1. In animation, we can animate this group of objects, by using:

<source>
<object-name>Collection1</object-name>
</source>

=== Object-name ===
These names are set in the 3D model. Each single object has a unique name; for easy identification it is advised to use descriptive names (LeftElevator, Rudder etc.). Animations are only applied to those objects that are mentioned in an object-name line (one object per line!). Animations lacking those, will be applied to the entire model.

=== Property ===
Each animation must be associated with exactly one property from the main FlightGear property tree (remember that the properties in the wrapper file are not part of the main tree), using <code><property></code> to provide the property path:

<source>
<animation>
<type>rotate</type>
<object-name>Rudder</object-name>
<property>controls/rudder</property>
</animation>
</source>

Note the omission of the leading slash '/' when referring to the property. This assures that when the model is used for AI or multiplayer traffic the animations will follow that of the AI controller instead of that of the user.

=== Axis ===
An axis part is required in every animation that involves a rotating or moving thing.

<source>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</source>

The axis are similar to the ones of the 3D model. There is a difference between rotation and translation:
* In rotation animations, the axis part defines around what axis the object rotates. Negative/positive values make the difference between counterclockwise and clockwise rotations.
* In translate animations, the part defines along what axis the object moves. If the x-axis is poiting backwards, an x-value of -1 will result in forward motion.

You could also define two points, between which FlightGear will calculate the correct axis. This makes the use of a [[#Center|<nowiki><center></nowiki>]] tag redundant! Such coordinates are extremely useful for animating control surfaces (rudder, elevators etc.).

<source>
<axis>
<x1-m> 4.9</x1-m>
<y1-m> 7.1</y1-m>
<z1-m>-1.0</z1-m>
<x2-m> 5.9</x2-m>
<y2-m>11.2</y2-m>
<z2-m>-0.5</z2-m>
</axis>
</source>

=== Center ===
Various animations ([[#Rotate|rotate]], [[#Spin|spin]], [[#Scale|scale]]) move around a center point.

<source>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
</source>

The axis are similar to the ones of the 3D model, so finding coordinates is easily done in 3D modeling software.

=== Using a geometry object for axis and centre (2017.2) ===

Added in V2017.2 is support to allow a geometry object (a line segment with two vertices) that is used to define both the centre and the axis for an animation. This will work with rotate, spin, translate and knob animations.

{{Note|Since SimGear commit 6ca9141083e62be1161d0ca2d1e3b918494dd6ad on next, this feature can also be used for slider (usage equivalent to that for a translate animation) and for any of the <*-center> / <*-axis> tags of a locked-track animation.}}

When used for translate animations, the axis line should be normalized (i.e. be 1 meter long) as its length acts as a factor for the translation distance.

The XML syntax for this is:

<source>
<axis>
<object-name>some-object</object-name>
</axis>
</source>

If the <code><axis>...</axis></code> section is omitted entirely, <code>{object-name}-axis</code> will be used by default, where <code>{object-name}</code> is the name of the object being animated (if we are animating more than one object, the first object is used). In the earlier example this would be <code>Rudder-axis</code>.

In the '''.ac''' file, specify a SURF with type (bottom 4 bits, 0=polygon, 1=closedline, 2=line) set to 2, and two vertices that define the axis. For example:

OBJECT poly
name "aileron.l-axis"
numvert 2
3.2077502191170844 0.18160835055097943 4.055616960642423
2.6758650763079 0.28024033462188946 6.477876098622225
numsurf 1
SURF 0x12
mat 0
refs 2
0 0 0
1 0 0
kids 0

Once the object-name used for the axis has been processed the geometry object will be hidden. This also allows a visual check for any axis objects that are not yet assigned.

It is possible to reuse the same object definition multiple times within a single XML file.

[[File:Canopy-animation-axis-object.png|small|Illustration of where an axis object (2017.2) can be placed for a canopy]]

[[File:Gauges-knobs-animation-axis-object.png|small|Illustration of where an axis object (2017.2) can be placed for cockpit elements]]

== Additional tags that can be used in most animations ==
=== Conditions ===
Multiple animations can make use of a conditional. Check <tt>$FGDATA/Docs/README.conditions</tt> for some more details.

* '''equals:''' property value (or second property) is equal to value/(first)property.
* '''greater-than:''' property value (or second property) is larger than value/(first)property.
* '''greater-than-equals:''' property value (or second property) is greater than or equal to value/(first)property.
* '''less-than:''' property value (or second property) is smaller than value/(first)property.
* '''less-than-equals:''' property value (or second property) is smaller than or equal to value/(first)property.

The example below is true when n1 has a value greater than 25.
<source>
<condition>
<greater-than>
<property>engines/engine[1]/n1</property>
<value>25</value>
</greater-than>
</condition>
</source>

Then there are some special tags:

* '''and:'''
* '''not:'''
* '''or:'''

In the example below, the condition is true when either n1 is greater than 25% or equal to 0%.
<source>
<condition>
<or>
<greater-than>
<property>engines/engine[1]/n1</property>
<value>25</value>
</greater-than>
<equals>
<property>engines/engine[1]/n1</property>
<value>0</value>
</equals>
</or>
</condition>
</source>

An example of implementation into an animation looks as follows:

<source>
<animation>
<object-name>Object</object-name>
<type>rotate</type>
<property>suface-positions/left-aileron-pos-norm</property>
<factor>25</factor>
<condition>
<greater-than>
<property>suface-positions/left-aileron-pos-norm</property>
<value>10</value>
</greater-than>
</condition>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

=== Interpolation ===
For non-fixed factors, an interpolation "table" can be created.

<source>
<interpolation>
<entry>
<ind> 0.0</ind>
<dep> 0.0</dep>
</entry>
<entry>
<ind> 0.667</ind>
<dep> 0.0</dep>
</entry>
<entry>
<ind> 1.0</ind>
<dep> 0.5</dep>
</entry>
</interpolation>
</source>

The lines above represent the following table:

{|
!Input
!Output
|-
|0.0
|0.0
|-
|0.667
|0.0
|-
|1.0
|0.5
|}

You can add as many entries as you need. Interpolation tables are often used for gear animations (eg. to open doors during gear-movements and close them again once the gear is either retracted or fully extended).

=== Expressions ===
For some animations it is possible to define complex animations by using [[Expressions|Expressions]]. This even allows to drive the animation from multiple properties without the need for additional Nasal scripts. Here is an example for a translate animation depending on two properties and the cosine function:
<syntaxhighlight lang="xml">
<animation>
<type>translate</type>
<expression>
<product>
<property>/my/factor-property</property>
<cos>
<deg2rad>
<property>/my/angular-property</property>
</deg2rad>
</cos>
</product>
</expression>
[..]more elements[..]
</animation>
</syntaxhighlight>

Animations which can utilize [[Expressions|Expressions]] are:
* [[Howto:Animate_models#Translate|Translate]]
* [[Howto:Animate_models#Rotate|Rotate]]
* [[Howto:Animate_models#Scale|Scale]]
* [[Howto:Animate_models#Range|Range]]
* [[Howto:Animate_models#Blend|Blend]]

See more detailed info at [[Expressions|Expressions]]

== Lights ==
As of January 2021 FlightGear supports multiple light sources just like Project Rembrandt has always done.
[[Compositor#Lights|Adding lights to a model]]

== Object animations ==
=== Alpha-test ===
<source>
<animation>
<type>alpha-test</type>
<object-name>Object</object-name>
<alpha-factor>0.01</alpha-factor>
</animation>
</source>
This "animation" is a way to set an alpha test on a model branch. The effect is to avoid depth buffer writing of pixel that are not seen because they are transparent. This is particulary useful when modeling a metallic structure or a tree with a billboard. The threshold of transparency is set with the <alpha-factor> element. See also [[Pixel testing in effects]].

=== Blend ===
Blends an object with the surrounding. Comparable to a translucency animation. A value of 0 corresponds to no transparency, i.e. and ordinary solid object, and a value of 1 makes the object fully transparent, i.e., not visible at all.

<source>
<animation>
<type>blend</type>
<property>/velocities/airspeed-kt</property>
<factor>0.00025</factor>
<min>0.2</min>
<max>0.7</max>
</animation>
</source>

* '''property:'''
* '''factor:'''
* '''min:'''
* '''max:'''
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

Note that when using the Project Rembrandt renderer, all transparent and translucent objects must be registered to display properly. [[Project_Rembrandt#Registering_all_translucent_surfaces|More information here.]]

=== Billboard ===
This faces an object towards the viewer. Often used on 2D objects, like clouds, trees and lights.

<source>
<animation>
<type>billboard</type>
<object-name>Object</object-name>
<spherical type="bool">true</spherical>
</animation>
</source>

* '''spherical:'''

=== Dist-scale ===
Used to scale an object, based on the distance to the viewer. <code><nowiki><ind></nowiki></code> and <code><nowiki><dep></nowiki></code> (independent and dependent) are the distance in meters and the scale at that distance.

<source>
<animation>
<type>dist-scale</type>
<object-name>Object</object-name>
<interpolation>
<entry>
<ind>0</ind>
<dep>1</dep>
</entry>
<entry>
<ind>300</ind>
<dep>4</dep>
</entry>
<entry>
<ind>1500</ind>
<dep>8</dep>
</entry>
</interpolation>
</animation>
</source>

You can optionally add [[#Center|<center>]] coordinates, to scale the object around that point.

=== Flash ===

Used to scale an object based on the cosine of the angle between the axis provided in the animation and the view vector.

<source>
<animation>
<type>flash</type>
<object-name>Object</object-name>
<offset>0.0</offset>
<factor>1.0</factor>
<power>2</power>
<two-sides type="bool">false</two-sides>
<min>0.0</min>
<max>1.0</max>
<center>
<x-m>0.0</x-m>
<y-m>0.0</y-m>
<z-m>0.0</z-m>
</center>
<axis>
<x>0.0</x>
<y>-1</y>
<z>0.1</z>
</axis>
</animation>
</source>

* '''offset:'''
* '''factor:'''
* '''power:'''
* '''two-sides:''' if false, nothing is drawn if the cosine is negative.
* '''min:'''
* '''max:'''

scale = factor * pow( cosine, power ) + offset

scale is then clamped between min and max.

and this scale factor is applied to the object, from the center specified. It works best if scale is less than 1. Otherwise, there will be clipping issues.

=== Noshadow ===
This animation is used to make sure an object will cast no shadow.

<source>
<animation>
<type>noshadow</type>
<object-name>Object</object-name>
</animation>
</source>

=== Range ===
: ''See also [[Modeling - Getting Started#Level of Detail (LOD)]].''

To prevent objects -like instruments- being drawn when the aircraft is actually too far away for them to be seen anyway, a range animation is used.

<syntaxhighlight lang="xml">
<animation>
<type>range</type>
<min-m>0</min-m>
<max-m>30</max-m>
</animation>
</syntaxhighlight>

* '''min-m:''' the shortest distance (in meters) from the object center at which it is visible.
* '''max-m:''' the largest distance (in meters) from the object center at which it is visible.

You could also use the generic level of detail (LOD) properties, which can be set by the user through View > Adjust LOD rangers:
{| class="wikitable"
! Property
! Description
! Default value
|-
|<tt>/sim/rendering/static-lod/bare</tt>
| only a rough exterior model
| 30,000 m
|-
|<tt>/sim/rendering/static-lod/rough</tt>
| most should be visible
| 9,000 m
|-
|<tt>/sim/rendering/static-lod/detailed</tt>
| all details should be visible
| 1,500 m
|}

The animation code will look like this:
<syntaxhighlight lang="xml">
<animation>
<type>range</type>
<min-m>0</min-m>
<max-property>sim/rendering/static-lod/bare</max-property>
</animation>
</syntaxhighlight>

You can have both ranges (max and min) bound to a property, or just one of them.
* '''min-property:'''
* '''max-property:'''
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

=== Rotate ===
One of the most important and frequently used animations of all. It rotates an object to an absolute position in degrees, as provided by the property-value.

<source>
<animation>
<object-name>Object</object-name>
<type>rotate</type>
<property>surface-positions/left-aileron-pos-norm</property>
<factor>25</factor>
<offset-deg>25</offset-deg>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

* '''factor:''' is optional.
* '''offset-deg:''' is optional. Offset in degrees.
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

=== Scale ===
A scale animation scales (resizes) an object. This can be either property-value dependant (first example) or a fixed scale (second example).

<source>
<animation>
<type>scale</type>
<object-name>Object</object-name>
<property>sim/time/sun-angle-rad</property>
<x-min>1.0</x-min>
<y-min>1.0</y-min>
<z-min>1.0</z-min>
<x-factor>1.4</x-factor>
<y-factor>1.4</y-factor>
<z-factor>2.0</z-factor>
</animation>
</source>

* ?-min: the mimimum scale factor for each axis. If the property value would result in a smaller factor than this setting, the scale animation will hold.
* ?-factor: the scale factor for each axis (factor*property=scale factor).

<source>
<animation>
<type>scale</type>
<x-offset>0.5</x-offset>
<y-offset>0.5</y-offset>
<z-offset>0.5</z-offset>
</animation>
</source>

* x.offset: the scale factor.
* Add [[#Center|<center>]] coordinates, to scale the object around that point.
* '''You can optionally use an [[Howto:Animate_models#Expressions|expression]] in the <factor> or <offset> inputs.''' For more details see [[Expressions|Expressions]]

=== Select ===
This animation selects (or unselects) objects when certain conditions are true (or false). The example below shows the object when the n1 of engine[1] is higher than 25%.

<source>
<animation>
<object-name>Object</object-name>
<type>select</type>
<condition>
<greater-than>
<property>engines/engine[0]/n1</property>
<value>25</value>
</greater-than>
</condition>
</animation>
</source>

=== Shader ===
<source>
<animation>
<type>shader</type>
<shader>chrome</shader>
<texture>chrome2.png</texture>
<object-name>Object</object-name>
</animation>
</source>

* '''shader:'''
* '''texture:''' path to the texture used by the shader.

=== Spin ===
Very similar to [[#Rotate|rotate]], but the property provides a value in revolutions per minute (RPM) rather than an absolute position in degrees, and offset cannot be used.

<source>
<animation>
<object-name>Object</object-name>
<type>spin</type>
<property>engines/engine[0]/n1</property>
<factor>25</factor>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

* '''factor:''' is optional.

=== Timed ===
Swtiches between objects at specified intervals. This example switches between a lights-on model and a lights-off model. Lights on are shown 0.2 seconds, while lights off are displayed for 0.8 seconds.

<source>
<animation>
<type>timed</type>
<object-name>BacklightOn</object-name>
<object-name>BacklightOff</object-name>
<use-personality type="bool">true</use-personality>
<branch-duration-sec>0.8</branch-duration-sec>
<branch-duration-sec>0.2</branch-duration-sec>
</animation>
</source>

=== Tracking ===
A ''locked-track animation'' can do exactly the same thing as the [https://docs.blender.org/manual/en/latest/animation/constraints/tracking/locked_track.html Locked Track constraint] available in Blender and can also be used to simulate simple inverse kinematic systems consisting of two bones connected with a revolute joint (aka hinge). For details see: [[Howto:Animate gear scissors using the tracking animation]]

=== Translate ===
The same as [[#Textranslate|textranslate]], but this animation moves a whole object (so including fixed textures). The example below will move an object in the y-direction:

{| class="wikitable" border="0" cellspacing="0"
!Property value
!Output
|-
| -1
| -2.5
|-
| 0
| 2.5
|-
| 1
| 7.5
|}

<source>
<animation>
<type>translate</type>
<object-name>Object</object-name>
<property>controls/seat/pilot/position-norm</property>
<factor>5</factor>
<offset-m>2.5</offset-m>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

When using interpolation tables such as:
<source>
<interpolation>
<entry><ind>0.0</ind><dep> 0</dep></entry>
<entry><ind>0.666</ind><dep>0.18</dep></entry>
<entry><ind>1.0</ind><dep>0.27</dep></entry>
</interpolation>
</source>
The first figure (<ind> refers to the value of the property associated with the object and the second figure (in <dep>) refers to the amount that the object moves in metres. For example, in this case, the object moves 18cm when the value reads 0.66 and 27cm when the value is 1.

'''IF used WTIHOUT property''' : The object is placed at some (Value of Offset) meters away from its original position, along the virtual axis formed by said original position and the point with coordinates x/y/z defined in the <axis> tag.
Mathematically, assuming the Object to translate is (in the model space) placed at point A (x1, y1, z1) and you want to relocate it to point B (x2, y2, z2) then x2,y2,z2 are the values in the <axis> tag of the Translate animation and <offset> can be computed as SQRT((x2-x1)^2+(y2-y1)^2+(z2-z1)^2)

* '''factor:''' is optional.
* '''offset-m:''' is optional. Offset in meters.
* '''[[Howto:Animate_models#Expressions|expression]]:''' is optional. For more details see [[Expressions|Expressions]]

== Material animation ==
An animation type that can be used in various ways. Of course you can combine the below mentiond systems into one (big) animation.

<source>
<animation>
<type>material</type>
<object-name>Object</object-name>
<property-base>sim/model/c172p/material</property-base>
<global type="bool">true</global> 
...
lines as mentioned below
...
</animation>
</source>

'''Optional:'''
* '''property-base:''' when using prop(erties), you might want to set a property-base. All props will be relative to this path.
* '''global (deprecated):''' by setting this to <tt>true</tt>, all objects using the same material as the defined object(s) (via <tt><object-name></tt>) will be affected by the animation. This is preferred to listing several objects in <object-name> tags. It's not only faster, but also doesn't break animations by forcing objects together. <span style="color:red; text-decoration: underline;">This tag is no longer supported</span>

'''Notes:'''
* Numbers are clamped to 0.0-1.0, except "shininess", which is clamped to 0-128.
* By appending <tt>-prop</tt> each of the material properties can read its value from another property.

=== Ambient ===
<source>
<ambient>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</ambient>
</source>

=== Diffuse ===
<source>
<diffuse>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</diffuse>
</source>

=== Emission ===
{{Main article|Howto: Illuminate faces}}
<source>
<emission>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
<factor-prop>controls/lighting/panel-norm</factor-prop>
</emission>
</source>

Emission colors are multiplied by the factor-prop value. 1 is maximum color intensity, while 0 is the minimum. Colors are calculated according to the [http://en.wikipedia.org/wiki/RGB_color_model RGB color model].

=== Shininess ===
Shininess is clamped to 0-128.
<source>
<shininess>105</shininess>
</source>

=== Specular ===
<source>
<specular>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</specular>
</source>

=== Texture ===
Used for the [[Livery over MP]] system.

<source>
<property-base>sim/model/livery</property-base>
<texture-prop>engine</texture-prop>
<texture>KLM.png</texture>
</source>

=== Transparency ===
<source>
<transparency>
<alpha-prop>rotors/tail/rpm</alpha-prop>
<factor>-0.0015</factor>
<offset>1</offset>
</transparency>
</source>

=== Threshold ===
<source>
<threshold>0.001</threshold>
</source>

== Texture Animations ==

Applying different matrix transformations to the textures of an object.

=== Textranslate ===
A very important animation for cockpits! This animation moves textures over a surface.

<source>
<animation>
<type>textranslate</type>
<object-name>Object</object-name>
<property>autopilot/settings/target-speed-kt</property>
<bias>0.0001</bias>
<factor>0.001</factor>
<step>100</step>
<axis>
<x>0</x>
<y>1</y>
</axis>
</animation>
</source>

* '''bias:''' Adds an offset to the property before factor/step. A small value is needed to compensate for [http://en.wikipedia.org/wiki/Floating_point#Accuracy_problems floating point accuracy].
* '''factor:''' property * factor * texture width/height = the amount of pixels that the texture should be translated. If your texture is 256 pixels, an textranslate of 0.1 will result in the texture moving with 26 pixels, into the direction specified by the axis settings.
* '''step:''' the step size at which the texture is translated. If this is set to 0.1, the texture will only be translated at 0.1, 0.2, 0.3 etc.
* '''axis:''' the direction in which the texture is translated. Y is up/down, while X is left/right.

=== Texrotate ===

<source>
<animation>
<object-name>Object</object-name>
<type>texrotate</type>
<property>some/property/path</property>
<factor>25</factor>
<offset-deg>25</offset-deg>
<center>
<x>0.5</x>
<y>0.5</y>
<z>0</z>
</center>
<axis>
<x>0</x>
<y>0</y>
<z>1</z>
</axis>
</animation>
</source>

=== Textrapezoid ===

<source>
<animation>
<type>textrapezoid</type>
<object-name>HUD.l.canvas</object-name>
<property>/hud/trapezoid-correction</property>
<side>bottom</side>
</animation>
</source>

* '''side''': side of quad which should be scaled (''top'' (default)/''right''/''bottom''/''left'')

=== Texmultiple ===

Only one texture matrix can be applied to each object. With ''textmultiple'' multiple texture animations can be combined into a single matrix, applied to the specified object.

<source>
<animation>
<type>texmultiple</type>
<object-name>HUD.l.canvas</object-name>
<transform>
<subtype>textranslate</subtype>
<property>/hud/offset-x</property>
<axis>
<x>1</x>
<y>0</y>
<z>0</z>
</axis>
</transform>
<transform>
<subtype>textranslate</subtype>
<property>/hud/offset-y</property>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</transform>
<transform>
<subtype>textrapezoid</subtype>
<property>/hud/trapezoid-correction</property>
</transform>
</animation>
</source>

== Object interaction animations ==
=== Enable-hot ===
Scenery objects are automatically defined as solid by FlightGear, meaning that an aircraft can taxi on them and/or crash when touching. For certain objects (groundmarkings, beacon light-beams etc.) this might be an unwanted feature. The solidness can be disabled with the following animation:

<source>
<animation>
<object-name>Object</object-name>
<enable-hot type="bool">false</enable-hot>
</animation>
</source>

* '''enable-hot:''' can be either true or false. Remember that objects are automatically solid, so it should not be necessary to set this at all when wanting solidness.

=== Interactions ===
<source>
<animation>
<type>interaction</type>
<object-name>Object</object-name>
<interaction-type>carrier-wire</interaction-type>
</animation>
</source>

* '''interaction-type:''' can have the following values:
**'''carrier-catapult:'''
** '''carrier-wire:''' makes the object act as an arresting wire, as used on [[aircraft carrier]]s.

== Direct manipulation animations ==
=== Knob / slider (v. 2.11-) ===
{{Main article|Knob / slider animation}}

=== Pick ===
{{Main article|Howto: Make a clickable panel#Pick}}

=== Touch ===

The touch animation provides the normalized coordinates of a touch (or click) event on a 2d surface. The coordinates are passed in the argument and can be accessed using cmdarg() in Nasal.

* Touch animation is designed to work with a quad that is being used as a Canvas placement (display).
* The touch animation must not be combined with a pick animation on the same object.
* More info here: [[Touch Animation]]

==== touch example ====

<animation>
<type>touch</type>
<visible>true</visible>
<object-name>CanvasPlacement</object-name>
<action>
<touch>0</touch>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>print("touch input (",cmdarg().getNode("x").getValue(),",",cmdarg().getNode("y").getValue())</script>
</binding>
</action>
</animation>

== Shadow Handling ==
There exist several possibilites for handling of shadows. <br />
See '''[[ALS_technical_notes|ALS Technical Notes]]''' and more specific '''[[ALS_technical_notes#ALS_fuselage_shadow_effect|Fuselage Shadow Effect with ALS]]''' for a relatively simple shadow handling.<br />
See '''[[Project Rembrandt]]''' which - amongst other functionality - implements a very realistic shadow mapping.
As of January 2021 Project Rembrandt was replaced by the '''[[Compositor]]''' renderer which combines both Project Rembrandt and ALS in a single rendering engine. This also means that the Fuselage Shadow Effect with ALS is now deprecated.

== References ==
{{Appendix|all|
* {{cite web |url=http://www.opensubscriber.com/message/flightgear-devel@flightgear.org/958955.html |title="material" animation (and the bo105 as an example) |first=Melchior |last=Franz |date=22 March 2005 |work=FlightGear-devel mailinglist }}
* {{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg01546.html |title=flash animation |first=Frederic |last=Bouvier |date=22 Feb 2006 |work=FlightGear-devel mailinglist }}
}}

== Related content ==
=== Wiki articles ===
* [[MP Fallback models]]
* [[Howto:Animate gear scissors]]
* [[Howto:Animate helicopters]]
* [[Howto:Creating 3D instruments]]

=== Forum topics ===
* {{forum link|t=37353|title=3d models, how to produce them in an understandable way}} (April 2020-) - Touches on the subject of not using LOD range animations in scenery models.
* {{forum link|t=36545|title=speedo Drum settings}} (November 2019) - Animating a mechanical multi-digit drum counter

[[Category:Aircraft enhancement|Animate models]]
[[Category:Howto|Animate models]]
[[Category:Modeling|Animate models]]
[[Category:Scenery enhancement|Animate models]]

Nasal library/math

2022-10-26T14:04:49Z

TheEagle: Fix inverted x, y params for math.atan2

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>math</code> namespace''' in [[Nasal]]. This namespace provides various mathematical [[#Functions|functions]] and [[#Variables|variables]]. The <code>math</code> namespace is sourced from two files:
* {{simgear file|simgear/nasal/mathlib.c}}
* {{fgdata file|Nasal/math.nas}}

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Functions ==
=== abs() ===
{{Nasal doc
|syntax = math.abs(x);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = x
|param1text = This argument is required and should be a number.
|example1 = print(math.abs(1)); # prints "1"
|example2 = print(math.abs(-1)); # prints "1"
}}

=== acos() ===
{{Nasal doc
|syntax = math.acos(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=196|t=Source}}
|text = Implements the arccosine trigonometric function. Returns an angle in radians from the given ratio.
|param1 = x
|param1text = Mandatory number that should be a ratio in the range -1 ≤ x ≤ 1.
|example1 = var ratio = 1 / 1.414;
print(math.acos(ratio) * R2D); # prints the angle in degrees (approximately 45)
}}

=== asin() ===
{{Nasal doc
|syntax = math.asin(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=187|t=Source}}
|text = Implements the arcsine trigonometric function. Returns an angle in radians from the given ratio.
|param1 = x
|param1text = Mandatory number that should be a ratio in the range -1 ≤ x ≤ 1.
|example1 = var ratio = 1 / 1.414;
print(math.asin(ratio) * R2D); # prints the angle in degrees (approximately 45)
}}

=== atan2() ===
{{Nasal doc
|syntax = math.atan2(x, y);
|source = {{simgear file|simgear/nasal/mathlib.c|l=78|t=Source}}
|text = Implements the {{wikipedia|Atan2|two-argument version}} of the arctangent trigonometric function. Returns an angle in radians between the positive x-axis of a plane and the point given by the coordinates (x, y) on it.
|param1 = x
|param1text = Mandatory x-axis coordinate as a number.
|param2 = y
|param2text = Mandatory y-axis coordinate as a number.
|example1 = var x = 1;
var y = 1;
print(math.atan2(x, y) * R2D); # prints the angle in degrees (45)
|example2 = var x = -1;
var y = -1;
print(math.atan2(x, y) * R2D); # prints the angle in degrees (-135)
}}

=== avg() ===
{{Nasal doc
|syntax = math.avg(x[, y[, z[, ...]]]);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|version = 2.4
|commit = {{fgdata commit|36c48c|t=Commit}}
|text = Returns the average of the given numbers. There must be at least one argument, but there may be as many as you like.
|example1 = print(math.avg(1, 2, 3, 4)); # prints 2.5
}}

=== ceil() ===
{{Nasal doc
|syntax = math.ceil(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=97|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3|t=Commit}}
|text = Returns the {{wikipedia|Ceiling function|ceiling}} of a number, that is, the smallest following integer.
|param1 = x
|param1text = Number to return the ceiling of.
|example1 = print(math.ceil(2)); # prints 2
|example2 = print(math.ceil(2.1)); # prints 3
|example3 = print(math.ceil(-2.9)); # prints -2
}}

=== clamp() ===
{{Nasal doc
|syntax = math.clamp(x, min, max);
|source = {{simgear file|simgear/nasal/mathlib.c|l=117|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3|t=Commit}}
|text = Clamps a number so that is within the range given. All arguments are mandatory and must be numbers.
{{Note|Up until FG v2016.2, the clamping algorithm was not correct, meaning that the function will not behave correctly in FlightGear versions below 2016.2. It was fixed by {{simgear commit|bba11c}}}}.
|param1 = x
|param1text = The number to be clamped.
|param2 = min
|param2text = Lower limit of the clamping range.
|param3 = max
|param3text = Upper limit of the clamping range.
|example1text = Note that none of these examples will work properly in FlightGear versions below 2016.2.
|example1 = print(math.clamp(5, 1, 10)); # prints 5
|example2 = print(math.clamp(0, 1, 10)); # prints 1
|example3 = print(math.clamp(12, 1, 10)); # prints 10
}}

=== cos() ===
{{Nasal doc
|syntax = math.cos(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=32|t=Source}}
|text = Implements the cosine trigonometric function. Returns a ratio from a given angle in radians.
|param1 = x
|param1text = Mandatory number that should be an angle in radians.
|example1 = var angle = 180 * D2R;
print(math.cos(angle)); # prints the ratio (-1)
}}

=== exp() ===
{{Nasal doc
|syntax = math.exp(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=41|t=Source}}
|text = Returns the value of ''{{wikipedia|E (mathematical constant)|e|noicon=1}}'' raised to the given poweer.
|param1 = x
|param1text = Mandatory number which is the value of the exponent.
|example1 = printf("%.4f", math.exp(2)); # prints 7.3891
}}

=== floor() ===
{{Nasal doc
|syntax = math.floor(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=88|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3|t=Commit}}
|text = Returns the {{wikipedia|Floor function|floor}} of a number, that is, the largest previous integer.
|param1 = x
|param1text = Number to return the floor of.
|example1 = print(math.floor(2)); # prints 2
|example2 = print(math.floor(2.1)); # prints 2
|example3 = print(math.floor(-2.9)); # prints -3
}}

=== fmod() ===
{{Nasal doc
|syntax = math.fmod(x, y);
|source = {{simgear file|simgear/nasal/mathlib.c|l=106|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3|t=Commit}}
|text = Returns the result of the modulo operation of the given numbers, that is, is returns the remainder of '''x''' divided by '''y'''. Unlike {{func link|mod()|page=this}}, this function uses the C library function {{func link|fmod()|link=http://www.cplusplus.com/reference/cmath/fmod/}}, and has different (and more correct) behavior when negative arguments are passed to it (compare example 3 with example 3 of {{func link|mod()|page=this}}). Both arguments are mandatory and must be numbers.
{{Note|This function was initially added <code>math.mod()</code>, but this was overridden by [[#mod.28.29|another version]] which already existed in FGData. In FlightGear 3.0, this function was {{simgear commit|ad83e7|t=renamed}} to <code>fmod()</code>.}}
|param1 = x
|param1text = The dividend.
|param2 = y
|param2text = The divisor. If this argument is 0, a floating point error will be generated.
|example1 = print(math.fmod(5, 2)); # prints 1 (2 goes into 5 twice with a remainder of 1; 2 * 2 + 1 = 5)
|example2 = print(math.fmod(10, 5)); # prints 0 (5 goes into 10 twice with a remainder of 0; 5 * 2 + 0 = 10)
|example3 = print(math.fmod(-5, 2)); # prints -1 (2 goes into -5 -2 times with a remainder of -1; 2 * -2 + -1 = -5)
}}

=== ln() ===
{{Nasal doc
|syntax = math.ln(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=50|t=Source}}
|text = Returns the natural (base ''e'') logarithm of the given number.
|param1 = x
|param1text = Number to return the logarithm of. Must be greater than 0.
|example1 = printf("%.4f", math.ln(60)); # prints 4.0943
}}

=== log10() ===
{{Nasal doc
|syntax = math.log10(x);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|text = Returns the common (base 10) logarithm of the given number.
|param1 = x
|param1text = Number to return the logarithm of. Must be greater than 0.
|example1 = printf("%g", math.log10(1000)); # prints 3
}}

=== max() ===
{{Nasal doc
|syntax = math.max(x[, y[, z[, ...]]]);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|version = 2.4
|commit = {{fgdata commit|36c48c|t=Commit}}
|text = Returns the highest number of the given numbers. There must be at least one argument, but there may be as many as you like.
|example1 = print(math.max(1, 2, 3, 4)); # prints 4
}}

=== min() ===
{{Nasal doc
|syntax = math.min(x[, y[, z[, ...]]]);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|version = 2.4
|commit = {{fgdata commit|36c48c|t=Commit}}
|text = Returns the lowest number of the given numbers. There must be at least one argument, but there may be as many as you like.
|example1 = print(math.min(1, 2, 3, 4)); # prints 1
}}

=== mod() ===
{{See also|Nasal library#fmod()}}
{{Nasal doc
|syntax = math.mod(x, y);
|source = {{simgear file|simgear/nasal/mathlib.c|l=106|t=Source}}
|text = Returns the result of the modulo operation of the given numbers, that is, is returns the remainder of '''x''' divided by '''y'''. Note that this function does not not return correct answers when either or both the arguments are negative (see example 3), unlike <code>[[#fmod.28.29|fmod()]]</code>. Both arguments are mandatory and must be numbers.
|param1 = x
|param1text = The dividend.
|param2 = y
|param2text = The divisor. If this argument is 0, infinity will be returned (printed as <code>0e-00</code>).
|example1 = print(math.mod(5, 2)); # prints 1 (2 goes into 5 twice with a remainder of 1; 2 * 2 + 1 = 5)
|example2 = print(math.mod(10, 5)); # prints 0 (5 goes into 10 twice with a remainder of 0; 5 * 2 + 0 = 10)
|example3 = print(math.mod(-5, 4)); # prints 3 (incorrect, should be -1)
}}

=== periodic() ===
{{Nasal doc
|syntax = math.periodic(min, max, x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=130|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3|t=Commit}}
|text = Normalizes the given number (e.g., a bearing) to be within a set periodic range (e.g., compass bearings, which go from 0 to 360). All the arguments are mandatory and must be numbers.
|param1 = min
|param1text = Lower boundary of the periodic range.
|param2 = max
|param2text = Upper boundary of the periodic range
|param3 = x
|param3text = Number to normalize.
|example1 = var norm_360 = func(a){
return math.periodic(0, 360, a);
}

print(norm_360(-90)); # prints 270
print(norm_360(45)); # prints 45
|example2 = var norm_180 = func(a){
return math.periodic(-180, 180, a);
}

print(norm_180(45)); # prints 45
print(norm_180(270)); # prints -90
|example3 = print(math.periodic(0, 10, 15)); # prints 5
}}

=== pow() ===
{{Nasal doc
|syntax = math.pow(b, n);
|source = {{simgear file|simgear/nasal/mathlib.c|l=68|t=Source}}
|text = Returns the base '''b''' raised to the '''n''' power. Both arguments are mandatory and must be numbers.
|param1 = b
|param1text = Base.
|param2 = n
|param2text = Exponent.
|example1 = print(math.pow(2, 2)); # prints 4
}}

=== round() ===
{{Nasal doc
|syntax = math.round(x[, p]);
|source = {{simgear file|simgear/nasal/mathlib.c|l=153|t=Source}}
|version = 3.0
|commit = {{simgear commit|ad83e7|t=Commit}}
|text = Rounds '''x''' to the optional precision ('''p'''). If the fractional part of '''x''' is 0.5, it will always be rounded up. Both argument must be numbers.
|param1 = x
|param1text = Mandatory number to round.
|param2 = p
|param2text = Optional precision to round to. For example, if this is set to 10, '''x''' will be rounded to the nearest 10. Defaults to 1, and should be greater than or equal to 1 for correct output. For rounding to decimal places, it is better to use {{func link|sprintf}}.
|example1 = print(math.round(4.2)); # prints 4
|example2 = print(math.round(4.7)); # prints 5
|example3 = print(math.round(4.5)); # prints 5
|example4 = print(math.round(127, 10)); # prints 130
|example5 = print(math.round(456, 100)); # prints 500
}}

=== sin() ===
{{Nasal doc
|syntax = math.sin(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=23|t=Source}}
|text = Implements the sine trigonometric function. Returns a ratio from a given angle in radians.
|param1 = x
|param1text = Mandatory number that should be an angle in radians.
|example1 = var angle = 90 * D2R;
print(math.sin(angle)); # prints the ratio (1)
}}

=== sgn() ===
{{Nasal doc
|syntax = math.sgn(x);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|text = Returns the result of the sign function on the given number. If '''x''' is less than 0, -1 one is returned. If '''x''' equals 0, 0 is returned. If '''x''' is greater than 0, 1 is returned.
|param1 = x
|param1text = Mandatory number to return the sign of.
|example1 = print(math.sgn(-6)); # prints -1
|example2 = print(math.sgn(0)); # prints 0
|example3 = print(math.sgn(12)); # prints 1
}}

=== sqrt() ===
{{Nasal doc
|syntax = math.sqrt(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=59|t=Source}}
|text = Returns the square root of the given number.
|param1 = x
|param1text = Mandatory number to return the square root of. Must be greater than or equal to 0.
|example1 = print(math.sqrt(9)); # prints 3
}}

=== tan() ===
{{Nasal doc
|syntax = math.tan(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=177|t=Source}}
|text = Implements the tangent trigonometric function. Returns a ratio from a given angle in radians.
|param1 = x
|param1text = Mandatory number that should be an angle in radians.
|example1 = var angle = 45 * D2R;
print(math.tan(angle)); # prints the ratio (1)
}}

== Variables ==
=== e ===
{{Nasal doc
|syntax = math.e;
|source = {{simgear file|simgear/nasal/mathlib.c|l=232|t=Source}}
|text = Important mathematical constant (see {{wikipedia|e (mathematical constant)}}). Value in simulation: 2.7182818284590452354
}}
=== pi ===
{{Nasal doc
|syntax = math.pi;
|source = {{simgear file|simgear/nasal/mathlib.c|l=231|t=Source}}
|text = Important mathematical constant (see {{wikipedia|pi (mathematical constant)}}). Value in simulation: 3.14159265358979323846
}}

{{Nasal namespaces}}

User:TheEagle

2022-10-03T14:10:40Z

TheEagle: Add wiki link for the C310

I like to fly in FlightGear, create and enhance scenery, aircraft and addons for FlightGear, write Python apps …

=== My aircraft ===
Cessna 210 ([https://github.com/TheFGFSEagle/c210-family GitHub] | [[Cessna 210 Centurion family|Wiki]])

Cessna 310 ([https://github.com/TheFGFSEagle/c310-family GitHub] | [[Cessna 310 family|Wiki]])

Pilatus PC-6 ([https://github.com/TheFGFSEagle/pilatus-pc6-family GitHub] | Wiki)

Cessna 208 ([https://github.com/TheFGFSEagle/c208-family GitHub] | Wiki)

Mudry CAP10 ([https://github.com/TheFGFSEagle/mudry-cap10-family GitHub] | Wiki)

User:TheEagle

2022-10-03T14:09:08Z

TheEagle:

I like to fly in FlightGear, create and enhance scenery, aircraft and addons for FlightGear, write Python apps …

=== My aircraft ===
Cessna 210 ([https://github.com/TheFGFSEagle/c210-family GitHub] | [[Cessna 210 Centurion family|Wiki]])

Cessna 310 ([https://github.com/TheFGFSEagle/c310-family GitHub] | Wiki)

Pilatus PC-6 ([https://github.com/TheFGFSEagle/pilatus-pc6-family GitHub] | Wiki)

Cessna 208 ([https://github.com/TheFGFSEagle/c208-family GitHub] | Wiki)

Mudry CAP10 ([https://github.com/TheFGFSEagle/mudry-cap10-family GitHub] | Wiki)

Cessna 310 family

2022-09-19T00:18:03Z

TheEagle: Created page

The '''Cessna 310''' is an American four-to-six-seat, low-wing, twin-engine monoplane produced by Cessna between 1954 and 1980. It was the first twin-engine aircraft that Cessna put into production after World War II.

== Status in FlightGear ==
The model is not very far advanced yet (thus not available on FGAddon), but work in progress.

== Variants ==
At the moment, the 310A variant is being developed - further variants are planned.

== Web links ==
Discord channel: https://discord.gg/8eFTtaBVAT then go to Cessna 310 #general.

Matrix space: https://matrix.to/#/!fEOTalzMFXdlqnGjUM:matrix.org

GitHub repo: https://github.com/TheFGFSEagle/c310-family

Forum development topic: https://forum.flightgear.org/viewtopic.php?f=4&t=40501

Hackathon Proposal:Canvas Widgets

2022-09-06T15:55:56Z

TheEagle: Remove double primarily

{{WIP}}

{{Hackathon Proposal
|year=2022
|title= Getting rid of PUI using the Canvas
|image = About-dialog-rendered-by-canvas.png
|imginfo = about.xml parsed and rendered by the Canvas GUI system
|status = RFC
|sponsor= |supporters= please add yourself if you are interested in working on this
|summary = {{Main article|PUI#Replacement_status}}
The [[PUI]] replacement [[QtQuick_use_in_FlightGear#Background|was going to be Qt]] but it started to get very complicated with changes in Qt 5.15 + Qt 6, so James is going with a more light-weight Canvas based approach now.

Qt added support for Vulkan / Metal / D3D starting in 5.15, but FlightGear / OpenSceneGraph can’t support those, so integrating the two renderers went from being ‘complicated but ok’ to ‘very very complicated’.

So now James is going with something much more lightweight using some C++ compatibility code, some Nasal for styling and the existing [[Canvas widgets|Canvas widget rendering]] from Thomas Geymayer (TheTom) with some extensions and additions, based on the [[Howto:Processing_legacy_PUI_dialogs_using_Canvas#Original_Discussion|plans originally discussed when the Canvas GUI system was added to FlightGear]]: some pieces are in FlightGear & FGData already.

James has basic dialogs working okay but not the more complex ones and everything looks kind of ugly, he needs to improve the visual look before he shares screenshots to avoid everyone freaking out :) The disadvantage of this approach is James is far from expert at creating visual appearances this way, so it’s kind on unrewarding and slow for him. If someone likes messing with CSS-type styling, border-images and hover-states, ping him since we could probably move things also faster <ref>https://sourceforge.net/p/flightgear/mailman/message/37701750/</ref>
|background= {{See also|Core Profile support|Unifying the 2D rendering backend via canvas}}
The bigger issue here is we need to ditch [[PUI]] (which is in progress) and some OpenGL 1.0 code (HUD, 2D panels especially - can be #ifdef for now) so we can enable Core profile on Mac - since Mac 4.x support (we only hit about 4.3 alas, but with some extensions to get in sight of 4.5) is Core profile only, no Compatability mode.

Improving the frame-rate and modernised 3D rendering, can’t be worked on until the PUI code, 2D panels and Shiva are removed, but doing so is a frustrating slow path<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35623408/
|title = <nowiki> Re: [Flightgear-devel] canvas non svg-elements broken </nowiki>
|author = <nowiki> James Turner </nowiki>
|date = Jan 24th, 2017
|added = Jan 24th, 2017
|script_version = 0.40
}}</ref>

Given that with many graphics drivers PUI doesn't render correctly when higher shader quality is on, many people are convinced PUI needs to be replaced.<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35624918/
|title = <nowiki> Re: [Flightgear-devel] canvas non svg-elements broken </nowiki>
|author = <nowiki> Thorsten Renk </nowiki>
|date = Jan 25th, 2017
|added = Jan 25th, 2017
|script_version = 0.40
}}</ref>

|details={{Main article|Howto:Creating a Canvas GUI Widget}}

It’s split between Simgear (see classes with widget / layout in the name) and in FGData. (Eg widgets/Button.nas) To be able to use the existing dialog XML files un-modified (which is a design goal), James is extending the widget types with many additional ones (eg PUI has slider, dial, combo-box, checkbox, all of which need to be created, see [[Canvas widget matrix]].

This is about 30% done and is the bit he's very slow at). Thomas’s canvas widgets have a very good separation of API + state from appearance, so all styling is in its own file, and James is being very strict about maintaining this separation, so we also retain the re-styling feature of the PUI UI, which many people also rely on. This does make the process of adding new widgets more complex, however.

|ideas = {{See also|Canvas_widget_matrix}}
There are only ~5 widgets in the Canvas GUI: currently
* {{Canvas Widget|widget=Button}}
* {{Canvas Widget|widget=CheckBox}}
* {{Canvas Widget|widget=Label}}
* {{Canvas Widget|widget=LineEdit}} (editable text box)
* {{Canvas Widget|widget=ScrollArea}} (for scrollable content)

In contrast, the [[PUI]] subsystem in FlightGear supports ~15 documented widgets (see {{readme file|gui|line=219}} for a list of widgets made available to FlightGear via PUI/XML).
For a complete list (including custom/undocumented widgets), refer to <code>FGPUIDialog::makeObject()</code> in {{flightgear file|src/GUI/FGPUIDialog.cxx|l=850}}

In addition, FlightGear introduces a handful of custom PUI widgets implemented in C++ space, that not even PUI itself supports directly:
* {{PUI widget|airport-list}} {{Dialog file|dialog=airports|l=393}}
* {{PUI widget|waypointlist}} (only used by the [[Route Manager]] i.e. {{Dialog file|dialog=route-manager|l=590}}
* {{PUI widget|property-list}} (only used by the [[Property browser]] i.e. {{Dialog file|dialog=property-browser|l=55}}

However, many PUI widgets can be emulated/approximated by using a combination of existing widgets, and/or functionality found in existing widgets, i.e. by referring to their source code.

For instance, all the data needed to obtain a list of airports or waypoints can be queried using the [[Navdata_cache#Accessing_via_Nasal| Navdb APIs]] exposed via [[Nasal/CppBind]], specifically:
* findAirportsWithinRange()
* findNavaidsWithinRange()

At this point, we can map arbitrary navdb calls to help populate a ScrollArea with entries.

Thus, what is primarily needed to implement support for arbitrary -list types is a ScrollArea that uses buttons (or labels) for each entry.

Primarily, the following widgets are needed to help getting rid of PUI (listed in ascending complexity):
* {{PUI widget|vrule}} (not critical, could be implemented OpenVG or simply by using a transparent image)
* {{PUI widget|hrule}} (not critical, could be implemented OpenVG or simply by using a transparent image)
* {{PUI widget|radio}} (Canvas images using event handling to dynamically change the image based on mouse events)
* {{PUI widget|slider}} (basically 3 buttons with the middle button supporting dragging, see also [https://forum.flightgear.org/viewtopic.php?f=71&t=19975])
* {{PUI widget|dial}} (see also [https://forum.flightgear.org/viewtopic.php?f=71&t=19975])
* {{PUI widget|combo}} (popup with a scrollArea that has buttons for each item (can be shared with {{tag|select}})

The key ones really being the last 4 in that list (radio, slider, dial and combo/dropdown)

|skills= [[Property tree]], [[PropertyList XML File]], [[Nasal]], [[Canvas]], [[Timers]], [[Listeners]]
|opportunities=</p>
* [[PUI]]
* [[Canvas event handling]]
* [[Canvas widgets]]
|notes = to learn more about the underlying idea/approach, please refer to [[pui2canvas]]
}}

User:TheEagle

2022-07-04T09:29:37Z

TheEagle: Added aircraft list

I like to fly in FlightGear, create and enhance scenery, aircraft and addons for FlightGear, …

=== My aircraft ===
Cessna 210 ([https://github.com/TheFGFSEagle/c210-family GitHub] | [[Cessna 210 Centurion family|Wiki]])

Pilatus PC-6 ([https://github.com/TheFGFSEagle/pilatus-pc6-family GitHub] | Wiki)

Cessna 208 ([https://github.com/TheFGFSEagle/c208-family GitHub] | Wiki)

Mudry CAP10 ([https://github.com/TheFGFSEagle/mudry-cap10-family GitHub] | Wiki)

Cessna 210 Centurion family

2022-07-04T09:26:25Z

TheEagle:

{{DISPLAYTITLE:Cessna 210 "Centurion"}}

{{Infobox aircraft|name=Cessna 210 "Centurion"|status-model=4|forumtid=39711|craft=aircraft|wikipedia=Cessna_210_Centurion|devel-repo=https://github.com/TheFGFSEagle/c210-family|status=3|status-cockpit=4|type=Light aircraft|status-systems=4|status-fdm=4|fdm=JSBsim|manufacturer=Cessna|fgname=p210n|author1=TheEagle|propulsion=Piston aircraft/Propeller aircraft|config=High wing aircraft/Retractable gear aircraft/Tricycle landing gear aircraft|image=Cessna_P210N_cruising.png}}

The '''Cessna 210 Centurion''' is a five- to six-seat, high-performance, retractable-gear, single-engine, high-wing general aviation aircraft. First flown in January 1957, it was produced by Cessna until 1986.

== Variants ==
The Cessna 210 family includes many variants, but only one (the P210N) is modelled for FlightGear so far.
(Silver Eagle turboprop modification of the P210N by O&N coming soon)

== Information and help==

===Startup===
Use either Menu -> Cessna 210 -> Autostart, or follow the checklist below:
# Master BAT: ON
#NAV lights: ON
#Mixture: FULL RICH (full forward) (<code>m</code> key)
#Prop RPM: HIGH (full forward) (<code>n</code> key)
#Throttle: IDLE (fully backward) (<code>PgDown</code> key)
#Parking brake: APPLIED (lever pointing down) (<code>Shift + b</code> keys)
#Fuel selector: LEFT or RIGHT
#Magneto keys: INSERT
#Magnetos: BOTH then START (or press <code>}</code> three times then hold <code>s</code> for two to three seconds)
#Master ALT: ON
#Avionics master: ON
If it won't start neither by hand nor through the autostart function, follow the checklist but at 9. hold the <code>s</code> and simultaneously lean (pull out) the mixture until the engine's RPM stabilizes at ~800 RPM.

==ToDo==

*Checklists, tutorials
*Liveries
*Damage, icing simulation
*WXRadar implementation

==External references==
*[https://forum.flightgear.org/viewtopic.php?f=4&t=39711 Official forum topic]
*[http://www.marksetcetera.com/N731PJ-P210N-POH.pdf P210N Pilots operating handbook (POH)]

[[Category:Aircraft|Cessna 210 Centurion]]
[[Category:Single-engine aircraft]]
{{DEFAULTSORT:Cessna 210 Centurion}}
__FORCETOC__
__INDEX__
__NEWSECTIONLINK__