add support for new defocus keyword

akohlmey · akohlmey · commit 53659dd23442 · 2026-07-28T02:16:04.000-04:00
diff --git a/doc/JPG/lammps-gui-image-box-axes.png b/doc/JPG/lammps-gui-image-box-axes.png
diff --git a/doc/JPG/lammps-gui-image-settings.png b/doc/JPG/lammps-gui-image-settings.png
diff --git a/doc/visualization.rst b/doc/visualization.rst
@@ -236,6 +236,11 @@ there are:
   fades distant objects toward a fog color for a stronger sense of
   depth.  The intensity, fog color, and start position are configured
   in the :ref:`Global image settings dialog <global_settings>`.
+- **Defocus** (toggle): Enable or disable defocusing, which blurs
+  distant objects as if the camera were focused on the front of the
+  scene, while leaving their colors untouched.  This can be combined
+  with depth cueing.  The intensity and start position are configured
+  in the :ref:`Global image settings dialog <global_settings>`.
 - **Shininess** (toggle): Switch between shiny and matte surface
   rendering of graphics objects like atoms and bonds.
 - **VDW style** (toggle): Switch between space-filling (Van der Waals)
@@ -331,10 +336,10 @@ in this dialog correspond to options of the LAMMPS `dump image and
 dump_modify commands <https://docs.lammps.org/dump_image.html>`_.
 
 .. |boxaxes| image:: JPG/lammps-gui-image-box-axes.png
-                     :width: 42%
+                     :width: 40%
 
 .. |global|  image:: JPG/lammps-gui-image-settings.png
-                     :width: 57%
+                     :width: 59%
 
 |boxaxes|  |global|
 
@@ -413,6 +418,26 @@ The dialog is organized into the following sections:
      the camera, 1.0 = far side), or "auto" (the default) to start at
      the nearest rendered object.
 
+**Defocus**
+   Controls defocusing, which blurs distant objects as if the camera
+   were focused on the front of the scene.  Like depth cueing this
+   draws the attention to the objects in front, but it leaves their
+   colors untouched, and the two effects may be combined.  There is no
+   color setting for this effect, so that field is left empty.
+
+   - **Defocus** (checkbox): Enable or disable defocusing.  This is
+     the same setting that the defocus toolbar button toggles.
+   - **Intensity**: The strength of the blur (range: 0.0 -- 1.0).  At
+     1.0 the most distant objects are blurred over a radius of 1
+     percent of the image height.  Blurring over much more than the
+     size of the rendered particles turns them into a uniform haze,
+     so moderate values usually give the best result.
+   - **Start**: Where the blurring starts, as a fraction of the
+     simulation box along the view direction (0.0 = side nearest to
+     the camera, 1.0 = far side), or "auto" (the default) to start at
+     the nearest rendered object, which keeps the front of the scene
+     sharp.
+
 **Quality**
    Controls rendering quality options.
 
diff --git a/resources/icons/defocus.svg b/resources/icons/defocus.svg
diff --git a/resources/lammpsgui.qrc b/resources/lammpsgui.qrc
@@ -50,6 +50,7 @@
     <file>icons/chart-smooth.svg</file>
     <file>icons/comment-out.svg</file>
     <file>icons/csv-file-icon.svg</file>
+    <file>icons/defocus.svg</file>
     <file>icons/depth-cue.svg</file>
     <file>icons/dialog-cancel.svg</file>
     <file>icons/dialog-no.svg</file>
diff --git a/src/dumpimage.cpp b/src/dumpimage.cpp
@@ -256,11 +256,13 @@ DumpImageCommand buildDumpImageCommand(const DumpImageParams &p)
         d += QString(" view %1 %2").arg(hhrot).arg(p.vrot);
     }
     if (p.usessao) d += QString(" ssao yes %1 %2").arg(Cfg::SSAO_SEED).arg(p.ssaoval);
-    // depth cueing and outlines default to "no" in LAMMPS, so emit them only when on
+    // depth cueing, defocus, and outlines default to "no" in LAMMPS, so emit
+    // them only when on
     if (p.usedepthcue)
         d += QString(" depthcue yes %1 %2 %3")
                  .arg(p.depthcuefactor)
                  .arg(p.depthcuecolor, p.depthcuestart);
+    if (p.usedefocus) d += QString(" defocus yes %1 %2").arg(p.defocusfactor).arg(p.defocusstart);
     if (p.useoutline) d += QString(" outline yes %1 %2").arg(p.outlinewidth).arg(p.outlinecolor);
     if (p.showbox)
         d += QString(" box yes %1").arg(p.boxdiam);
diff --git a/src/dumpimage.h b/src/dumpimage.h
@@ -103,6 +103,9 @@ struct DumpImageParams {
     double depthcuefactor; ///< depth cueing strength (0.0 - 1.0)
     QString depthcuecolor; ///< fog color name, or "auto" = fade toward the background
     QString depthcuestart; ///< fading start as a box fraction along the view direction, or "auto"
+    bool usedefocus;       ///< enable defocusing of distant objects
+    double defocusfactor;  ///< defocus blur strength (0.0 - 1.0)
+    QString defocusstart;  ///< blurring start as a box fraction along the view direction, or "auto"
     bool useoutline;       ///< draw outlines at depth jumps
     int outlinewidth;      ///< outline width in pixels (1 - 16)
     QString outlinecolor;  ///< outline color name
diff --git a/src/imageviewer.cpp b/src/imageviewer.cpp
@@ -444,6 +444,10 @@ ImageViewer::ImageViewer(const QString &fileName, LammpsWrapper *_lammps, Lammps
     dodepth->setCheckable(true);
     dodepth->setToolTip("Toggle depth cueing");
     dodepth->setObjectName("depthcue");
+    auto *dodefocus = new QPushButton(QIcon(":/icons/defocus.svg"), "");
+    dodefocus->setCheckable(true);
+    dodefocus->setToolTip("Toggle defocusing of distant objects");
+    dodefocus->setObjectName("defocus");
     auto *doshiny = new QPushButton(QIcon(":/icons/image-shiny.svg"), "");
     doshiny->setCheckable(true);
     doshiny->setToolTip("Toggle shininess");
@@ -502,8 +506,8 @@ ImageViewer::ImageViewer(const QString &fileName, LammpsWrapper *_lammps, Lammps
 
     // square toolbar buttons with a snug, uniform icon (shared policy)
     styleToolButtons(buttonhint,
-                     {dossao, doanti, dodepth, doshiny, dovdw, dobond, dobox, doaxes, zoomin,
-                      zoomout, rotleft, rotright, rotup, rotdown, recenter, reset, fitwin});
+                     {dossao, doanti, dodepth, dodefocus, doshiny, dovdw, dobond, dobox, doaxes,
+                      zoomin, zoomout, rotleft, rotright, rotup, rotdown, recenter, reset, fitwin});
 
     // match the first-row controls (menu bar and size fields) to the toolbar
     // button height so both rows line up and the layout looks balanced
@@ -580,6 +584,7 @@ ImageViewer::ImageViewer(const QString &fileName, LammpsWrapper *_lammps, Lammps
     buttonLayout->addWidget(dossao);
     buttonLayout->addWidget(doanti);
     buttonLayout->addWidget(dodepth);
+    buttonLayout->addWidget(dodefocus);
     buttonLayout->addWidget(doshiny);
     buttonLayout->addWidget(dovdw);
     buttonLayout->addWidget(dobond);
@@ -621,6 +626,7 @@ ImageViewer::ImageViewer(const QString &fileName, LammpsWrapper *_lammps, Lammps
     connect(dossao, &QPushButton::released, this, &ImageViewer::toggleSsao);
     connect(doanti, &QPushButton::released, this, &ImageViewer::toggleAnti);
     connect(dodepth, &QPushButton::released, this, &ImageViewer::toggleDepthcue);
+    connect(dodefocus, &QPushButton::released, this, &ImageViewer::toggleDefocus);
     connect(doshiny, &QPushButton::released, this, &ImageViewer::toggleShiny);
     connect(dovdw, &QPushButton::released, this, &ImageViewer::toggleVdw);
     connect(dobond, &QPushButton::released, this, &ImageViewer::toggleBond);
@@ -670,6 +676,7 @@ ImageViewer::ImageViewer(const QString &fileName, LammpsWrapper *_lammps, Lammps
     dossao->setChecked(usessao);
     doanti->setChecked(antialias);
     dodepth->setChecked(usedepthcue);
+    dodefocus->setChecked(usedefocus);
 
     scrollArea->setVisible(true);
     updateActions();
@@ -743,6 +750,9 @@ void ImageViewer::readImageSettings()
     depthcuefactor = 0.5;
     depthcuecolor  = "auto";
     depthcuestart  = "auto";
+    usedefocus     = false;
+    defocusfactor  = 0.5;
+    defocusstart   = "auto";
     useoutline     = false;
     outlinewidth   = 2;
     outlinecolor   = "black";
@@ -818,6 +828,8 @@ void ImageViewer::resetView()
     if (button) button->setChecked(antialias);
     button = findChild<QPushButton *>("depthcue");
     if (button) button->setChecked(usedepthcue);
+    button = findChild<QPushButton *>("defocus");
+    if (button) button->setChecked(usedefocus);
     button = findChild<QPushButton *>("shiny");
     if (button) button->setChecked(shinyfactor > SHINY_CUT);
     button = findChild<QPushButton *>("vdw");
@@ -898,6 +910,15 @@ void ImageViewer::toggleDepthcue()
     createImage();
 }
 
+void ImageViewer::toggleDefocus()
+{
+    auto *button = qobject_cast<QPushButton *>(sender());
+    if (!button) return;
+    usedefocus = !usedefocus;
+    button->setChecked(usedefocus);
+    createImage();
+}
+
 void ImageViewer::toggleShiny()
 {
     auto *button = qobject_cast<QPushButton *>(sender());
@@ -1495,6 +1516,9 @@ DumpImageParams ImageViewer::gatherDumpImageParams(const QString &dumpfilename)
     p.depthcuefactor = depthcuefactor;
     p.depthcuecolor  = depthcuecolor;
     p.depthcuestart  = depthcuestart;
+    p.usedefocus     = usedefocus;
+    p.defocusfactor  = defocusfactor;
+    p.defocusstart   = defocusstart;
     p.useoutline     = useoutline;
     p.outlinewidth   = outlinewidth;
     p.outlinecolor   = outlinecolor;
diff --git a/src/imageviewer.h b/src/imageviewer.h
@@ -87,6 +87,7 @@ private slots:
     void toggleSsao();        ///< Toggle screen-space ambient occlusion
     void toggleAnti();        ///< Toggle anti-aliasing
     void toggleDepthcue();    ///< Toggle depth cueing
+    void toggleDefocus();     ///< Toggle defocusing of distant objects
     void toggleShiny();       ///< Toggle shiny/specular rendering
     void toggleVdw();         ///< Toggle Van der Waals radii
     void toggleBond();        ///< Toggle bond display
@@ -243,6 +244,8 @@ private slots:
     double depthcuefactor;                       ///< Depth cueing strength
     QString depthcuecolor;                       ///< Depth cueing fog color or "auto"
     QString depthcuestart;                       ///< Depth cueing start fraction or "auto"
+    double defocusfactor;                        ///< Defocus blur strength
+    QString defocusstart;                        ///< Defocus start fraction or "auto"
     int outlinewidth;                            ///< Outline width in pixels
     QString outlinecolor;                        ///< Outline color
     QString specular;                            ///< Specular preset or "auto"
@@ -284,6 +287,7 @@ private slots:
     bool antialias;                              ///< Anti-aliasing enabled flag
     bool usessao;                                ///< SSAO enabled flag
     bool usedepthcue;                            ///< Depth cueing enabled flag
+    bool usedefocus;                             ///< Defocus enabled flag
     bool useoutline;                             ///< Outline drawing enabled flag
     bool showatoms;                              ///< Show atoms
     bool showbonds;                              ///< Show bonds if atom style supports it
diff --git a/src/imageviewersettings.cpp b/src/imageviewersettings.cpp
@@ -249,13 +249,43 @@ void ImageViewer::globalSettings()
                          "(0.0 = near side, 1.0 = far side), or \"auto\" to start at the\n"
                          "nearest rendered object");
     layout->addWidget(cuestart, idx++, n++, 1, 1);
-    layout->addWidget(new QHline, idx++, 0, 1, MAXCOLS);
     connect(cuebutton, &QCheckBox::toggled, cueval, &QDoubleSpinBox::setEnabled);
     connect(cuebutton, &QCheckBox::toggled, cuecolor, &QLineEdit::setEnabled);
     connect(cuebutton, &QCheckBox::toggled, cuestart, &QLineEdit::setEnabled);
 
     n = 0;
 
+    auto *focusbutton = new QCheckBox("Defocus ", this);
+    focusbutton->setChecked(usedefocus);
+    focusbutton->setToolTip("Blur distant objects as if the camera were focused on the front");
+    layout->addWidget(focusbutton, idx, n++, 1, 1);
+    layout->addWidget(new QLabel("Intensity: "), idx, n++, 1, 1, Qt::AlignVCenter | Qt::AlignRight);
+    auto *focusval = new QDoubleSpinBox;
+    focusval->setRange(0.0, 1.0);
+    focusval->setSingleStep(0.05);
+    focusval->setValue(defocusfactor);
+    focusval->setMaximumWidth(fwidth);
+    focusval->setEnabled(usedefocus);
+    focusval->setToolTip("Strength of the blur; at 1.0 the most distant objects are\n"
+                         "blurred over a radius of 1 percent of the image height");
+    layout->addWidget(focusval, idx, n++, 1, 1);
+    // the defocus keyword has no color argument, so this column stays empty
+    n += 2;
+    layout->addWidget(new QLabel("Start: "), idx, n++, 1, 1, Qt::AlignVCenter | Qt::AlignRight);
+    auto *focusstart = new QLineEdit(defocusstart);
+    focusstart->setValidator(cuestartvalidator);
+    focusstart->setMaximumWidth(fwidth);
+    focusstart->setEnabled(usedefocus);
+    focusstart->setToolTip("Box fraction along the view direction where the blurring starts\n"
+                           "(0.0 = near side, 1.0 = far side), or \"auto\" to start at the\n"
+                           "nearest rendered object");
+    layout->addWidget(focusstart, idx++, n++, 1, 1);
+    layout->addWidget(new QHline, idx++, 0, 1, MAXCOLS);
+    connect(focusbutton, &QCheckBox::toggled, focusval, &QDoubleSpinBox::setEnabled);
+    connect(focusbutton, &QCheckBox::toggled, focusstart, &QLineEdit::setEnabled);
+
+    n = 0;
+
     layout->addWidget(new QLabel("Quality:"), idx, n++, 1, 1);
     n++;
     auto *fsaa = new QCheckBox("FSAA  ", this);
@@ -514,6 +544,12 @@ void ImageViewer::globalSettings()
     button = findChild<QPushButton *>("depthcue");
     if (button) button->setChecked(usedepthcue);
 
+    usedefocus    = focusbutton->isChecked();
+    defocusfactor = focusval->value();
+    if (focusstart->hasAcceptableInput()) defocusstart = focusstart->text();
+    button = findChild<QPushButton *>("defocus");
+    if (button) button->setChecked(usedefocus);
+
     useoutline   = outlinebutton->isChecked();
     outlinewidth = olwidth->value();
     if (olcolor->hasAcceptableInput()) outlinecolor = olcolor->text();
diff --git a/src/lammpssyntax.cpp b/src/lammpssyntax.cpp
@@ -422,7 +422,7 @@ LammpsSyntax::LammpsSyntax()
                QStringLiteral("zoom"),    QStringLiteral("box"),       QStringLiteral("axes"),
                QStringLiteral("region"),  QStringLiteral("subbox"),    QStringLiteral("shiny"),
                QStringLiteral("fsaa"),    QStringLiteral("ssao"),      QStringLiteral("depthcue"),
-               QStringLiteral("outline")});
+               QStringLiteral("defocus"), QStringLiteral("outline")});
     specialWords = {QStringLiteral("INF"),  QStringLiteral("EDGE"), QStringLiteral("NULL"),
                     QStringLiteral("SELF"), QStringLiteral("if"),   QStringLiteral("then"),
                     QStringLiteral("else"), QStringLiteral("elif")};
diff --git a/test/test_dumpimage.cpp b/test/test_dumpimage.cpp
@@ -84,6 +84,9 @@ DumpImageParams makeParams()
     p.depthcuefactor = 0.5;
     p.depthcuecolor  = "auto";
     p.depthcuestart  = "auto";
+    p.usedefocus     = false;
+    p.defocusfactor  = 0.5;
+    p.defocusstart   = "auto";
     p.useoutline     = false;
     p.outlinewidth   = 2;
     p.outlinecolor   = "black";
@@ -382,6 +385,7 @@ TEST(DumpImageCommand, DepthCueOutlineSpecular)
     auto p      = makeParams();
     QString cmd = buildCmd(p);
     EXPECT_FALSE(cmd.contains(" depthcue ")) << cmd.toStdString();
+    EXPECT_FALSE(cmd.contains(" defocus "));
     EXPECT_FALSE(cmd.contains(" outline "));
     EXPECT_FALSE(cmd.contains(" specular "));
     EXPECT_FALSE(cmd.contains(" ssaosamples "));
@@ -397,6 +401,16 @@ TEST(DumpImageCommand, DepthCueOutlineSpecular)
     cmd             = buildCmd(p);
     EXPECT_TRUE(cmd.contains(" depthcue yes 0.7 white 0.25")) << cmd.toStdString();
 
+    // defocus takes no color argument, only the strength and the start position
+    p.usedefocus    = true;
+    p.defocusfactor = 0.4;
+    cmd             = buildCmd(p);
+    EXPECT_TRUE(cmd.contains(" defocus yes 0.4 auto")) << cmd.toStdString();
+
+    p.defocusstart = "0.5";
+    cmd            = buildCmd(p);
+    EXPECT_TRUE(cmd.contains(" defocus yes 0.4 0.5")) << cmd.toStdString();
+
     p.useoutline   = true;
     p.outlinewidth = 3;
     p.outlinecolor = "gray";
@@ -489,6 +503,7 @@ TEST(DumpImageCommand, AllDefaultsPruned)
     EXPECT_FALSE(cmd.contains(" btrans"));
     EXPECT_FALSE(cmd.contains(" lights"));
     EXPECT_FALSE(cmd.contains(" gamma"));
+    EXPECT_FALSE(cmd.contains(" defocus"));
     EXPECT_FALSE(cmd.contains(" subbox "));
     EXPECT_FALSE(cmd.contains(" axes "));
     EXPECT_FALSE(cmd.contains(" center "));
diff --git a/test/test_highlighter.cpp b/test/test_highlighter.cpp
@@ -289,7 +289,7 @@ TEST_F(HighlighterTest, DumpImageColorsAndKeywords)
                        "dump_modify 2 backcolor white acolor 1 red\n"
                        "dump 3 all atom 100 f.dump\n"
                        "dump 4 all image 100 j.png type type depthcue yes 0.5 auto auto "
-                       "outline yes 2 dodgerblue"));
+                       "outline yes 2 dodgerblue defocus yes 0.4 auto"));
     Highlighter hl(&syntax, &doc);
     hl.rehighlight();
 
@@ -302,6 +302,7 @@ TEST_F(HighlighterTest, DumpImageColorsAndKeywords)
     EXPECT_EQ(formatAt(doc, 0, 46).foreground(), formatAt(doc2, 0, 6).foreground()); // box
     EXPECT_EQ(formatAt(doc, 3, 38).foreground(), formatAt(doc2, 0, 6).foreground()); // depthcue
     EXPECT_EQ(formatAt(doc, 3, 65).foreground(), formatAt(doc2, 0, 6).foreground()); // outline
+    EXPECT_EQ(formatAt(doc, 3, 90).foreground(), formatAt(doc2, 0, 6).foreground()); // defocus
     // the outline color value renders in its own color
     EXPECT_EQ(formatAt(doc, 3, 78).foreground().color(), QColor(QStringLiteral("dodgerblue")));
 
