diff --git a/src/main/java/io/github/dsheirer/gui/spectrum/ChannelSpectralDisplay.java b/src/main/java/io/github/dsheirer/gui/spectrum/ChannelSpectralDisplay.java index 474cb0690..e395c44ea 100644 --- a/src/main/java/io/github/dsheirer/gui/spectrum/ChannelSpectralDisplay.java +++ b/src/main/java/io/github/dsheirer/gui/spectrum/ChannelSpectralDisplay.java @@ -65,7 +65,7 @@ public class ChannelSpectralDisplay extends DftSpectralDisplay SpectralDisplayModel model = getSpectralDisplay().getModel(); getSpectralDisplay().messageProperty().set(MESSAGE_NO_CHANNEL); - //Noise floor slider along the right edge, below the configuration panel tab + //Noise floor slider for the spectrum mNoiseFloorSlider = new EdgeSlider("Floor", "Noise floor: moves the bottom of the spectrum's dB range. " + "Higher settings show a deeper range and move the noise floor up the display.", MINIMUM_SAMPLE_SIZE, MAXIMUM_SAMPLE_SIZE, 1, this::formatPlotBottom); @@ -82,9 +82,10 @@ public class ChannelSpectralDisplay extends DftSpectralDisplay model.binCountProperty().addListener((ob, ov, nv) -> mNoiseFloorSlider.refreshLabel()); model.noiseBandwidthProperty().addListener((ob, ov, nv) -> mNoiseFloorSlider.refreshLabel()); mNoiseFloorSlider.refreshLabel(); + //Along the right edge of the spectrum section, below the configuration panel tab StackPane.setAlignment(mNoiseFloorSlider, Pos.CENTER_RIGHT); StackPane.setMargin(mNoiseFloorSlider, new Insets(44, 0, 8, 0)); - getChildren().add(mNoiseFloorSlider); + getSpectralDisplay().addSectionOverlay(DisplaySection.SPECTRUM, mNoiseFloorSlider); installConfigPanel(); } diff --git a/src/main/java/io/github/dsheirer/gui/spectrum/DftSpectralDisplay.java b/src/main/java/io/github/dsheirer/gui/spectrum/DftSpectralDisplay.java index 71f68d40b..08b74938a 100644 --- a/src/main/java/io/github/dsheirer/gui/spectrum/DftSpectralDisplay.java +++ b/src/main/java/io/github/dsheirer/gui/spectrum/DftSpectralDisplay.java @@ -55,6 +55,8 @@ public abstract class DftSpectralDisplay extends StackPane private static final String PEAK_HOLD = "peak.hold"; private static final String SPECTRUM_ENABLED = "spectrum.enabled"; private static final String WATERFALL_ENABLED = "waterfall.enabled"; + private static final String WATERFALL_RANGE = "waterfall.range"; + private static final String WATERFALL_AVERAGING = "waterfall.averaging"; private static final String DIVIDER_POSITION = "divider.position"; private static final String DECIBEL_SCALE = "decibel.scale"; private static final String CONFIG_PINNED = "config.pinned"; @@ -121,6 +123,9 @@ public abstract class DftSpectralDisplay extends StackPane }); mSpectralDisplay.averagingProperty().addListener((ob, ov, nv) -> save(AVERAGING, nv.intValue())); mSpectralDisplay.peakHoldProperty().addListener((ob, ov, nv) -> save(PEAK_HOLD, nv)); + mSpectralDisplay.waterfallRangeProperty().addListener((ob, ov, nv) -> save(WATERFALL_RANGE, nv.intValue())); + mSpectralDisplay.waterfallAveragingProperty().addListener((ob, ov, nv) -> + save(WATERFALL_AVERAGING, nv.intValue())); mSpectralDisplay.dividerPositionProperty().addListener((ob, ov, nv) -> save(DIVIDER_POSITION, String.valueOf(nv.doubleValue()))); mDecibelLayer.visibleProperty().addListener((ob, ov, nv) -> save(DECIBEL_SCALE, nv)); @@ -205,6 +210,12 @@ public abstract class DftSpectralDisplay extends StackPane mSpectralDisplay.averagingProperty().set(Math.max(SpectralDisplay.AVERAGING_MINIMUM, Math.min(SpectralDisplay.AVERAGING_MAXIMUM, averaging))); mSpectralDisplay.peakHoldProperty().set(properties.get(key(PEAK_HOLD), false)); + mSpectralDisplay.waterfallRangeProperty().set(Math.max(WaterfallScaler.RANGE_MINIMUM, + Math.min(WaterfallScaler.RANGE_MAXIMUM, properties.get(key(WATERFALL_RANGE), + WaterfallScaler.RANGE_DEFAULT)))); + mSpectralDisplay.waterfallAveragingProperty().set(Math.max(WaterfallScaler.AVERAGING_MINIMUM, + Math.min(WaterfallScaler.AVERAGING_MAXIMUM, properties.get(key(WATERFALL_AVERAGING), + WaterfallScaler.AVERAGING_DEFAULT)))); mDecibelLayer.visibleProperty().set(properties.get(key(DECIBEL_SCALE), true)); try diff --git a/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplay.java b/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplay.java index cabc1f0d6..a4ab235c0 100644 --- a/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplay.java +++ b/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplay.java @@ -42,6 +42,8 @@ import javafx.beans.property.SimpleIntegerProperty; import javafx.beans.property.SimpleObjectProperty; import javafx.beans.property.SimpleStringProperty; import javafx.beans.property.StringProperty; +import javafx.geometry.Insets; +import javafx.geometry.Pos; import javafx.geometry.Orientation; import javafx.geometry.VPos; import javafx.scene.Cursor; @@ -104,6 +106,10 @@ public class SpectralDisplay extends StackPane private final SplitPane mSplitPane = new SplitPane(); private final CanvasPane mSpectrumPane = new CanvasPane(DisplaySection.SPECTRUM); private final CanvasPane mWaterfallPane = new CanvasPane(DisplaySection.WATERFALL); + //Each section's canvas with overlay controls stacked on top + private final StackPane mSpectrumSection = new StackPane(mSpectrumPane); + private final StackPane mWaterfallSection = new StackPane(mWaterfallPane); + private final EdgeSlider mWaterfallRangeSlider; private final StackPane mDisabledPane = new StackPane(); private final BooleanProperty mSpectrumEnabled = new SimpleBooleanProperty(true); @@ -112,6 +118,8 @@ public class SpectralDisplay extends StackPane private final IntegerProperty mAveraging = new SimpleIntegerProperty(AVERAGING_DEFAULT); private final BooleanProperty mPeakHold = new SimpleBooleanProperty(false); private final DoubleProperty mDividerPosition = new SimpleDoubleProperty(0.5); + private final IntegerProperty mWaterfallRange = new SimpleIntegerProperty(WaterfallScaler.RANGE_DEFAULT); + private final IntegerProperty mWaterfallAveraging = new SimpleIntegerProperty(WaterfallScaler.AVERAGING_DEFAULT); private final StringProperty mMessage = new SimpleStringProperty(); //Values read on the DFT results thread @@ -119,6 +127,7 @@ public class SpectralDisplay extends StackPane private volatile boolean mWaterfallActive = true; private volatile boolean mWaterfallPausedFlag = false; private final SpectrumAverager mAverager = new SpectrumAverager(); + private final WaterfallScaler mWaterfallScaler = new WaterfallScaler(); //Hand off from the DFT results thread to the JavaFX thread private final AtomicReference mLatestSpectrum = new AtomicReference<>(); @@ -133,8 +142,10 @@ public class SpectralDisplay extends StackPane private WritableImage[] mWaterfallTiles; private int mWaterfallWidth; private int mWaterfallHeight; - private byte[] mWaterfallIndexes; + private byte[] mWaterfallLevels; private int[] mWaterfallPixels; + //ARGB color for each waterfall level code, for the current theme and range. Null when it needs to be rebuilt. + private int[] mWaterfallColors; private int mWaterfallWriteRow = 0; private double[] mPolygonX = new double[0]; private double[] mPolygonY = new double[0]; @@ -167,6 +178,37 @@ public class SpectralDisplay extends StackPane themeChanged(disabledLabel); getChildren().addAll(mDisabledPane, mSplitPane); setMinSize(0, 0); + mSpectrumSection.setMinSize(0, 0); + mWaterfallSection.setMinSize(0, 0); + + //Waterfall gain slider along the right edge of the waterfall. The slider value is inverted so that moving it + //up narrows the dB range, which raises the contrast of weak signals. + int rangeSum = WaterfallScaler.RANGE_MINIMUM + WaterfallScaler.RANGE_MAXIMUM; + mWaterfallRangeSlider = new EdgeSlider("Gain", "Waterfall gain: dB range from the noise floor to the top " + + "of the color palette. Higher settings use a smaller range, which gives weak signals more contrast " + + "against the noise and saturates strong signals sooner.", WaterfallScaler.RANGE_MINIMUM, + WaterfallScaler.RANGE_MAXIMUM, 1, value -> (rangeSum - Math.round(value)) + " dB"); + mWaterfallRangeSlider.valueProperty().set(rangeSum - mWaterfallRange.get()); + mWaterfallRangeSlider.valueProperty().addListener((ob, ov, nv) -> + mWaterfallRange.set(rangeSum - (int)Math.round(nv.doubleValue()))); + mWaterfallRange.addListener((ob, ov, nv) -> { + int range = Math.max(WaterfallScaler.RANGE_MINIMUM, Math.min(WaterfallScaler.RANGE_MAXIMUM, + nv.intValue())); + + if(range != nv.intValue()) + { + mWaterfallRange.set(range); + return; + } + + mWaterfallRangeSlider.valueProperty().set(rangeSum - range); + mWaterfallColors = null; + repaintWaterfallImage(); + }); + StackPane.setAlignment(mWaterfallRangeSlider, Pos.CENTER_RIGHT); + mWaterfallSection.getChildren().add(mWaterfallRangeSlider); + + mWaterfallAveraging.addListener((ob, ov, nv) -> mWaterfallScaler.setAveraging(nv.intValue())); mSpectrumEnabled.addListener((ob, ov, nv) -> updateSections()); mWaterfallEnabled.addListener((ob, ov, nv) -> updateSections()); @@ -261,6 +303,7 @@ public class SpectralDisplay extends StackPane SpectralDisplayTheme theme = getTheme(); mDisabledPane.setBackground(new Background(new BackgroundFill(theme.getBackground(), null, null))); disabledLabel.setTextFill(theme.getLine()); + mWaterfallColors = null; repaintWaterfallImage(); requestRender(); } @@ -357,6 +400,42 @@ public class SpectralDisplay extends StackPane return mPeakHold; } + /** + * Waterfall dB range from the noise floor to the top of the color palette, from WaterfallScaler.RANGE_MINIMUM to + * RANGE_MAXIMUM. Smaller ranges give weak signals more contrast. JavaFX thread only. + */ + public IntegerProperty waterfallRangeProperty() + { + return mWaterfallRange; + } + + /** + * Number of DFT frames averaged into each waterfall row, from WaterfallScaler.AVERAGING_MINIMUM to + * AVERAGING_MAXIMUM. Averaging steadies the noise floor so weak signals stand out, but the waterfall scrolls + * more slowly. + */ + public IntegerProperty waterfallAveragingProperty() + { + return mWaterfallAveraging; + } + + /** + * Waterfall gain slider along the right edge of the waterfall section. + */ + public EdgeSlider getWaterfallRangeSlider() + { + return mWaterfallRangeSlider; + } + + /** + * Adds a control on top of the spectrum or the waterfall section, for example an EdgeSlider. Set its StackPane + * alignment and margin before adding it. The control is hidden with its section. + */ + public void addSectionOverlay(DisplaySection section, javafx.scene.Node node) + { + (section == DisplaySection.SPECTRUM ? mSpectrumSection : mWaterfallSection).getChildren().add(node); + } + /** * Divider position (0 - 1.0) between the spectrum and the waterfall when both are showing. */ @@ -395,6 +474,7 @@ public class SpectralDisplay extends StackPane public void clear() { mAverager.reset(); + mWaterfallScaler.reset(); mLatestSpectrum.set(null); mWaterfallRows.clear(); @@ -412,10 +492,11 @@ public class SpectralDisplay extends StackPane return; } - //The first DFT results on startup can be NaN or infinite + //The first DFT results on startup can be NaN or infinite - drop them. Replacing them with zeros would add + //full scale (0 dBFS) values to the spectrum averaging and the waterfall floor tracking. if(Float.isNaN(bins[0]) || Float.isInfinite(bins[0])) { - bins = new float[bins.length]; + return; } if(mSpectrumActive) @@ -425,11 +506,16 @@ public class SpectralDisplay extends StackPane if(mWaterfallActive && !mWaterfallPausedFlag) { - mWaterfallRows.offer(toWaterfallRow(bins)); + byte[] row = mWaterfallScaler.process(bins); - while(mWaterfallRows.size() > WATERFALL_QUEUE_LIMIT) + if(row != null) { - mWaterfallRows.poll(); + mWaterfallRows.offer(row); + + while(mWaterfallRows.size() > WATERFALL_QUEUE_LIMIT) + { + mWaterfallRows.poll(); + } } } } @@ -452,33 +538,7 @@ public class SpectralDisplay extends StackPane mLatestSpectrum.set(null); mWaterfallRows.clear(); mWaterfallTiles = null; - mWaterfallIndexes = null; - } - - /** - * Converts the DFT results to a row of waterfall intensity indexes (0 - 255). Each bin is scaled relative to the - * average bin value so the noise floor stays at the bottom of the palette regardless of tuner gain. - */ - private static byte[] toWaterfallRow(float[] bins) - { - double sum = 0.0; - - for(float bin: bins) - { - sum += bin; - } - - float average = (float)(sum / bins.length) - 1.0f; - float scale = 256.0f / average; - byte[] row = new byte[bins.length]; - - for(int x = 0; x < bins.length; x++) - { - int value = (int)((average - bins[x]) * scale); - row[x] = (byte)Math.max(0, Math.min(255, value)); - } - - return row; + mWaterfallLevels = null; } /** @@ -491,11 +551,11 @@ public class SpectralDisplay extends StackPane mSpectrumActive = spectrum; mWaterfallActive = waterfall; - List items = new ArrayList<>(); + List items = new ArrayList<>(); if(spectrum) { - items.add(mSpectrumPane); + items.add(mSpectrumSection); } else { @@ -505,13 +565,16 @@ public class SpectralDisplay extends StackPane if(waterfall) { - items.add(mWaterfallPane); + items.add(mWaterfallSection); } else { mWaterfallRows.clear(); } + //Keep the waterfall slider below the configuration panel tab when the waterfall is at the top + StackPane.setMargin(mWaterfallRangeSlider, new Insets(spectrum ? 8 : 44, 0, 8, 0)); + mSplitPane.getItems().setAll(items); mSplitPane.setVisible(!items.isEmpty()); @@ -543,7 +606,7 @@ public class SpectralDisplay extends StackPane if(mWaterfallTiles != null) { mWaterfallTiles = null; - mWaterfallIndexes = null; + mWaterfallLevels = null; mWaterfallWriteRow = 0; } @@ -581,8 +644,8 @@ public class SpectralDisplay extends StackPane /** * Writes the row into the waterfall ring buffer. The newest row is at mWaterfallWriteRow and older rows follow - * it, wrapping around the end of the image. The intensity indexes are kept alongside the image so the history - * can be recolored when the theme changes. + * it, wrapping around the end of the image. The level codes are kept alongside the image so the history + * can be recolored when the theme or the waterfall range changes. */ private void writeWaterfallRow(byte[] row) { @@ -590,7 +653,7 @@ public class SpectralDisplay extends StackPane if(mWaterfallTiles == null || mWaterfallWidth != row.length) { - mWaterfallIndexes = new byte[row.length * rows]; + mWaterfallLevels = new byte[row.length * rows]; createWaterfallTiles(row.length, rows); mWaterfallWriteRow = 0; repaintWaterfallImage(); @@ -602,7 +665,7 @@ public class SpectralDisplay extends StackPane int width = row.length; mWaterfallWriteRow = (mWaterfallWriteRow - 1 + mWaterfallHeight) % mWaterfallHeight; - System.arraycopy(row, 0, mWaterfallIndexes, mWaterfallWriteRow * width, width); + System.arraycopy(row, 0, mWaterfallLevels, mWaterfallWriteRow * width, width); writeWaterfallPixels(mWaterfallWriteRow); } @@ -625,7 +688,7 @@ public class SpectralDisplay extends StackPane } /** - * Colors one row of the waterfall image tiles from the stored intensity indexes. + * Colors one row of the waterfall image tiles from the stored level codes. */ private void writeWaterfallPixels(int imageRow) { @@ -636,12 +699,12 @@ public class SpectralDisplay extends StackPane mWaterfallPixels = new int[width]; } - SpectralDisplayTheme theme = getTheme(); + int[] colors = getWaterfallColors(); int offset = imageRow * width; for(int x = 0; x < width; x++) { - mWaterfallPixels[x] = theme.getWaterfallColor(mWaterfallIndexes[offset + x]); + mWaterfallPixels[x] = colors[mWaterfallLevels[offset + x] & 0xFF]; } for(int tile = 0; tile < mWaterfallTiles.length; tile++) @@ -653,11 +716,33 @@ public class SpectralDisplay extends StackPane } /** - * Recolors the whole waterfall image from the stored intensity indexes using the current theme. + * ARGB color for each waterfall level code, for the current theme and range. + */ + private int[] getWaterfallColors() + { + if(mWaterfallColors == null) + { + SpectralDisplayTheme theme = getTheme(); + int range = mWaterfallRange.get(); + int[] colors = new int[256]; + + for(int level = 0; level < colors.length; level++) + { + colors[level] = theme.getWaterfallColor(WaterfallScaler.paletteIndex(level, range)); + } + + mWaterfallColors = colors; + } + + return mWaterfallColors; + } + + /** + * Recolors the whole waterfall image from the stored level codes using the current theme and range. */ private void repaintWaterfallImage() { - if(mWaterfallTiles != null && mWaterfallIndexes != null) + if(mWaterfallTiles != null && mWaterfallLevels != null) { for(int y = 0; y < mWaterfallHeight; y++) { @@ -689,10 +774,10 @@ public class SpectralDisplay extends StackPane for(int y = 0; y < previousHeight; y++) { int source = (mWaterfallWriteRow + y) % previousHeight; - System.arraycopy(mWaterfallIndexes, source * width, indexes, y * width, width); + System.arraycopy(mWaterfallLevels, source * width, indexes, y * width, width); } - mWaterfallIndexes = indexes; + mWaterfallLevels = indexes; createWaterfallTiles(width, rows); mWaterfallWriteRow = 0; repaintWaterfallImage(); diff --git a/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplayConfigPanel.java b/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplayConfigPanel.java index 26d77b0d6..b274d6b1b 100644 --- a/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplayConfigPanel.java +++ b/src/main/java/io/github/dsheirer/gui/spectrum/SpectralDisplayConfigPanel.java @@ -353,6 +353,27 @@ public class SpectralDisplayConfigPanel extends VBox "falling slowly")); row = addRow(grid, row, peakHold.label(), peakHold.control()); + //Waterfall + grid.add(sectionLabel("Waterfall"), 0, row++, 2, 1); + ComboBox waterfallAveraging = new ComboBox<>(); + for(int frames = WaterfallScaler.AVERAGING_MINIMUM; frames <= WaterfallScaler.AVERAGING_MAXIMUM; frames++) + { + waterfallAveraging.getItems().add(frames); + } + waterfallAveraging.setMaxWidth(Double.MAX_VALUE); + waterfallAveraging.setConverter(converter(frames -> frames == 1 ? "Off" : frames + " frames")); + waterfallAveraging.setValue(mSpectralDisplay.waterfallAveragingProperty().get()); + waterfallAveraging.valueProperty().addListener((ob, ov, nv) -> { + if(nv != null) + { + mSpectralDisplay.waterfallAveragingProperty().set(nv); + } + }); + waterfallAveraging.setTooltip(new Tooltip("FFT frames averaged into each waterfall row. Averaging steadies " + + "the noise floor so weak signals stand out, but the waterfall scrolls more slowly.")); + trackPopup(waterfallAveraging.showingProperty()); + row = addRow(grid, row, "Averaging", waterfallAveraging); + //Layer settings for(SpectralDisplayLayer layer: mSpectralDisplay.getLayers()) { diff --git a/src/main/java/io/github/dsheirer/gui/spectrum/WaterfallPalette.java b/src/main/java/io/github/dsheirer/gui/spectrum/WaterfallPalette.java index d60b4d7d8..525efe5a3 100644 --- a/src/main/java/io/github/dsheirer/gui/spectrum/WaterfallPalette.java +++ b/src/main/java/io/github/dsheirer/gui/spectrum/WaterfallPalette.java @@ -33,44 +33,31 @@ public class WaterfallPalette } /** - * Palette of the original Swing waterfall: dark blue noise floor, a blue to yellow ramp, yellow fading to orange, - * then red. + * Palette based on the original Swing waterfall colors: a dark to bright blue ramp, a blue to yellow ramp, yellow + * fading to orange, then red. The blue ramp covers the bottom quarter of the palette, where the waterfall places + * the noise floor, so the noise stays blue and weak signals stand out from it. */ public static int[] classic() { int[] palette = new int[SIZE]; - for(int x = 0; x < 16; x++) + for(int x = 0; x < 64; x++) { - palette[x] = argb(0, 0, 127); + palette[x] = argb(0, 0, blend(64, 191, x / 63.0)); } - for(int x = 16; x < 32; x++) + for(int x = 64; x < 100; x++) { - palette[x] = argb(0, 0, 191); + double t = (x - 64) / 36.0; + palette[x] = argb(blend(0, 255, t), blend(0, 255, t), blend(191, 0, t)); } - int r = 0; - int g = 0; - int b = 191; - - for(int x = 32; x < 60; x++) + for(int x = 100; x < 220; x++) { - palette[x] = argb(r, g, b); - r += 9; - g += 9; - b -= 6; + palette[x] = argb(255, blend(255, 0, (x - 100) / 120.0), 0); } - g = 255; - - for(int x = 60; x < 188; x++) - { - palette[x] = argb(255, g, 0); - g -= 2; - } - - for(int x = 188; x < SIZE; x++) + for(int x = 220; x < SIZE; x++) { palette[x] = argb(255, 0, 0); } @@ -78,6 +65,11 @@ public class WaterfallPalette return palette; } + private static int blend(int from, int to, double fraction) + { + return (int)Math.round(from + (to - from) * fraction); + } + /** * Palette that blends linearly between evenly spaced colors. * @param colors web color strings (for example #440154), lowest intensity first diff --git a/src/main/java/io/github/dsheirer/gui/spectrum/WaterfallScaler.java b/src/main/java/io/github/dsheirer/gui/spectrum/WaterfallScaler.java new file mode 100644 index 000000000..6ea8a1f2a --- /dev/null +++ b/src/main/java/io/github/dsheirer/gui/spectrum/WaterfallScaler.java @@ -0,0 +1,289 @@ +/* + * ***************************************************************************** + * Copyright (C) 2014-2026 Dennis Sheirer + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see + * **************************************************************************** + */ + +package io.github.dsheirer.gui.spectrum; + +import java.util.Arrays; + +/** + * Converts DFT results in dB to rows of waterfall level codes, and level codes to palette indexes. + * + * Optionally averages several DFT frames (in linear power) into each row. Averaging reduces the random variation of + * the noise bins (about 5.6 dB for a single frame), which is the only thing that makes weak signals statistically + * easier to see, at the cost of fewer rows per second. + * + * The noise floor reference is a low percentile of the bins, so signals that fill much of the span don't raise it, + * smoothed across rows so the waterfall background doesn't flicker. + * + * Each row stores a level code per bin: the bin level relative to the floor reference in LEVEL_STEP_DB steps. The + * level codes are mapped to palette indexes over a dB range above the floor (see paletteIndex()) when the row is + * colored, so the range can change and the waterfall history can be recolored without the original DFT results. + * + * Not thread safe: process() on the DFT results thread only. reset() and setAveraging() are safe from any thread. + */ +public class WaterfallScaler +{ + public static final int RANGE_MINIMUM = 20; + public static final int RANGE_MAXIMUM = 80; + public static final int RANGE_DEFAULT = 45; + public static final int AVERAGING_MINIMUM = 1; + public static final int AVERAGING_MAXIMUM = 4; + public static final int AVERAGING_DEFAULT = 2; + + //Percentile of the bins used as the noise floor reference. Robust to signals in up to 75% of the bins. + static final double FLOOR_PERCENTILE = 0.25; + //Smoothing applied to the floor reference each row: about 5 rows. The percentile barely varies from row to row, + //so this mostly limits jumps from bursts of signals while still following tuner gain changes quickly. + static final float FLOOR_SMOOTHING = 0.2f; + //Floor reference changes larger than this jump straight to the new level instead of smoothing, for example when + //the first samples arrive after DFT frames of an empty buffer (-196 dB), or after a tuner or gain change. + static final float FLOOR_JUMP_DB = 10.0f; + //Level code resolution and the level code of the floor reference: codes cover -8 dB to +94 dB from the floor, + //which covers the palette at the maximum range. + static final float LEVEL_STEP_DB = 0.4f; + static final int FLOOR_LEVEL = 20; + //Palette index for the floor reference. Noise bins spread above the 25th percentile, so this places the noise in + //the lower part of the palette as texture with only the weakest noise bins at the background color. + static final float FLOOR_INDEX = 16.0f; + + private static final float DB_TO_LN_POWER = (float)(Math.log(10.0) / 10.0); + + private float mFloor = Float.NaN; + private volatile boolean mResetRequested; + private volatile int mAveraging = AVERAGING_DEFAULT; + private float[] mScratch = new float[0]; + private float[] mPowerSum = new float[0]; + private float[] mAverage = new float[0]; + private int mFrameCount; + + /** + * Restarts floor tracking and frame averaging on the next frame, for example after the source changes. Safe to + * call from any thread. + */ + public void reset() + { + mResetRequested = true; + } + + /** + * Sets the number of DFT frames averaged into each waterfall row. Safe to call from any thread. + * @param frames from AVERAGING_MINIMUM to AVERAGING_MAXIMUM + */ + public void setAveraging(int frames) + { + mAveraging = Math.max(AVERAGING_MINIMUM, Math.min(AVERAGING_MAXIMUM, frames)); + } + + /** + * Current noise floor reference in dB, or NaN before the first row. + */ + public float getFloor() + { + return mFloor; + } + + /** + * Adds the DFT results to the current row. + * @param bins in dB + * @return the row of level codes (unsigned bytes) when the row is complete, otherwise null + */ + public byte[] process(float[] bins) + { + if(mResetRequested) + { + mResetRequested = false; + mFloor = Float.NaN; + mFrameCount = 0; + } + + int frames = mAveraging; + + if(frames <= 1 && mFrameCount == 0) + { + return levels(bins); + } + + if(mPowerSum.length != bins.length) + { + mPowerSum = new float[bins.length]; + mAverage = new float[bins.length]; + mFrameCount = 0; + } + + if(mFrameCount == 0) + { + Arrays.fill(mPowerSum, 0.0f); + } + + for(int x = 0; x < bins.length; x++) + { + mPowerSum[x] += (float)Math.exp(bins[x] * DB_TO_LN_POWER); + } + + mFrameCount++; + + //The averaging can drop below the frames already summed - complete the row with what has been summed + if(mFrameCount < frames) + { + return null; + } + + float scale = 1.0f / mFrameCount; + + for(int x = 0; x < bins.length; x++) + { + mAverage[x] = (float)(10.0 * Math.log10(mPowerSum[x] * scale)); + } + + mFrameCount = 0; + return levels(mAverage); + } + + /** + * Updates the floor reference and converts the bins to level codes. + */ + private byte[] levels(float[] bins) + { + float percentile = percentile(bins); + + if(Float.isNaN(mFloor) || Float.isInfinite(mFloor) || Math.abs(percentile - mFloor) > FLOOR_JUMP_DB) + { + mFloor = percentile; + } + else + { + mFloor += (percentile - mFloor) * FLOOR_SMOOTHING; + } + + byte[] row = new byte[bins.length]; + float floor = mFloor; + + for(int x = 0; x < bins.length; x++) + { + int level = Math.round((bins[x] - floor) / LEVEL_STEP_DB) + FLOOR_LEVEL; + row[x] = (byte)Math.max(0, Math.min(255, level)); + } + + return row; + } + + /** + * Palette index for a level code. + * @param level code (0 - 255) + * @param range in dB from the noise floor reference to the top of the palette. Smaller ranges give weak signals + * more contrast against the noise and saturate strong signals sooner. + * @return palette index (0 - 255) + */ + public static int paletteIndex(int level, double range) + { + double db = (level - FLOOR_LEVEL) * LEVEL_STEP_DB; + long index = Math.round(db * (WaterfallPalette.SIZE - 1) / range + FLOOR_INDEX); + return (int)Math.max(0, Math.min(WaterfallPalette.SIZE - 1, index)); + } + + /** + * Floor reference percentile of the bins, using quickselect on a scratch copy. + */ + private float percentile(float[] bins) + { + if(mScratch.length != bins.length) + { + mScratch = new float[bins.length]; + } + + System.arraycopy(bins, 0, mScratch, 0, bins.length); + return select(mScratch, (int)(FLOOR_PERCENTILE * (bins.length - 1))); + } + + /** + * Quickselect: the k-th smallest value, partially reordering the array. + */ + static float select(float[] values, int k) + { + int left = 0; + int right = values.length - 1; + + while(left < right) + { + //Median of three pivot + int middle = (left + right) >>> 1; + + if(values[middle] < values[left]) + { + swap(values, middle, left); + } + + if(values[right] < values[left]) + { + swap(values, right, left); + } + + if(values[right] < values[middle]) + { + swap(values, right, middle); + } + + float pivot = values[middle]; + int i = left; + int j = right; + + while(i <= j) + { + while(values[i] < pivot) + { + i++; + } + + while(values[j] > pivot) + { + j--; + } + + if(i <= j) + { + swap(values, i, j); + i++; + j--; + } + } + + if(k <= j) + { + right = j; + } + else if(k >= i) + { + left = i; + } + else + { + return values[k]; + } + } + + return values[k]; + } + + private static void swap(float[] values, int a, int b) + { + float temp = values[a]; + values[a] = values[b]; + values[b] = temp; + } +} diff --git a/src/test/java/io/github/dsheirer/gui/spectrum/SpectralDisplayThemeTest.java b/src/test/java/io/github/dsheirer/gui/spectrum/SpectralDisplayThemeTest.java index 72ceee47b..8e2cf2409 100644 --- a/src/test/java/io/github/dsheirer/gui/spectrum/SpectralDisplayThemeTest.java +++ b/src/test/java/io/github/dsheirer/gui/spectrum/SpectralDisplayThemeTest.java @@ -39,15 +39,25 @@ public class SpectralDisplayThemeTest } @Test - void classicPaletteMatchesTheOriginalWaterfall() + void classicPaletteUsesTheOriginalWaterfallColors() { int[] palette = WaterfallPalette.classic(); - assertEquals(0xFF00007F, palette[0]); - assertEquals(0xFF0000BF, palette[16]); - assertEquals(0xFFFFFF00, palette[60]); + assertEquals(0xFF0000BF, palette[63]); + assertEquals(0xFFFFFF00, palette[100]); assertEquals(0xFFFF0000, palette[255]); } + @Test + void classicPaletteHasDistinctColorsNearTheNoiseFloor() + { + int[] palette = WaterfallPalette.classic(); + + for(int index = 1; index < 64; index++) + { + assertTrue((palette[index] & 0xFF) > (palette[index - 1] & 0xFF), "index " + index); + } + } + @Test void everyThemeHasAnOpaqueWaterfallAndALabel() { diff --git a/src/test/java/io/github/dsheirer/gui/spectrum/WaterfallScalerTest.java b/src/test/java/io/github/dsheirer/gui/spectrum/WaterfallScalerTest.java new file mode 100644 index 000000000..a411b8bf3 --- /dev/null +++ b/src/test/java/io/github/dsheirer/gui/spectrum/WaterfallScalerTest.java @@ -0,0 +1,312 @@ +/* + * ***************************************************************************** + * Copyright (C) 2014-2026 Dennis Sheirer + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see + * **************************************************************************** + */ + +package io.github.dsheirer.gui.spectrum; + +import java.util.Arrays; +import java.util.Random; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Tests the waterfall noise floor tracking and dB to palette index mapping. + */ +public class WaterfallScalerTest +{ + private static final int BINS = 4096; + + /** + * Noise bins in dB: exponentially distributed power with the given mean power in dB. + */ + private static float[] noise(Random random, float meanDb) + { + float[] bins = new float[BINS]; + + for(int x = 0; x < BINS; x++) + { + double power = -Math.log(1.0 - random.nextDouble()); + bins[x] = (float)(meanDb + 10.0 * Math.log10(power)); + } + + return bins; + } + + private static int index(byte value) + { + return WaterfallScaler.paletteIndex(value & 0xFF, WaterfallScaler.RANGE_DEFAULT); + } + + /** + * Scaler with one DFT frame per row. + */ + private static WaterfallScaler single() + { + WaterfallScaler scaler = new WaterfallScaler(); + scaler.setAveraging(1); + return scaler; + } + + private static double medianIndex(byte[] row, int from, int to) + { + int[] values = new int[to - from]; + + for(int x = from; x < to; x++) + { + values[x - from] = index(row[x]); + } + + Arrays.sort(values); + return values[values.length / 2]; + } + + @Test + void selectFindsTheKthSmallestValue() + { + Random random = new Random(1); + float[] values = new float[1001]; + + for(int x = 0; x < values.length; x++) + { + values[x] = random.nextFloat() * 100 - 50; + } + + float[] sorted = values.clone(); + Arrays.sort(sorted); + + for(int k: new int[]{0, 1, 250, 500, 999, 1000}) + { + assertEquals(sorted[k], WaterfallScaler.select(values.clone(), k), "k " + k); + } + } + + @Test + void contrastDoesNotDependOnTheAbsoluteNoiseFloorLevel() + { + for(float floor: new float[]{-60, -100, -140}) + { + WaterfallScaler scaler = single(); + float[] bins = noise(new Random(2), floor); + + //A 6 dB signal across bins 1000 - 1199 + for(int x = 1000; x < 1200; x++) + { + bins[x] = floor + 6.0f; + } + + byte[] row = scaler.process(bins); + double noiseMedian = medianIndex(row, 0, 1000); + double signal = index(row[1100]); + + //Noise median sits in the lower part of the palette, above the background + assertTrue(noiseMedian > 25 && noiseMedian < 50, "floor " + floor + " noise median " + noiseMedian); + //6 dB signal is 7.6 dB above the noise median (1.6 dB below mean power): about 43 palette steps + assertEquals(43.0, signal - noiseMedian, 3.0, "floor " + floor); + } + } + + /** + * Strong signals in a fraction of the bins move the 25th percentile up the noise distribution: about 1.5 dB at + * 25% occupancy and 3.8 dB (the noise median) at 50% occupancy. A mean of the dB values would move 5 and 10 dB. + */ + @Test + void signalsInMuchOfTheSpanBarelyRaiseTheFloor() + { + float[] noise = noise(new Random(3), -100); + WaterfallScaler empty = single(); + empty.process(noise); + + assertEquals(1.5, occupiedFloor(noise, 0.25) - empty.getFloor(), 0.5); + assertEquals(3.8, occupiedFloor(noise, 0.5) - empty.getFloor(), 0.5); + } + + private static float occupiedFloor(float[] noise, double occupancy) + { + float[] bins = noise.clone(); + + for(int x = 0; x < (int)(BINS * occupancy); x++) + { + bins[x] += 20.0f; + } + + WaterfallScaler scaler = single(); + scaler.process(bins); + return scaler.getFloor(); + } + + @Test + void floorIsSmoothedAcrossRowsJumpsLargeStepsAndResets() + { + WaterfallScaler scaler = single(); + Random random = new Random(4); + scaler.process(noise(random, -100)); + float initial = scaler.getFloor(); + + //A 5 dB step moves the floor only part way on the next row + scaler.process(noise(random, -95)); + float stepped = scaler.getFloor() - initial; + assertTrue(stepped > 0.5 && stepped < 1.5, "stepped " + stepped); + + //A 20 dB step jumps straight to the new level + scaler.process(noise(random, -80)); + assertEquals(initial + 20.0, scaler.getFloor(), 1.0); + + //Reset restarts from the next row + scaler.reset(); + scaler.process(noise(random, -100)); + assertEquals(initial, scaler.getFloor(), 1.0); + } + + @Test + void averagingCompletesARowEveryNFramesWithTheMeanPower() + { + WaterfallScaler scaler = new WaterfallScaler(); + scaler.setAveraging(2); + float[] low = new float[BINS]; + float[] high = new float[BINS]; + java.util.Arrays.fill(low, -100.0f); + java.util.Arrays.fill(high, -100.0f); + + //One bin at -100 dB then -90 dB: mean power is 10 * log10((1 + 10) / 2) = 7.4 dB above -100 dB + low[10] = -100.0f; + high[10] = -90.0f; + + assertNull(scaler.process(low)); + byte[] row = scaler.process(high); + assertNotNull(row); + float level = ((row[10] & 0xFF) - WaterfallScaler.FLOOR_LEVEL) * WaterfallScaler.LEVEL_STEP_DB; + assertEquals(7.4, level, WaterfallScaler.LEVEL_STEP_DB); + + assertNull(scaler.process(low)); + assertNotNull(scaler.process(low)); + } + + /** + * Averaging two frames should cut the noise spread (about 5.6 dB for one frame) to about 3.5 dB, so a weak signal + * stands further out of the noise. + */ + @Test + void averagingSeparatesWeakSignalsFromTheNoise() + { + double single = separation(1); + double averaged = separation(2); + assertTrue(averaged > single * 1.1, "single " + single + " averaged " + averaged); + } + + /** + * Mean level difference between a 3 dB signal and the noise, relative to the noise level spread, in level codes. + */ + private static double separation(int frames) + { + WaterfallScaler scaler = new WaterfallScaler(); + scaler.setAveraging(frames); + Random random = new Random(6); + byte[] row = null; + + while(row == null) + { + float[] bins = noise(random, -100); + + for(int x = 0; x < BINS / 2; x++) + { + double power = -Math.log(1.0 - random.nextDouble()) + Math.pow(10, 0.3); + bins[x] = (float)(-100 + 10.0 * Math.log10(power)); + } + + row = scaler.process(bins); + } + + double[] signal = stats(row, 0, BINS / 2); + double[] noise = stats(row, BINS / 2, BINS); + return (signal[0] - noise[0]) / noise[1]; + } + + private static double[] stats(byte[] row, int from, int to) + { + double sum = 0; + double squares = 0; + + for(int x = from; x < to; x++) + { + int level = row[x] & 0xFF; + sum += level; + squares += level * level; + } + + double mean = sum / (to - from); + return new double[]{mean, Math.sqrt(squares / (to - from) - mean * mean)}; + } + + @Test + void smallerRangesGiveMoreContrast() + { + int level6dB = WaterfallScaler.FLOOR_LEVEL + Math.round(6.0f / WaterfallScaler.LEVEL_STEP_DB); + int floor = WaterfallScaler.paletteIndex(WaterfallScaler.FLOOR_LEVEL, WaterfallScaler.RANGE_DEFAULT); + assertEquals(WaterfallScaler.FLOOR_INDEX, floor, 0.5); + + int wide = WaterfallScaler.paletteIndex(level6dB, WaterfallScaler.RANGE_MAXIMUM) - floor; + int normal = WaterfallScaler.paletteIndex(level6dB, WaterfallScaler.RANGE_DEFAULT) - floor; + int narrow = WaterfallScaler.paletteIndex(level6dB, WaterfallScaler.RANGE_MINIMUM) - floor; + assertTrue(wide < normal && normal < narrow, wide + " " + normal + " " + narrow); + assertEquals(6.0 * 255 / WaterfallScaler.RANGE_DEFAULT, normal, 1.0); + + //The level codes reach the top of the palette at the widest range + assertEquals(255, WaterfallScaler.paletteIndex(255, WaterfallScaler.RANGE_MAXIMUM)); + } + + /** + * At startup the DFT runs on an empty sample buffer, which converts to -196 dB in every bin. The first rows of + * real noise must not show as strong signals while the floor reference catches up. + */ + @Test + void silentStartupFramesDoNotFlashTheFirstNoiseRows() + { + WaterfallScaler scaler = single(); + float[] silence = new float[BINS]; + Arrays.fill(silence, -196.0f); + + for(int x = 0; x < 3; x++) + { + scaler.process(silence); + } + + Random random = new Random(7); + + for(int x = 0; x < 3; x++) + { + double median = medianIndex(scaler.process(noise(random, -100)), 0, BINS); + assertTrue(median > 25 && median < 50, "row " + x + " noise median index " + median); + } + } + + @Test + void indexesClampToThePalette() + { + WaterfallScaler scaler = single(); + float[] bins = noise(new Random(5), -100); + bins[0] = 0.0f; + bins[1] = -300.0f; + byte[] row = scaler.process(bins); + assertEquals(255, index(row[0])); + assertEquals(0, index(row[1])); + } +}