Skip to content

Commit 2437d14

Browse files
hweifluidshweifluids
committed
Update 5_gui.rst
1 parent 2660f1b commit 2437d14

1 file changed

Lines changed: 265 additions & 4 deletions

File tree

‎source/5_gui.rst‎

Lines changed: 265 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,269 @@
33
Graphical User Interface (GUI)
44
==============================
55

6-
This page describes how to use GUI mode of ``Streamcenter+``, which is friendly for who would like to use the software without command-line operations.
7-
The author holds the opinion that coding should not be a barrier for using scientific analysis tools such as ``FTLE``.
8-
For some peers or even experts and professors, coding is absolutely boring, especially for GPU tasks on such large dataset scale.
6+
The current mainline GUI of ``Streamcenter+`` is a native Qt/VTK desktop front end for the native
7+
CUDA solver.
8+
It is intended for users who prefer an interactive workflow for setting up ``.par`` files, launching
9+
solver runs, monitoring progress, and previewing FTLE results without typing the full command line
10+
manually.
911

10-
The GUI shares exactly the same functionalities as the command-line mode, but is more difficult to customize, as ``PyQt`` is used for building it.
12+
Unlike the archived legacy GUI, the current interface no longer offers multiple backends.
13+
It always launches the native CUDA solver, using the same ``.par``-based workflow described in
14+
:ref:`inputdeck` and the same structured-VTK input assumptions described in :ref:`input`.
15+
16+
17+
General Workflow
18+
----------------
19+
20+
In typical use, the GUI is operated in the following order:
21+
22+
1. Select the input ``.vtk`` folder and the output folder.
23+
2. Fill in the solver parameters on the left-side parameter pages.
24+
3. Save or reload a ``.par`` file if desired.
25+
4. Start the FTLE run from the toolbar.
26+
5. Monitor progress in the run-status strip and the live console.
27+
6. Open the generated ``.vts`` or ``.pvd`` result for visualization.
28+
7. Export a PNG snapshot or, for time-series results, an MP4 animation.
29+
30+
The GUI does not replace external post-processing entirely.
31+
For publication-quality rendering and advanced analysis, ``ParaView`` or other VTK-capable tools
32+
are still recommended after the initial inspection.
33+
34+
35+
Top Toolbar and File Menu
36+
-------------------------
37+
38+
The top toolbar combines run control and result viewing.
39+
Its main groups are:
40+
41+
- the file menu, opened from the left-most menu button;
42+
- run controls for start, pause/resume, and stop;
43+
- a result-file row for browsing and opening ``*.vts``, ``*.vtk``, or ``*.pvd`` files;
44+
- animation controls for time-series browsing;
45+
- view/export controls such as parallel projection, PNG capture, and MP4 export.
46+
47+
The file menu currently provides these actions:
48+
49+
- ``Open Input Folder``;
50+
- ``Open Output Folder``;
51+
- ``Reload *.Par File``;
52+
- ``Generate *.Par for FTLE``;
53+
- ``About``.
54+
55+
This makes the GUI suitable both as a run launcher and as a lightweight parameter-file editor.
56+
57+
58+
Left Panel: Parameter Pages
59+
---------------------------
60+
61+
The left side of the window is organized as a tree and stacked pages.
62+
In the current mainline GUI, the main pages are:
63+
64+
- ``File IO and Range Settings``;
65+
- ``Numerical Methods Control``;
66+
- ``Visualization``;
67+
- ``Dynamic LCS``.
68+
69+
70+
File IO and Range Settings
71+
~~~~~~~~~~~~~~~~~~~~~~~~~~
72+
73+
This page collects the basic case definition:
74+
75+
- input ``.vtk`` folder;
76+
- results folder;
77+
- automatic or manual wall range;
78+
- particle lattice sizes in :math:`x`, :math:`y`, and :math:`z`;
79+
- integration range ``T_range``;
80+
- advection step ``dt``;
81+
- physical frame step ``physical_dt``.
82+
83+
Both the input folder and the output folder must already exist when a run is launched.
84+
The current GUI checks these folders before starting the solver and warns if either one is missing.
85+
86+
When ``Auto wall range`` is enabled, the solver uses the input grid bounds automatically.
87+
When it is disabled, the manual wall ranges must be filled explicitly.
88+
89+
90+
Numerical Methods Control
91+
~~~~~~~~~~~~~~~~~~~~~~~~~
92+
93+
This page exposes the major solver options currently supported by the native backend:
94+
95+
- direction: double-side or forward-only;
96+
- wall treatment;
97+
- advection scheme;
98+
- interpolation method;
99+
- gradient discretization;
100+
- Cauchy-Green eigenvalue method.
101+
102+
The backend label shown on this page is informative: in the current mainline it is always the
103+
native CUDA path.
104+
105+
106+
Visualization
107+
~~~~~~~~~~~~~
108+
109+
This page controls how loaded FTLE results are displayed in the embedded viewer.
110+
The current options include:
111+
112+
- whether to display forward FTLE, backward FTLE, or both;
113+
- opaque versus transparent surface rendering;
114+
- one isovalue slider for ``FTLE_forward``;
115+
- one isovalue slider for ``FTLE_backward``.
116+
117+
These sliders become meaningful only after a result file containing the corresponding FTLE arrays
118+
has been loaded.
119+
If one of the arrays is absent, the related control becomes unavailable automatically.
120+
121+
122+
Dynamic LCS
123+
~~~~~~~~~~~
124+
125+
This page switches between steady and dynamic operation:
126+
127+
- ``Steady`` corresponds to one still FTLE solve over the chosen range;
128+
- ``Dynamic`` enables sliding-window processing and exposes ``win_size`` and ``win_step``.
129+
130+
When dynamic mode is disabled, the window-size entries are cleared and ignored.
131+
When dynamic mode is enabled, these values should be provided consistently with the finite-time
132+
interpretation discussed in :ref:`unsteady`.
133+
134+
135+
Launching a Run
136+
---------------
137+
138+
Pressing the run button causes the GUI to collect the current settings, validate the required
139+
entries, and write an auto-generated ``.par`` file into the selected output directory.
140+
Its filename follows the form
141+
``GUIsolve_YYMMDDhhmmss.par``.
142+
143+
The GUI then launches the native solver executable with that generated parameter file.
144+
If the solver executable cannot be found, the GUI reports where it looked and instructs the user to
145+
build or install the solver first.
146+
147+
At present, the GUI does not launch an alternative Python backend, nor does it expose command-line
148+
style ad hoc overrides outside the parameter pages.
149+
150+
151+
Run Monitoring
152+
--------------
153+
154+
During execution, two feedback channels are visible:
155+
156+
- a compact run-status strip under the parameter pages;
157+
- a console panel on the lower right.
158+
159+
The run-status strip summarizes stages such as launching, loading, running, completion, pause, or
160+
failure.
161+
The console shows the forwarded solver output and GUI-side messages such as generated filenames and
162+
log-file locations.
163+
164+
For each GUI-launched run, the current implementation also opens a log file in the output
165+
directory, named after the solver process ID, for example ``12345.log``.
166+
167+
The pause button suspends or resumes the solver process.
168+
The stop button terminates the running process.
169+
These controls are intended for long FTLE jobs where an interactive interruption may be necessary.
170+
171+
172+
Embedded Result Viewer
173+
----------------------
174+
175+
The right side of the main window contains an embedded VTK viewer.
176+
It can open:
177+
178+
- ``*.vts`` result files;
179+
- legacy ``*.vtk`` files for general inspection;
180+
- ``*.pvd`` collections for time-series browsing.
181+
182+
Once a result is loaded, the viewer shows:
183+
184+
- a structured-domain outline;
185+
- FTLE isosurfaces if ``FTLE_forward`` and/or ``FTLE_backward`` arrays are present;
186+
- an orientation axes marker;
187+
- a small ``Streamcenter+`` watermark;
188+
- for ``.pvd`` time series, a time label and a frame slider.
189+
190+
The current visualization model is iso-surface based.
191+
When both forward and backward FTLE fields are available, the GUI can display both simultaneously
192+
with separate colors.
193+
The transparency toggle is useful when overlapping surfaces should remain visible.
194+
195+
Parallel projection can be toggled directly from the toolbar.
196+
The viewer uses standard interactive camera manipulation through the VTK trackball camera style.
197+
198+
199+
Time-Series Playback
200+
--------------------
201+
202+
When a ``.pvd`` time series is loaded, the viewer enables:
203+
204+
- jump to first frame;
205+
- play or stop animation;
206+
- jump to last frame;
207+
- direct frame selection through the on-screen slider.
208+
209+
The GUI sorts and follows the time information contained in the ``.pvd`` collection file.
210+
This makes it convenient to inspect dynamic-window outputs produced by the solver.
211+
212+
The MP4 export function is available only in this time-series state.
213+
If a single still ``.vts`` file is loaded instead, the GUI informs the user that MP4 export is not
214+
available for that case.
215+
216+
217+
Saving and Reusing Parameter Files
218+
----------------------------------
219+
220+
The GUI can both load an existing ``.par`` file and generate a new one from the current widget
221+
state.
222+
This is useful for moving between GUI-driven setup and command-line execution.
223+
224+
In practical terms:
225+
226+
- ``Reload *.Par File`` imports settings from an existing parameter file into the GUI;
227+
- ``Generate *.Par for FTLE`` writes a user-chosen parameter file without starting a run;
228+
- pressing ``Run`` writes a fresh auto-generated ``.par`` file and immediately launches the solver.
229+
230+
This workflow is especially convenient when one wants to prototype a case visually and later move
231+
the exact setup to command-line or batch execution.
232+
233+
234+
PNG and MP4 Export
235+
------------------
236+
237+
Two export paths are currently integrated:
238+
239+
- ``PNG`` saves the current viewer image as a snapshot;
240+
- ``MP4`` exports a time-series animation by rendering frames and calling ``ffmpeg``.
241+
242+
PNG export requires only a loaded scene.
243+
MP4 export additionally requires:
244+
245+
- a loaded ``.pvd`` time series;
246+
- a valid output file path;
247+
- an ``ffmpeg`` executable available on ``PATH``.
248+
249+
The MP4 dialog lets the user choose:
250+
251+
- output filename;
252+
- frame rate;
253+
- frame stride;
254+
- exported frame window.
255+
256+
If ``ffmpeg`` is missing, the export fails with an explicit error message.
257+
258+
259+
Important Notes and Limits
260+
--------------------------
261+
262+
- The GUI is a front end to the native CUDA solver only; the legacy Python GUI is not the active
263+
mainline path.
264+
- The GUI does not create missing input or output folders automatically; they should exist before a
265+
run is started.
266+
- The GUI-side result viewer can open ``.vtk`` files, but the solver input workflow itself still
267+
expects a folder of qualified legacy ``.vtk`` frames as described in :ref:`input`.
268+
- Interactive plotting through ``if_visual`` is not the mainline command-solver workflow. Result
269+
inspection is expected to happen through the embedded viewer or an external post-processor.
270+
- The embedded viewer is intentionally lightweight. For more advanced clipping, transfer functions,
271+
camera scripting, or batch rendering, external VTK tools remain preferable.

0 commit comments

Comments
 (0)