TUI System Architecture

The Problem: GUI-Only Tools in Remote Environments

Many scientific computing tools only provide graphical interfaces, making them unusable on remote servers, HPC clusters, and SSH connections. Researchers working with high-content screening data often need to process images on remote machines where X11 forwarding is slow or unavailable. This forces users to either transfer large datasets locally (slow, error-prone) or use command-line tools that lack the visual feedback and interactive configuration that GUIs provide.

Overview

OpenHCS provides a terminal user interface (TUI) built with the Textual framework. This interface works in terminal environments, including remote servers, containers, and SSH connections.

Note: This document describes the actual TUI implementation. Some features are aspirational and marked as “Future Enhancements”.

Architecture

Core Components

Real-Time Pipeline Editor

# Interactive pipeline creation with live validation:
┌─ Pipeline Editor ─────────────────────────────────┐
│ [Add Step] [Delete] [Edit] [Load] [Save]          │
│                                                   │
│ 1. ✓ gaussian_filter (sigma=2.0)                 │
│ 2. ✓ binary_opening (footprint=disk(3))          │
│ 3. ⚠ custom_function (missing parameter)         │
│ 4. ✓ label (connectivity=2)                      │
│                                                   │
│ Status: 3/4 steps valid | GPU Memory: 2.1GB      │
└───────────────────────────────────────────────────┘

Features: - Live validation: Steps validated as you type - Visual feedback: Color-coded status indicators - Resource monitoring: Real-time GPU memory usage - Button-based management: Add, Delete, Edit, Load, Save operations - Per-plate pipeline storage: Separate pipelines for each plate

Live Configuration Management

# Dynamic configuration with instant validation:
┌─ Global Configuration ────────────────────────────┐
│ Workers: [8] ▲▼     VFS Backend: [memory] ▼       │
│ GPU Slots: [4] ▲▼   Zarr Compression: [lz4] ▼     │
│                                                   │
│ ✓ Configuration valid                             │
│ ⚠ Warning: High memory usage with 8 workers       │
└───────────────────────────────────────────────────┘

Features: - Instant validation: Configuration checked in real-time - Smart warnings: Proactive resource usage alerts - Type-safe inputs: Prevents invalid configuration values - Context-sensitive help: Tooltips and documentation - Profile management: Save/load configuration presets

Integrated Help System

# Context-sensitive help with full type information:
┌─ Help: gaussian_filter ───────────────────────────┐
│ gaussian_filter (sigma: float = 1.0)              │
│                                                   │
│ Apply Gaussian blur to image stack.               │
│                                                   │
│ Parameters:                                       │
│ • sigma: float - Standard deviation for blur      │
│ • mode: str (optional) - Boundary condition       │
│                                                   │
│ Memory: numpy → numpy | Contract: SLICE_SAFE      │
└───────────────────────────────────────────────────┘

Features: - Full type information: Complete Union types, not just “Union” - Parameter separation: Individual parameters with descriptions - Memory contracts: Shows input/output memory types - Processing behavior: SLICE_SAFE vs CROSS_Z indicators - Example usage: Code snippets and common patterns

Professional Log Monitoring

# Real-time log viewing with filtering:
┌─ System Logs ─────────────────────────────────────┐
│ [Current Session ▼] [Filter: ERROR ▼] [Tail: ON]  │
│                                                   │
│ 12:34:56 INFO  Pipeline compiled successfully     │
│ 12:34:57 DEBUG GPU memory allocated: 1.2GB        │
│ 12:34:58 ERROR Step 3 validation failed           │
│ 12:34:59 INFO  Retrying with CPU fallback         │
│                                                   │
│ Lines: 1,247 | Filtered: 23 errors                │
└───────────────────────────────────────────────────┘

Features: - Multi-file support: Switch between different log files - Real-time tailing: Live updates as logs are written - Advanced filtering: Filter by level, component, or pattern - Session management: Only shows current session logs - Search functionality: Find specific log entries quickly

Architecture

Textual Framework Integration

# Actual TUI architecture (window-based):
class OpenHCSTUIApp(App):
    """Main OpenHCS Textual TUI Application."""

    def __init__(self, global_config: Optional[GlobalPipelineConfig] = None):
        super().__init__()
        self.global_config = global_config or get_default_global_config()
        self.storage_registry = storage_registry
        self.filemanager = FileManager(self.storage_registry)

    def compose(self) -> ComposeResult:
        """Compose the main application layout."""
        # Custom window bar for window management
        yield CustomWindowBar(dock="bottom", start_open=True)

        # Status bar for messages
        yield StatusBar()

        # Main content with system monitor background
        yield MainContent(
            filemanager=self.filemanager,
            global_config=self.global_config
        )

Component Architecture

# Actual TUI component architecture:
TUI Components:
├── Core Application (OpenHCSTUIApp)
├── Main Layout
│   ├── CustomWindowBar (window management)
│   ├── StatusBar (status messages)
│   └── MainContent (SystemMonitor background)
├── Floating Windows (textual-window)
│   ├── PipelinePlateWindow (PlateManagerWidget + PipelineEditorWidget)
│   ├── ConfigWindow (configuration editing)
│   ├── HelpWindow (help system)
│   ├── DualEditorWindow (function step editing)
│   └── ErrorDialog (error display)
├── Core Widgets
│   ├── PlateManagerWidget (plate management)
│   ├── PipelineEditorWidget (pipeline editing)
│   ├── OpenHCSToolongWidget (log viewing)
│   ├── FunctionListEditorWidget (function editing)
│   └── ConfigFormWidget (configuration forms)
└── Services
    ├── ValidationService (form validation)
    ├── TerminalLauncher (external editor)
    └── GlobalConfigCache (configuration caching)

