Massive UI revamping (v7): spectrum documentation

pull/1214/head
f4exb 2022-04-18 18:33:37 +02:00
rodzic 560d61abcb
commit 0779ab0c70
29 zmienionych plików z 334 dodań i 15 usunięć

Plik binarny nie jest wyświetlany.

Przed

Szerokość:  |  Wysokość:  |  Rozmiar: 18 KiB

Po

Szerokość:  |  Wysokość:  |  Rozmiar: 14 KiB

Plik binarny nie jest wyświetlany.

Plik binarny nie jest wyświetlany.

Przed

Szerokość:  |  Wysokość:  |  Rozmiar: 5.8 KiB

Po

Szerokość:  |  Wysokość:  |  Rozmiar: 5.1 KiB

Plik binarny nie jest wyświetlany.

Plik binarny nie jest wyświetlany.

Przed

Szerokość:  |  Wysokość:  |  Rozmiar: 8.1 KiB

Po

Szerokość:  |  Wysokość:  |  Rozmiar: 5.0 KiB

Plik binarny nie jest wyświetlany.

Plik binarny nie jest wyświetlany.

Po

Szerokość:  |  Wysokość:  |  Rozmiar: 4.3 KiB

Plik binarny nie jest wyświetlany.

Plik binarny nie jest wyświetlany.

Po

Szerokość:  |  Wysokość:  |  Rozmiar: 72 KiB

Plik binarny nie jest wyświetlany.

Po

Szerokość:  |  Wysokość:  |  Rozmiar: 131 KiB

Wyświetl plik

@ -12,7 +12,7 @@ The top and bottom bars of the channel window are described [here](../../../sdrg
The interface is divided in 3 sections that will be detailed next:
- A: settings. These are the plugin controls
- B: spectrum (frequency domain). This is a spectrum display analogous to other spectrum displays. Its input varies depending on the correlation function selected
- B: spectrum (frequency domain). This is a spectrum display analogous to other spectrum displays. Its input varies depending on the correlation function selected. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)
- C: scope (time domain). This is a scope display analogous to other scope displays. Its input varies depending on the correlation function selected. For FFT type correlation this is not a time domain but a frequency domain display transposed to time analogous to a frequency sweep.
<h2>A. Settings section</h2>

Wyświetl plik

@ -38,7 +38,7 @@ The interface is essentially divided in the following sections
Note 1: the scope trace is updated continuously for sweep times of 1 second or more else the display is refreshed only when the trace finishes.
Note 2: the spectrum view (Channel spectrum) is not presented here.
Note 2: details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)
<h2>C. Channel controls</h2>

Wyświetl plik

@ -70,6 +70,10 @@ This is the relative AF volume from 0 to 10.
Adjust squelch in dB.
<h2>B: Spectrum</h2>
Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)
<h2>C: RDS display</h2>
![BFM Demodulator plugin RDS 1](../../../doc/img/BFMDemod_plugin_rds.png)

Wyświetl plik

@ -268,7 +268,7 @@ This is the UDP address and port to where the decoded message is sent when (12)
<h3>B: De-chirped spectrum</h3>
This is the spectrum of the de-chirped signal when a ChirpChat signal can be decoded.
This is the spectrum of the de-chirped signal when a ChirpChat signal can be decoded. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)
The frequency span corresponds to the bandwidth of the ChirpChat signal (3). Default FFT size is 2<sup>SF</sup> where SF is the spread factor (7).

Wyświetl plik

