:Revision=2
:html
<<
128.180
Curve-Object|Curve
--
The IP-Object Curve is used to access to analog measurement curves of the curve-set.

At the moment, there is only one curve set. But the syntax has been defined to allow more than one curve set.  Therefore, the first parameter in each command is always 1 for the moment.

The following applies for all the enquiries:
If the curve is not available or if a searched event cannot be found, then the error value -999999999 is returned.

<!REM>
Hint: 
The Curve Monitor may be shown with the <a href="128.10.3.16">System Action</a> 2020.
<!TXT>
<!CODE>
System.Action.Trigger (2020);
<!TXT>

Example how to show 2 simple curves inside the curve monitor
<!CODE>
var
  Curve1 : vector;
  Curve2 : vector;
  Loop   : real;

step

// Create the first measurement curve
  Curve1 :=[];
  for Loop := 1 to 1000 step 1 do begin
    Curve1 := Curve1 + [(Math.Sin( Loop / 100 )/25) ];
  end;

// Create the second measurement curve
  Curve2 :=[];
  for Loop := 1 to 1000 step 1 do begin
    Curve2 := Curve2 + [Math.Sin ( Loop / 10) * 1/ Loop];
  end;

// Set the names for the X and Y axes
  Curve.Scale.SetText ( 1, 1, 'Volt' );
  Curve.Scale.SetText ( 1, 0, 'Sample' );
  Curve.Name( 1, 'Curve 1', 'Curve 2' );

// Set the curve names
  Curve.Setup ( 1, Len ( Curve1 ), Curve1, Curve2 );

// Show the curve Monitor
  Action.Trigger ( 2020, 'SHOW' );

...

end.
<!TXT>

>>
<<
128.180.1
Functions of the  Curve-Object|Functions
--
>>
<<
128.180.1.1
Curve.Find|Find
!128.180.2.1
--
<!DEF>
function <!TW>Curve.Find (rSet, rCurve, rWhat, rVolt : real [; rHoldTimeMS : real]) : real;
<!TXT>
Returns the time (in ms from start of curve) when the <!PW>rSet/<!PW>rCurve curve crosses the <!PW>rVolt voltage line.
If the requested event is not found, then -999999999 is returned.

 <!PW>rWhat selects, whether the curve should cross the voltage falling (0) or rising (1).

If <!PW>rHoldTimeMS is specified, then the curve must remain for the specified time (ms) under, resp. above the given voltage. Thus, short peaks can be filtered.

Only the selected part (<!RW>Curve.Select) of the curve is evaluated. However, the returned time refers to the entire curve (first sample = 0).

Example:
<!CODE>  
nTime:=Curve.Find (1, 1, 1, 4.5, 10);
<!TXT>
Searches for the time (the edge), when curve 1 of set 1 rises above 4.5 Volt and remains there for at least 10 ms.
>>
<<
128.180.1.2
Curve.MinValue|MinValue
--
<!DEF>
function <!TW>Curve.MinValue (rSet, rCurve : real) : real;
<!TXT>
Returns the minimum value of the curve <!PW>rSet/<!PW>rCurve in Volt.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>
<<
128.180.1.3
Curve.MaxValue|MaxValue
!128.180.2.1
!128.180.1.2
--
<!DEF>
function <!TW>Curve.MaxValue (rSet, rCurve : real) : real;
<!TXT>
Returns the maximum value of the curve <!PW>rSet/<!PW>rCurve in Volt.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>
<<
128.180.1.4
Curve.AvgValue|AvgValue
!128.180.2.1
--
<!DEF>
function <!TW>Curve.AvgValue (rSet, rCurve : real) : real;
<!TXT>
Returns the average value (arithmetic average of all samples) of the curve <!PW>rSet/<!PW>rCurve in Volt.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>
<<
128.180.1.5
Curve.RMSValue|RMSValue
!128.180.2.1
--
<!DEF>
function <!TW>Curve.RMSValue (rSet, rCurve : real) : real;
<!TXT>
Returns the effective value (square average of all samples / Root Mean Square) of the curve <!PW>rSet/<!PW>rCurve in Volt.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>
<<
128.180.1.6
Curve.Value|Value
--
<!DEF>
function <!TW>Curve.Value (rSet, rCurve, rTimeMS : real) : real;
<!TXT>
Returns the value of the curve <!PW>rSet/<!PW>rCurve at the nTimeMS moment in Volt.

