Daqarta
Data AcQuisition And Real-Time Analysis
Scope - Spectrum - Spectrogram - Signal Generator
Software for Windows
Science with your Sound Card!
The following is from the Daqarta Help system:

Features:

Oscilloscope

Spectrum Analyzer

8-Channel
Signal Generator

(Absolutely FREE!)

Spectrogram

Pitch Tracker

Pitch-to-MIDI

DaqMusiq Generator
(Free Music... Forever!)

Engine Simulator

LCR Meter

Remote Operation

DC Measurements

True RMS Voltmeter

Sound Level Meter

Frequency Counter
    Period
    Event
    Spectral Event

    Temperature
    Pressure
    MHz Frequencies

Data Logger

Waveform Averager

Histogram

Post-Stimulus Time
Histogram (PSTH)

THD Meter

IMD Meter

Precision Phase Meter

Pulse Meter

Macro System

Multi-Trace Arrays

Trigger Controls

Auto-Calibration

Spectral Peak Track

Spectrum Limit Testing

Direct-to-Disk Recording

Accessibility

Applications:

Frequency response

Distortion measurement

Speech and music

Microphone calibration

Loudspeaker test

Auditory phenomena

Musical instrument tuning

Animal sound

Evoked potentials

Rotating machinery

Automotive

Product test

Contact us about
your application!

Macro Array Display Operations

Introduction:

The contents of any array buffer uf0-7 can be displayed graphically. The display is redrawn when the main Daqarta input and output channel displays are updated at each Trace Update Interval. (You can toggle any or all of the main channel displays off to reduce screen clutter. The BufN displays will still be updated at the same rate.)

Besides data display, constant-filled buffers can also be used as indicator lines to show range limits or center, or the highest peak previously encountered. See Display Line Style and Custom Color, below.


Command Summary:

Buf0#d=UB              Set  Upload Bitmap UB 
Buf0#Ch=n             Set  main Display Channel buttons 
Buf0="<dWB"            Display  Bipolar Waveform 
Buf0="<dWB1"           Bipolar Waveform, dashed  line style 
Buf0="<dWB2(255,0,0)"  Bipolar Waveform, dotted  red color 
Buf0="<dWB(h00FF00)"   Bipolar Waveform, solid  green color 
Buf0#C=h0000FF          Color  to blue, no other change
Buf0="<dWU"            Display  Unipolar Waveform 
Buf0="<dSB"            Display  Bipolar Spectrum  - linear only
Buf0="<dSu"            Display  Unipolar Spectrum  - linear only
Buf0="<dSU"            Display  Unipolar Spectrum  - linear or dB
Buf0="<dCN"           Unipolar dB Spectrum with  Curve  in BufN
Buf0="<dcn"           Unipolar dB Spectrum, channel n  calibration 
Buf0="<d-"             Disable  Buf0 display
Buf0#Z=K                Vertical Zero position  to K
Buf0#G=M                Gain (Magnification)  to M
Buf0#R=n              Waveform  X-axis display Sample Rate  to n
Buf0#Rs=n             Spectrum  X-axis display Sample Rate  to n
Buf0#V=n              Waveform  Vertical bipolar range  to +/-n
Buf0#VU=n             Waveform  Vertical unipolar range  to 0-n
Buf0#Vs=n             Spectrum magnitude  Vertical range  to n
Buf0#Vx=1               Vertical Range  #V, #VU, #Vs w/o User Units state
Buf0#U="Deg"           Waveform  Vertical Units  to Deg
Buf0#Ux="Deg"          Waveform  Horizontal Units  to Deg
Buf0#Us="Deg"          Spectrum  Vertical Units  to Deg
Buf0="<dX1"             X-Y Display  with Buf0 as Y, Buf1 as X
Buf0#Y=n               Line style  n = 0-5

Direct Display vs. Uploaded Data:

Most of the commands discussed in this Display Operations topic are for direct display of BufN data. The buffer contents are displayed as-is, and are simply screen images; no further processing is applied. They are displayed separately from the normal Input and Generator traces and do not interact. They do not work with cursor readouts and are not saved to files via the File menu options, for example.

