Preprocessor functions ---------------------------------------------------------- ExecutePreprocessor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The pre-processor functions are executed *before* the calculation of the channels. The execution of the Pre-processor before executing the calculation file runs automatically. In the code, you can use the command ExecutePreprocessor to force execution of the Pre-processor .. code-block:: none ExecutePreProcessor ; Forcing Pre-Processor executing at respective point in code. .. important:: Forcing Pre-processor execution is necessary if e.g. a SpecSheet entry was written in a previous group of the same calculation file is used later again .. _link_CalcTool_Include: Include files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the CalcTool there are several possibilities to include other files in a calculation. It is possible to include the following types of files: - Parameter files (.HED). - Variable files (.Var) - Calculation files (.CAL/.CCF) .. attention:: Variable files are included at the beginning of a calculation file! .. attention:: Calculation files are included within groups! .. important:: In chapter 3.3 an overview over different path-placeholders can be found which can replace … in the path calls like *…\\FileName.VAR* Parameter files ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' Only the measurement related parameter file (.HED), which are located **in the respective measurement directory** can be accessed from calculation files! .. important:: For more information about parameter files (.HED) please see chapter 4. Variable files ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' For including variable files (.VAR), the following call is valid: .. code-block:: none {$V FileName.VAR} ; Including variable file FileName.VAR .. code-block:: none {$V …\FileName.VAR} ; Including variable file FileName.VAR .. important:: If there is *no* path defined at a VAR-File include (...\), the VAR-File is searched **inside Race-installation folder**! .. important:: For more information about VAR-file see 6.1.4.4.2. .. attention:: The VAR-file include call must be placed at the beginning of a calculation file! .. attention:: If more than one VAR-files are included at the beginning of a calculation file, only the **first** include call is considered! Calculation files ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' Include calculation files are very suitable for outsourcing frequently used routines and thus making the calculation file clearer. Since parameters and channels can also be passed to the include files, generally valid functions for several purposes can also be used as include files. .. Include calls can also be linked to a condition. File extension '''''''''''''' Cryped as well as encrypted calculation files can be included. .. code-block:: none {$I FileName.CAL} ; Including encrypted calculation file from current event .. code-block:: none {$I …\FileName.CAL} ; Including encrypted calculation file from respective path .. code-block:: none {$I FileName.CCF} ; Including crypted calculation file from current event .. code-block:: none {$I …\FileName.CCF} ; Including crypted calculation file from respective path a) If *no* extension, e.g. **…\FileName**, is available in the include call, first a CAL file is searched for in event directory b) If no CAL file could be found in respective directory, it is searched for a CCF with same name c) If no CCF is found in respective directory, an error message appears .. important:: This approach applies to both unconditional and conditional inclusions! Path definitions '''''''''''''''' .. important:: This approach applies to both crypted and encrypted calculation files If there is *no* path defined at a calculation file include call, e.g. **{$I FileName.CAL}**, the calculation file to be included is searched for the in the directory, the calculation file **with include call** is located in! If a calculation file from another directory must be included, the file-path must be defined at include call. Only since *Race2021* the path of third stage include call (CAL3 see following ***Example: Race2021***) no longer needs to be defined separately, because the path will of CAL3 is traced back to the include call of CAL2. .. important:: The advantage of this is that when moving CAL2 and CAL3 to another directory, only the include path of CAL2 in include call at CAL1 needs to be changed. (***Example: Race2021 C & D***) In older Race-versions, the path of CAL3 must also be defined for the include call in CAL2, because if no path is defined for the include call in CAL2, the system will search in the directory of CAL1 for CAL3 (***Example: Race2020 and older versions A***). .. attention:: Keep in mind that include-call of CAL3 in CAL2 must be changed if CAL2 and CAL3 are moved to another directory! .. figure:: /Images/Calctool/IncludeCalls.png :scale: 65% :align: center Unconditional include ''''''''''''''''''''' For including calculation files without any conditions, the following calls are valid: +------------------------+----------------------------------------+ | **Syntax** | **Meaning** | +========================+========================================+ | {$I …\\FileName.CAL} | Including encrypted calculation file | +------------------------+----------------------------------------+ | {$I …\\FileName.CCF} | Including crypted calculation file | +------------------------+----------------------------------------+ .. _link_CalcTool_ConditionalExecution: Conditional include ''''''''''''''''''' For including a calculation files only if *one* conditions is fulfilled, the following calls are valid: .. important:: Conditional include commands are only executed if the respective condition is fulfilled! .. important:: Conditional include is possible for crypted and encrypted calculation files! +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | **The following conditional includes are possible:** | | +=====================================================================================+===============================================================================================+ | {$IfExists(#CH) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if channel #CH available | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfNotExists(#CH) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if channel #CH not available | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfLaptimesExist ...\\FileName.CAL, P(P1, P2, ...)} | Only include if laptimes exists | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfNotLaptimesExist ...\\FileName.CAL, P(P1, P2, ...)} | Only include if laptimes exists | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfLicenceNameContains(‘Name’) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry INFO\_2D.LicenseName contains entry ‘Name’ | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfNotLicenceNameContains(‘Name’) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry INFO\_2D.LicenseName contains entry ‘Name’ | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfSpecValueContains(Group.Entry, ‘Value’) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry Group.Entry not contains entry ‘Name’ | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfNotSpecValueContains(Group.Entry, ‘Value’) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry Group.Entry not contains ‘Value’ | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfSpecIs(Group.Entry, ‘Value’) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry Group.Entry is ‘Value’ | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfNotSpecIs(Group.Entry, ‘Value’) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry Group.Entry not is ‘Value’ | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfSpecValueExists(Group.Entry) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry Group.Entry exists | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ | {$IfNotSpecValueExists(Group.Entry) ...\\FileName.CAL, P(P1, P2, ...)} | Only include if Spec-Entry Group.Entry not exists | +-------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ Parameter handover '''''''''''''''''' To be able to call a CAL file several times with different parameters, the parameter handover of the include command is used .. important:: Conditional and unconditional includes both also provide the possibility for parameter handover! .. important:: Beside numbers, also names or SpecSheet placeholder can be used as handover parameter. For including calculation files with parameter handover, the following calls are valid. +-------------------------------------------------+-------------------------------------------------------------------------------+ | **Syntax** |**Meaning** | +=================================================+===============================================================================+ | {$I …\\FileName.CAL, P(p1, p2,…)} | Unconditional include of encrypted calculation file with parameter handover | +-------------------------------------------------+-------------------------------------------------------------------------------+ | {$IfExists(#CH) …\\FileName.CAL, P(p1, p2,…)} | Conditional include of encrypted calculation file with parameter handover | +-------------------------------------------------+-------------------------------------------------------------------------------+ | {$I …\\FileName.CCF, P(p1, p2,…)} | Unconditional include of crypted calculation file with parameter handover | +-------------------------------------------------+-------------------------------------------------------------------------------+ | {$IfExists(#CH) …\\FileName.CCF, P(p1, p2,…)} | Conditional include of crypted calculation file with parameter handover | +-------------------------------------------------+-------------------------------------------------------------------------------+ .. important:: In the included calculation file the link to the handover parameters of the include file is established via the calls @P1, @P2, @... .. important:: Parameter-handover is also possible with all other conditions! **Example:** Include calls: .. code-block:: none [FilterAcc] {$I _Filter.CAL, P(Acc)} ; Unconditional Include: Call CAL-File "_Filter" and handing over one parameter "Acc" [FilterGyro] {$Ifexists(#Gyro_x_1) _Filter.CAL, P(Gyro)} ; Conditional Include: Call CAL-File "_Filter" only if channel "#Gyro_x_1" exists and handing over one parameter "Gyro" Calculation file to be included: _Filter.CAL .. code-block:: none [Filter_@P1] @P1_x_1_F = F(#@P1_x_1, F(IIR(FilterSettings.FilterFreq Hz))) ; Filtering #@P1_x_1 (e.g Acc_x_1) with an IIR-Filter with filter frequency defined by SpecSheet entry @P1_y_1_F = F(#@P1_y_1, F(IIR(FilterSettings.FilterFreq Hz))) ; Filtering #@P1_y_1 (e.g Acc_y_1) with an IIR-Filter with filter frequency defined by SpecSheet entry @P1_z_1_F = F(#@P1_z_1, F(IIR(FilterSettings.FilterFreq Hz))) ; Filtering #@P1_z_1 (e.g Acc_z_1) with an IIR-Filter with filter frequency defined by SpecSheet entry Created channels: * Acc_x_1_F * Acc_y_1_F * Acc_z_1_F * Gyro_x_1_F (only if channel Gyro_x_1 exists) * Gyro_y_1_F (only if channel Gyro_x_1 exists) * Gyro_z_1_F (only if channel Gyro_x_1 exists) Conditional execution of CAL-file groups ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In some cases, it is useful to execute a group in calculation file only if a certain channel or *SpecSheet* value exists (or if it doesn´t exist). .. For this reason, *CalcTool* provides the conditional execution of **calculation groups**. .. important:: It is possible to use more than one condition for a group, but the condition lines must be one after the other at the start of the group: IfLaptimesExist ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' With this condition it is possible to calculate a single group only if the measurement contains lap times. .. code-block:: none [MyCalc] ; Start of group IfLaptimesExists ; Condition: This group is only executed if the measurement contains lap times. ; Group calculations IfNotLaptimesExist ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' This condition is the opposite of the one above. A single calculation group is calculated only if the measurement does not contain lap times. .. code-block:: none [MyCalc] ; Start of group IfNotLaptimesExists ; Condition: This group is only executed if the measurement contains DOES NOT lap times. ; Group calculations IfExists ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' With this condition it is possible to calculate a single group only if a channel exists. .. code-block:: none [MyCalc] ; Start of group IfExists(#CH) ; Condition: This group is only executed if #CH exists. ; Group calculations IfNotExists ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' This condition is the opposite of the one above. A single calculation group is performed only if a certain channel doesn´t exist. .. code-block:: none [MyCalc] ; Start of group IfNotExists(#CH) ; Condition: This group is only executed if #CH DOES NOT exists. ; Group calculations IfOrgExists ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' With this condition it is possible to calculate a single group only if a respective originally recorded channel exists. .. code-block:: none [CH] ; Start of group IfOrgExists(#CH) ; Condition: This group is only executed if #CH exists as originally recorded channel. ; Group calculations NewResult = ; Overwrite originally recorded channel CH .. attention:: IfOrgExists will most likely be used in combination with NewResult (3.7) to check if an originally recorded channel is available. NewResult is only able to overwrite originally recorded channels with the group name [‘Ch’] but not CALC channels! IfNotOrgExists ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' This condition is the opposite of the one above. A single calculation group is performed only if a respective originally recorded channel doesn´t exist. .. code-block:: none [MyCalc] ; Start of group IfNotOrgExists(#CH) ; Condition: This group is only executed if #CH DOES NOT exists as originally recorded channel. ; Group calculations CH = ; Create permanent channel with name CH .. attention:: IfNotOrgExists will most likely be used in combination with creating new permanent channels (3.6) when no originally recorded channel is available. .. attention:: Please see the following example why it is important to use ‘Ch’ **Example IfOrgExists/IfNotOrgExists** Especially GPS channels Altitude and Course are at different 2D-GPS-Systems sometimes available as originally recorded channels or generated CALC channels. .. To handle the different options in calculation files the IfOrgExists/IfNotOrgExists were created: .. code-block:: none [Course] ; Name of group IfOrgExists(#Course) ; Condition: This group is only executed if #CH DOES NOT exists as originally recorded channel. ... ; Calculations NewResult = noop(#C1) ; Overwrite originally recorded channel #Course with temporary channel #C1 [Course_NotExists] ; Name of group IfNotOrgExists(#Course) ; Condition: This group is only executed if #CH DOES NOT exists as originally recorded channel. ... ; Calculations Course = noop(#C1) ; Overwrite channel #Course with temporary channel #C1 IfSpecValueExists ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' With this condition it is possible to calculate a single group only if the *SpecSheet* of the measurement contains a certain entry. .. code-block:: none [MyCalc] ; Start of group IfSpecValueExists(Group.Entry) ; Condition: This calculation is only done if the *SpecSheet* of the measurement contains group “Group” with the entry “Entry". ; Group calculations IfNotSpecValueExists ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' This condition is the opposite of the one above. A single calculation group is calculated only if the *SpecSheet* of the measurement does not contain the entry “Entry” in the group “Group”. .. code-block:: none [MyCalc] ; Start of group IfNotSpecValueExists(Group.Entry) ; Condition: This calculation is only done if the *SpecSheet* of the measurement DOES NOT contain group “Group” with the entry “Entry”. ; Group calculations IfSpecValueContains ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' With this condition the user has possibility to calculate a single group only if the *SpecSheet* of the measurement contains a certain entry and if the entry contains a certain string (SearchStr). .. code-block:: none [MyCalc] ; Start of group IfSpecValueContains(Group.Entry, SearchStr) ; Condition: This calculation is only executed if the *SpecSheet* of the measurement contains group “Group” with the entry “Entry” and the entry contains the searched string. ; Group calculations IfNotSpecValueContains ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' This condition is the opposite of the one above. A single calculation group is only calculated if the *SpecSheet* of the measurement does not contain the entry “Entry” in the group “Group” or if the entry exists but does not contain a certain string (SearchStr). .. code-block:: none [MyCalc] ; Start of group IfNotSpecValueContains(Group.Entry, SearchStr) ; Condition: This calculation is only executed if the *SpecSheet* of the measurement does not contain an entry “Entry” in the group “Group” or the entry exists but DOES NOT contain a certain searched string. ; Group calculations IfLicenceNameContains ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' With this condition it is possible to calculate a single group only if the *License Name* of the software contains a certain string. Normally this is only used in encrypted CAL-files prepared by 2D for a specific customer. .. code-block:: none [MyCalc] ; Start of group IfLicenceNameContains(LicenceName) ; Condition: This calculation is only executed if the *License Name* of the software contains the searched string. ; Group calculations IfNotLicenceNameContains ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' This condition is the opposite of the one above. A single calculation group is only calculated if the *Licence Name* of the software does not contain a certain string. .. code-block:: none [MyCalc] ; Start of group IfNotLicenceNameContains(LicenceName) ; This calculation is only executed if the *License Name* of the software DOES NOT contain the searched string. ; Group calculations IfSpecValueIs ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' The calculation group is only calculated if a SpecSheet-entry is a certain value. .. code-block:: none [MyCalc] ; Start of group IfSpecValueIs(Group.Entry, SearchValue) ; This calculation is only executed if the *Group.Entry is the SearchValue ; Group calculations IfNotSpecValueIs ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' The calculation group is only calculated if a SpecSheet-entry is not a certain value. .. code-block:: none [MyCalc] ; Start of group IfNotSpecValueIs(Group.Entry, SearchValue) ; This calculation is only executed if the *Group.Entry is NOT the SearchValue ; Group calculations Substitution of place holders ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In CalcTool differnt placeholders can be used. .. important:: A place holder always starts with the “@” character The following for four kinds of place holders can be used for substitution: - :ref:`Special channels ` - :ref:`Pre-defined constants ` - :ref:`SpecSheet-Values ` - :ref:`Local and global variables ` .. important:: When executing a CAL file, the Preprocessor replaces all found special character with the respective parameters/channels .. _link_CalcTool_SpecialChannels: Special channels ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. figure:: /Images/CalcTool/SpecialChannels.png :scale: 80 % :align: center Special channels selection In the *Analyzer*, special channels can be defined. The advantage is that flexibility is increased when working with measurements where different channel names have been assigned to channels with the same purpose. A calculation file with fixed channel names could only be applied to certain measurements! With the special channels this problem is solved because the respective special channels inside the calculation files are replaced by the channels linked in the adjoining list by the Preprocessor. In the *Analyzer*, the adjacent *Special channels* list can be opened under the tab *Settings*. .. important:: Also <**SHIFT**> + <**s**> can be used. In this list the user can define the special channels for the measurement currently selected in the *Analyzer*. In addition to defined special channels, the user can also assign his own special channels. .. important:: The list can also be edited in the *Event.ini* via text editor .. important:: In Tab *User defined*, own special channels can be defined! There are two possibilities to select at special channels list: **Option 1** When in current event no channel suits the respective special channel this option can be chosen. .. figure:: /Images/CalcTool/SpecialChannels_None.png :scale: 100 % :align: center No channel can be linked to respective special channel .. important:: :ref:`Conditional execution ` leads to result FALSE! When a special channel is used in calculation file, and this option is used, the *CalcTool* will bring up **no** error, that no channel is selected at the respective special channel. .. important:: Option 1 is selected by the user when no channel can be linked to the respective special channel. **Option 2** When a channel suits the respective special channel then it can be linked here. .. figure:: /Images/CalcTool/SpecialChannels_Selected.png :scale: 100 % :align: center Channel linked to respective special channel .. important:: :ref:`Conditional execution ` leads to result TRUE! .. important:: This option is selected by the user when channel can be linked to the respective special channel. **Option 3** - Selected channel not available If a channel is selected, but currently not present in measurement, the special channel is automatically marked with the following symbol: .. figure:: /Images/CalcTool/SpecialChannels_NA.png :scale: 100 % :align: center Selected channel is not available in current measurement .. important:: :ref:`Conditional execution ` leads to result FALSE! .. attention:: This option can not be chosen by user! **Option 4** - Default setting When a special channel is used in calculation file, and this option is used, the *CalcTool* will bring up an error, that no channel is selected at the respective special channel. .. figure:: /Images/CalcTool/SpecialChannels_Empty.png :scale: 100 % :align: center Default setting when no channel is selected .. important:: :ref:`Conditional execution ` leads to an CalcTool error! .. attention:: This option can not be chosen by user! **Example:** .. figure:: /Images/CalcTool/SpecialChannels_FrontSusp.png :scale: 100 % :align: center Special channel Front_Susp set to channel #Sus_F Cal-File example: .. .. code-block:: none FrontSusp_F = F(@Front_susp, F(L_PHAMM3hz77)) ; Special Channel @Front\_Susp is called in CAL-file .. figure:: /Images/CalcTool/SpecialChannels_PreProc.png :scale: 100 % :align: center Preprocessor replaces Special channel @Front_Susp with linked channel #SUS_F **Frequently used special channels with description** +-------------------------+--------------------------------------------------------+ | **Special channel** | **Description** | +=========================+========================================================+ | Int\_Speed | Speed channel used for integration of speed | +-------------------------+--------------------------------------------------------+ | Drive\_RPM | Engine RPM | +-------------------------+--------------------------------------------------------+ | Drive\_Speed | Engine speed (for gear calculation when no Gear\_Nr) | +-------------------------+--------------------------------------------------------+ | Slip | Slip rear wheel | +-------------------------+--------------------------------------------------------+ | Gear\_Nr | Gear number | +-------------------------+--------------------------------------------------------+ | Throttle | Throttle-grip signal | +-------------------------+--------------------------------------------------------+ | Throttle\_E | Throttle butterfly position (drive by wire) | +-------------------------+--------------------------------------------------------+ | Front\_Susp | Signal of front suspension (Cars: front left) | +-------------------------+--------------------------------------------------------+ | Rear\_Susp | Signal of rear suspension (Cars: rear left) | +-------------------------+--------------------------------------------------------+ | Front\_SuspRight | Signal of front suspension (Cars: front right) | +-------------------------+--------------------------------------------------------+ | Rear\_SuspRight | Signal of rear suspension (Cars: rear right) | +-------------------------+--------------------------------------------------------+ | Acc\_Lat | Lateral acceleration | +-------------------------+--------------------------------------------------------+ | Acc\_Lon | Longitudinal acceleration | +-------------------------+--------------------------------------------------------+ | Banking | Banking of motorcycle | +-------------------------+--------------------------------------------------------+ | GPS\_Longitude | Longitudinal position | +-------------------------+--------------------------------------------------------+ | GPS\_Latitude | Latitudinal position | +-------------------------+--------------------------------------------------------+ | GPS\_Altitude | Altitude | +-------------------------+--------------------------------------------------------+ | GPSValid | Valid GPS-Signal | +-------------------------+--------------------------------------------------------+ | Brake\_Front | Pressure front brake | +-------------------------+--------------------------------------------------------+ | Brake\_Rear | Pressure rear brake | +-------------------------+--------------------------------------------------------+ | Steering\_Angle | Position signal of steering wheel | +-------------------------+--------------------------------------------------------+ | Yaw\_Rate | Yaw-Rate of vehicle | +-------------------------+--------------------------------------------------------+ | Mileage\_Speed | Speed channel used for determining the mileage | +-------------------------+--------------------------------------------------------+ .. _link_CalcTool_PredefinedConstants: Predefined constants ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' The following constants can be used in calculation files: +------------------+---------------------------------------------------+ | **Constant** | **Description** | +==================+===================================================+ | @PI | 3.145… | +------------------+---------------------------------------------------+ | @2PI | 6.283… | +------------------+---------------------------------------------------+ | @PI/2 | 1.571… | +------------------+---------------------------------------------------+ | @E | 2.71828 (Euler constant) | +------------------+---------------------------------------------------+ | @G | 9.80665 (Gravity constant) | +------------------+---------------------------------------------------+ | @LN2 | Natural logarithm of 2 | +------------------+---------------------------------------------------+ | @RAD2DEG | 180/PI constant to calculate radiant to degrees | +------------------+---------------------------------------------------+ | @DEG2RAD | PI/180 constant to calculate degrees to radiant | +------------------+---------------------------------------------------+ +---------------------+-----------------------------------+ | **Others** | **Description** | +=====================+===================================+ | @MainSamplingRate | Mainsamplingrate of measurement | +---------------------+-----------------------------------+ SpecSheet variables ^^^^^^^^^^^^^^^^^^^ How to use SpecSheet-Values as constants click :ref:`here `! .. _link_CalcTool_Variables: Variables ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' In *CalcTool* it is also possible to use global and local variables. .. attention:: Either global or local variables can be used! Local variables ''''''''''''''' Local variables are defined **inside a calculation file** in a group called [Variables]. .. important:: Local Variables can only be used inside respective calculation file! This group is located before each other calculation groups in the file. .. Beside values also channel names can be used as constant (e.g., when input channels are defined via Variables)! .. +-----------------+-----------------------+ | **Syntax** | **Meaning** | +=================+=======================+ | [Variables] | Start of group | +-----------------+-----------------------+ | Variable1=815 | Defining Variable 1 | +-----------------+-----------------------+ | Variable2=#Test | Defining Variable 2 | +-----------------+-----------------------+ .. important:: The call of the variables in the following code is again done via the character “@” **Example:** .. code-block:: none c1 = *(#c1 , @Variable1) ; Using @Variable1 for calculation --> #C1 * 815 c2 = *(#c2 , @Variable2) ; Using @Variable2 for calculation --> #C1 * #Test Global variables '''''''''''''''' Global variables must be defined in standalone VAR files. .. This VAR file can be created with a text editor. .. important:: Global Variables can be called from every calculation file! Within this file the variable definition is done in the same way as for local variables via the group [Variables]. +------------------------+--------------------+ | **Syntax** | **Meaning** | +========================+====================+ | {$V …\\Filename.VAR} | Include VAR-file | +------------------------+--------------------+ .. attention:: The Filename must contain the full path information! .. attention:: The created VAR-file must first be included **before the variables can be used in the actual calculation groups**! .. attention:: A VAR-file always contains only on group [Variables] .. attention:: The VAR-file entries can be accessed in CAL-file by using @ .. important:: For the path of file, placeholders can be used (see 3.3)! .. important:: Another predefined filename placeholder could be used only at global variables to load a variable file depending on the name of the current logger: will be replaced by the name of the logger with which the measurement was recorded {$V ….VAR} **Example:** Two-stage placeholder replacement How to recalculate the speed channel of a bike if the circumference of the tire was not set correctly before the measurement. In the following example the following features are used togehter: - SpecSheet Value - Global variables - Creating new channel - Overwrite originally recorded channel +--------------------+ |**SpecSheet entry:**| +====================+ | [Tire] | | | | Front=Soft05 | +--------------------+ +-----------------------------+ | **Tires.VAR:** | +=============================+ | [Variables] | | | | Soft05 = 1885 | | | | Hard05 = 1885 | | | | Another = 1885 | | | | M4124C = 1887 | | | | DefaultCircumference=1890 | +-----------------------------+ .. code-block:: none {$V \Tires.VAR} ; Include Tires.VAR from Event directory [SpeedRecalc] ; Defining group name C1 =/(#VFront, @DefaultCircumference) ; Global Variable: @DefaultCircumference” is replaced by Tires.VAR-Value 1890 --> Division of #V_Front and 1890 C2 =*(#C1, @Tire.Front) ; SpecSheet Variable: @Tire.Front --> @Soft05 --> 1885 Result = WORD(#C2) ; Creating new channel #SpeedRecalc defined by name of group in word-format [VFront] ; Defining group name IfExists(#SpeedRecalc) ; Execute group [VFront] only if channel #SpeedRecalc exists NewResult= Word(#SpeedRecalc, 0, 500) ; Convert the recalculated speed channel to word using the borders 0 and 500 km/h ; If the keyword “NewResult” is used, the calculated channel will replace an originally recorded channel. *Two-stage placeholder replacement:* .. figure:: /Images/CalcTool/CalcTool_Variables.png :scale: 100 % :align: center Preprocessor protocol The PreProcessor first replaces SpecSheet-Placeholder Tire.Front by Soft05. .. Therefore, the placeholder @Soft05 is created which is then also converted by the Preprocessor to the value 1885. *Channel properties* ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' In some cases, it is useful to use channel properties like sampling rate for calculation. These properties are replaced by their corresponding values before the calculation is started. *CalcTool* allows to use the following channel properties: +----------------+------------------------------------------------------------------------------+ | **Syntax** | **Meaning** | +================+==============================================================================+ | #CH.Rate | Sampling rate of the channel (i.e. 100 for a channel sampled with 100 Hz) | +----------------+------------------------------------------------------------------------------+ | #CH.DT | Sampling time of the channel (i.e. 0.01 for a 100 Hz channel) | +----------------+------------------------------------------------------------------------------+ | #CH.P1 | First of the three parameters of channel. Meaning depends on channel type | +----------------+------------------------------------------------------------------------------+ | #CH.P2 | Second of the three parameters of channel. Meaning depends on channel type | +----------------+------------------------------------------------------------------------------+ | #CH.P3 | Third of the three parameters of channel. Meaning depends on channel type | +----------------+------------------------------------------------------------------------------+ .. attention:: Parameters P1, P2 and P3 are only for 2D-internal use! *Example:* .. code-block:: none C1 = const(100, #V_Sat.Rate) * **Value**: Set value 100 of constant .. * **Rate**: Defines smapling rate to sampling channel rate as channel #V_Sat Mileage ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The 2D software structure makes it possible to record and document in the respective *SpecSheet* which mileage in kilometres various components have completed on the vehicle. .. important:: This functionality can be used for planning the maintenance and replacement intervals of components! .. admonition:: Addtional manual For more information about Mileage click :doc:`here `! Format of numeric parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some functions of *CalcTool* require one or more numbers as parameter. .. There are three different possibilities to write a numeric parameter: +---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Data type | Description | +===============+==============================================================================================================================================================================================+ | Decimal | The number is written using the usual syntax, i.e. 350 or 17.5. | | | | | | The decimal separator is independent of your computer’s language settings. Always use a *point* as decimal separator since the colon is used as parameter separator. | +---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Hexadecimal | This notation starts with “0x” or “0h” and is followed by hexadecimal digits (0...F); i.e. 0xFF or 0hFF for the decimal value of 255. Only integer numbers can be written in this notation | +---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Binary | This notation starts with “0b” and is followed by binary digits (0 and 1) i.e. 0b11111111 for the decimal value of 255. Only integer numbers can be written in this notation. | +---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ User interaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To make calculation files more flexible, CalcTool provides two functions to enable the user to enter data. .. important:: Commands are executed by the Preprocessor and thus values can be entered by user before complete calculation is executed! Entering a channel name ^^^^^^^^^^^^^^^^^^^^^^^ This function opens a dialog to ask the user for the name of a channel to use in further calculation. The user may choose from a list of channels available in the specific measurement. .. code-block:: none C1=EnterChannel(‘Text shown in dialog’) ; Opens a dialog to ask the user for a channel name. The text in the parameter is shown in the dialog. * **‘Text shown in dialog’**: The text in the parameter is shown in the dialog .. figure:: /Images/CalcTool/UserInteraction_ChannelName.png :scale: 60 % :align: center User interaction - channel name .. code-block:: none C1=EnterChannel(‘Text shown in dialog’, #CH) ; Opens a dialog to ask the user for a channel name with preselected channel. The text in the parameter is shown in the dialog. * **‘Text shown in dialog’**: The text in the parameter is shown in the dialog * **#CH**: Selected channel is preselected in user interaction dropdown menu .. figure:: /Images/CalcTool/UserInteraction_ChannelNamePre.png :scale: 60 % :align: center User interaction - channel name with preselected channel #V_Sat *Example:* The user is queried at execution of respective CAL-file to select a Video\_File\_Index-Channel for Dashware-export. #VideoFile\_Index\_1 is preselected. .. code-block:: none [Dialog_Camera] Camera = EnterChannel(Select camera for Dashware, #Video_file_Index) .. important:: The created channel (e.g. Camera) can be used like any other channel in following calculations .. attention:: When the user cancels the dialog, the calculation will stop at this line. Channels which were calculated in lines before will be stored, lines and groups after this line will be ignored. Entering a numeric value ^^^^^^^^^^^^^^^^^^^^^^^^ This function opens a dialog asking the user to enter a numeric value to use in further calculation .. code-block:: none C1=EnterValue(‘Text shown in dialog’) ; Opens a dialog to ask the user for a channel value. The text in the parameter is shown in the dialog. * **‘Text shown in dialog’**: The text in the parameter is shown in the dialog .. figure:: /Images/CalcTool/UserInteraction_ChannelValue.png :scale: 60 % :align: center User interaction - channel value - "0" is default value .. code-block:: none C1=EnterValue(‘Text shown in dialog’, Value) ; Opens a dialog to ask the user for a channel value with preselected value. The text in the parameter is shown in the dialog. * **‘Text shown in dialog’**: The text in the parameter is shown in the dialog * **‘Value**: Preselected value .. figure:: /Images/CalcTool/UserInteraction_ChannelValuePre.png :scale: 60 % :align: center User interaction - channel value with preselected value *Example:* The user is queried to select, which video should be used for Dashware-export. Value 1 is preselected. .. code-block:: none [Dialog_Video] C0 = EnterChannel(Select video for Dashware, 1) Video = Const(@C0, #Video_file_Index.Rate) .. important:: The dialog shows the text parameter of the function. The entered value is stored in a *constant* with the name which is given on the left side of the “=”. .. important:: The *constant* must be called in the following calculations with character “@” (e.g. @C0) .. attention:: When the user cancels the dialog without entering a value, the calculation will stop at this line. Channels which were calculated in lines before will be stored, lines and groups after this line will be ignored