Returned value is the value of the next sample which follows at that moment.
>>
<<
128.180.1.7
Curve.MeasRiseTime|MeasRiseTime
!128.180.2.1
--
<!DEF>
function <!TW>Curve.MeasRiseTime (rSet, rCurve : real [; rHoldTimeMS : real]) : real;
<!TXT>
Calculates the rising time of the first edge of curve <!PW>rSet/<!PW>rCurve which crosses the threshold value determined with SetThreshold. (time until reaching the threshold value)

If the requested event is not found, then -999999999 is returned.

If <!PW>rHoldTimeMS is specified, then the curve must remain for the specified time (ms) above the threshold value. Hereby, there is the possibility to filter short peaks.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>
<<
128.180.1.8
Curve.MeasFallTime|MeasFallTime
!128.180.2.1
--
<!DEF>
function <!TW>Curve.MeasFallTime (rSet, rCurve : real [; rHoldTimeMS: real]) : real;
<!TXT>
Calculates the falling time of the first edge of curve <!PW>rSet/<!PW>rCurve which crosses the threshold value defined with SetThreshold. (time until reaching the threshold value)

If the requested event is not found, then -999999999 is returned.

If <!PW>rHoldTimeMS is specified, then the curve must remain for the specified time (ms) above the threshold value. Hereby, there is the possibility to filter short peaks.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>
<<
128.180.1.9
Curve.MeasLowTime|MeasLowTime
!128.180.2.1
--
<!DEF>
function <!TW>Curve.MeasLowTime (rSet, rCurve : real [; rHoldTimeMS: real]) : real;
<!TXT>
Calculates the time (in ms) for which the curve <!PW>rSet/<!PW>rCurve remains under the threshold defined with SetThreshold for the first time.

The threshold value is expected to be intersected first from up to down and then back from down to up.

If the requested event is not found, then -999999999 is returned.

If <!PW>rHoldTimeMS is specified, then the curve must remain for the specified time (ms) under resp. above the threshold value. Hereby, there is the possibility to filter short peaks.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>

<<
128.180.1.10
Curve.MeasHighTime|MeasHighTime
!128.180.2.1
--
<!DEF>
function <!TW>Curve.MeasHighTime (rSet, rCurve : real [; rHoldTimeMS: real]) : real;
<!TXT>
Calculates the time (in ms) for which the curve <!PW>rSet/<!PW>rCurve remains above the threshold defined with SetThreshold for the first time.

It is expected that the threshold value is intersected from down to up first and then back from up to down.

If the requested event is not found, then -999999999 is returned.

If <!PW>rHoldTimeMS is specified, then the curve must remain for the specified time (ms) below resp. above the threshold value. Hereby, there is the possibility to filter short peaks.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>

<<
128.180.1.11
Curve.MeasLowHighTime|MeasLowHighTime
!128.180.2.1
--
<!DEF>
function <!TW>Curve.MeasLowHighTime (rSet, rCurve : real [; rHoldTimeMS: real]) : real;
<!TXT>
Calculates the time (in ms) needed by the curve <!PW>rSet/<!PW>rCurve for a certain period. (based on the threshold value defined with SetThreshold).

The threshold value is expected to be intersected first from up to down, then back from down to up and then once again from up to down.

If the required event is not found, then -999999999 is returned.

If <!PW>rHoldTimeMS is specified, then the curve must remain for the specified time (ms) below resp. above the threshold value. Hereby, there is the possibility to filter short peaks.

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.
>>
<<
128.180.1.12
Curve.BaseValue|BaseValue
!128.180.1.13
!128.180.2.1
--
<!DEF>
function <!TW>Curve.BaseValue (rSet, rCurve: real) : real;
<!TXT>
This value is reasonable only if the curve reperesents a square-wave signal.

