GUI Tutorial
=============

Launching the GUI
-----------------

Start the application:

.. code-block:: bash

   python -m pyhnhtools.gui.app

Or programmatically:

.. code-block:: python

   from pyhnhtools.gui import make_main_window
   
   window = make_main_window()
   window.show()

Interface Overview
------------------

The GUI consists of three main panels:

**Left Panel (Input)**
    - Load/Save models
    - Create new models
    - Edit parameters

**Center Panel (Visualization)**
    - Interactive plots
    - Profile display
    - Cross-section view

**Right Panel (Results)**
    - Summary statistics
    - Detailed results table
    - Analysis information

Main Workflow
-------------

1. **Load or Create a Model**

   - Click "Load Model" to open existing JSON file
   - Or click "New Model" to start fresh

2. **Edit Model Parameters**

   - Set reach name
   - Specify discharge (Q)
   - Set Manning's roughness (n)

3. **Add/Edit Cross-Sections**

   - Define station and elevation
   - Input cross-section coordinates
   - Add multiple sections

4. **Validate Model**

   - Check for errors
   - Verify data completeness

5. **Run Analysis**

   - Click "Run Solver"
   - Monitor progress
   - View results in real-time

6. **Visualize Results**

   - Water surface profile plot
   - Cross-section plots
   - Velocity visualization

7. **Save Results**

   - Export to JSON
   - Save plots as images
   - Export to CSV

Creating a New Model
--------------------

Step-by-step model creation:

1. Click **"New Model"** button
2. Enter reach name (e.g., "Example Reach")
3. Set discharge: 500 cfs
4. Set Manning's n: 0.035
5. Click **"Add Cross-Section"** button
6. Enter section 1:
   
   - Station: 0.0
   - Elevation: 100.0
   - Coordinates (click to add points):
     - (0, 100)
     - (10, 105)
     - (20, 100)

7. Add section 2:
   
   - Station: 100.0
   - Elevation: 99.5
   - Coordinates:
     - (0, 99.5)
     - (10, 104.5)
     - (20, 99.5)

8. Click **"Run Solver"** to analyze
9. Review results in right panel

Editing Cross-Sections
----------------------

Modify existing cross-sections:

1. Select section from table
2. Click **"Edit Section"**
3. Modify coordinates
4. Click **"Update Section"**
5. Click **"Run Solver"** to recalculate

Plotting Options
----------------

Interactive Plot Features:

- **Hover** for values
- **Zoom** by clicking and dragging
- **Pan** with middle mouse button
- **Reset** view with home icon
- **Export** as PNG using camera icon

Interpretation
^^^^^^^^^^^^^^^

**Profile Plot**
    - Blue line: Channel bed
    - Red line: Water surface
    - Green line: Critical depth (if calculated)

**Cross-Section Plot**
    - Black line: Channel geometry
    - Blue fill: Wetted area

**Velocity Plot**
    - Color gradient: Velocity magnitude
    - Warmer colors: Higher velocities

Saving Your Work
----------------

**Save Model** (JSON)
    - Preserves all geometry and parameters
    - Human-readable format
    - Can be opened in any text editor

**Export Results** (CSV)
    - Station, elevation, WSE, velocity, depth
    - Easy import to Excel or other tools

**Save Plot** (PNG/SVG)
    - High-resolution images
    - Suitable for reports

Keyboard Shortcuts
------------------

- **Ctrl+O**: Open model
- **Ctrl+S**: Save model
- **Ctrl+N**: New model
- **Ctrl+R**: Run solver
- **Ctrl+Q**: Quit application
- **Ctrl+Z**: Undo (if available)

Tips & Tricks
-------------

**Quick Model Setup**
    Use template models and modify parameters

**Batch Analysis**
    Create multiple models with varying discharge

**Quality Checks**
    Always run model validation before solving

**Performance**
    Large cross-sections (>100 points) may slow rendering

**Export Workflow**
    Save JSON model → Run → Export results → Process in Excel

Troubleshooting
---------------

**Plots not displaying**
    - Check data validity
    - Ensure cross-sections overlap
    - Verify water surface solution

**Solver errors**
    - Add more cross-sections
    - Check Manning's n reasonableness (0.02-0.08)
    - Verify coordinate units consistency

**Memory issues**
    - Close other applications
    - Reduce number of cross-section points
    - Use command-line API for large batches

Next Steps
----------

- :doc:`../user_guide/std_step_1d` - Understand solver methodology
- :doc:`../api/core` - Explore Python API
- :doc:`../developer/module_integration` - Extend functionality