@ -154,4 +154,4 @@ If you right click on it a dialog will open to select the audio output device. S
<h3>14: Spectrum display</h3>
This is the spectrum display of the demodulated signal (SSB) or translated signal (DSB). Controls on the bottom of the panel are identical to the ones of the main spectrum display.
This is the spectrum display of the demodulated signal (SSB) or translated signal (DSB). Controls on the bottom of the panel are identical to the ones of the main spectrum display. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -101,4 +101,4 @@ The file path currently being written (or last closed) appears at the right of t
<h3>15: Channel spectrum</h3>
This is the spectrum display of the IQ stream seen by the channel. It is the same as all spectrum displays in the program and is identical to the [main window](../../../sdrgui/readme.md#) spectrum display.
This is the spectrum display of the IQ stream seen by the channel. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -108,4 +108,4 @@ The channel signal is decimated by a power of two before being applied to the ch
<h3>12: Channel spectrum</h3>
This is the spectrum display of the tracker channel. When the tracker is locked to the signal the center of the channel should fall almost in the middle of the signal spectrum (ideally in the middle when the tracker error is zero). Thus the locking can be followed dynamically and it can be more reliable than the lock indicator. A channel marker shows the tracker offset from the channel center frequency (tracker error). Its width is the tracker error tolerance and is &plusmn;1/1000th of the channel width. Controls on the bottom of the panel are identical to the ones of the main spectrum display.
This is the spectrum display of the tracker channel. When the tracker is locked to the signal the center of the channel should fall almost in the middle of the signal spectrum (ideally in the middle when the tracker error is zero). Thus the locking can be followed dynamically and it can be more reliable than the lock indicator. A channel marker shows the tracker offset from the channel center frequency (tracker error). Its width is the tracker error tolerance and is &plusmn;1/1000th of the channel width. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -102,4 +102,4 @@ The path of the selected meta file appears at the right of the button. If it is
<h3>15: Channel spectrum</h3>
This is the spectrum display of the IQ stream seen by the channel. It is the same as all spectrum displays in the program and is identical to the [main window](../../../sdrgui/readme.md#) spectrum display.
This is the spectrum display of the IQ stream seen by the channel. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -126,7 +126,7 @@ The delay in milliseconds is displayed at the right of the button.
<h3>14: Spectrum display</h3>
This is the spectrum display of the channel signal after bandpass filtering. Please refer to the Spectrum display description for details.
This is the spectrum display of the channel signal after bandpass filtering. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)
This spectrum is centered on the center frequency of the channel (center frequency of reception + channel shift) and is that of a complex signal i.e. there are positive and negative frequencies. The width of the spectrum is proportional of the sample rate. That is for a sample rate of S samples per seconds the spectrum spans from -S/2 to +S/2 Hz.

Wyświetl plik

@ -179,4 +179,4 @@ The transmitted signal is further decimated by a power of two before being appli
<h3>17: Channel spectrum display</h3>
This is the channel spectrum display. Controls at the bottom of the panel are the same as with the central spectrum display.
This is the channel spectrum display. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -249,4 +249,4 @@ This slider can be used to randomly set the current position in the file when fi
<h3>22: Channel spectrum display</h3>
This is the channel spectrum display. Controls at the bottom of the panel are the same as with the central spectrum display.
This is the channel spectrum display. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -123,6 +123,6 @@ When any item of these items is changed the button is lit in green until it is p
<h3>21: Spectrum display</h3>
This is the spectrum display of the channel signal before filtering. Please refer to the Spectrum display description for details.
This is the spectrum display of the channel signal before filtering. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)
This spectrum is centered on the center frequency of the channel (center frequency of reception + channel shift) and is that of a complex signal i.e. there are positive and negative frequencies. The width of the spectrum is proportional of the sample rate. That is for a sample rate of S samples per seconds the spectrum spans from -S/2 to +S/2 Hz.

Wyświetl plik

@ -75,7 +75,7 @@ Average total power in dB relative to a +/- 1.0 amplitude signal received in the
<h2>B. Spectrum view</h2>
This is the same display as with the channel analyzer spectrum view. This is the spectrum of a real signal so it is symmetrical around zero frequency. See Channel Analyzer plugin documentation for details.
This is the same display as with the channel analyzer spectrum view. This is the spectrum of a real signal so it is symmetrical around zero frequency. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)
<h2>C. Scope view</h2>

Wyświetl plik

