Add compensation overrides and figure export

Author: Codex

README.md

@@ -8,7 +8,7 @@
 
 Parallax is a local-first cytometry workstation built around one shared Rust engine, an explicit command log, and a native Qt/QML desktop. It is designed for teams who care about speed, deterministic results, and a clean handoff between interactive desktop work and reproducible execution.
 
-Today, Parallax is an early but real workstation shell. You can launch the desktop, start from the bundled demo sample or import one or many `.fcs` files, switch between samples inside one local session, assign cohort labels to samples, author rectangle, polygon, quadrant, and histogram range gates, inspect a native histogram view for channel distributions, review per-population counts, frequencies, means, and medians, define replayable derived metrics such as positive fractions and mean ratios, compare the selected population across loaded samples, inspect grouped cohort summaries, export active-sample, selected-population, derived-metric, cohort-summary, or batch stats to CSV, apply replayable compensation and transform settings, adjust plot views through explicit view actions, inspect the command log, and undo or redo gate actions through the same replayable state model.
+Today, Parallax is an early but real workstation shell. You can launch the desktop, start from the bundled demo sample or import one or many `.fcs` files, switch between samples inside one local session, assign cohort labels to samples, author rectangle, polygon, quadrant, and histogram range gates, inspect a native histogram view for channel distributions, review per-population counts, frequencies, means, and medians, define replayable derived metrics such as positive fractions and mean ratios, compare the selected population across loaded samples, inspect grouped cohort summaries, export active-sample, selected-population, derived-metric, cohort-summary, or batch stats to CSV, apply or override compensation with QC feedback, export high-resolution PNG plot figures, adjust plot views through explicit view actions, inspect the command log, and undo or redo gate actions through the same replayable state model.
 
 ## Why Parallax
 
@@ -38,8 +38,9 @@ Today, Parallax is an early but real workstation shell. You can launch the deskt
 - Qt/QML desktop with live rectangle, polygon, quadrant, and histogram range-gate authoring
 - Desktop FCS import and multi-sample switching in one local session
 - Workspace save/load that reopens sessions from sample sources plus replayable command history
-- Parsed FCS compensation toggle plus per-channel linear, signed-log10, asinh, biexponential, and logicle transform presets
+- Parsed FCS compensation toggle, manual spillover override with QC, plus per-channel linear, signed-log10, asinh, biexponential, and logicle transform presets
 - Native histogram panel with population-aware highlighting, drag-authored range gates, exact min/max threshold entry, and midpoint `Low Gate` / `High Gate` shortcuts
+- High-resolution PNG export for plot cards with interaction controls hidden during capture
 - Population stats panel with matched-event counts, parent/all frequencies, and per-channel mean/median summaries
 - CSV export for active-sample population stats
 - Active-sample gate-template application across the other loaded samples
@@ -57,8 +58,8 @@ Today, Parallax is an early but real workstation shell. You can launch the deskt
 - Multi-factor cohort labels, group template tools, and richer cohort-review layouts are not implemented yet
 - Workspace persistence is source-path based today; bundled raw-data snapshots and derived caches are not implemented yet
 - Derived metrics are limited to positive fraction and mean ratio today; custom formula editors and spreadsheet-style expressions are not implemented yet
-- Compensation override editing, contour/density plot controls, and reference-matched transform tuning are not implemented yet
-- Gate editing handles, freeform pan, and figure/report export are not implemented yet
+- Contour/density plot controls and reference-matched transform tuning are not implemented yet
+- Gate editing handles, freeform pan, PDF/SVG figure export, and multi-panel report export are not implemented yet
 - Cloud sync, jobs, and AI assistance are future phases
 
 ## Repository Layout

apps/desktop-qt/qml/Main.qml

