viz: make TUI the default mode, add --png flag for image output

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sbryngelson

docs/documentation/visualization.md

@@ -14,16 +14,16 @@ MFC includes a built-in visualization command that renders images and videos dir
 ### Basic usage
 
 ```bash
-# Plot pressure at the last available timestep (--step defaults to 'last')
-./mfc.sh viz case_dir/ --var pres
+# Launch the terminal UI (default mode)
+./mfc.sh viz case_dir/
 
-# Plot density at all available timesteps
-./mfc.sh viz case_dir/ --var rho --step all
+# Launch with a specific variable pre-selected
+./mfc.sh viz case_dir/ --var pres
 ```
 
 The command auto-detects the output format (binary or Silo-HDF5) and dimensionality (1D, 2D, or 3D).
-Output images are saved to `case_dir/viz/` by default.
-The default colormap is `viridis`, default DPI is 150, and `--step` defaults to `last`.
+By default it launches an interactive terminal UI that works over SSH.
+Use `--interactive` for a browser-based UI (supports 3D), `--png` to save images, or `--mp4` for video.
 
 ### Exploring available data
 
@@ -54,13 +54,13 @@ Customize the appearance of plots:
 
 ```bash
 # Custom colormap and color range
-./mfc.sh viz case_dir/ --var rho --step 1000 --cmap RdBu --vmin 0.5 --vmax 2.0
+./mfc.sh viz case_dir/ --var rho --step 1000 --png --cmap RdBu --vmin 0.5 --vmax 2.0
 
 # Higher resolution
-./mfc.sh viz case_dir/ --var pres --step 500 --dpi 300
+./mfc.sh viz case_dir/ --var pres --step 500 --png --dpi 300
 
 # Logarithmic color scale
-./mfc.sh viz case_dir/ --var schlieren --step 1000 --log-scale
+./mfc.sh viz case_dir/ --var schlieren --step 1000 --png --log-scale
 ```
 
 | Option | Description | Default |
@@ -84,13 +84,13 @@ By default, it slices at the midplane along the z-axis.
 
 ```bash
 # Default z-midplane slice
-./mfc.sh viz case_dir/ --var pres --step 500
+./mfc.sh viz case_dir/ --var pres --step 500 --png
 
 # Slice along the x-axis at x=0.25
-./mfc.sh viz case_dir/ --var pres --step 500 --slice-axis x --slice-value 0.25
+./mfc.sh viz case_dir/ --var pres --step 500 --png --slice-axis x --slice-value 0.25
 
 # Slice by array index
-./mfc.sh viz case_dir/ --var pres --step 500 --slice-axis y --slice-index 50
+./mfc.sh viz case_dir/ --var pres --step 500 --png --slice-axis y --slice-index 50
 ```
 
 ### Video generation
@@ -117,10 +117,10 @@ For 1D cases, omitting `--var` (or passing `--var all`) renders all variables in
 
 ```bash
 # Tiled plot of all variables at the last timestep
-./mfc.sh viz case_dir/ --step last
+./mfc.sh viz case_dir/ --step last --png
 
 # Equivalent explicit form
-./mfc.sh viz case_dir/ --var all --step last
+./mfc.sh viz case_dir/ --var all --step last --png
 ```
 
 Each variable gets its own subplot with automatic LaTeX-style axis labels.
@@ -147,13 +147,13 @@ The interactive viewer provides a Dash web UI with:
 
 ### Terminal UI (TUI)
 
-For environments without a browser — such as SSH sessions or HPC login nodes — use `--tui` to launch a live terminal UI:
+The default mode launches a live terminal UI that works over SSH with no browser or port-forwarding needed:
 
 ```bash
-./mfc.sh viz case_dir/ --tui
+./mfc.sh viz case_dir/
 
 # Start with a specific variable pre-selected
-./mfc.sh viz case_dir/ --var pres --tui
+./mfc.sh viz case_dir/ --var pres
 ```
 
 The TUI loads all timesteps and renders plots directly in the terminal using Unicode block characters.

toolchain/mfc/cli/commands.py

