%% Read Data from MDF-Files with Applied Conversion Rules
% This example shows you how to read channel data applying conversion rules from an MDF-file and configure different reading options in MATLAB.
%
%% Introduction to ASAM MDF Conversion Rules
% According to the ASAM MDF standard, a data value encoded in the MDF channel is denoted as a raw value. It can be converted to a physical, engineering unit value using a conversion rule that describes the data. Conversion rules are the methods defined at the channel level to convert raw values to physical values.
% ASAM MDF V4.2.0 supports the following conversion rules:
%     No Conversion
% CC_Type 0: Identity (“1:1”) conversion
%     Numeric to Numeric Conversions
% CC_Type 1: Linear conversion
% CC_Type 2: Rational conversion formula
% CC_Type 3: Algebraic conversion
% CC_Type 4: Value to value tabular look-up with interpolation
% CC_Type 5: Value to value tabular look-up without interpolation
% CC_Type 6: Value range to value tabular look-up
%     Numeric to Text Conversions
% CC_Type 7: Value to text/scale conversion tabular look-up
% CC_Type 8: Value range to text/scale conversion tabular look-up
%     Text to Numeric Conversion
% CC_Type 9: Text to value tabular look-up
%     Text to Text Conversion
% CC_Type 10: Text to text tabular look-up
%     Other Conversion
% CC_Type 11: Bitfield text table
% Vehicle Network Toolbox™ provides the functionality to read your desired data from the MDF-file with different Conversion options. The allowed options are:
% Numeric — Apply only numeric to numeric conversions (CC_Type 1-6). Data with other conversion rules are read as raw values.
% None — Do not apply any conversion. All data are read as raw values.
% All — Apply all numeric and text conversions (CC_Type 1-10). All data are read as physical values.
% Note that if there is an identity conversion (CC_Type 0), or a none conversion (no conversion rule) in the channel, the data are read as raw values regardless of which Conversion option is specified.
%
%% Open the MDF-File
% Open access to an MDF-file using the mdf function. The object mdfObj has the property Conversion with the default value Numeric.

mdfObj = mdf("MDF_Conversion_Example.mf4")

% Use the channelList function to view the list of channels available in mdfObj.

channelList(mdfObj)

%
%% Conversion Property and Conversion Name-Value Pair
% You can choose a Conversion option to apply when reading data from an MDF-file in MATLAB. You specify the option in either of the following ways:
%  Set the Conversion property of the MDF object and call the read function.
%  Specify a Conversion name-value pair when calling the read function.
% View the details about the channel Engine temperature in channel group 1. The output shows that it has Linear conversion (CC_Type 1).

mdfObj.ChannelGroup(1).Channel(2)

% You can set the Conversion property of the mdfObj to be Numeric and read data from channel Engine temperature in channel group 1.

mdfObj.Conversion = "Numeric"
dataPropNum = read(mdfObj, 1, "Engine temperature")

% You can also read data with the name-value pair Conversion, None. Note that the Conversion name-value pair has a higher priority than the Conversion property, which means the name-value pair is applied when the values are different.

dataNameValueNone = read(mdfObj, 1, "Engine temperature", "Conversion", "None")

% Using the Conversion name-value pair does not change the Conversion property of mdfObj. The Conversion property value of mdfObj after reading data with a name-value pair is still Numeric.

mdfObj.Conversion

%
%% Read Data with Different Conversion Options on Numeric to Numeric Conversions
% The following code shows how to read your desired data from a channel with a numeric to numeric conversion. The channel Engine temperature has Linear conversion (CC_Type 1) and it is chosen to represent the reading behavior of numeric to numeric conversions (CC_Type 1-6).
% Read data with the name-value pair Conversion, Numeric. In this case, Linear conversion is applied when reading data because the Numeric option supports numeric to numeric conversions. The physical data are returned and the physical numeric data have data type double.

dataLinearNum = read(mdfObj, 1, "Engine temperature", "Conversion", "Numeric")
class(dataLinearNum.EngineTemperature)

% Read data with the name-value pair Conversion, None. In this case, Linear conversion is not applied when reading data because the None option does not apply any conversion. Raw data are returned with the original data type, which is an int32.

dataLinearNone = read(mdfObj, 1, "Engine temperature", "Conversion", "None")
class(dataLinearNone.EngineTemperature)

% Read data with the name-value pair Conversion, All. In this case, Linear conversion is applied when reading data because the All option supports all numeric and text conversions. The physical data are returned and the physical numeric data have data type double.

dataLinearAll = read(mdfObj, 1, "Engine temperature", "Conversion", "All")
class(dataLinearAll.EngineTemperature)

%
%% Read Data with Different Conversion Options on Numeric to Text Conversions
% The following code shows how to read your desired data from a channel with a numeric to text conversion. The channel Gear position has ValueToText conversion (CC_Type 7) and it is chosen to represent the reading behavior of numeric to text conversions (CC_Type 7-8).
% View the details about the channel Gear position in channel group 1. The output shows that it has ValueToText conversion.

mdfObj.ChannelGroup(1).Channel(3)

% Read data with the name-value pair Conversion, Numeric. In this case, ValueToText conversion is not applied when reading data because the Numeric option supports only numeric to numeric conversions. The raw data are returned with the original data type, which is an int8.

dataV2TNum = read(mdfObj, 1, "Gear position", "Conversion", "Numeric")
class(dataV2TNum.GearPosition)

% Read data with the name-value pair Conversion, None. In this case, ValueToText conversion is not applied when reading data because the None option does not apply any conversion. Raw data are returned with the original data type, which is an int8.

dataV2TNone = read(mdfObj, 1, "Gear position", "Conversion", "None")
class(dataV2TNone.GearPosition)

% Read data with the name-value pair Conversion, All. In this case, ValueToText conversion is applied when reading data because the All option supports all numeric and text conversions. The physical data are returned and the physical text data have data type char.

dataV2TAll = read(mdfObj, 1, "Gear position", "Conversion", "All")
class(dataV2TAll.GearPosition{1})

%
%% Other Conversion Examples
% There are some other channels in the mdfObj. The channels Ambient temperature, Windshield wiper speed level, and Fault code have conversions None, TextToValue, and TextToText, respectively. You can try to read these channels with different Conversion options.
% View the details about the channel Ambient temperature in channel group 1. The output shows that it has None conversion.

mdfObj.ChannelGroup(1).Channel(1)

% View the details about the channel Windshield wiper speed level in channel group 1. The output shows that it has TextToValue conversion.

mdfObj.ChannelGroup(1).Channel(4)

% View the details about the channel Fault code in channel group 1. The output shows that it has TextToText conversion.

mdfObj.ChannelGroup(1).Channel(5)

%
%% Close the File
% Close access to the MDF-file by clearing the variable from the workspace.

clear mdfObj

%
% Copyright 2020-2021 The MathWorks, Inc.