An alternative is to "upload" the buffer data to Daqarta's internal processing stream, replacing the raw waveform data from the sound card. This has advantages and disadvantages.

Upload:
    Allows up to 4 channels, replacing Input/Generator data.
    Allows normal cursor readout, File save.
    Vertical position adjust via Screen Zero controls.
    Traces use same colors as Input/Generator.
    Upload commands must be given to refresh each trace.
    Allows toggle to Spectrum after waveform upload.
    Normal Spectrum dialog options, including Peak Track.

Direct:
    Allows up to 8 channels, plus normal Input/Generator display.
    No built-in cursor readout or file save.
    Independent vertical position for each channel.
    Complete control over color and line style.
    Traces refreshed simply by changing buffer contents.
    Separate waveform and Spectrum display modes.
    Limited Spectrum dialog options, no Peak Track, etc.
    Allows X-Y display mode.

Both:
    Allow axes and units control.

The upload method is typically used to process and display data obtained from a source other than a sound card, such as an Arduino or Numato device that uses Port Access. See the DC_Chart_Recorder or DaquinOscope macro mini-app code for examples.

See the Upload To Waveform Channel subtopic under Macro Array Copy/Swap Operations for information about upload commands.


Upload Display Bitmap:

Please note: A macro that uses the upload method must include a Buf0#d=UB command, where UB is a constant, variable, or expression that provides a bitmap of desired display channels:

    b0001    Left In
    b0010    Right In
    b0100    Left Out
    b1000    Right Out

So, for example, to display data sent to both Left In and Right In, you'd use Buf0#d=b0011, while Buf0#d=b1100 would show both outputs, and Buf0#d=b1111 would show all 4 channels.

Note that although Buf0 is used here, it doesn't matter which buffer you use in the command. You only need to give this command when you change the channels you want to upload to.


Main Display Channel Buttons:

When a macro uses the upload method to replace Input/Generator data, it can change the main Display Channels buttons at the lower left of the main display area to indicate their new function. The command to do this is Buf0#Ch=n, where n is -1 for normal operation and 0-4 for upload operation. (It doesn't matter which BufN you use on the left side.) This single command changes all the uploaded channel buttons as follows:

     -1       0       1       2       3       4
    L.In     Ch0     Ch1     Ch2     Ch3     Ch4
    R.In     Ch1     Ch2     Ch3     Ch4     Ch5
    L.Out    Ch2     Ch3     Ch4     Ch5     Ch6
    R.Out    Ch3     Ch4     Ch5     Ch6     Ch7

As shown above, the Buf0#Ch command effectively sets the first button label, which is normally L.In, to Chn, and the rest of the buttons continue up from there. Buf0#Ch=0 is used for up to 4 uploaded channels. Values from 1 to 4 are used when uploading a 4-channel subset of an 8-channel data stream, as in the DC_Chart_Recorder 8-Channel Subset button that is enabled when recording 8 inputs in Process (upload) mode.

If the Input or Generator is active, uploaded data replaces the corresponding stream(s). But it's possible to have a mixed data setup, where (say) L.In is replaced by Ch0 but R.In is still active, or both Input streams are replaced by Ch0 and Ch1 but L.Out and R.Out are still active. In such cases the buttons will be labeled properly.