@@ -867,19 +867,19 @@
     description=(
         "Render post-processed MFC output as PNG images or MP4 video, or explore "
         "interactively. Supports 1D line plots, 2D colormaps, 3D midplane slices, "
-        "and tiled all-variable views. PNG files are saved to case_dir/viz/ by default.\n\n"
+        "and tiled all-variable views.\n\n"
         "Output modes:\n"
-        "  (default)      Save PNG image(s) to case_dir/viz/\n"
-        "  --mp4          Encode frames into an MP4 video\n"
+        "  (default)      Launch a terminal UI (works over SSH, no browser needed)\n"
         "  --interactive  Launch a Dash web UI in your browser\n"
-        "  --tui          Launch a terminal UI (works over SSH, no browser needed)\n\n"
+        "  --png          Save PNG image(s) to case_dir/viz/\n"
+        "  --mp4          Encode frames into an MP4 video\n\n"
         "Variable selection:\n"
         "  --var NAME     Plot a single variable\n"
         "  (omit --var)   1D/2D: tiled layout of all variables; 3D: first variable\n\n"
         "Quick-start workflow:\n"
         "  1. ./mfc.sh viz case_dir/ --list-steps\n"
         "  2. ./mfc.sh viz case_dir/ --list-vars --step 0\n"
-        "  3. ./mfc.sh viz case_dir/ --var pres --step 1000"
+        "  3. ./mfc.sh viz case_dir/"
     ),
     positionals=[
         Positional(
@@ -927,15 +927,15 @@
         Argument(
             name="output",
             short="o",
-            help="Directory for saved PNG images or MP4 video (default: case_dir/viz/).",
+            help="Directory for saved PNG images or MP4 video.",
             type=str,
             default=None,
             metavar="DIR",
             completion=Completion(type=CompletionType.DIRECTORIES),
         ),
         Argument(
             name="cmap",
-            help="Matplotlib colormap name (default: viridis).",
+            help="Matplotlib colormap name.",
             type=str,
             default='viridis',
             metavar="CMAP",
@@ -981,14 +981,14 @@
         ),
         Argument(
             name="dpi",
-            help="Image resolution in DPI (default: 150).",
+            help="Image resolution in DPI.",
             type=int,
             default=150,
             metavar="DPI",
         ),
         Argument(
             name="slice-axis",
-            help="Axis for 3D slice: x, y, or z (default: z).",
+            help="Axis for 3D slice.",
             type=str,
             default='z',
             choices=["x", "y", "z"],
@@ -1019,7 +1019,7 @@
         ),
         Argument(
             name="fps",
-            help="Frames per second for MP4 output (default: 10).",
+            help="Frames per second for MP4 output.",
             type=int,
             default=10,
             metavar="FPS",
@@ -1058,38 +1058,36 @@
         ),
         Argument(
             name="port",
-            help="Port for the interactive web server (default: 8050).",
+            help="Port for the interactive web server.",
             type=int,
             default=8050,
             metavar="PORT",
         ),
         Argument(
             name="host",
-            help="Host/bind address for the interactive web server (default: 127.0.0.1).",
+            help="Host/bind address for the interactive web server.",
             default="127.0.0.1",
             metavar="HOST",
         ),
         Argument(
-            name="tui",
+            name="png",
             help=(
-                "Launch an interactive terminal UI (1D/2D only). "
-                "Works over SSH with no browser required. "
-                "Use arrow keys to step through timesteps."
+                "Save PNG image(s) to the output directory instead of "
+                "launching the terminal UI."
             ),
             action=ArgAction.STORE_TRUE,
             default=False,
         ),
     ],
     examples=[
+        Example("./mfc.sh viz case_dir/", "Launch terminal UI (default mode)"),
         Example("./mfc.sh viz case_dir/ --list-steps", "Discover available timesteps"),
         Example("./mfc.sh viz case_dir/ --list-vars --step 0", "Discover available variables at step 0"),
-        Example("./mfc.sh viz case_dir/ --var pres --step 1000", "Save pressure PNG at step 1000 → case_dir/viz/"),
-        Example("./mfc.sh viz case_dir/ --step 1000", "Save tiled PNG of all variables (1D/2D) at step 1000"),
-        Example("./mfc.sh viz case_dir/ --var schlieren --step 0:10000:500 --mp4", "Encode schlieren MP4 from range"),
-        Example("./mfc.sh viz case_dir/ --step 0,100,200,...,1000", "Render all steps 0–1000 (stride inferred)"),
-        Example("./mfc.sh viz case_dir/ --var pres --step 500 --slice-axis x", "3D: x-plane slice of pressure"),
         Example("./mfc.sh viz case_dir/ --var pres --interactive", "Browser UI — scrub timesteps and switch vars"),
-        Example("./mfc.sh viz case_dir/ --var pres --tui", "Terminal UI over SSH (1D/2D, no browser)"),
+        Example("./mfc.sh viz case_dir/ --var pres --step 1000 --png", "Save pressure PNG at step 1000"),
+        Example("./mfc.sh viz case_dir/ --var schlieren --step 0:10000:500 --mp4", "Encode schlieren MP4 from range"),
+        Example("./mfc.sh viz case_dir/ --step 0,100,200,...,1000 --png", "Render all steps 0–1000 as images"),
+        Example("./mfc.sh viz case_dir/ --var pres --step 500 --slice-axis x --png", "3D: x-plane slice of pressure"),
     ],
     key_options=[
         ("-- Discovery --", ""),
@@ -1099,10 +1097,10 @@
         ("--var NAME", "Variable to plot (omit for tiled all-vars layout)"),
         ("--step STEP", "last (default), int, start:stop:stride, list, or 'all'"),
         ("-- Output modes --", ""),
-        ("(default)", "Save PNG to case_dir/viz/; use -o DIR to change"),
-        ("--mp4", "Encode frames into an MP4 video"),
+        ("(default)", "Terminal UI — works over SSH, no browser needed (1D/2D)"),
         ("--interactive / -i", "Dash web UI in browser (supports 1D/2D/3D)"),
-        ("--tui", "Terminal UI over SSH — no browser needed (1D/2D)"),
+        ("--png", "Save PNG image(s) to case_dir/viz/; use -o DIR to change"),
+        ("--mp4", "Encode frames into an MP4 video"),
         ("-- Appearance --", ""),
         ("--cmap NAME", "Matplotlib colormap (default: viridis)"),
         ("--vmin / --vmax", "Fix color-scale limits"),

toolchain/mfc/viz/tui.py

@@ -1,7 +1,7 @@
 """
 Terminal UI (TUI) for MFC visualization using Textual + plotext.
 
-Launched via ``./mfc.sh viz <dir> --tui [--var VAR] [--step STEP]``.
+Launched via ``./mfc.sh viz <dir> [--var VAR] [--step STEP]``.
 Opens a full-terminal interactive viewer that works over SSH with no
 browser or port-forwarding required.
 
@@ -688,7 +688,7 @@ def run_tui(
     """Launch the Textual TUI for MFC visualization (1D/2D only)."""
     if ndim not in (1, 2):
         raise MFCException(
-            f"--tui only supports 1D and 2D data (got ndim={ndim}). "
+            f"Terminal UI only supports 1D and 2D data (got ndim={ndim}). "
             "Use --interactive for 3D data."
         )
 

toolchain/mfc/viz/viz.py

@@ -265,7 +265,10 @@ def viz():  # pylint: disable=too-many-locals,too-many-statements,too-many-branc
     step_arg = ARG('step')
     tiled = varname is None or varname == 'all'
 
-    if ARG('interactive') or ARG('tui') or ARG('mp4'):
+    # TUI is the default mode; --interactive, --png, and --mp4 are explicit.
+    use_tui = not ARG('interactive') and not ARG('png') and not ARG('mp4')
+
+    if ARG('interactive') or use_tui or ARG('mp4'):
         # Load all steps by default; honour an explicit --step so users can
         # reduce the set for large 3D cases before hitting the step limit.
         if step_arg == 'last':
@@ -313,7 +316,7 @@ def viz():  # pylint: disable=too-many-locals,too-many-statements,too-many-branc
 
     # Load all variables when tiled, interactive, or TUI; filter otherwise.
     # TUI needs all vars loaded so the sidebar can switch between them.
-    load_all = tiled or interactive or ARG('tui')
+    load_all = tiled or interactive or use_tui
 
     def read_step(step):
         if fmt == 'silo':
@@ -334,7 +337,7 @@ def read_step(step):
             f"(limit is {_3d_limit}). Use --step with a range or stride to reduce.")
 
     # Tiled mode works for 1D and 2D.  For 3D, auto-select the first variable.
-    if tiled and not interactive and not ARG('tui'):
+    if tiled and not interactive and not use_tui:
         if test_assembled.ndim == 3:
             varname = avail[0] if avail else None
             if varname is None:
@@ -343,7 +346,7 @@ def read_step(step):
             cons.print(f"[dim]Auto-selected variable: [bold]{varname}[/bold]"
                        " (use --var to specify)[/dim]")
 
-    if not tiled and not interactive and not ARG('tui') and varname not in test_assembled.variables:
+    if not tiled and not interactive and not use_tui and varname not in test_assembled.variables:
         # test_assembled was loaded with var_filter=varname so its variables dict
         # may be empty. Re-read without filter (errors only, so extra I/O is fine)
         # to build a useful "available variables" list for the error message.
@@ -367,10 +370,10 @@ def read_step(step):
         _validate_cmap(cmap_name)
 
     # TUI mode — launch Textual terminal UI (1D/2D only)
-    if ARG('tui'):
+    if use_tui:
         if test_assembled.ndim == 3:
             raise MFCException(
-                "--tui only supports 1D and 2D data. "
+                "Terminal UI only supports 1D and 2D data. "
                 "Use --interactive for 3D data."
             )
         from .tui import run_tui  # pylint: disable=import-outside-toplevel