It returns the lower setteled value of the curve (the value after the settling time of the square-wave signal). 

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.

To calculate the BaseValue a histogram is calculated first built over the value range of the curve. This histogram indicates the propability of a certain voltage value in the curve. If the shape of the curve is rectangular, the voltage values of the two setteled phases occur more frequently than the voltage values of the edges or the possible voltage-spikes. Afterwards, the histogram is folded with a triangle-curve, where the width of the triangle is one percent of the value range (similar to a smoothing with a current median, whereby the middle of the averaged range is emphasized). In the next step, the most common voltage value in the lower half or the histogram is searched. This voltage is the BaseValue.
The same search is done in the upper half to get the TopValue. So, when TopValue or BaseValue is calculated, the other one is available too. Because these calculations are not very fast, they only are done if required.
>>
<<
128.180.1.13
Curve.TopValue|TopValue
!128.180.1.12
!128.180.2.1
--
<!DEF>
function <!TW>Curve.TopValue (rSet, rCurve: real) : real;
<!TXT>
This value is reasonable only if the curve represents a square-wave signal.

It returns the upper setteled value of the curve (the value after the settling time of the square-wave signal). 

Only the selected part of the curve (<!RW>Curve.Select) will be evaluated.

For comments regarding the calculation of the <!RW>TopValue see <!RW>BaseValue.
>>

<<
128.180.1.14
Curve.FFT|FFT
--
<!DEF>
function <!TW>Curve.FFT (rSet, rCurve: real) : vector;
<!TXT>
Calculate the FFT spectrum off the curve <!PW>rSet / <!PW>rCurve. The first Curve has the index 0.

<!CODE>
const
  rDuration    =     1;
  rSampleRate  =  8192;
  rFrequencyA  =  1000;
  rAmplitudeA  =    10;

  rFrequencyB  =  1500;
  rAmplitudeB  =     5;

var
  rIndex  : real;
  vCurveA : vector;
  vCurveB : vector;

  vCurveS : vector;

  vFFT : vector;

step
  for rIndex := 1 to rSampleRate * rDuration do begin
    vCurveA [rIndex] := math.Sin ( math.DegToRad ( rFrequencyA * 360 * rIndex / rSampleRate )) * rAmplitudeA;
    vCurveB [rIndex] := math.Sin ( math.DegToRad ( rFrequencyB * 360 * rIndex / rSampleRate )) * rAmplitudeB;
    vCurveS[rIndex] := vCurveA [rIndex] + vCurveB [rIndex];
  end;

  Curve.Setup ( 1, rSampleRate, vCurveA, vCurveB, vCurveS );

  DateTime.Delay ( 2000 );

  vFFT := Curve.FFT ( 1, 2 );

  Curve.Setup ( 1, 2000 * Len ( vFFT ) / rSampleRate, vFFT );
  Curve.Scale.SetText ( 1, 0, '[Hz]');
  Curve.Scale.SetText ( 1, 1, 'Spectrum');

end.
<!TXT>
>>

<<
128.180.1.15
Curve.FFTFreqValue|FFTFreqValue
--
<!DEF>
function <!TW>Curve.FFTFreqValue (rSet, rCurve: real) : real;
<!TXT>
Calculates the base frequency off the curve <!PW>rSet / <!PW>rCurve. The first Curve has the index 0.
>>

<<
128.180.1.16
Curve.FFTTHDAllValue|FFTTHDAllValue
--
<!DEF>
function <!TW>Curve.FFTTHDAllValue (rSet, rCurve: real) : real;
<!TXT>
Calculates the distortion factor for all harmonics off the curve <!PW>rSet / <!PW>rCurve. The first Curve has the index 0.
>>

<<
128.180.1.17
Curve.FFTTHDEvenValue|FFTTHDEvenValue
--
<!DEF>
function <!TW>Curve.FFTTHDEvenValue (rSet, rCurve: real) : real;
<!TXT>
Calculates the distortion factor for all even harmonics off the curve <!PW>rSet / <!PW>rCurve. The first Curve has the index 0.
>>