(Note that when a Generator stream is replaced by uploaded data, the raw Generator output still goes to the sound card output as usual... you just don't see it on the screen.)

Besides the Display Channels buttons, the same labels replace the Voltmeter channel select buttons when it is active. If you save a trace (1024 time samples) to a text file those labels are also used as column headers.

Note that when a macro stops using the upload mode (such as when it closes) it must use Buf0#Ch=-1 to restore the normal button display.


Waveform and Spectrum Displays:

There are separate display commands for waveform and Spectrum modes; each buffer can be shown in only one mode. (But you can copy its contents to a second buffer and set it to display in the other mode.) Note that in Spectrum mode only the first 512 points of the buffer are displayed, corresponding to the 512 spectral lines that are shown for main channel spectra on the same display. To display a magnitude spectrum from 512 Re,Im raw FFT pairs (perhaps obtained by array copy operation Buf0="<=S1" from a main channel FFT, or from a waveform that you have taken the FFT of using spectrum operation Buf0="<fB1"), you must first use magnitude operation Buf0="<mB1".

In addition, the display command must specify whether the buffer should be shown as bipolar (typical for waveform displays) or unipolar (typical for Spectrum displays). The display commands all have a d immediately after the < caret. Here are examples for Buf0:

    Buf0="<dWB"    Waveform Bipolar
    Buf0="<dWU"    Waveform Unipolar
    Buf0="<dSB"    Spectrum Bipolar - linear only
    Buf0="<dSU"    Spectrum Unipolar - linear or dB
    Buf0="<dSu"    Spectrum Unipolar - linear only

Display Line Style:

As given above, the buffer would be displayed with a solid line style in the color of the main input or output channel that has the same number (0-3) as the buffer number. (Buf4-7 are shown using the same colors as 0-3.) You can retain the same colors but specify a different line style by appending a digit 0-4, as in Buf0="<dWU1". (It must be a single digit, not a variable or expression.) The line style numbers are:

    0 = Solid
    1 = Dash
    2 = Dot
    3 = Dash-dot
    4 = Dash-dot-dot

Alternatively, you can change the line style without changing the display mode or color via Buf0#Y=n, where n is the line style number.


Custom Line Color:

You can further specify a custom color by providing the RGB (Red, Green, Blue) color triplet in parentheses after the line style digit. For example, Buf0="<dWU1(255,0,0)" would specify pure red. Unlike the line style digit, each of the three values may be a constant, variable, or math expression. Each color component is limited to the 0-255 range.

You can also specify only the color, without changing the current line style, by simply omitting the line style digit as in Buf0="<dWU(255,0,0)".

Alternatively, you can use a single constant, variable, or expression to set the color, as in Buf0="<dWU2(X<<8)" or Buf0="<dWU(hFF00FF)". Only the low 24 bits of the value are used. The low 8 are Red, the middle 8 are Green, and the next 8 are Blue... so for a hexadecimal value the colors are in BBGGRR order, the opposite of the above (R,G,B) order.

To change only the color, without affecting the display mode or line style, use Buf0#C=X<<8 or Buf0#C=hFF00FF instead of the above. (There is no 3-value RGB equivalent.)

The colr() function can be used with a Custom Control to smoothly change the color. See the Channel Difference, Lissajous, and FFT Filter macro mini-apps for examples.

You can obtain the color value of any main Daqarta trace via the ColorNum macro, as in Buf0="<dWU(ColorNum?L)" to use the Left Input color. To get the color value that corresponds to the current Channel Select Ch setting, use ColorNum?c.

If you use empty parentheses, as in Buf0="<dWU1()" or Buf0="<dWU()", it resets back to the default main channel color that corresponds to the buffer number.


Spectrum Curve Application:

The above Buf0="<dSU" (Spectrum Unipolar) display mode will show Buf0 data as linear magnitude or as dB, depending on the Y-log toggle state.

In dB mode, you can specify that another buffer be associated with the display buffer to apply a calibration or curve function to the data. Buf0="<dCN" sets the Buf0 display to use BufN for this purpose, where N is any buffer except Buf0.

The EQ_Curve macro mini-app uses this method to display the shape of the curve it has computed. It first fills Buf1 with a constant-magnitude (flat) spectrum, then computes the target curve in Buf2. Then it uses Buf1="<dC2" to apply that curve to Buf1, and Buf1="<dSU" to display the result.

You can copy a loaded User Units calibration (CAL) file to Buf1 via Buf1="<=Cn", where n is main channel 0-3.

Alternatively, you can copy a loaded Spectrum Curve file via Buf1="<=Vn", where n is curve (not channel) 0-3. The curve may be a Memory Curve created by a macro script for on-the-fly frequency response corrections or modifications of displayed data.

Instead of using a buffer as the curve source, you can use Buf0="<dcn" (note lowercase 'c'), to specify that Buf0 be shown with the total calibration that is currently active for main channel n. This can include User Units calibration plus a Spectrum Curve or Tilt.

The use of a specified curve while displaying a particular buffer will persist as long as that buffer is displayed (see Persistent Display, below). The association, via a <dCN or <dcn command, only needs to be made once, after which you can change either the buffer contents or the curve contents (or both) and the display will automatically be updated on the next trace update.

If a new <dCN or <dcn command is given for the display buffer (Buf0 in these examples), it replaces any prior association... you can't combine multiple curves via multiple commands. (If you want to do that, add individual curves together separately via Buf1="<+BufN".)

To remove all curve associations from a specific buffer display, use Buf0="<dCx".


Persistent Display:

The display command is persistent, so you only need to give it once. After that, whenever you change the contents of the buffer, the display will automatically reflect those changes on the next trace update. You don't need to give the display command again until you want to modify the command parameters (waveform/spectrum, unipolar/bipolar, line style, or color).

Typically, you might give the display command at the same time you set up Macro Multitasking for a buffer, via an initial Task command. Then on each trace update the task can update the contents of the buffer before the display is automatically updated.

When you end the task, you can manually disable the display via Buf0="<d-".


Display Vertical Position:

Buf0#Z=K sets the vertical (zero) position of the Buf0 display to the value of K, which may be a constant, variable, or expression. The screen range for K is +127 to -128, rounded to integer values. In Bipolar mode, this is relative to the vertical center of the trace area. Thus, Buf0#Z=64 would cause the Buf0 display to be shifted up by a quarter of the height of the trace area. Displays are always clipped as needed to limit them to the trace area.

In Unipolar mode, the screen range for K is relative to the bottom of the trace area. Note that the maximum of +127 only goes to mid-trace. Negative values would place the zero position below the bottom of the trace area, but since off-screen values are clipped you could still see positive peaks.


Display Magnification:

Normally, as for main Daqarta channels, the PgUp/PgDn keys control display magnification. You can override this and set a different magnification for any buffer via Buf0#G=M, where M is a magnification range value that may be a constant, variable, or expression. Results are rounded to integer range numbers.

Note that more-positive values result in less magnification. Each integer step increase halves the magnification while each integer decrease doubles it. Please note that the actual values are quite different for each display mode: In normal waveform display mode, the range is -30 to +12, with 8 resulting in a full-scale waveform just filling the trace area vertically.

In Spectrum mode, the useful range is -17 to +25, with 21 resulting in a full-scale peak for a sine wave whose frequency falls exactly on a spectral line.

Histogram averages use a range of -31 to +11, with 7 giving a full-scale display.

Note that this custom buffer magnification only applies to waveform and linear Spectrum modes, not Y-log Spectrum (dB vertical axis).

Setting a value of 1000 or more restores the default PgUp/PgDn magnification control for the buffer.


Display Axes and Units:

You can specify the horizontal and vertical display axis ranges, as well as the vertical units names and time-axis horizontal units names. These settings only apply to multitasking macros, and will remain in effect until the last task is uninstalled. You may install the included _Dummy_Task subroutine if you don't need any other multitasking features.

There are analogous commands for setting ranges and units when saving buffers as .DQA files, so they will appear the same way when the file is later opened.

These commands all set individual global variables, regardless of which specific BufN you use. A range can be restored to its default value by setting it to 0. A units name can be restored by setting it to an empty string, as in Buf0#Ux="", or more simply by omitting the right-hand term as in Buf0#Ux=.

Buf0#R=n sets the effective sample Rate to n for the waveform display X axis. The normal uneXpanded axis shows time points from 0 to 1023, assuming each time point is the reciprocal of the effective Sample Rate (including any Decimate Factor, if active). Here, you can set a dummy effective rate to get a specific unexpanded axis range. This only affects the display, not the real sample rate, and so may be much higher... over 2 GHz.

For example, a chart recorder macro may scroll at only 0.1 seconds per update, which is 10 samples per second. You'd use Buf0#R=10 to set the waveform display to show the proper time for the chart recorder trace. This will give a maximum time point of 0.1 * 1023 = 102.3 seconds, and the unexpanded X axis will be marked and labeled in 20 second steps up to 100 seconds... exactly as if observing a normal input waveform with a sample rate of 10 Hz. (It will likewise respond to eXpand properly.)

The Buf0#R command controls the X-axis range, which is all you'd need for a chart recorder. But an oscilloscope such as DaquinOscope that supports trigger delay will also need to control the position of that range. For example, if the sample rate is 10240 samples per second, then the 1024-sample X axis would show as 100 microseconds per sample from 0 to 100 milliseconds. But if there is a Trigger Delay of 100 samples (10 msec), the axis would run from 10 ms to 110 ms.

You control this with the main Trigger Delay control, either manually from the Trigger dialog or, for a macro like DaquinOscope, with the TrigDelay macro command. DaquinOscope uses the TrigDelay#N=QD variant to set the delay directly in samples instead of seconds. Note that Trigger Delay only affects the X axis when the main Trigger is active.


Buf0#Rs=n sets the effective sample Rate to n for the spectrum display X axis. Here the normal uneXpanded axis runs from 0 to just under half (511/1024) of the effective sample rate, so you can use this to set an arbitrary apparent frequency range.

Please note that these effective sample rate changes only affect the X axis; they do not change any actual sample rates, such as the sound card sample rate. In particular this means that if the axis is set to reflect a scroll rate or external device sample rate, as in the DC Chart Recorder or the DaquinOscope macro mini-apps, then any raw sound card Input or Generator display channels will not be shown with the proper axis. The waveform or spectrum display for these channels will have its original appearance, but the wrong axis and cursor readouts.


Buf0#V=n sets the Vertical range to +/-n for waveform display mode. Note that it only takes effect when User Units mode is active, so you can toggle back and forth to the normal vertical axis with the ALT+U hot-key combination. (But see Buf0#Vx=1 below.)

Buf0#VU=n sets the Vertical range to Unipolar 0-n.

Buf0#Vs=n sets the Vertical range to n for spectrum magnitude display mode; it does not affect the Y-log power spectrum (dB) mode.

Buf0#Vx=1 enables the above Buf0#V, Buf0#VU, and Buf0#Vs ranges to be shown regardless of the User Units state. Buf0#Vx=0 restores the normal vertical axis. Buf0#Vx=2 specifies that all BufN file saves use the current #V or #VU values, instead of #Vf.

Buf0#U="Deg" sets the vertical Units to Deg for waveform display mode, while Buf0#Us="Deg" does the same for spectrum display. As for Vertical range, these units are only seen in User Units mode.

Buf0#Ux="Deg" sets the X-axis units to Deg for waveform display mode, including the label at the right end of the axis as well as the cursor position readout label. This does not require User Units mode.


X-Y Display Mode:

Buf0="<dX1" sets the Buf0 display to use Buf1 as the X axis. This only applies to waveform mode. A value of 0 corresponds to the left edge of the display, while 511 corresponds to the right.

The Lissajous (X vs. Y) Mini-App uses this command to set X-Y display mode in the main Lissajous Macro Listing.

Alternatively, in this and any buffer command that uses a source (right side) buffer number, you may use an expression to specify the source by enclosing it in parentheses, as in Buf0="<dX(P+Q)".

A typical application might obtain the X-axis values from an input or output waveform, which has a +/-32767 range. To fit that range onto the display, you would first divide by 128 to get +/-256, then add 256. Since the signals can change continuously, you would do this in a Multitasking Macro that is run before every trace update:

    Buf0="<=W0"         ;Copy Left In to Buf0
    Buf1="<=W1"         ;Copy Right In to Buf1
    Buf1="</(128)"      ;Divide Buf1 by 128
    Buf1="<+(256)"      ;Add 256 to Buf1

Note that X-Axis eXpand has no effect on the X-axis of the buffer trace, but it still operates on other traces.

Buf0="<dX-" restores normal X-axis operation for Buf0.


See also Macro Overview, Macro Arrays Buf0-Buf7

GO:

Questions? Comments? Contact us!

We respond to ALL inquiries, typically within 24 hrs.
INTERSTELLAR RESEARCH:
Over 35 Years of Innovative Instrumentation
© Copyright 2007 - 2023 by Interstellar Research
All rights reserved