@@ -20,6 +20,7 @@ ApplicationWindow {
     property string derivedMetricDraftNumeratorChannel: ""
     property string derivedMetricDraftDenominatorChannel: ""
     property string derivedMetricDraftThreshold: "1.00"
+    property bool figureExportInProgress: false
 
     function transformIndex(kind) {
         if (kind === "signed_log10")
@@ -72,6 +73,37 @@ ApplicationWindow {
                     Number(maxText))
     }
 
+    function safeFileStem(value) {
+        const text = String(value || "parallax-figure").trim().replace(/[^A-Za-z0-9._-]+/g, "_")
+        return text.length > 0 ? text : "parallax-figure"
+    }
+
+    function exportPlotCard(card, plot) {
+        const suggested = window.safeFileStem(plot.title || plot.id || "parallax-plot") + ".png"
+        const path = desktopController.chooseFigureExportPath(suggested)
+        if (path === "")
+            return
+
+        window.figureExportInProgress = true
+        Qt.callLater(function () {
+            const targetWidth = Math.max(1800, Math.round(card.width * 3))
+            const targetHeight = Math.max(1200, Math.round(card.height * 3))
+            card.grabToImage(function (result) {
+                const ok = result.saveToFile(path)
+                window.figureExportInProgress = false
+                if (!ok)
+                    desktopController.reportFigureExportFailure("Failed to save figure to " + path)
+            }, Qt.size(targetWidth, targetHeight))
+        })
+    }
+
+    function compensationOverrideExample() {
+        const channels = desktopController.sample.channels || []
+        if (channels.length >= 2)
+            return "2," + channels[0] + "," + channels[1] + ",1,0,0,1"
+        return "2,FITC-A,PE-A,1,0,0,1"
+    }
+
     function formatPercent(value) {
         const numeric = Number(value)
         if (!isFinite(numeric))
@@ -723,7 +755,9 @@ ApplicationWindow {
                             }
 
                             CheckBox {
-                                text: desktopController.sample.compensation_available
+                                text: desktopController.sample.compensation_override_active
+                                      ? "Apply Compensation Override"
+                                      : desktopController.sample.compensation_available
                                       ? "Apply Parsed Compensation"
                                       : "No Compensation Matrix In Sample"
                                 enabled: desktopController.sample.compensation_available || false
@@ -735,6 +769,7 @@ ApplicationWindow {
                                 width: parent.width
                                 text: desktopController.sample.compensation_source_key
                                       ? "Source: " + desktopController.sample.compensation_source_key
+                                        + (desktopController.sample.compensation_override_active ? " (manual override)" : " (parsed from FCS)")
                                       : "Transforms and compensation are replayed before every gate redraw."
                                 color: "#6d5941"
                                 font.pixelSize: 13
@@ -811,6 +846,53 @@ ApplicationWindow {
                                 }
                             }
 
+                            Column {
+                                width: parent.width
+                                spacing: 6
+
+                                Text {
+                                    width: parent.width
+                                    text: "Manual Compensation Override"
+                                    color: "#2e2216"
+                                    font.pixelSize: 14
+                                    font.weight: Font.DemiBold
+                                }
+
+                                Text {
+                                    width: parent.width
+                                    text: "Paste an FCS spillover string: dimension, channels, then row-major matrix values. Overrides are replayable and QC-checked before use."
+                                    color: "#6d5941"
+                                    font.pixelSize: 12
+                                    wrapMode: Text.WordWrap
+                                }
+
+                                TextArea {
+                                    id: compensationOverrideField
+                                    width: parent.width
+                                    height: 84
+                                    wrapMode: TextEdit.Wrap
+                                    selectByMouse: true
+                                    placeholderText: window.compensationOverrideExample()
+                                }
+
+                                Row {
+                                    spacing: 8
+
+                                    Button {
+                                        text: "Apply Override"
+                                        enabled: compensationOverrideField.text.trim().length > 0
+                                        onClicked: desktopController.setCompensationOverrideFromText(
+                                                       compensationOverrideField.text)
+                                    }
+
+                                    Button {
+                                        text: "Clear Override"
+                                        enabled: desktopController.sample.compensation_override_active || false
+                                        onClicked: desktopController.clearCompensationOverride()
+                                    }
+                                }
+                            }
+
                             Repeater {
                                 model: desktopController.sample.channel_transforms || []
 
@@ -1526,6 +1608,7 @@ ApplicationWindow {
                 spacing: 18
 
                 Rectangle {
+                    id: plotACard
                     Layout.fillWidth: true
                     Layout.preferredHeight: 1
                     Layout.fillHeight: true
@@ -1566,6 +1649,7 @@ ApplicationWindow {
 
                         RowLayout {
                             Layout.fillWidth: true
+                            visible: !window.figureExportInProgress
                             spacing: 8
 
                             Button {
@@ -1606,6 +1690,12 @@ ApplicationWindow {
                                 onClicked: desktopController.scalePlotView(plotA.id || "", 1.4)
                             }
 
+                            Button {
+                                text: "Export PNG"
+                                enabled: !window.figureExportInProgress
+                                onClicked: window.exportPlotCard(plotACard, plotA)
+                            }
+
                             Item { Layout.fillWidth: true }
 
                             Text {
@@ -1616,6 +1706,7 @@ ApplicationWindow {
                         }
 
                         Text {
+                            visible: !window.figureExportInProgress
                             text: window.plotHelperText(plotA)
                             color: "#8b6a3c"
                             font.pixelSize: 13
@@ -1624,6 +1715,7 @@ ApplicationWindow {
                         RowLayout {
                             Layout.fillWidth: true
                             visible: (plotA.kind || "") === "histogram"
+                                     && !window.figureExportInProgress
                             spacing: 8
 
                             Text {
@@ -1720,6 +1812,7 @@ ApplicationWindow {
                 }
 
                 Rectangle {
+                    id: plotBCard
                     Layout.fillWidth: true
                     Layout.preferredHeight: 1
                     Layout.fillHeight: true
@@ -1760,6 +1853,7 @@ ApplicationWindow {
 
                         RowLayout {
                             Layout.fillWidth: true
+                            visible: !window.figureExportInProgress
                             spacing: 8
 
                             Button {
@@ -1800,6 +1894,12 @@ ApplicationWindow {
                                 onClicked: desktopController.scalePlotView(plotB.id || "", 1.4)
                             }
 
+                            Button {
+                                text: "Export PNG"
+                                enabled: !window.figureExportInProgress
+                                onClicked: window.exportPlotCard(plotBCard, plotB)
+                            }
+
                             Item { Layout.fillWidth: true }
 
                             Text {
@@ -1810,6 +1910,7 @@ ApplicationWindow {
                         }
 
                         Text {
+                            visible: !window.figureExportInProgress
                             text: window.plotHelperText(plotB)
                             color: "#8b6a3c"
                             font.pixelSize: 13
@@ -1818,6 +1919,7 @@ ApplicationWindow {
                         RowLayout {
                             Layout.fillWidth: true
                             visible: (plotB.kind || "") === "histogram"
+                                     && !window.figureExportInProgress
                             spacing: 8
 
                             Text {
@@ -1914,6 +2016,7 @@ ApplicationWindow {
                 }
 
                 Rectangle {
+                    id: plotCCard
                     Layout.fillWidth: true
                     Layout.preferredHeight: 1
                     Layout.fillHeight: true
@@ -1955,6 +2058,7 @@ ApplicationWindow {
 
                         RowLayout {
                             Layout.fillWidth: true
+                            visible: !window.figureExportInProgress
                             spacing: 8
 
                             Button {
@@ -1995,6 +2099,12 @@ ApplicationWindow {
                                 onClicked: desktopController.scalePlotView(plotC.id || "", 1.4)
                             }
 
+                            Button {
+                                text: "Export PNG"
+                                enabled: !window.figureExportInProgress
+                                onClicked: window.exportPlotCard(plotCCard, plotC)
+                            }
+
                             Item { Layout.fillWidth: true }
 
                             Text {
@@ -2005,6 +2115,7 @@ ApplicationWindow {
                         }
 
                         Text {
+                            visible: !window.figureExportInProgress
                             text: window.plotHelperText(plotC)
                             color: "#8b6a3c"
                             font.pixelSize: 13
@@ -2013,6 +2124,7 @@ ApplicationWindow {
                         RowLayout {
                             Layout.fillWidth: true
                             visible: (plotC.kind || "") === "histogram"
+                                     && !window.figureExportInProgress
                             spacing: 8
 
                             Text {

apps/desktop-qt/src/DesktopController.cpp

@@ -661,6 +661,35 @@ void DesktopController::setCompensationEnabled(bool enabled) {
         QJsonDocument(command).toJson(QJsonDocument::Compact)));
 }
 
+void DesktopController::setCompensationOverrideFromText(const QString &matrixText) {
+    const QString trimmed = matrixText.trimmed();
+    if (trimmed.isEmpty()) {
+        setLastError("Compensation override cannot be empty");
+        return;
+    }
+
+    QJsonObject command;
+    const QString sampleId = activeSampleId();
+    command.insert("kind", "set_compensation_override");
+    command.insert(
+        "sample_id",
+        sampleId.isEmpty() ? QStringLiteral("desktop-demo") : sampleId);
+    command.insert("matrix_text", trimmed);
+    dispatchCommandJson(QString::fromUtf8(
+        QJsonDocument(command).toJson(QJsonDocument::Compact)));
+}
+
+void DesktopController::clearCompensationOverride() {
+    QJsonObject command;
+    const QString sampleId = activeSampleId();
+    command.insert("kind", "clear_compensation_override");
+    command.insert(
+        "sample_id",
+        sampleId.isEmpty() ? QStringLiteral("desktop-demo") : sampleId);
+    dispatchCommandJson(QString::fromUtf8(
+        QJsonDocument(command).toJson(QJsonDocument::Compact)));
+}
+
 void DesktopController::setChannelTransform(const QString &channel, const QString &kind) {
     if (channel.trimmed().isEmpty()) {
         setLastError("Transform channel cannot be empty");
@@ -701,6 +730,28 @@ void DesktopController::setChannelTransform(const QString &channel, const QStrin
         QJsonDocument(command).toJson(QJsonDocument::Compact)));
 }
 
+QString DesktopController::chooseFigureExportPath(const QString &suggestedName) {
+    QString candidate = suggestedName.trimmed();
+    if (candidate.isEmpty()) {
+        candidate = QStringLiteral("parallax-figure.png");
+    }
+    if (!candidate.endsWith(QStringLiteral(".png"), Qt::CaseInsensitive)) {
+        candidate.append(QStringLiteral(".png"));
+    }
+
+    return QFileDialog::getSaveFileName(
+        nullptr,
+        tr("Export Publication Figure"),
+        candidate,
+        tr("PNG Images (*.png);;All Files (*)"));
+}
+
+void DesktopController::reportFigureExportFailure(const QString &message) {
+    setLastError(message.trimmed().isEmpty()
+                     ? QStringLiteral("Failed to export figure")
+                     : message.trimmed());
+}
+
 void DesktopController::resetPlotView(const QString &plotId) {
     if (plotId.trimmed().isEmpty()) {
         setLastError("Plot id cannot be empty");

apps/desktop-qt/src/DesktopController.h

@@ -86,7 +86,11 @@ class DesktopController : public QObject {
         const QString &numeratorChannel,
         const QString &denominatorChannel);
     Q_INVOKABLE void setCompensationEnabled(bool enabled);
+    Q_INVOKABLE void setCompensationOverrideFromText(const QString &matrixText);
+    Q_INVOKABLE void clearCompensationOverride();
     Q_INVOKABLE void setChannelTransform(const QString &channel, const QString &kind);
+    Q_INVOKABLE QString chooseFigureExportPath(const QString &suggestedName);
+    Q_INVOKABLE void reportFigureExportFailure(const QString &message);
     Q_INVOKABLE void resetPlotView(const QString &plotId);
     Q_INVOKABLE void focusPlotOnSelectedPopulation(const QString &plotId);
     Q_INVOKABLE void scalePlotView(const QString &plotId, double factor);