FourierFiltering.m

classdef FourierFiltering < matlab.apps.AppBase
% FOURIERFILTERING Interactive FFT frequency-domain filtering GUI.
%
%   FourierFiltering removes selected frequency components from spectral data.
%   It mirrors each row, changes it to the frequency domain with an FFT,
%   keeps the selected positive and matching negative frequencies, and changes
%   it back to the original domain. Rows are samples and columns are channels.
%
%   The FourierFiltering app lets users draw the frequencies to keep, inspect
%   the filtered result, apply the calculation to all rows, and export it.
%
%   USAGE:
%       app = FourierFiltering();
%       app = FourierFiltering(spectra);
%       app = FourierFiltering(struct('spectra', spectra, ...
%                                     'wavelengths', wavelength));
%
%   INPUTS:
%       spectra     Numeric, real, finite matrix [nSamples x nChannels].
%       input       Scalar struct with a spectra field and optional
%                   wavelengths field. Channel indices are used by default.
%
%   INPUT AND OUTPUT COMMANDS:
%       app.setInputData(input)  Load a spectra struct programmatically.
%       app.getData()            Return processed data after Apply.
%       delete(app)               Close the application safely.
%
%   EXAMPLE:
%       FourierFiltering_test
%       input.spectra = spectra;
%       input.wavelengths = wavelength;
%       app = FourierFiltering(input);
%       % Draw intervals on the frequency chart, click Apply, then:
%       result = app.getData();
%
%   FREQUENCY UNITS:
%       The filter uses cycles per channel, with a positive
%       frequency range from 0 to 0.5. The wavelength vector is an x-axis
%       for plots and is not used to resample the data.
%
%   REFERENCES:
%
%     - Oppenheim, A.V. & Schafer, R.W. (2010). Discrete-Time Signal
%       Processing, 3rd ed. Pearson. ISBN: 978-0131988422.
%     - Harris, F.J. (1978). On the use of windows for harmonic analysis
%       with the DFT. Proc. IEEE 66(1), 51-83. doi:10.1109/PROC.1978.10837
%
%   SEE ALSO: FourierFilter, DataValidator
%
% Author: Lovelace's Square
% Affiliation: Lovelace's Square
% Date Created: 2026-03-08
% License: MIT
% Reviewed by Lovelace's Square: Yes
% Version: v 3.0

    properties (Access = public)
        UIFigure                matlab.ui.Figure
        HTMLComponent           matlab.ui.control.HTML
    end

    properties (Access = private)
        % Business logic
        Filter                  % FourierFilter instance
        Validator               % DataValidator instance

        % Data
        InputData               % Input data struct
        ProcessedData           % Filtered data struct
        FrequencyVector  double = []
        NumFftPoints     double = 0
        SelectedSampleIndex double = 1

        % Orchestrator sync
        IsOrchestratorWaiting   logical = false
        IsClosed                logical = false

        % UI update sync
        UIUpdateCounter         double = 0

        % Plot limits
        MaxPlotSamples          double = 5000
        MaxPlotWavelengths      double = 100
        MaxPlotBytes            double = 1024^3
        MaxPreviewPlotElements  double = 500000
    end

    % ================================================================
    %  Constructor / Destructor
    % ================================================================
    methods (Access = public)
        function app = FourierFiltering(data)
            createComponents(app);
            initializeBusinessLogic(app);
            registerApp(app, app.UIFigure);
            runStartupFcn(app, @startupFcn);

            if nargin >= 1 && ~isempty(data)
                if isstruct(data) && isfield(data, 'spectra')
                    app.setInputData(data);
                elseif isnumeric(data)
                    s = struct();
                    s.spectra = double(data);
                    s.wavelengths = 1:size(data, 2);
                    app.setInputData(s);
                end
            end

            if nargout == 0
                clear app
            end
        end

        function delete(app)
            % DELETE Close the Fourier filtering window and release resources.
            if ~isempty(app.UIFigure) && isvalid(app.UIFigure)
                delete(app.UIFigure);
            end
        end
    end

    % ================================================================
    %  UI Creation & Initialization
    % ================================================================
    methods (Access = private)

        function createComponents(app)
            app.UIFigure = uifigure('Visible', 'off');
            app.UIFigure.Position = [100 100 1200 800];
            app.UIFigure.Name = 'Fourier Filtering';
            app.UIFigure.Color = [0.91, 0.92, 0.93];
            app.UIFigure.CloseRequestFcn = createCallbackFcn(app, @closeRequest, true);
            app.UIFigure.AutoResizeChildren = 'off';
            app.UIFigure.SizeChangedFcn = createCallbackFcn(app, @figureResized, true);

            app.HTMLComponent = uihtml(app.UIFigure);
            app.HTMLComponent.Position = [1 1 1200 800];

            modulePath = fileparts(mfilename('fullpath'));
            htmlPath = fullfile(modulePath, 'ui', 'fourier_filtering_ui.html');
            app.HTMLComponent.HTMLSource = htmlPath;
            app.HTMLComponent.DataChangedFcn = createCallbackFcn(app, @HTMLDataChanged, true);

            app.UIFigure.Visible = 'on';
        end

        function initializeBusinessLogic(app)
            modulePath = fileparts(mfilename('fullpath'));
            addpath(fullfile(modulePath, 'business_logic'));

            app.Filter = FourierFilter();
            app.Validator = DataValidator();

            app.InputData = [];
            app.ProcessedData = [];
        end

        function startupFcn(app)
            movegui(app.UIFigure, 'center');
            pause(0.3);
            updateHTMLStatus(app, 'Ready. Load spectral data to begin.');
        end

        function figureResized(app, ~, ~)
            pos = app.UIFigure.Position;
            app.HTMLComponent.Position = [1 1 pos(3) pos(4)];
        end
    end

    % ================================================================
    %  HTML Communication
    % ================================================================
    methods (Access = private)

        function HTMLDataChanged(app, ~)
            data = app.HTMLComponent.Data;
            if isempty(data) || ~isstruct(data)
                return;
            end
            if isfield(data, 'source') && strcmp(data.source, 'matlab')
                return;
            end
            if ~isfield(data, 'action')
                return;
            end

            switch data.action
                case 'load_data'
                    loadDataFromWorkspace(app);
                case 'load_variable'
                    loadSelectedVariable(app, char(data.varName));
                case 'preview'
                    previewFiltering(app, data);
                case 'apply'
                    applyFiltering(app, data);
                case 'export'
                    exportData(app);
                case 'do_export'
                    exportData(app, char(data.varName));
                case 'next'
                    resumeOrchestratorIfWaiting(app);
                case 'plot_option'
                    handlePlotOption(app, data);
                case 'preview_plot_option'
                    handlePreviewPlotOption(app, data);
                case 'import_intervals'
                    listIntervalVariables(app);
                case 'load_intervals'
                    loadIntervalsFromWorkspace(app, char(data.varName));
                case 'export_intervals'
                    exportIntervals(app, data);
            end
        end

        function updateHTMLStatus(app, message)
            sendUIUpdate(app, struct('kind', 'status', 'message', message));
        end

        function updateHTMLResults(app, statusMessage)
            if isempty(app.ProcessedData)
                payload = struct('kind', 'results_reset');
                if nargin > 1 && ~isempty(statusMessage)
                    payload.statusMessage = statusMessage;
                end
                sendUIUpdate(app, payload);
                return;
            end

            try
                spectra = app.ProcessedData.spectra;
                [nSamples, nWavelengths] = size(spectra);
                rawBytes = estimatePlotBytes(app, nSamples, nWavelengths);
                memoryExceeded = rawBytes > app.MaxPlotBytes;
                maxElements = double(app.MaxPlotSamples) * double(app.MaxPlotWavelengths);
                totalElements = double(nSamples) * double(nWavelengths);
                tooLargeByElements = totalElements > maxElements;
                tooLarge = tooLargeByElements || memoryExceeded;

                payload = struct( ...
                    'kind', 'filtering_done', ...
                    'nSamples', nSamples, ...
                    'nWavelengths', nWavelengths, ...
                    'tooLarge', tooLarge, ...
                    'tooLargeByElements', tooLargeByElements, ...
                    'memoryExceeded', memoryExceeded, ...
                    'memoryBytes', rawBytes, ...
                    'memoryLimitBytes', app.MaxPlotBytes, ...
                    'totalElements', totalElements, ...
                    'maxElements', maxElements, ...
                    'maxSamples', app.MaxPlotSamples, ...
                    'maxWavelengths', app.MaxPlotWavelengths);

                if ~tooLarge
                    payload.spectra = spectra;
                    payload.wavelengths = app.ProcessedData.wavelengths;
                    payload.plotNote = sprintf('Filtered spectra (%d x %d)', nSamples, nWavelengths);
                end

                if nargin > 1 && ~isempty(statusMessage)
                    payload.statusMessage = statusMessage;
                end

                sendUIUpdate(app, payload);
            catch ME
                fprintf('Error updating results: %s\n', ME.message);
            end
        end

        function sendUIUpdate(app, payload)
            try
                app.UIUpdateCounter = app.UIUpdateCounter + 1;
                payload.source = 'matlab';
                payload.timestamp = app.UIUpdateCounter;
                app.HTMLComponent.Data = payload;
            catch
            end
        end
    end

    % ================================================================
    %  Processing Methods
    % ================================================================
    methods (Access = private)

        function previewFiltering(app, data)
            try
                if isempty(app.InputData)
                    updateHTMLStatus(app, 'No input data available. Load data first.');
                    return;
                end

                intervalsStr = '';
                if isfield(data, 'intervals')
                    intervalsStr = char(data.intervals);
                end

                intervals = app.Filter.parseIntervals(intervalsStr);
                if isempty(intervals) && ~isempty(strtrim(intervalsStr))
                    updateHTMLStatus(app, 'Invalid interval format. Use [low1:high1, low2:high2].');
                    return;
                end

                if ~isempty(intervals)
                    [valid, msg] = app.Validator.validateIntervals(intervals, app.FrequencyVector);
                    if ~valid
                        updateHTMLStatus(app, msg);
                        return;
                    end
                    intervals = app.Filter.mergeRanges(intervals);
                end

                transitionWidth = 0;
                if isfield(data, 'transitionWidth')
                    transitionWidth = double(data.transitionWidth);
                end


                spectra = app.InputData.spectra;
                sampleIndex = round(readSampleIndex(app, data, size(spectra, 1)));
                app.SelectedSampleIndex = sampleIndex;
                sampleSpec = spectra(sampleIndex, :);

                wl = app.InputData.wavelengths;
                if isempty(wl)
                    wl = 1:numel(sampleSpec);
                end

                sampleFiltered = app.Filter.filter(sampleSpec, intervals, ...
                    app.NumFftPoints, app.FrequencyVector, transitionWidth);
                sampleFft = fft(sampleSpec, app.NumFftPoints);
                sampleMagnitude = abs(sampleFft(1:app.NumFftPoints/2+1));
                maxMagnitude = max(sampleMagnitude);
                if maxMagnitude > 0, sampleMagnitude = sampleMagnitude / maxMagnitude; end

                payload = struct( ...
                    'kind', 'preview_done', ...
                    'wavelengths', wl, ...
                    'original', sampleSpec, ...
                    'filtered', sampleFiltered, ...
                    'magnitudeSpectrum', sampleMagnitude, ...
                    'sampleIndex', sampleIndex);
                payload.statusMessage = sprintf('Preview updated for sample %d. Fourier filtering is applied to every sample when Apply is clicked.', sampleIndex);
                sendUIUpdate(app, payload);

            catch ME
                updateHTMLStatus(app, sprintf('Preview error: %s', ME.message));
                fprintf('Error: %s\n', ME.message);
            end
        end

        function applyFiltering(app, data)
            try
                if isempty(app.InputData)
                    updateHTMLStatus(app, 'No input data available. Load data first.');
                    return;
                end

                intervalsStr = '';
                if isfield(data, 'intervals')
                    intervalsStr = char(data.intervals);
                end

                intervals = app.Filter.parseIntervals(intervalsStr);
                if isempty(intervals) && ~isempty(strtrim(intervalsStr))
                    updateHTMLStatus(app, 'Invalid interval format. Use [low1:high1, low2:high2].');
                    return;
                end

                if ~isempty(intervals)
                    [valid, msg] = app.Validator.validateIntervals(intervals, app.FrequencyVector);
                    if ~valid
                        updateHTMLStatus(app, msg);
                        return;
                    end
                    intervals = app.Filter.mergeRanges(intervals);
                end

                transitionWidth = 0;
                if isfield(data, 'transitionWidth')
                    transitionWidth = double(data.transitionWidth);
                end

                spectra = app.InputData.spectra;
                [nRows, nCols] = size(spectra);

                filteredSpectra = zeros(nRows, nCols);
                for r = 1:nRows
                    filteredSpectra(r, :) = app.Filter.filter( ...
                        spectra(r, :), intervals, ...
                        app.NumFftPoints, app.FrequencyVector, transitionWidth);
                end

                % Build output structure
                outData = struct();
                outData.spectra = filteredSpectra;
                outData.wavelengths = app.InputData.wavelengths;
                if isfield(app.InputData, 'sampleNames')
                    outData.sampleNames = app.InputData.sampleNames;
                end
                outData.metadata = struct();
                outData.metadata.method = 'FourierFiltering';
                outData.metadata.intervalsStr = intervalsStr;
                outData.metadata.numFftPoints = app.NumFftPoints;
                outData.metadata.applied = datetime('now');
                if isfield(app.InputData, 'metadata')
                    outData.metadata.originalMetadata = app.InputData.metadata;
                end

                app.ProcessedData = outData;

                updateHTMLResults(app, sprintf('Fourier filtering applied (%d x %d)', nRows, nCols));

            catch ME
                updateHTMLStatus(app, sprintf('Error applying filtering: %s', ME.message));
                fprintf('Error: %s\n', ME.message);
            end
        end

        function exportData(app, varName)
            if isempty(app.ProcessedData)
                updateHTMLStatus(app, 'No filtered data to export.');
                return;
            end

            if nargin < 2 || isempty(varName)
                % Show export dialog in JS
                sendUIUpdate(app, struct('kind', 'show_export_dialog'));
                return;
            end

            try
                if ~isvarname(varName)
                    updateHTMLStatus(app, 'Invalid variable name.');
                    return;
                end
                assignin('base', varName, app.ProcessedData.spectra);
                updateHTMLStatus(app, sprintf('Exported to workspace as ''%s''.', varName));
            catch ME
                updateHTMLStatus(app, sprintf('Export error: %s', ME.message));
            end
        end

        function handlePlotOption(app, data)
            if isempty(app.ProcessedData)
                return;
            end

            mode = '';
            if isfield(data, 'mode')
                mode = lower(char(data.mode));
            end

            spectra = app.ProcessedData.spectra;
            wavelengths = app.ProcessedData.wavelengths;
            [nSamples, nWavelengths] = size(spectra);
            maxElements = double(app.MaxPlotSamples) * double(app.MaxPlotWavelengths);
            rawBytes = estimatePlotBytes(app, nSamples, nWavelengths);

            if rawBytes > app.MaxPlotBytes && strcmp(mode, 'all')
                sendUIUpdate(app, struct('kind', 'plot_disabled', ...
                    'message', 'Dataset exceeds 1 GB payload. Use downsample or do not show.'));
                return;
            end

            switch mode
                case 'none'
                    sendUIUpdate(app, struct('kind', 'plot_disabled', 'message', 'Plot disabled'));

                case 'all'
                    note = sprintf('Showing all %d spectra (may be slow)', nSamples);
                    plotBytes = estimatePlotBytes(app, size(spectra, 1), size(spectra, 2));
                    if plotBytes > app.MaxPlotBytes
                        sendUIUpdate(app, struct('kind', 'plot_disabled', ...
                            'message', 'Preview still exceeds 1 GB. Increase step size.'));
                        return;
                    end
                    payload = struct('kind', 'plot_data', ...
                        'spectra', spectra, ...
                        'wavelengths', wavelengths, ...
                        'plotNote', note, ...
                        'nSamples', nSamples, ...
                        'nWavelengths', nWavelengths);
                    sendUIUpdate(app, payload);

                case 'every'
                    step = 1;
                    if isfield(data, 'step')
                        if isnumeric(data.step)
                            step = max(1, round(data.step));
                        else
                            stepVal = str2double(char(data.step));
                            if ~isnan(stepVal)
                                step = max(1, round(stepVal));
                            end
                        end
                    end

                    rowIdx = 1:step:nSamples;
                    plotSpectra = spectra(rowIdx, :);
                    plotWavelengths = wavelengths;
                    note = sprintf('Showing every %dth spectrum (%d of %d)', step, size(plotSpectra, 1), nSamples);

                    if size(plotSpectra, 1) * size(plotSpectra, 2) > maxElements || nWavelengths > app.MaxPlotWavelengths
                        colStep = max(1, ceil(nWavelengths / app.MaxPlotWavelengths));
                        plotWavelengths = wavelengths(1:colStep:end);
                        plotSpectra = plotSpectra(:, 1:colStep:end);
                        note = sprintf('%s, wavelengths every %d', note, colStep);
                    end

                    plotBytes = estimatePlotBytes(app, size(plotSpectra, 1), size(plotSpectra, 2));
                    if plotBytes > app.MaxPlotBytes
                        sendUIUpdate(app, struct('kind', 'plot_disabled', ...
                            'message', 'Preview still exceeds 1 GB. Increase step size.'));
                        return;
                    end
                    payload = struct('kind', 'plot_data', ...
                        'spectra', plotSpectra, ...
                        'wavelengths', plotWavelengths, ...
                        'plotNote', note, ...
                        'nSamples', nSamples, ...
                        'nWavelengths', nWavelengths);
                    sendUIUpdate(app, payload);

                otherwise
                    updateHTMLStatus(app, sprintf('Unknown plot option: %s', mode));
            end
        end

        function exportIntervals(app, data)
            if isempty(app.InputData)
                updateHTMLStatus(app, 'Load data before exporting intervals.');
                return;
            end
            if ~isfield(data, 'varName') || ~isfield(data, 'intervals')
                updateHTMLStatus(app, 'Interval export requires a variable name and interval values.');
                return;
            end

            varName = strtrim(char(data.varName));
            if ~isvarname(varName)
                updateHTMLStatus(app, 'Invalid interval variable name.');
                return;
            end

            intervalsStr = char(data.intervals);
            intervals = app.Filter.parseIntervals(intervalsStr);
            if isempty(intervals)
                updateHTMLStatus(app, 'Add at least one valid interval before exporting.');
                return;
            end

            [valid, msg] = app.Validator.validateIntervals(intervals, app.FrequencyVector);
            if ~valid
                updateHTMLStatus(app, msg);
                return;
            end
            intervals = app.Filter.mergeRanges(intervals);

            try
                assignin('base', varName, intervals);
                sendUIUpdate(app, struct( ...
                    'kind', 'intervals_exported', ...
                    'varName', varName, ...
                    'message', sprintf('Exported %d interval(s) as ''%s''.', size(intervals, 1), varName)));
            catch ME
                updateHTMLStatus(app, sprintf('Interval export error: %s', ME.message));
            end
        end

        function handlePreviewPlotOption(app, data)
            if isempty(app.InputData)
                updateHTMLStatus(app, 'Load data before changing preview plot options.');
                return;
            end

            mode = 'none';
            if isfield(data, 'mode')
                mode = lower(char(data.mode));
            end

            if strcmp(mode, 'none')
                sendUIUpdate(app, struct('kind', 'preview_plot_disabled', ...
                    'message', 'Showing the selected sample only.'));
                return;
            end

            if ~strcmp(mode, 'all')
                updateHTMLStatus(app, sprintf('Unknown preview plot option: %s', mode));
                return;
            end

            spectra = app.InputData.spectra;
            totalElements = double(numel(spectra));
            if totalElements > app.MaxPreviewPlotElements
                sendUIUpdate(app, struct( ...
                    'kind', 'preview_plot_unavailable', ...
                    'message', sprintf(['Show all was not enabled because the dataset has ' ...
                        '%.0f points; the safe preview limit is %.0f.'], ...
                        totalElements, app.MaxPreviewPlotElements), ...
                    'totalElements', totalElements, ...
                    'maxElements', app.MaxPreviewPlotElements));
                return;
            end

            sendUIUpdate(app, struct( ...
                'kind', 'preview_plot_data', ...
                'spectra', spectra, ...
                'nSamples', size(spectra, 1), ...
                'nWavelengths', size(spectra, 2), ...
                'message', sprintf('Showing all %d input spectra.', size(spectra, 1))));
        end
    end

    % ================================================================
    %  Helpers
    % ================================================================
    methods (Access = private)

        function loadDataFromWorkspace(app)
            % Send variable list to HTML for selection (no native dialog)
            vars = evalin('base', 'whos');
            varList = {};

            for k = 1:numel(vars)
                v = vars(k);
                if numel(v.size) == 2 && ismember(v.class, ...
                        {'double','single','uint8','uint16','uint32','uint64','int8','int16','int32','int64'}) ...
                        && all(v.size >= 2)
                    sizeStr = strjoin(arrayfun(@num2str, v.size, 'UniformOutput', false), 'x');
                    varList{end+1} = struct('name', v.name, 'size', sizeStr); %#ok<AGROW>
                    continue;
                end

                if strcmp(v.class, 'struct')
                    try
                        s = evalin('base', v.name);
                    catch
                        continue;
                    end
                    if isstruct(s) && isscalar(s) && isfield(s, 'spectra') && ...
                            isnumeric(s.spectra) && ismatrix(s.spectra) && ~isempty(s.spectra)
                        sizeStr = strjoin(arrayfun(@num2str, size(s.spectra), 'UniformOutput', false), 'x');
                        varList{end+1} = struct('name', v.name, 'size', [sizeStr ' (struct)']); %#ok<AGROW>
                    end
                end
            end

            if isempty(varList)
                updateHTMLStatus(app, 'No compatible workspace variable found.');
                return;
            end

            payload = struct('kind', 'show_var_list');
            payload.variables = varList;
            sendUIUpdate(app, payload);
        end

        function loadSelectedVariable(app, varName)
            if ~isvarname(varName)
                updateHTMLStatus(app, 'Invalid variable name.');
                return;
            end
            raw = evalin('base', varName);

            dataStruct = struct();
            if isstruct(raw) && isfield(raw, 'spectra')
                dataStruct = raw;
                spectra = raw.spectra;
            else
                spectra = raw;
            end

            if ~isnumeric(spectra) || ~ismatrix(spectra) || isempty(spectra)
                updateHTMLStatus(app, sprintf('Variable "%s" must be a non-empty numeric 2-D matrix.', varName));
                return;
            end

            spectra = double(spectra);
            [valid, msg] = app.Validator.validateMatrix(spectra);
            if ~valid
                updateHTMLStatus(app, msg);
                return;
            end

            dataStruct.spectra = spectra;
            if ~isfield(dataStruct, 'wavelengths') || isempty(dataStruct.wavelengths)
                dataStruct.wavelengths = 1:size(spectra, 2);
            end

            try
                setInputData(app, dataStruct);
            catch ME
                updateHTMLStatus(app, ME.message);
            end
        end

        function listIntervalVariables(app)
            if isempty(app.InputData)
                updateHTMLStatus(app, 'Load data before importing intervals.');
                return;
            end

            vars = evalin('base', 'whos');
            numericClasses = {'double','single','uint8','uint16','uint32','uint64', ...
                'int8','int16','int32','int64'};
            varList = {};

            for k = 1:numel(vars)
                v = vars(k);
                if numel(v.size) ~= 2 || v.size(1) < 1 || v.size(2) ~= 2 || ...
                        ~ismember(v.class, numericClasses)
                    continue;
                end

                try
                    candidate = evalin('base', v.name);
                    candidate = double(candidate);
                    if ~isreal(candidate) || any(~isfinite(candidate(:)))
                        continue;
                    end
                    [valid, ~] = app.Validator.validateIntervals(candidate, app.FrequencyVector);
                    if ~valid
                        continue;
                    end
                catch
                    continue;
                end

                sizeStr = sprintf('%dx2', v.size(1));
                varList{end+1} = struct('name', v.name, 'size', sizeStr); %#ok<AGROW>
            end

            if isempty(varList)
                updateHTMLStatus(app, 'No valid M-by-2 interval matrix was found in the workspace.');
                return;
            end

            sendUIUpdate(app, struct('kind', 'show_interval_var_list', ...
                'variables', {varList}));
        end

        function loadIntervalsFromWorkspace(app, varName)
            if isempty(app.InputData)
                updateHTMLStatus(app, 'Load data before importing intervals.');
                return;
            end
            if ~isvarname(varName)
                updateHTMLStatus(app, 'Invalid interval variable name.');
                return;
            end

            try
                intervals = evalin('base', varName);
                if ~isnumeric(intervals) || ~isreal(intervals) || ...
                        isempty(intervals) || size(intervals, 2) ~= 2 || ...
                        any(~isfinite(intervals(:)))
                    updateHTMLStatus(app, 'Imported intervals must be a finite real M-by-2 numeric matrix.');
                    return;
                end
                intervals = double(intervals);
                [valid, msg] = app.Validator.validateIntervals(intervals, app.FrequencyVector);
                if ~valid
                    updateHTMLStatus(app, msg);
                    return;
                end
                intervals = app.Filter.mergeRanges(intervals);
                sendUIUpdate(app, struct( ...
                    'kind', 'intervals_loaded', ...
                    'intervals', intervals, ...
                    'varName', varName, ...
                    'message', sprintf('Imported %d interval(s) from ''%s''.', size(intervals, 1), varName)));
            catch ME
                updateHTMLStatus(app, sprintf('Interval import error: %s', ME.message));
            end
        end

        function resumeOrchestratorIfWaiting(app)
            if app.IsOrchestratorWaiting
                app.IsOrchestratorWaiting = false;
                try
                    uiresume(app.UIFigure);
                catch
                end
            end
        end

        function bytes = estimatePlotBytes(~, nSamples, nWavelengths)
            bytes = double(nSamples) * double(nWavelengths) * 8;
        end

        function closeRequest(app, ~)
            app.IsClosed = true;
            if app.IsOrchestratorWaiting
                try
                    uiresume(app.UIFigure);
                catch
                end
            end
            delete(app);
        end
    end

    % ================================================================
    %  Input and output commands for the workflow
    % ================================================================
    methods (Access = public)

        function setInputData(app, data)
            % SETINPUTDATA Load a spectra struct programmatically.
            %
            %   The struct must contain a real finite `spectra` matrix. The
            %   optional `wavelengths` field must be a finite strictly
            %   monotonic vector with one value per channel.
            arguments
                app
                data struct
            end

            app.InputData = data;

            spectra = data.spectra;
            [~, nCols] = size(spectra);

            if ~isfield(data, 'wavelengths') || isempty(data.wavelengths)
                data.wavelengths = 1:nCols;
            elseif ~isnumeric(data.wavelengths) || ...
                    ~isreal(data.wavelengths) || ...
                    ~isvector(data.wavelengths) || ...
                    numel(data.wavelengths) ~= nCols || ...
                    any(~isfinite(data.wavelengths(:)))
                error('FourierFiltering:InvalidWavelengths', ...
                    'The wavelength axis must be a finite real vector with one value per channel.');
            else
                data.wavelengths = double(data.wavelengths(:).');
                if nCols > 1
                    axisDifferences = diff(data.wavelengths);
                    if ~(all(axisDifferences > 0) || all(axisDifferences < 0))
                        error('FourierFiltering:InvalidWavelengths', ...
                            'The wavelength axis must be strictly monotonic.');
                    end
                end
            end

            app.InputData = data;
            app.SelectedSampleIndex = 1;

            % Compute FFT parameters
            meanSpec = mean(spectra, 1);
            numPoints = length(meanSpec);
            % The core filter mirrors the signal on both sides before the
            % FFT, so the displayed frequency axis must use that length.
            app.NumFftPoints = 2^nextpow2(3 * numPoints);
            samplingFreq = 1;
            app.FrequencyVector = (samplingFreq / 2) * ...
                linspace(0, 1, app.NumFftPoints / 2 + 1);

            % Compute magnitude spectrum of the first sample for display
            sampleSpec = spectra(1, :);
            Y = fft(sampleSpec, app.NumFftPoints);
            magSpectrum = abs(Y(1:app.NumFftPoints/2+1));
            maxMag = max(magSpectrum);
            if maxMag > 0
                magSpectrum = magSpectrum / maxMag;
            end

            wl = data.wavelengths;
            if isempty(wl)
                wl = 1:nCols;
            end

            payload = struct( ...
                'kind', 'data_loaded', ...
                'wavelengths', wl, ...
                'meanSpectrum', meanSpec, ...
                'sampleSpectrum', sampleSpec, ...
                'frequencyVector', app.FrequencyVector, ...
                'magnitudeSpectrum', magSpectrum, ...
                'sampleMagnitudeSpectrum', magSpectrum, ...
                'nSamples', size(spectra, 1), ...
                'nWavelengths', nCols, ...
                'sampleIndex', 1, ...
                'statusMessage', sprintf('Data loaded: %d x %d', size(spectra, 1), nCols));

            sendUIUpdate(app, payload);
        end

        function index = readSampleIndex(~, data, nSamples)
            index = 1;
            if isstruct(data) && isfield(data, 'sampleIndex')
                raw = data.sampleIndex;
                if isnumeric(raw) && isscalar(raw) && isfinite(raw)
                    index = round(double(raw));
                end
            end
            index = max(1, min(nSamples, index));
        end

        function data = getData(app)
            % GETDATA Return the processed data struct, or [] before Apply.
            data = app.ProcessedData;
        end

        function waitForOrchestrator(app)
            % WAITFORORCHESTRATOR Block until the UI completion action.
            if ~isvalid(app) || ~isvalid(app.UIFigure)
                return;
            end
            if isprop(app, 'IsClosed') && app.IsClosed
                return;
            end
            app.IsOrchestratorWaiting = true;
            uiwait(app.UIFigure);
            if ~isvalid(app)
                return;
            end
            try
                app.IsOrchestratorWaiting = false;
            catch
            end
        end
    end
end