GEECS Scanner GUI - Installation & Setup¶

This guide covers the complete installation and setup process for the GEECS Scanner GUI, including both basic usage and development environment setup.

Prerequisites¶

Required Software¶

Python 3.11: The Scanner GUI requires Python 3.11 (it's pinned to >=3.11,<3.12 in pyproject.toml). Download from: Python 3.11 and use the "Windows installer (64-bit)" link. Important: Check "Add Python 3.11 to PATH" during installation.

Poetry: For dependency management install using the official installer: Poetry Installation. Note, there is a common issue when installing on a windows computer when using the powershell command from the official installer. You may need to change the powershell command to use 'python' rather than 'py' (as noted on the website) if there is an error in installation. After installing, add poetry to PATH.

GEECS-Plugins and GEECS-Plugins-Configs Repositories: Clone or ensure access to the GEECS Plugings and GEECS Plugins Configuration repositories. For basic usage (run only) it is easiest to map to the 'network' repos (i.e. 'z' or 'n' drive). For Development, it is recommended to clone the repos with GitHub Desktop. The HTU workflow for development is to clone the repositories to the 'source' folder located at C:\GEECS\Developers Version\source.

Verify Installation¶

Check your Python installation:

python --version
# Should show: Python 3.11.x

Check your Poetry installation:

poetry --version
# Should show: Poetry (version 2.10.x)
# Note: If poetry version is not shown, make sure poetry was added to PATH.

Installation Options¶

Option 1: Basic Usage (Run Only)¶

For users who only want to run the GUI:

Launch the GUI:¶

a. Open Terminal: Navigate to the GEECS-Scanner-GUI folder in Z: drive

cd Z:\path\to\control-all-loasis\HTU\Active Version\GEECS-Plugins\GEECS-Scanner-GUI

b. Install Dependencies:

poetry install

c. Run the GUI:

poetry run python main.py

Experiment Configuration¶

When you first run the GUI, a pop-up window will prompt for three essential settings (if not prompted, see the 'Create Configuration File' section):

a. GEECS User Data Path: path to the user data in network drive used for configs, database access etc.
```
 - Example: `Z:\path\to\control-all-loasis\HTU\user data`
```
b. Experiment Name: Must match the name shown in Master Control
```
 - Example: `Undulator`, `Thomson`, etc.
 - Case-sensitive!
```
c. Repetition Rate: Experiment repetition rate in Hz
```
 - Used for timing estimates
 - Example: `1` for 1 Hz operation
```
These settings are saved to the path defined in the pop-up window. To populate existing scan elements etc, edit this new config file to be the same as the config template located in: Z:\path\to\control-all-loasis\HTU\geecs_python_api.

Note: If the GUI configuration dialog doesn't work when you first run the GUI, create the config file manually:

a. Create Directory:
```
mkdir ~Users/loasis.LOASIS/.config/geecs_python_api
```
b. Create Config File (~Users/loasis.LOASIS/.config/geecs_python_api/config.ini):
```
[Paths]
geecs_data = Z:\path\to\control-all-loasis\HTU\user data
scanner_config_root_path = Z:\path\to\control-all-loasis\HTU\Active Version\GEECS-Plugins-Configs
image_analysis_configs_path = Z:\path\to\control-all-loasis\HTU\Active Version\GEECS-Plugins-Configs\image_analysis_configs
scan_analysis_configs_path = Z:\path\to\control-all-loasis\HTU\Active Version\GEECS-Plugins-Configs\scan_analysis_configs

[Experiment]
expt = YourExperimentName
rep_rate_hz = 1
```
Create Shortcut to launch GUI day-to-day:¶

Navigate to Z:\path\to\control-all-loasis\HTU\Active Version\GEECS-Plugins\GEECS-Scanner-GUI and create a desktop shortcut to the following file:
```
./GEECS_Scanner.sh
```
Double-click this script every time you want to launch the GUI. If needed, edit this script and add poetry lock before poetry install.

Option 2: Develop + Basic Usage¶

For users who want to run and develop/customize the GUI:

If you have multiple Python versions, specify Python 3.11 explicitly:¶

# Find your Python 3.11 path (example path shown)
poetry env use C:\Users\username\AppData\Local\Programs\Python\Python311\python.exe
poetry install

Verify Environment:¶

poetry env info --path
# This shows the virtual environment location for your IDE configuration.

Setup Data Directory:¶

You must copy the experiment's user data from the server to your local path if not already done:

a. Create Local Directory: Make the directory specified in your config
```
mkdir "C:\GEECS\user data"
```
b. Copy Server Data: Copy existing user data from the server into the local directory specified in previous step.
```
 - HTU example: Copy from `Z:\software\control-all-loasis\HTU\user data`
 - Copy to your configured local path
```
Launch the GUI:¶

a. Open Terminal: Navigate to the GEECS-Scanner-GUI folder
```
cd path/to/GEECS-Plugins/GEECS-Scanner-GUI
```
b. Install Dependencies:
```
poetry install
```
c. Run the GUI:
```
poetry run python main.py
```
Experiment Configuration¶

When you first run the GUI, a pop-up window will prompt for three essential settings (if not prompted, see the 'Create Configuration File' section):

a. GEECS User Data Path: Local path to the user data used for configs, database access etc.
- Example: C:\GEECS\user data\
b. Experiment Name: Must match the name shown in Master Control
- Example: Undulator, Thomson, etc.
- Case-sensitive!
c. Repetition Rate: Experiment repetition rate in Hz
- Used for timing estimates
- Example: 1 for 1 Hz operation
These settings are saved to: ~\.config\geecs_python_api\config.ini

Note: If the GUI configuration dialog doesn't work when you first run the GUI, create the config file manually:

a. Create Directory:
```
mkdir ~/.config/geecs_python_api
```
b. Create Config File (~/.config/geecs_python_api/config.ini):
```
[Paths]
geecs_data = C:\GEECS\user data\
scanner_config_root_path = C:\GEECS\Developers Version\source\GEECS-Plugins-Configs
image_analysis_configs_path = C:\GEECS\Developers Version\source\GEECS-Plugins-Configs\image_analysis_configs
scan_analysis_configs_path = C:\GEECS\Developers Version\source\GEECS-Plugins-Configs\scan_analysis_configs

[Experiment]
expt = YourExperimentName
rep_rate_hz = 1
```
Modify the script if your installation path differs from the default.
Create Shortcut to launch GUI day-to-day¶

Navigate to C:\GEECS\Developers Version\source\GEECS-Plugins\GEECS-Scanner-GUI and create a desktop shortcut to the following file:
```
./GEECS_Scanner.sh
```
Double-click this script every time you want to launch the GUI. Note: you can modify this script to remove poetry install to remove redundancy.

Option 2: Development Environment¶

For code development and customization:

Navigate to Project Directory:

cd path/to/GEECS-Plugins/GEECS-Scanner-GUI

Create Virtual Environment:
```
poetry install
```

If you have multiple Python versions, specify Python 3.11 explicitly:

# Find your Python 3.11 path (example path shown)
poetry env use C:\Users\username\AppData\Local\Programs\Python\Python311\python.exe
poetry install

Verify Environment:
```
poetry env info --path
```
This shows the virtual environment location for your IDE configuration.

First-Time Configuration¶

Development Setup¶

GUI Development¶

The GUI uses PyQt5. To edit GUI files:

Launch Designer:

# From within the poetry environment
pyqt5-tools designer

Edit GUI Files: Located in geecs_scanner/app/gui/

Compile Changes: After editing any .ui file:

cd geecs_scanner/app/gui/
pyuic5 -o ./YourFile_ui.py ./YourFile.ui

Adding Dependencies¶

To add new Python packages:

poetry add package_name

Troubleshooting¶

Common Issues¶

Python Version Problems¶

Error: Poetry can't find Python 3.11 Solution: Explicitly specify the Python path:

poetry env use /path/to/python3.11/python.exe

First Launch Issues¶

Problem: GUI freezes or doesn't enable scanning after first configuration Solution: Restart the GUI after initial configuration

No Save Elements Error¶

Problem: Starting scan with no save elements causes freeze Solution: Always add at least one save element before starting a scan

Immediate Stop Issues¶

Problem: Stopping scan immediately after start causes problems Solution: Wait a few seconds after starting before stopping

Configuration Reset¶

To reconfigure experiment settings, use the "Reset Config" button in the GUI, or delete the config file:

rm ~/.config/geecs_python_api/config.ini

Verification¶

Test Installation¶

Launch GUI: Should open without errors
Check Configuration: Experiment settings should be loaded
Test Elements: Try creating a save element
Test Scan: Run a simple NoScan to verify functionality

Expected File Structure¶

After successful setup, you should have:

~/.config/geecs_python_api/
├── config.ini

C:/GEECS/user data/
├── [experiment-specific directories]

Next Steps¶

Once installation is complete:

Tutorial: Work through the Tutorial for hands-on learning
Configuration: Set up timing and scan variables for your experiment
Elements: Create save elements for your devices
Scanning: Start with simple NoScans before attempting parameter scans

For additional help, consult the Tutorial.

GEECS Scanner GUI - Installation & Setup¶

Prerequisites¶

Required Software¶

Verify Installation¶

Installation Options¶

Option 1: Basic Usage (Run Only)¶

Launch the GUI:¶

Experiment Configuration¶

Create Shortcut to launch GUI day-to-day:¶

Option 2: Develop + Basic Usage¶

If you have multiple Python versions, specify Python 3.11 explicitly:¶

Verify Environment:¶

Setup Data Directory:¶

Launch the GUI:¶

Experiment Configuration¶

Create Shortcut to launch GUI day-to-day¶

Option 2: Development Environment¶

First-Time Configuration¶

Development Setup¶

GUI Development¶

Adding Dependencies¶

Troubleshooting¶

Common Issues¶

Python Version Problems¶

First Launch Issues¶

No Save Elements Error¶

Immediate Stop Issues¶

Configuration Reset¶

Verification¶

Test Installation¶

Expected File Structure¶

Next Steps¶