X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=docs-mini%2FREADME.digitalfilters;h=ad7a26e2666f7e363933364adc2827c21d17c59e;hb=afb0ada81f6fd0fe179ab00f048134d101f5f311;hp=96d7defc5e32f320260aaf7052ff45f4b62199f9;hpb=2186fdf96161ebf857cc48425d782331f4f9c53e;p=flightgear.git diff --git a/docs-mini/README.digitalfilters b/docs-mini/README.digitalfilters index 96d7defc5..ad7a26e26 100644 --- a/docs-mini/README.digitalfilters +++ b/docs-mini/README.digitalfilters @@ -1,3 +1,247 @@ +COMMON SETTINGS +============================================================================== + +Currently four types of digital filter implementations are supported. They all serve an +individual purpose or are individual implementations of a specific filter type. +Each filter implementation uses the same set of basic configuration tags and individual +configuration elements. These individual elements are described in the section of the +filter. + +The InputValue +============================================================================== +Each filter has several driving values, like the input value itself, sometimes a reference +value, a gain value and others. Most of these input values can bei either a constant value +or the value of a property. They all use the same syntax and will be referred to as InputValue +in the remaining document. + +The complete XML syntax for a InputValue is + + + + + + /some/property/name + 0.0 + 1.0 + 0.0 + infinity + -infinity + false + + +The enclosing element is the element defined in each filter, like , , + etc. These elements will be described later. +The value of the input is calculated based on the given value, scale and offset as +value * scale + offset +and the result is clipped to min/max, if given. +With the full set of given elements, the InputValue will initialize the named property to the value +given, reduced by the given offset and reverse scaled by the given scale. + +Example: + + /controls/flight/rudder + 0.0 + 0.5 + 0.5 + + +Will use the property /controls/flight/rudder as the input of the filter. The property will be initialized +at a value of zero and since the property usually is in the range [-1..+1], the the value of will +be in the range (-1)*0.5+0.5 to (+1)*0.5+0.5 which is [0..1]. + +The default values for elements not given are: + : 0.0 + : 1.0 +: 0.0 + : none + : unclipped + : unclipped + : false + +Some examples: + + /position/altitude-ft + 0.3048 + +Gives the altitude in meters. No initialization of the property is performed, no offset applied. + + + 0.0 + +A constant reference of zero. + +A abbreviated method of defining values exist for using a just constant or a property. The above +example may be written as +0.0 +Or if the reference is defined in a property +/some/property/name +No initialization, scaling or offsetting is performed here. +The logic behind this is: If the text node in the element (the text between the opening and closing tag) +can be converted to a double value, it will be interpreted as a double value. Otherwise the text will +be interpreted as a property name. +Examples: +3.1415927 - The constant of PI (roughly) +/position/altitude-ft - The property /position/altitude-ft +3kings - The constant 3. The word kings is ignored +food4less - The property food4less + +The element may also be written as for backward compatibility. + +There may be one or more InputValues for the same input of a filter which may be bound to conditions. +Each InputValue will have its condition checked in the order of InputValues given in the configuration +file. The first InputValue that returns true for its condition will be evaluated. Chaining a number +of InputValues with conditions and an unconditioned InputValue works like the C language equivalent +if( condition ) { + // compute value of first element +} else if( condition2 ) { + // compute value of second element +} else if( condition3 ) { + // compute value of third element +} else { + // compute value of last element +} + +Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold or 2.0 otherwise. + + + + + /autopilot/locks/heading + dg-heading-hold + + + 3.0 + + + + 2.0 + + + +If the element is used and set to the value "true", only the absolute value of the input +(the positive part) is used for further computations. The abs function is applied after all +other computations are completed. + +OutputValue +============================================================================== +Each filter drives one to many output properties. No scaling of offsetting is implemented +for the output value, these should be done in the filter itself. +The output properties are defined in the element by adding elements +within the element. For just a single output property, the element +may be ommited. For backward compatibility, may be replaced by . +Nonexisting properties will be created with type double. + +Example: (Multiple output properties) + + /some/output/property + /some/other/output/property + /and/another/output/property + + +Example: a single output property +/just/a/single/property + +Other Common Settings +============================================================================== + String The name of the filter. Used for debug purpose. +Example: +pressure rate filter + + Boolean If true, this filter puts out debug information when updated. +Example: +false + + InputValue The input property driving the filter. + Refer to InputValue for details. + + InputValue The reference property for filter that need one. + Refer to InputValue for details. + + Complex Each filter can drive one to many output properties. + Refer to OutputValue for details. + + InputValue This defines the optional minimum and maximum value the output + is clamped to. If neither nor exists, the output + is only limited by the internal limit of double precision float computation. + If either or is given, clamping is activated. A missing + min or max value defaults to 0 (zero). + Note: and may also occour within a element. + and may be used as a substitude for the corresponding u_xxx element. + +Example: Limit the pilot's body temperature to a constant minimum of 36 and a maximum defined in + /pilots/max-body-temperature-degc, initialized to 40.0 + + /pilots/max-body-temperature-degc + 40.0 + + 36.0 + + 100.0 + + + Complex Define a condition to enable or disable the filter. For disabled + filters, no output computations are performed. Only enabled + filters fill the output properties. The default for undefined + conditions is enabled. + Several way exist to define a condition. The most simple case + is checking a boolean property. For this, just a element + naming this boolean property is needed. The boolean value of the + named property defines the enabled state of the filter. + To compare the value of a property with a constant, a and + a element define the property name and the value to be + compared. The filter is enabled, if the value of the property + equals the given value. A case sensitive string compare is + performed here. + To define more complex conditions, a element may be + used to define any condition described in README.conditions. + If a element is present and if it contains a valid + condition, this conditions has precedence over a given / + condition. + The child element , a boolean flag, may be present + within the element. If this element is true, the property + /autopilot/locks/passive-mode is checked and if it is true, the + filter output is computed, but the output properties are not set. + The default for honor-passive is false +Example: Check a boolean property, only compute this filter if gear-down is true and + /autopilot/locks/passive-mode is false + + /gear/gear-down + true + + +Check a property for equality, only compute this filter if the autopilot is locked in heading mode. + + /autopilot/locks/heading + dg-heading-hold + + +Use a complex condition, only compute this filter if the autopilot is serviceable and the lock +is either dg-heading-hold or nav1-heading-hold + + + /autopilo/serviceable + + + /autopilot/locks/heading + dg-heading-hold + + + /autopilot/locks/heading + nav1-heading-hold + + + + + +INDIVIDUAL FILTER CONFIGURATION +============================================================================== + +Digital Filter + Six different types of digital filter can be configured inside the autopilot configuration file. There are four low-pass filter types and two gain filter types. @@ -14,7 +258,32 @@ The gain filter types are: * gain * reciprocal -Example 1: +To add a digital filter, place a element under the root element. Next to +the global configuration elements described above, the following elements configure +the digital filter: + InputValue This tag is only applicable for the exponential and + double-exponential filter types. It controls the bandwidth + of the filter. The bandwidth in Hz of the filter is: + 1/filter-time. So a low-pass filter with a bandwidth of + 10Hz would have a filter time of 1/10 = 0.1 + + InputValue This tag only makes sense for the moving-average filter. + It says how many past samples to average. + + + InputValue This tag is applicable for the noise-spike filter. + It says how much the value is allowed to change per second. + + InputValue This is only applicable to the gain and reciprocal filter types. + The output for gain filter is computed as input*gain while + the reciprocal filter computes output as gain/input for input + values != 0 (zero). Gain may be a constant, a property name + defined by a element within the element or a + property name initialized to a value by using a and + element. + +Example: a pressure-rate-filter implemented as a double exponential low pass filter + with a bandwith of 10Hz pressure-rate-filter @@ -110,7 +379,9 @@ Parameters console. Encloses the and tags which are used to enable or -disable the filter. Defaults to enabled if unspecified. +disable the filter. Instead of the and tags, a +tag may be used to define a condition. Check README.conditions for more +details about conditions. Defaults to enabled if unspecified. The type of filter. This can be exponential, double-exponential, moving-average, noise-spike, gain or reciprocal.