@ -46,4 +46,4 @@ Use the wheels to adjust the sample rate. Left click on a digit sets the cursor
<h3>7: Spectrum display</h3>
This is the final output stream spectrum display after interpolation (5). This would be sent to the hardware device. Controls on the bottom of the panel are identical to the ones of the main spectrum display.
This is the final output stream spectrum display after interpolation (5). This would be sent to the hardware device. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -42,4 +42,4 @@ Use the wheels to adjust the sample rate. Left click on a digit sets the cursor
<h3>6: Spectrum display</h3>
This is the final output stream spectrum display after interpolation (4). This would be sent to the hardware device. Controls on the bottom of the panel are identical to the ones of the main spectrum display.
This is the final output stream spectrum display after interpolation (4). This would be sent to the hardware device. Details on the spectrum view and controls can be found [here](../../../sdrgui/gui/spectrum.md)

Wyświetl plik

@ -0,0 +1,315 @@
<h1>Spectrum component</h1>
This page details the spectrum component that takes part of the main spectrum display and is also used in some channel and feature plugins.
For example:
- Channel Analyzer
- Demod Analyzer
- Interferometer
- Broadcast FM demodulator
- ChirpChat (LoRa) demodulator
- File sink
- FreeDV demodulator and modulator
- Frequency tracker
- SigMF file sink
- SSB demodulator and modulator
- UDP source and sink
It comprises the spectrum display itself and the controls generally placed at the bottom of the spectrum display
<h2>A. Spectrum display</h2>
<h3>Status line</h3>
![Spectrum Statuss](../../doc/img/Spectrum_Status.png)
A status line is displayed at the left of the top margin. It displays the following items from left to right:
- if frequency zooming is active the zooming factor
- `CF:` followed by the Center Frequency of the displayed spectrum possibly with multiplier suffix (G, M, k)
- `SP:` followed by the frequency SPan of the displayed spectrum possibly with multiplier suffix (M, k)
<h3>Spectrum markers</h3>
![Spectrum Markers](../../doc/img/Spectrum_Markers.png)
Note that spectrum markers appear only when spectrum display is active (shows data)
The spectrum markers can be set either with the mouse as explained next or with the [spectrum markers dialog](spectrummarkers.md) that can be opened with the markers button (B.4.3).
Use Shift and mouse left click to set a new marker. There is a maximum of two markers with a different status:
- The first marker will display frequency (2) and power (1) or time (5) on the scale side of the view. Frequency units are the same as displayed in the frequency scale.
- The second marker will display frequency difference (3 or 6) and power difference (4) or time difference (7) from the first marker on the opposite side of the scales. Difference values may be suffixed with a multiplier character.
Base units are Hz for frequency difference and seconds for time. Power is expressed either in dB or plain value depending on the linear or log setting for the spectrum display.
Values may be suffixed by a multiplier character:
- **p**: pico (times 1e-12)
- **n**: nano (times 1e-9)
- **u**: micro (times 1e-6)
- **m**: milli (times 1e-3)
- no character: no change (times one)
- **k**: kilo (times 1e3)
- **M**: mega (times 1e6)
- **G**: giga (times 1e9)
Use mouse right click anywhere in the view to remove the last entered marker. Use shift and mouse right click to remove all markers.
<h3>Mouse scroll wheel</h3>
![Spectrum Mousewheel](../../doc/img/MainWindow_spectrum_mousewheel.png)
<h4>A: Channel moving</h4>
When the mouse is over the center line of a channel:
- scrolling will move the channel by +/- 10 Hz at each scroll up/down respectively
- combined with Ctrl it will move the channel by +/- 100 Hz
- combined with Shift it will move the channel by +/- 1 kHz
<h4>B: Frequency zooming</h4>
When the mouse is in the spectrum or waterfall area but not over the center line of a channel it will zoom in/out along X (frequency) axis by a 0.5 step at each scroll up/down respectively between 1x (no zoom) and 10x. Note that in order to zoom on the center line of a channel you may move the mouse pointer in the top margin (center line moving is not active there but zooming is).
When frequency zooming is active use Alt + left click to move the center frequency to the clicked point.
<h4>C: Power zooming</h4>
When the mouse is inside the power scale (spectrum) the power range is decreased by 2 (zoom in) or increased by 2 (zoom in) at each wheel step forward or backward respectively. The behavior of the reference level depends on where in the scale is the mouse pointer:
- in the top third: the reference level is maintained thus the reference level at the top stays the same
- in the middle third: the reference level is decreased by 1 (zoom in) or increased by 1 (zoom out) at each wheel step forward or backward thus the level in the middle stays the same
- in the bottom third: the reference level is decreased by 2 (zoom in) or increased by 2 (zoom out) at each wheel step forward or backward thus the level at the bottom stays the same
<h4>D: Time zooming</h4>
When the mouse is inside the time scale (waterfall) the overlap is increased by 1 (zoom in) or decreased by 1 (zoom out) at each wheel step forward or backward respectively. Overlap is bounded by 0 and half of the FFT size minus one.
<h2>B. Spectrum controls</h2>
Controls are organized in 4 blocks arranged in a flow layout so that the size of the control area can adapt to the width of the spectrum arranging the blocks from 3 to 1 line as the spectrum widens. The buttons and various controls in each block remain at the same place.
Narrow (3 lines):
![Spectrum GUI](../../doc/img/MainWindow_spectrum_gui_narrow.png)
Wide (1 line):
![Spectrum GUI](../../doc/img/MainWindow_spectrum_gui_wide.png)
The 4 blocks are detailed next:
![Spectrum GUI](../../doc/img/MainWindow_spectrum_gui.png)
<h3>B.1: Spectrum display control line 1</h3>
![Spectrum GUI C](../../doc/img/MainWindow_spectrum_gui_C.png)
<h4>B.1.1: Clear spectrum</h4>
This resets the maximum spectrum trace and phosphor remanence
<h4>B.1.2: Phosphor display</h4>
Toggles the phosphor display on the spectrum
<h4>B.1.3: Phosphor display stroke and max hold decay</h4>
This controls the decay rate of the stroke when phosphor display is engaged (B.1.2). The histogram pixel value is diminished by this value each time a new FFT is produced. A value of zero means no decay and thus phosphor history and max hold (red line) will be kept until the clear button (B.1.1) is pressed.
<h4>B.1.4: Phosphor display stroke and max hold decay divisor</h4>
When phosphor display is engaged (B.1.2) and stroke decay is 1 (B.1.3) this divides the unit decay by this value by diminishing histogram pixel value by one each time a number of FFTs equal to this number have been produced. Thus the actual decay rate is 1 over this value. This allow setting a slower decay rate than one unit for each new FFT.
<h4>B.1.5: Phosphor display stroke strength</h4>
This controls the stroke strength when phosphor display is engaged (B.1.2). The histogram value is incremented by this value at each new FFT until the maximum (red) is reached.
<h4>B.1.6: Maximum hold trace</h4>
Toggles the maximum hold trace display (red trace) on the spectrum
<h4>B.1.7: Current trace</h4>
Toggles the current trace display (yellow trace) on the spectrum
<h4>B.1.8: Trace intensity</h4>
This controls the intensity of the maximum (B.1.6) and current (B.1.7) spectrum trace
<h4>B.1.9: Waterfall/spectrum placement</h4>
Toggles the spectrum on top or on bottom versus waterfall
<h4>B.1.10: Waterfall</h4>
Toggles the waterfall display
<h4>B.1.11: Grid</h4>
Toggles the grid display
<h4>B.1.12: Grid intensity</h4>
Controls the intensity of the grid display
<h3>B.2: Spectrum display control block #2</h3>
![Spectrum GUI A](../../doc/img/MainWindow_spectrum_gui_A.png)
<h4>B.2.1. FFT window selector</h4>
Use this combo box to select which window is applied to the FFT:
- **Bart**: Bartlett
- **B-H**: Blackmann-Harris
- **FT**: Flat top
- **Ham**: Hamming
- **Han**: Hanning (default)
- **Rec**: Rectangular (no window)
- **Kai**: Kaiser with alpha = 2.15 (beta = 6.76) gives sidelobes &lt; -70dB
<h4>B.2.2. FFT size</h4>
Select the size of the FFT window among these values:
- 128
- 256
- 512
- 1k = 1024 (default)
- 2k = 2048
- 4k = 4096
<h4>B.2.3: FFT Overlap</h4>
FFT Overlap in number of samples over half of the FFT size. The percentage of overlap appears in the tooltip. Ranges from 0 (no overlap) to half the FFT size minus one (maximum overlap).
Example with a FFT of 1k (1024) and an overlap of 128 the overlap percentage is 128 &divide; 512 = 25%
<h4>B.2.4: Averaging mode</h4>
Use this combo to select which averaging mode is applied:
- **No**: no averaging. Disables averaging regardless of the number of averaged samples (B.2.5). This is the default option
- **Mov**: moving average. This is a sliding average over the amount of samples specified next (B.2.5). There is one complete FFT line produced at every FFT sampling period
- **Fix**: fixed average. Average is done over the amount of samples specified next (B.2.5) and a result is produced at the end of the corresponding period then the next block of averaged samples is processed. There is one complete FFT line produced every FFT sampling period multiplied by the number of averaged samples (4.6). The time scale on the waterfall display is updated accordingly.
- **Max**: this is not an averaging but a max hold. It will retain the maximum value over the amount of samples specified next (B.2.5). Similarly to the fixed average a result is produced at the end of the corresponding period which results in slowing down the waterfall display. The point of this mode is to make outlying short bursts within the "averaging" period stand out. With averaging they would only cause a modest increase and could be missed out.
<h4>B.2.5: Number of averaged samples</h4>
Each FFT bin (squared magnitude) is averaged or max'ed over a number of samples. This combo allows selecting the number of samples between these values: 1 (no averaging), 2, 5, 10, 20, 50, 100, 200, 500, 1k (1000) for all modes and in addition 2k, 5k, 10k, 20k, 50k, 1e5 (100000), 2e5, 5e5, 1M (1000000) for "fixed" and "max" modes. Averaging reduces the noise variance and can be used to better detect weak continuous signals. The fixed averaging mode allows long time monitoring on the waterfall. The max mode helps showing short bursts that may appear during the "averaging" period.
The resulting spectrum refresh period appears in the tooltip taking sample rate, FFT size (B.2.2), average size (B.2.5) and overlap (B.2.3) into consideration. Averaging size adjustment is valid for fixed average and max modes only:
Period = ((((FFT_size &divide; 2) - overlap) &times; 2) &divide; sample_rate) &times; averaging_size
<h3>B.3: Spectrum display control block #3</h3>
![Spectrum GUI B](../../doc/img/MainWindow_spectrum_gui_B.png)
<h4>B.3.1: Autoscale</h4>
Scales spectrum by setting reference level and range automatically based on maximum and minimum levels. Takes the average of FFT size &divide; 32 minima for the minimum and 10 dB over maximum for the maximum.
<h4>B.3.2: Reference level</h4>
This is the level in dB at the top of the display range. You can select values between 0 and -110 in 1 dB steps
<h4>B.3.3: Range</h4>
This is the range of display in dB. You can select values between 1 and 100 in 1 dB steps
<h4>B.3.4: FPS capping</h4>
The refresh rate of the spectrum is capped by this value in FPS i.e the refresh period in seconds is 1 &divide; FPS. The default value is 20 and corresponds to general usage. You may use a lower value to limit GPU usage and power consumption. You may also use a higher value for an even more reactive display. "NL" corresponds to "No Limit". With "No Limit" the spectrum update will be triggered immediately when a new FFT is calculated. Note that actual refresh rate will be limited by other factors related to hardware and graphics drivers.
The refresh period is limited anyway by the FFT period which is the FFT size divided by the baseband sampling rate and multiplied by the fixed average or max size (3A.5) in case these features are engaged (3A.4). Setting a resulting FFT refresh time above the refresh rate will make sure that a short burst is not missed particularly when using the max mode.
Example with a FFT size of 1k (1024) and no overlap, a baseband rate of 48 kS/s and an averaging size of 5 the refresh period is:
(1024 &divide; 48000) &times; 5 &approx; 107 ms
Thus if the FPS capping is 20 (50 ms) the refresh period will be in fact 107 ms (&approx; 9 FPS) anyway.
<h4>B.3.5: Logarithmic/linear scale</h4>
Use this toggle button to switch between spectrum logarithmic and linear scale display. The face of the button will change to represent either a logaritmic or linear curve.
When in linear mode the range control (B.3.3) has no effect because the actual range is between 0 and the reference level. The reference level in dB (B.3.2) still applies but is translated to a linear value e.g -40 dB is 1e-4. In linear mode the scale numbers are formatted using scientific notation so that they always occupy the same space.
<h3>B.4: Spectrum display control block #4</h3>
![Spectrum GUI D](../../doc/img/MainWindow_spectrum_gui_D.png)
<h4>B.4.1: Play/Pause spectrum</h4>
Use this button to freeze the spectrum update. Useful when making measurements with the markers.
<h4>B.4.2: Spectrum server control</h4>
A websockets based server can be used to send spectrum data to clients. An example of such client can be found in the [SDRangelSpectrum](https://github.com/f4exb/sdrangelspectrum) project.
- Left button: toggles server on/off
- Right button: opens a secondary dialog that lets you choose the server listening (local) address and port.
The server only sends data. Control including FFT details is done via the REST API. FFT frames are formatted as follows (in bytes):
<table>
<tr>
<th>Offset</th>
<th>Length</th>
<th>Value</th>
</tr>
<tr>
<td>0</td>
<td>8</td>
<td>Center frequency in Hz as 64 bit integer</td>
</tr>
<tr>
<td>8</td>
<td>8</td>
<td>Effective FFT time in milliseconds as 64 bit integer</td>
</tr>
<tr>
<td>16</td>
<td>8</td>
<td>Unix timestamp in milliseconds as 64 bit integer</td>
</tr>
<tr>
<td>24</td>
<td>4</td>
<td>FFT size as 32 bit integer</td>
</tr>
<tr>
<td>28</td>
<td>4</td>
<td>FFT bandwidth in Hz as 32 bit integer</td>
</tr>
<tr>
<td>32</td>
<td>4</td>
<td>
Indicators as 32 bit integer LSB to MSB:
<ul>
<li>bit 0: Linear (1) / log (0) spectrum indicator</li>
<li>bit 1: SSB (1) / DSB (0) spectrum indicator</li>
<li>bit 2: USB (1) / LSB (0) spectrum indicator</li>
</ul>
</td>
</tr>
<tr>
<td>36</td>
<td>N*4</td>
<td>Vector of N = FFT size 32 bit floating point spectrum power values either log (dB) or linear</td>
</tr>
</table>
<h4>B.4.3: Spectrum markers dialog</h4>
Opens the [spectrum markers dialog](spectrummarkers.md)
<h4>B.4.4: Spectrum calibration</h4>
Use the toggle button to switch between relative and calibrated power readings.
Right click to open the [calibration management dialog](spectrumcalibration.md)

Wyświetl plik

@ -1,6 +1,6 @@
<h1>Main spectrum window</h1>
This page details the top and bottom bars of the window and not the spectrum nor the spectrum controls. Documentation on the spectrum display and controls can be found here (TBD)
This page details the top and bottom bars of the window and not the spectrum nor the spectrum controls. Documentation on the spectrum display and controls can be found [here](../gui/spectrum.md)
![Channel window](../../doc/img/MainSpectrum.png)