<<
128.180.1.18
Curve.FFTTHDOddValue|FFTTHDOddValue
--
<!DEF>
function <!TW>Curve.FFTTHDOddValue (rSet, rCurve: real) : real;
<!TXT>
Calculates the distortion factor for all odd harmonics off the curve <!PW>rSet / <!PW>rCurve. The first Curve has the index 0.
>>

<<
128.180.2
Procedures of the Curve-Object|Procedures
--
>>

<<
128.180.2.1
Curve.Select|Select
--
<!DEF>
procedure <!TW>Curve.Select (rSet, rFromMS : real [; rToMS: real]);
<!TXT>
Determines, which part of the curve in the curve set <!PW>rSet is evaluated by later opratiomns. This setup will be applied for all the curves in the curve set.

If only <!PW>rFromMS is given, only the samples after this point in time are evaluated.

So, after the command <!RW>Curve.Select (1, 2) the first 2 ms of the measurement will be ignored.

If <!PW>rToMS is specified too, then only the samples between these two moments are evaluated.

So, after the command <!RW>Curve.Select (1, 2, 3) the samples which have been taken within the period from 2 ms to 3 ms after the start of the measurement process are evaluated. (<!PW>rToMS mus be greater than <!PW>rFromMS)

Directly after the measurement of a curve set, the entire curve is selected. This corresponds to the call of the command <!RW>Curve.Select (1, 0).
>>

<<
128.180.2.2
Curve.Smooth|Smooth
--
<!DEF>
procedure <!TW>Curve.Smooth (rSet, rCurve, rToCurve, rMethod, rSamples : real);
<!TXT>
Smoothes the curve <!PW>rSet/<!PW>rCurve with the method selected by <!PW>rMethod over <!PW>rSamples value. The obtained curve is saved in <!PW>rSet/<!PW>rToCurve. <!PW>rCurve and <!PW>rToCurve may be identical. If <!PW>rToCurve was not existing yet, then it will be created.

 <!PW>rMethod may take the following values:
<!STBL>
<!+>rMethod<!+>Method<  !>
<!c>1<!>Calculates a variable median over the specified number of samples . All the samples are equally weighted (corresponds to the folding of the curve with square-wave impuls with a width of rSamples and area 1)<!>
<!c>2<!>Calculates a variable median over the specified number of samples, where the samples closer to the center are more strongly weighted (corresponds to the folding of the curve with a triangular impuls with a width of rSamples and area 1)<!>
<!ETBL>

Method 1 is faster.

As a matter of principle, the first and the last <!PW>rSamples values of the curve are not smoothed with the entire number of samples and should be unselected with <!RW>Curve.Select.
>>

<<
128.180.2.3
Curve.SetThreshold|SetThreshold
--
<!DEF>
procedure <!TW>Curve.SetThreshold (rSet, rCurve : real; <!RW>ABS|<!RW>REL; rLow, rMid, rHigh : real);
<!TXT>
Sets the three threshold values for the curve <!PW>rSet/<!PW>rCurve; these threshold values are used for evaluations with the MEASxxx-Routines.

 <!PW>rLow determines the lower threshold value
 <!PW>rMid determines the medium threshold value
 <!PW>rHigh determines the upper threshold value

For the calculation of the rise- and / or fall time the lower and the upper threshold values are used.

The medium threshold value is used to calculate the Low- /High- /LowHigh-Time.

If <!RW>ABS is specified, then the <!PW>rLow/<!PW>rMid/<!PW>rHigh values are absolute voltage values in Volts.
If <!RW>REL is specified, then the <!PW>rLow/<!PW>rMid/<!PW>rHigh values are relative values expressed as percentage (0..100) based on the range between the minimum- and maximum value of the curve in the range established via <!RW>Curve.Select.