State Management

# Actual reactive state implementation:
class PipelineEditorWidget(ButtonListWidget):
    # Real reactive properties from implementation
    pipeline_steps = reactive([])
    current_plate = reactive("")
    selected_step = reactive("")
    plate_pipelines = reactive({})  # Per-plate pipeline storage

    def watch_pipeline_steps(self, old_steps, new_steps):
        """Automatically called when pipeline_steps changes."""
        logger.debug(f"Pipeline steps changed: {len(new_steps)} steps")
        self._update_button_states()
        self._update_display()

Remote Access Capabilities

SSH-Friendly Design

# Works perfectly over SSH connections:
ssh user@remote-server
cd /path/to/openhcs
python -m openhcs.textual_tui

# Full functionality maintained:
✅ Interactive editing
✅ Real-time updates
✅ Mouse support (when available)
✅ Keyboard navigation
✅ Copy/paste operations

Web Interface Option

# Optional web interface for browser access:
python -m openhcs.textual_tui --web

# Serves TUI in browser:
🌐 Starting OpenHCS web server...
🔗 Your TUI will be available at: http://localhost:8000
📝 Share this URL to give others access to your OpenHCS TUI
⚠️  Note: The TUI runs on YOUR machine, others just see it in their browser

Container Compatibility

# Works in Docker containers:
docker run -it openhcs/openhcs python -m openhcs.textual_tui

# Kubernetes deployment:
kubectl run openhcs-tui --image=openhcs/openhcs --stdin --tty \
  --command -- python -m openhcs.textual_tui

Comparison with Other Scientific Tools

Traditional Scientific Interfaces

T ool

Interface Type

Remote Access

Real-time Updates

Help System

Im age J*

Desktop GUI

❌ X11 forwarding only

❌ Manual refresh

⚠️ Basic tooltips

Ce llP rof ile r*

Desktop GUI

❌ X11 forwarding only

❌ Static interface

⚠️ Separate doc umentation

na par i*

Desktop GUI

❌ X11 forwarding required

⚠️ Limited updates

⚠️ Plugin -dependent

** FIJ I**

Desktop GUI

❌ X11 forwarding only

❌ Manual refresh

⚠️ Wiki-based help

** Ope nHC S**

Terminal TUI

✅ SSH native

✅ Live updates

Integrated help**

Command-Line Tools

Tool

Interactivity

Configuration

Monitoring

Usability

Tra diti onal C LI*

❌ Batch only

⚠️ Config files

❌ Log files only

⚠️ Expert users

Ope nHCS T UI*

✅ * Interactive*

✅ Live editing

Real-time**

✅ User- friendly

Performance Characteristics

Resource Usage

# Terminal interface characteristics:
Memory Usage: Lightweight compared to desktop GUIs
CPU Usage: Low idle, moderate during updates
Network: Minimal (text-based updates only)
Latency: Responsive over SSH connections

Scalability

# Handles large-scale operations:
✅ 100GB+ dataset monitoring
✅ Multi-GPU resource tracking
✅ Thousands of pipeline steps
✅ Real-time log streaming
✅ Concurrent user sessions

Future Enhancements

Planned Features

# Roadmap for TUI improvements:
├── Advanced Visualizations
│   ├── ASCII-based image previews
│   ├── Progress bars with ETA
│   └── Resource usage graphs
├── Collaboration Features
│   ├── Multi-user editing
│   ├── Session sharing
│   └── Real-time collaboration
├── Automation Integration
│   ├── Workflow scheduling
│   ├── Batch job management
│   └── CI/CD integration
└── Mobile Support
    ├── Responsive layouts
    ├── Touch-friendly navigation
    └── Mobile-optimized workflows

Plugin Architecture

# Extensible widget system:
class CustomWidget(Widget):
    """User-defined TUI widget."""

    def compose(self) -> ComposeResult:
        yield Static("Custom functionality")

    def on_mount(self):
        """Register with TUI system."""
        self.app.register_widget(self)

Technical Implementation

Event System

# Reactive event handling:
class PipelineEditor(Widget):
    def on_button_pressed(self, event: Button.Pressed) -> None:
        """Handle button press events."""
        if event.button.id == "add_step":
            self.add_new_step()
        elif event.button.id == "delete_step":
            self.delete_selected_step()

    def on_selection_changed(self, event: SelectionList.SelectionChanged) -> None:
        """Handle selection changes."""
        self.selected_step = event.selection
        self.update_step_details()

Validation Integration

# Real-time validation:
def validate_pipeline_step(self, step_data):
    """Validate step configuration in real-time."""
    try:
        # Use OpenHCS validation services
        result = ValidationService.validate_step(step_data)
        self.update_validation_status(step_data.id, result)
    except Exception as e:
        self.show_validation_error(step_data.id, str(e))

This TUI system represents a paradigm shift in scientific computing interfaces - providing comprehensive functionality in a terminal-native environment that works anywhere researchers need to process data.

See Also

Core Integration:

Practical Usage:

Advanced Topics: