@@ -0,0 +1,24 @@
+---
+type: pitfall
+title: "`Builder::execute()` paints after every command, so a command sequence shows each intermediate state (#226)"
+area: wx-viewer
+paths: [src/apps/builder/Builder.C, src/wxviz/viewer/SGViewer.C, src/apps/builder/MoPanel.C, src/viz/propsgcommands/IsoSurfaceCmd.C, src/viz/propsgcommands/IsoValueCmd.C, src/inv/moiv/ChemIso.C]
+issues: [226]
+---
+`Builder::execute(cmd)` (non-batch) ends with `SGViewer::refreshRenderArea()`,
+which is `Refresh(false)` + `Update()`: a synchronous paint. A panel that
+reaches its final scene through several commands therefore puts every
+intermediate scene on screen, one frame each.
+
+MoPanel's Compute ran `IsoSurfaceCmd` (built at a hard-wired 0.05, 0.002
+for ESP), `SurfDisplayTypeCmd`, then `IsoValueCmd` (the slider's cutoff):
+two frames of a 0.05 surface before the requested one. `IsoSurfaceCmd` now
+takes an `isovalue` parameter (0 = the field-type default) and MoPanel
+passes the cutoff it is about to put on the slider. Cube.C still builds at
+the default and never applies its slider on grid selection.
+
+To see it headlessly: `tools/coin/scenes/calc-water-mopanel.scene`
+(`mopanel <name>`, a Builder-only scene command) presses Compute and writes
+every frame of the Builder canvas with the thresholds of the `ChemIso`
+nodes in the scene at that frame; `ECCE_DEBUG_ISO=1` also logs each surface
+`ChemIso::regenerate` actually generates.
@@ -15,6 +15,8 @@ Read this before changing any dialog, panel, sizer, grid, ewx control or the Ope
 - [`ECCE_USE_COIN` (default ON) builds the viewer against Coin3D; `=OFF` keeps the vendored core for one release](ecce-use-coin-builds-the-viewer-against-coin3d.md)
 - [Coin SORTED_LAYERS_BLEND is the default lobe transparency (6 passes, alpha canvas); slow scenes fall back to SCREEN_DOOR](coin-sorted-layers-blend-is-the-default-lobe-transparency.md)
 - [`GlPlatform` is the viewer's only GLX/EGL code; `tools/nonx11/check.py` compiles the viewer as a non-X11 port (#232)](glplatform-is-the-viewers-only-glx-egl-code.md)
+- [`Builder::execute()` paints after every command, so a command sequence shows each intermediate state (#226)](builder-execute-paints-after-every-command.md)
+- [Normal-mode arrows start at the atom centre and scale uniformly; small ones end inside the sphere (#228)](normal-mode-arrows-start-at-the-atom-centre.md)
 - [`tools/coin/compare.sh` renders a fixed scene set with both viewer builds (#166 stage 2); harness pitfalls](tools-coin-compare-sh-renders-both-viewer-builds.md)
 - [Atom labels drew nothing in 9.x: the sh wrappers dropped `FL_FONT_PATH`; flclient now defaults to `$ECCE_HOME/data/client/fonts`](atom-labels-need-the-bundled-font-fl-font-path.md)
 - [Builder Reset View (toolbar, Render menu, Home) is camera only; the old home button restored a pre-molecule camera](builder-reset-view-is-camera-only-home-key.md)
 
@@ -0,0 +1,23 @@
+---
+type: map
+title: "Normal-mode arrows start at the atom centre and scale uniformly; small ones end inside the sphere (#228)"
+area: wx-viewer
+paths: [src/viz/propsgcommands/NModeVectCmd.C, src/viz/nodes/VRVector.C, src/apps/builder/NModePanel.C, src/wxviz/viewer/SceneScript.C]
+issues: [228]
+---
+`NModeVectCmd` puts one `VRVector` per atom at the atom centre, direction
+`d * 0.5/maxnorm` (Scale slider multiplies it). `VRVector` scales its whole
+geometry (shaft, head, thickness) by |d|; the tip is at 1.075 |d|, so the
+longest arrow reaches 0.5375 A from its centre.
+
+Displayed sphere radii (Ball And Stick and the default style) are covalent
+x 0.5: O 0.365, H 0.20, C about 0.38. An atom whose displacement is below
+about 70 % of the largest one (any heavy atom in an X-H stretch) has its
+whole arrow inside its sphere. Separately, in Ball And Stick an arrow
+pointing along a bond lies inside the bond cylinder and is hidden too (the
+water symmetric stretch shows no arrows at all with Sign unticked).
+
+Measured, not computed: the scene command `nmcheck <name>` reports per atom
+the farthest arrow vertex from the atom centre (`SoCallbackAction`
+triangles) and where a ray along the arrow meets that atom's sphere
+(`SoRayPickAction`, atom detail); `tools/coin/scenes/calc-water-nmcheck.scene`.
@@ -1,6 +1,7 @@
 #ifndef SCENESCRIPT_H_
 #define SCENESCRIPT_H_
 
+#include <functional>
 #include <string>
 #include <vector>
 using std::string;
@@ -9,6 +10,7 @@ using std::vector;
 class IPropCalculation;
 class SGContainer;
 class SGViewer;
+class wxWindow;
 
 /**
  * Drives the viewer from a text script and writes offscreen snapshots, so
@@ -32,6 +34,11 @@ class SGViewer;
  *   viewall | clear               reset the camera / hide MO and modes
  *   snap <name>   the canvas, read back with glReadPixels -> <name>.ppm
  *   thumb <name>  64x64 black background, as the calculation thumbnail
+ *   nmcheck <name>  per normal-mode arrow: tip distance from its atom centre
+ *                   (arrow triangles) and the atom's sphere surface along
+ *                   the arrow (ray pick) -> <name>.txt
+ * Commands this class does not know go to the caller's extension, if set
+ * (the Builder adds "mopanel", which presses the MO panel's Compute).
  */
 class SceneScript
 {
@@ -43,20 +50,32 @@ class SceneScript
     bool run(const string& scriptPath);
     const string& message() const { return p_msg; }
 
+    // Unknown commands go here; return false (and set fail()) on error.
+    typedef std::function<bool(SceneScript&, const vector<string>&)> Extension;
+    void setExtension(Extension e) { p_ext = e; }
+
+    // Runs act() and records every frame the render area under canvasOwner
+    // paints meanwhile: <name>-NN.ppm plus one line per frame in
+    // <name>-frames.txt with the thresholds of the isosurfaces drawn.
+    bool recordFrames(wxWindow *canvasOwner, const string& name,
+                      std::function<void()> act);
+    bool fail(const string& m) { p_msg = m; return false; }
+
   private:
     bool exec(const vector<string>& w, const string& rest);
     bool pickAtoms(const string& name, const vector<string>& atoms);
     bool dragAtom(const string& name, int atom, int dx, int dy);
     bool countRedraws(const string& name, const vector<string>& steps);
     bool snapshot(const string& name, int size, float r, float g, float b);
     bool exportIso(const string& name);
-    bool fail(const string& m) { p_msg = m; return false; }
+    bool nmCheck(const string& name);
 
     SGViewer *p_viewer;
     SGContainer *p_sg;
     IPropCalculation *p_calc;
     string p_outdir;
     string p_msg;
+    Extension p_ext;
 };
 
 #endif
@@ -178,6 +178,7 @@ using std::vector;
 #include "Peptide.H"
 #include "PropertyIndexPanel.H"
 #include "PropertyPanel.H"
+#include "MoPanel.H"
 #include "PropertyPanelFactory.H"
 #include "ShapeDropDown.H"
 #include "StructLib.H"
@@ -5104,6 +5105,24 @@ void Builder::updatePropertyMenus()
       for (int i = 0; i < 30; i++) { wxTheApp->Yield(true); wxMilliSleep(10); }
       viewer->viewAll();
       SceneScript run(viewer, sg, p_calculation, outdir);
+      //  "mopanel <name>": press the MO panel's Compute, as a user would,
+      //  recording every frame the Builder's own canvas paints meanwhile.
+      run.setExtension([this](SceneScript& s, const vector<string>& w) {
+        if (w[0] != "mopanel" || w.size() != 2)
+          return s.fail("unknown command: " + w[0]);
+        MoPanel *mo = 0;
+        set<PropertyPanel*> panels =
+            PropertyPanel::getPanels(p_calculation->getURL().toString());
+        for (set<PropertyPanel*>::iterator it = panels.begin();
+             it != panels.end() && !mo; ++it)
+          mo = dynamic_cast<MoPanel*>(*it);
+        if (!mo) return s.fail("mopanel: no MO panel");
+        return s.recordFrames(p_viewer, w[1], [mo]() {
+          wxCommandEvent ev(wxEVT_BUTTON, MoGUI::ID_BUTTON_MO_COMPUTE);
+          ev.SetEventObject(mo->FindWindow(MoGUI::ID_BUTTON_MO_COMPUTE));
+          mo->GetEventHandler()->ProcessEvent(ev);
+        });
+      });
       if (!ready || !run.run(script)) {
         string msg = ready ? run.message() : "molecule never loaded";
         fprintf(stderr, "ECCE_VIEWER_SCENE: %s\n", msg.c_str());
 
@@ -981,20 +981,6 @@ void MoPanel::OnButtonMoComputeClick( wxCommandEvent& event )
       double posR, posG, posB, negR, negG, negB;
       getSurfaceColors(posR, posG, posB, negR, negG, negB);
 
-      cmd = new IsoSurfaceCmd("Iso Surface", &sg, expt);
-      applyEspRange(cmd);
-      cmd->getParameter("transparency")->setDouble(getTransparency());
-      cmd->getParameter("positiveRed")->setDouble(posR);
-      cmd->getParameter("positiveGreen")->setDouble(posG);
-      cmd->getParameter("positiveBlue")->setDouble(posB);
-      cmd->getParameter("negativeRed")->setDouble(negR);
-      cmd->getParameter("negativeGreen")->setDouble(negG);
-      cmd->getParameter("negativeBlue")->setDouble(negB);
-      fw.execute(cmd);
-
-      updateSurface();
-
-
       // Determine max abs value of field for the (abs value) slider
       // Bruce says that for spin density, its better to hardwire the max
       // scale to no omre than 1.0 but probably even less.
@@ -1035,6 +1021,22 @@ void MoPanel::OnButtonMoComputeClick( wxCommandEvent& event )
       if (espSurface) {
          isovalue = log10(0.002);
       }
+
+      cmd = new IsoSurfaceCmd("Iso Surface", &sg, expt);
+      applyEspRange(cmd);
+      cmd->getParameter("isovalue")->setDouble(pow(10.0, isovalue));
+      cmd->getParameter("transparency")->setDouble(getTransparency());
+      cmd->getParameter("positiveRed")->setDouble(posR);
+      cmd->getParameter("positiveGreen")->setDouble(posG);
+      cmd->getParameter("positiveBlue")->setDouble(posB);
+      cmd->getParameter("negativeRed")->setDouble(negR);
+      cmd->getParameter("negativeGreen")->setDouble(negG);
+      cmd->getParameter("negativeBlue")->setDouble(negB);
+      fw.execute(cmd);
+
+      updateSurface();
+
+
       p_slider->SetValue(isovalue);
       updateIsoValue(isovalue);
 
@@ -1614,6 +1616,8 @@ void MoPanel::rebuildEspSurface()
 
    Command *cmd = new IsoSurfaceCmd("Iso Surface", &sg, expt);
    applyEspRange(cmd);
+   cmd->getParameter("isovalue")->setDouble(
+         pow(10.0, static_cast<double>(p_slider->GetFloatValue())));
    cmd->getParameter("transparency")->setDouble(getTransparency());
    cmd->getParameter("positiveRed")->setDouble(posR);
    cmd->getParameter("positiveGreen")->setDouble(posG);
 
@@ -55,6 +55,8 @@
 
 #ident "$Revision: 22147 $"
 
+#include <cstdio>
+#include <cstdlib>
 #include "inv/actions/SoCallbackAction.H"
 #include "inv/actions/SoGetBoundingBoxAction.H"
 #include "inv/actions/SoGetMatrixAction.H"
@@ -485,4 +487,10 @@ RESET_TIMER();
 
     isoLibIso(threshold.getValue());
 MARK_TIME("DONE with ISO");
+    //  ECCE_DEBUG_ISO: every surface actually generated, with its cutoff.
+    static const bool isoDebug = getenv("ECCE_DEBUG_ISO") != 0;
+    if (isoDebug) {
+        fprintf(stderr, "ISO: ChemIso %p generated at threshold %g, %d vertices\n",
+                (void *)this, threshold.getValue(), vp->vertex.getNum());
+    }
 }
@@ -59,6 +59,12 @@ void IsoSurfaceCmd::init()
    addParameter(new CommandParameter("colorMin", -0.05));
    addParameter(new CommandParameter("colorMax", 0.05));
 
+   //  The cutoff to build the surface at; 0 or less means the field
+   //  type's default below.  A caller that knows the user's cutoff passes
+   //  it: building at the default first showed that surface for a frame
+   //  or two before IsoValueCmd replaced it (#226).
+   addParameter(new CommandParameter("isovalue", 0.0));
+
 }
 
 bool IsoSurfaceCmd::execute()
@@ -287,8 +293,12 @@ bool IsoSurfaceCmd::execute()
         }
       }
 
+      const double requested = getParameter("isovalue")->getDouble();
+      const float threshold = requested > 0.0 ? (float)requested : isovalue;
+      ISO_LOG << "ISO: building at threshold " << threshold << std::endl;
+
       // Since we only deal with absolute values of isovalues:
-      if (isovalue > 0.0) {
+      if (threshold > 0.0) {
          positiveLobeColor = posColor;
          negativeLobeColor = negColor;
       }
@@ -331,7 +341,7 @@ bool IsoSurfaceCmd::execute()
                           gridStruct->colorFieldMax(), transparency);
       }
 
-      isosurf1->threshold.setValue(isovalue);
+      isosurf1->threshold.setValue(threshold);
 
 #ifndef MI10
       /* Well, I guess I sort of screwed you over here, but nothing that can't be
@@ -378,7 +388,7 @@ bool IsoSurfaceCmd::execute()
 
          isosurf2->dataVar = 0;
          isosurf2->colorVar = 0;
-         isosurf2->threshold.setValue(-isovalue);
+         isosurf2->threshold.setValue(-threshold);
 
 #ifndef MI10
          childList = isosurf2->getChildren();
@@ -410,13 +420,13 @@ bool IsoSurfaceCmd::execute()
       chemMesh->kAxis.setValue(true);
       chemMesh->dataVar = 0;
 
-      chemMesh->levels.set1Value(0, isovalue);
+      chemMesh->levels.set1Value(0, threshold);
       chemMesh->orderedRGBA.set1Value(0, positiveLobeColor);
 
       // For other than Density field, we want to display both positive and
       // negative lobes (isosurfaces)
       if (!densityLike) {
-         chemMesh->levels.set1Value(1, -isovalue);
+         chemMesh->levels.set1Value(1, -threshold);
          chemMesh->orderedRGBA.set1Value(1, negativeLobeColor);
       }
 
@@ -438,15 +448,15 @@ bool IsoSurfaceCmd::execute()
       chemContour->kAxis.setValue(false);
       chemContour->dataVar = 0;
 
-      chemContour->levels.set1Value(0, isovalue);
+      chemContour->levels.set1Value(0, threshold);
       chemContour->orderedRGBA.set1Value(0, positiveLobeColor);
       //  vp = (SoVertexProperty *)chemContour->vertexProperty.getValue();
       //  vp->orderedRGBA.setValue(positiveLobeColor);
 
       // For other than Density field, we want to display both positive and
       // negative lobes (isosurfaces)
       if (!densityLike) {
-         chemContour->levels.set1Value(1, -isovalue);
+         chemContour->levels.set1Value(1, -threshold);
          chemContour->orderedRGBA.set1Value(1, negativeLobeColor);
       }