<!RW>ABS can be replaced with 0 and <!RW>REL can be replaced with 1.
>>
<<
128.180.2.3.1
Curve.SetThreshold.Low|Low
--
<!DEF>
procedure <!TW>Curve.SetThreshold.Low (rSet, rCurve : real; <!RW>ABS|<!RW>REL; rValue : real);
<!TXT>
Sets the lower threshold value for the curve <!PW>rSet/<!PW>rCurve; this threshold value is used for the evaluations with the MEASxxx-Routines.

This threshold value is used for the calculation of the rise- and / or fall time.

If <!RW>ABS is specified, then the value for <!PW>rValue is an absolute voltage value in Volts.
If <!RW>REL is specified, then the value for <!PW>rValue is a relative value expressed as percentage (0..100) based on the range between the minimum- and maximum value of the curve in the range established via <!RW>Curve.Select.

<!RW>ABS can be replaced with 0 and <!RW>REL can be replaced with 1.
>>
<<
128.180.2.3.2
Curve.SetThreshold.Mid|Mid
--
<!DEF>
procedure <!TW>Curve.SetThreshold.Mid (rSet, rCurve : real; <!RW>ABS|<!RW>REL; rValue : real);
<!TXT>
Sets the medium threshold value for the curve <!PW>rSet/<!PW>rCurve; this threshold value is used for the evaluations with the MEASxxx-Routines.

This threshold value is used to determine the Low-/High-/LowHigh-Time.

If <!RW>ABS is specified, then the value for the <!PW>rValue is an absolute voltage value in Volts.
If <!RW>REL is specified, then the value for the <!PW>rValue is a relative value expressed as percentage (0..100) based on the range between the minimum- and maximum value of the curve in the range established via <!RW>Curve.Select.

<!RW>ABS can be replaced with 0 and <!RW>REL can be replaced with 1.
>>
<<
128.180.2.3.3
Curve.SetThreshold.High|High
--
<!DEF>
procedure <!TW>Curve.SetThreshold.High (rSet, rCurve : real; <!RW>ABS|<!RW>REL; rValue : real);
<!TXT>
Sets the upper threshold value for the curve <!PW>rSet/<!PW>rCurve; this threshold value is used for the evaluations with the MEASxxx-Routines.

This threshold value is used for the calculation of the rise- and / or fall time.

If <!RW>ABS is specified, then the value for <!PW>rValue is an absolute voltage value in Volts.
If <!RW>REL is specified, then the value for <!PW>rValue is a relative value expressed as percentage (0..100) based on the range between the minimum- and maximum value of the curve in the range established via <!RW>Curve.Select.

<!RW>ABS can be replaced with 0 and <!RW>REL can be replaced with 1.
>>
<<
128.180.2.4
Curve.Setup|Setup
--
<!DEF>
procedure <!TW>Curve.Setup (rSet, rFrequency : real; vData : vector [; vData : vector ... ]);
<!TXT>
Tranfers data from one or more vectors into a curve set of the curve object. The data already existing in the curve set is lost. Each vector creates a separate curve. Therefore the vectors should have the same number of elements (though this is not mandatory). The elements of each vectors are considered to be distributed equidistantly on the complete X-axis. A maximum of 100 vectors (=curves) can be defined.

 <!PW>rFrequency specifies the frequency of the sampled data (in Hz). The curve object calculates automatically the label of the X-axis in [ms]. If another unit system is wished, it must be converted:
<!CODE>
nFrequency := (NumberOfPoints-1)/(FinalXValue-FirstXValue)*1000
<!TXT>

All the values which are calculated with the Meas...Time routines or are used in Select, use this frequency!
>>
<<
128.180.2.5
Curve.Scale|Scale
--
>>
<<
128.180.2.5.1
Curve.Scale.Offset|Offset
--
<!DEF>
procedure <!TW>Curve.Scale.Offset (rSet, rScaleNr, rOffset : real);
<!TXT>
Shifts the zero point of the X-axis to the selected Offset value.

This is possible only for the X-axis; therefore <!PW>rScaleNr must be 0.


 <!PW>rScaleNr selects the axis
<!STBL>
<!+>nScaleNr<!+>Axis<!+>
<!c>0<!>X-Axis<!>
<!ETBL>

