dScope Series III Scripting and automation

Exporting dScope Traces

There are several ways of exporting or retrieving data from a dScope trace. Some are for graphical exports, some are for numerical data. The various options are listed below:

Save trace to dScope trace file
dScope can save its traces to file and re-load them into the trace window. Saving a trace in this way is very efficient as the trace file is small and contains all the data necessary to retrieve the trace points at a later date. From a script this is achieved by firstly selecting the trace to be saved, and then saving it with a defined file name. In the example below, the script gets the first FFT trace it finds on channel A, then sets the trace title and a comment before saving the trace as "example.tra". The .tra file name extension will be added automatically if none is specified. If no path is set, the file will be saved in the dScope traces folder - this is normally a subfolder of the dScope installation folder simply called "traces", but can be set elsewhere in the Options panel, or using the Options.OPT_TracesFolder automation property. By default the dScope installation folder is C:\Program Files\Prism Sound\dScope Series III. To save to any other folder, simply define the full path along with the file name.

    sTraceID = TraceWindow.TW_GetFirstTraceOfType(TRACETYPE_FFT, CHANNEL_A)
    TraceWindow.TW_GraphTitle = "Graph title goes here"
    TraceWindow.TW_GraphComment = "Graph Comment goes here"
    bRet = Trace.TRACE_SaveTrace("example")

Get trace values directly
There are occasions when you might want to be able to read the values from a sweep or any other trace directly. These values can be retrieved from the trace with full precision so it is a useful way of getting accurate measurement data fast. As in the previous example, the first thing to do is define which trace you want to get the values from. In the example below, we are getting the sweep that comes from the first sweep result on channel A. If this call is successful, it will return the trace ID (an integer). It returns TRACE_NULL_ID if no matching trace can be found. The script checks that a trace has been found, and then proceeds to get the X and Y values for the whole trace into a couple of arrays dXValue() and dYValue(). In this example we have shown how to set up these arrays by intitially setting them as dimensionless, and then "ReDimensioning" (ReDim) them when we know how many points we will need in order to be able to hold all the trace points. In practice it would be better not to ReDim the arrays every time you use them, but it is shown this way for simplicity.

    'define the arrays which will hold the X and Y values
    Dim dXValue()
    Dim dYValue() 

    'retrieve the trace you want to get data from
    sTraceID = TraceWindow.TW_GetFirstTraceOfType(TRACETYPE_SWEEP1, CHANNEL_A)
    
    'check whether we got a valid trace
    If sTraceID <> TRACE_NULL_ID then 'we have the trace
    
    	'get the number of points in the trace and re-dimension the arrays
    	iTracePoints = Trace.TRACE_GetNumPoints()
    	ReDim dXValue(iTracePoints)
    	ReDim dYValue(iTracePoints)
    	
    	'go through each of the trace points, getting the values into the arrays
    	For i = 0 to iTracePoints - 1
    		dYValue(i)  = Trace.TRACE_GetYValueAt(i)
    		dXValue(i)  = Trace.TRACE_GetXValueAt(i)
    	Next
    	
    End If

You can retrieve trace data from most kinds of trace in this way, but it should be noted that for the FFT traces and Scope traces where there can be many thousands of trace points, it may be faster to retrieve the FFT buffer or the Sample Buffer directly than attempt to read the values from the trace which will be quite slow. See the dScope Help documentation or Scripting Manual on the FFTD_GetBuffer method for more information on retrieving buffers.

Copy graph to clipboard
This option allows us to copy the Trace Window as a graphic to the Windows Clipboard from where it can be used by other Windows applications. In the example below, we have selected the Channel A trace window and copied it to the Windows Clipboard. The Trace window must be open on the current Page for this method to work, and if exporting both channels A and B, both channels must be shown on the same View.

    bRet = TraceWindow.TW_CopyToClipboard(CHANNEL_A)

Export the graph to file
dScope can export graphs in a number of graphical formats. These can be used to generate reports including web/HTML based formats. In the example below, the script first sets the graph title and comment, then exports the channel A trace window to a file called "filename.png". This file can then be used in a word processor document or web page etc.

    TraceWindow.TW_GraphTitle = "Graph title goes here"
    TraceWindow.TW_GraphComment = "Graph Comment goes here"
    bRet = TraceWindow.TW_Export(CHANNEL_A, "filename.png" )

The Trace window must be open on the current Page for this method to work, and there must not be a Print Preview or Export Preview window open. The graph that is exported depends on the channel that is specified. There are three options: CHANNEL_A exports traces from the channel A view, CHANNEL_B exports traces from the channel B view, and, if the trace window is set to show "All traces in one view", you can export Channel A and B traces in one go by using the CHANNEL_BOTH option.

If a file name only is specified, then the dScope will save the file in the folder specified in the Options dialogue box for Graph exports (normally this is the "graph exports" folder, a subfolder of the dScope installation folder.) - it can be saved in other locations by specifying the full path along with the name. The graph export options such as whether to display the graph title, comments, legend etc, should be set in the dScope user interface and saved in the configuration prior to exporting the graph. If the file name extension is not set or is not valid, the graph will be exported as a Windows Enhanced Metafile (EMF). Other formats are possible by specifying the appropriate file name extension. The supported formats are as follows:

emf: Windows Enhanced Metafile.
bmp: 24-bit colour Bitmap file.
jpg: JPEG (Joint Photographic Experts Group) file.
gif: GIF (Graphic Interchange Format) file.
tif: TIFF (Tagged Image File Format) file.
png: PNG (Portable Network Graphics) file.

Export numeric data to file
Within the dScope Trace Window menu is the option to display a list of numeric values for the selected trace. Within this dialogue there are two more buttons to export the numeric data to tab separated or CSV files. Note that the data displayed in the numerical data dialogue is rounded to a number of decimal places dependent on the units, and may also be converted to different ranges within the same units (eg, V or mV, or Hz and kHz) - this also applies to the exported data although the number of decimal places will often be higher. Exporting data in this way can not currently be automated from a script directly, but the same data can be retrieved by exporting trace values directly as described above. This has the added advantage that the readings will be retrieved with full precision and will all be in the same range (ie, not a mix of mV and V values for example.)