All the values which are calculated with the Meas...Time routines or are used in Select, take in cosinderation the Offset!
>>
<<
128.180.2.5.2
Curve.Scale.SetText|SetText
--
<!DEF>
procedure <!TW>Curve.Scale.SetText (rSet, rScaleNr : real; sText : string);
<!TXT>
Modifies the label of an axis.


 <!PW>rScaleNr selects the axis
<!STBL>
<!+>nScaleNr<!+>Axis<!+>
<!c>0<!>X-Axis<!>
<!c>1<!>Y-Axis<!>
<!ETBL>

 <!PW>sText is the text used for the labelling. If <!PW>sText contains a part in squared brackets "[xxx]", this part is used as measurement unit for the measurement segment of the label.
>>
<<
128.180.2.6
Curve.Add|Add
--
<!DEF>
procedure <!TW>Curve.Add (rSet, rSourceCurve, rTargetCurve, rValue : real);
<!TXT>
Adds <!PW>rValue to each separate point of the <!PW>rSourceCurve curve in the curve set <!PW>rSet and stores the result in the curve <!PW>rTargetCurve. Thus the curve is shifted with <!PW>rValue. <!PW>rSourceCurve and <!PW>rTargetCurve can be identical. If <!PW>rTargetCurve is not available yet, then the curve is added to the curve set.
>>
<<
128.180.2.7
Curve.Abs|Abs
--
<!DEF>
procedure <!TW>Curve.Abs (rSet, rSourceCurve, rTargetCurve : real);
<!TXT>
Converts the values of each separate point of the curve <!PW>rSourceCurve in the curve set <!PW>rSet into the absolute value (removes the sign) and stores the result in the curve <!PW>rTargetCurve. Thus the points below the X-axis are quasi folded into the upper half. <!PW>rSourceCurve and <!PW>rTargetCurve can be identical. If <!PW>rTargetCurve is not available yet, then the curve is added to the curve set.
>>
<<
128.180.2.8
Curve.Name|Name
--
<!DEF>
procedure <!TW>Curve.Name (rSet : real [; sName1 : string [; sName2 : string [; sNameN : string ...]]]]);
<!TXT>
Defines the name of a the curves of the curve set <!PW>rSet. These names are used in the curve monitor to label the data.

The first string is the name of the first curve, the secons string is the name of the second curve and so on.

If a string is empty (''), the name of the curve will not be changed.

If there are fewer strings than curves, the names of the 'orphaned' curves will not be changed.

If there are more string than curves, the surplus strings will be ignored.

A call without any string:
<!CODE>
Curve.Name (1);
<!TXT>
will remove any user defines curve name and use the default curve names.
>>
<<
128.180.2.9
Curve.Color|Color
!128.154.9
--
<!DEF>
procedure <!TW>Curve.Color (rSet : real; vColors : vector);
<!TXT>
Defines the colors of the curves in the curve monitor.

The first element of the vector is the color of the first curve, the second element of the vector is the color of the second curve, and so on.

The elements may be RGB-Triple or DOS-color codes. A value of -1 doesn't change the color.

If there are fewer elements strings than curves, the colors of the 'orphaned' curves will not be changed.

If there are more elements than curves, the surplus elements will be ignored.

A call with an empty vector:
<!CODE>
Curve.Color (1, []);
<!TXT>
will remove any user defines curve colors and use the default curve colors.
>>

<<
128.180.2.10
Curve.Save|Save
!128.180.2.11
--
<!DEF>
procedure <!TW>Curve.Save (rSet : real; sFileName : string);
<!TXT>
Stores the curve set <!PW>rSet in in the file <!PW>sFileName. The default directory ist the typedata directory of the current loaded type. The default extension is .cst.
>>

<<
128.180.2.11
Curve.Load|Load
!128.180.2.10
--
<!DEF>
procedure <!TW>Curve.Load (rSet : real; sFileName : string);
<!TXT>
Loads the curve data in the file <!PW>sFileName to the curve set <!PW>rSet. The default directory ist the typedata directory of the current loaded type. The default extension is .cst.
>>
