dudong-v2/ui/dialogs/help_dialog.py

"""
Help Dialog

Displays usage instructions and help information for the DuDONG application.
"""

from PyQt5.QtWidgets import (QDialog, QVBoxLayout, QLabel, QPushButton, 
                              QScrollArea, QWidget, QTabWidget)
from PyQt5.QtCore import Qt
from PyQt5.QtGui import QFont

from resources.styles import STANDARD_BUTTON_STYLE, TAB_WIDGET_STYLE


class HelpDialog(QDialog):
    """
    Help dialog window showing usage instructions.
    
    Displays:
    - Getting started guide
    - Feature descriptions
    - Usage instructions for each tool
    - Troubleshooting tips
    - Keyboard shortcuts
    """
    
    def __init__(self, parent=None):
        """
        Initialize the help dialog.
        
        Args:
            parent: Parent widget
        """
        super().__init__(parent)
        self.setWindowTitle("DuDONG Help")
        self.setMinimumSize(950, 650)
        self.init_ui()
    
    def init_ui(self):
        """Initialize the UI components."""
        layout = QVBoxLayout()
        layout.setContentsMargins(10, 10, 10, 10)
        layout.setSpacing(10)
        
        # Title
        title = QLabel("DuDONG Help & Documentation")
        title.setFont(QFont("Arial", 16, QFont.Bold))
        title.setAlignment(Qt.AlignCenter)
        title.setStyleSheet("color: #2c3e50; margin: 5px;")
        layout.addWidget(title)
        
        # Tab widget for different help sections
        tabs = QTabWidget()
        tabs.setStyleSheet(TAB_WIDGET_STYLE)
        tabs.setTabPosition(QTabWidget.North)
        tabs.setMovable(False)
        tabs.setDocumentMode(False)
        
        # Getting Started Tab
        tabs.addTab(self._create_getting_started(), "Getting Started")
        
        # Comprehensive Analysis Tab (NEW - Primary workflow)
        tabs.addTab(self._create_comprehensive_analysis(), "Analyze Durian")
        
        # System Info Tab
        tabs.addTab(self._create_system_info(), "System Requirements")
        
        # Troubleshooting Tab
        tabs.addTab(self._create_troubleshooting(), "Troubleshooting")
        
        layout.addWidget(tabs, 1)
        
        # Close button
        close_btn = QPushButton("Close")
        close_btn.setStyleSheet(STANDARD_BUTTON_STYLE)
        close_btn.clicked.connect(self.accept)
        layout.addWidget(close_btn, alignment=Qt.AlignRight)
        
        self.setLayout(layout)
    
    def _create_scrollable_content(self, content_text: str) -> QScrollArea:
        """
        Create a scrollable text area.
        
        Args:
            content_text: HTML formatted text content
        
        Returns:
            QScrollArea with content
        """
        scroll = QScrollArea()
        scroll.setWidgetResizable(True)
        scroll.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
        
        label = QLabel(content_text)
        label.setWordWrap(True)
        label.setTextFormat(Qt.RichText)
        label.setStyleSheet("padding: 20px; color: #2c3e50; line-height: 1.6;")
        
        scroll.setWidget(label)
        return scroll
    
    def _create_comprehensive_analysis(self) -> QWidget:
        """Create the comprehensive analysis (Analyze Durian) help tab."""
        content = """
        <h2>Comprehensive Durian Analysis</h2>
        
        <h3>Overview</h3>
        <p>The <b>"Analyze Durian"</b> feature is DuDONG's primary workflow for comprehensive fruit grading. It combines multiple AI models to analyze different aspects of durian quality, ripeness, and maturity in a single analysis session.</p>
        
        <h3>Two Analysis Modes</h3>
        
        <h4>1. Manual Entry Mode (Current)</h4>
        <p>Select data files from different camera and sensor sources:</p>
        <ul>
            <li><b>DSLR Side View</b> (JPG/PNG/BMP) - Plain durian image for defect detection</li>
            <li><b>DSLR Top View</b> (JPG/PNG/BMP) - Cross-section or top view for locule counting</li>
            <li><b>Multispectral TIFF</b> (TIF/TIFF) - 12-band multispectral image for maturity analysis</li>
            <li><b>Thermal CSV</b> (CSV) - Thermal imaging data (future integration)</li>
            <li><b>Audio WAV</b> (WAV) - Audio recording of knock sound for ripeness classification</li>
        </ul>
        <p><i>At least one input is required. All other inputs are optional.</i></p>
        
        <h4>2. Auto Mode (Future)</h4>
        <p>Automatically detects and captures data from running camera applications:</p>
        <ul>
            <li><b>EOS Utility</b> - Canon DSLR capture</li>
            <li><b>2nd Look</b> - Multispectral camera capture</li>
            <li><b>AnalyzIR</b> - Thermal imaging capture</li>
        </ul>
        
        <h3>Available Analysis Models</h3>
        
        <p><b>1. Ripeness Classification (Audio)</b></p>
        <ul>
            <li><b>Input:</b> Audio WAV file of knock sound</li>
            <li><b>Processing:</b> Detects individual knocks and averages predictions</li>
            <li><b>Output:</b> Unripe, Ripe, or Overripe (with confidence %)</li>
        </ul>
        
        <p><b>2. Defect Detection (RGB Side View)</b></p>
        <ul>
            <li><b>Input:</b> Image of durian side view</li>
            <li><b>Processing:</b> YOLOv8-based defect detection</li>
            <li><b>Output:</b> No Defects, Minor Defects, or Reject classification</li>
        </ul>
        
        <p><b>3. Locule Counting (RGB Top View)</b></p>
        <ul>
            <li><b>Input:</b> Cross-section or top view image</li>
            <li><b>Processing:</b> YOLOv8 segmentation to identify and count locules</li>
            <li><b>Output:</b> Total locule count with color-coded visualization</li>
        </ul>
        
        <p><b>4. Maturity Classification (Multispectral)</b></p>
        <ul>
            <li><b>Input:</b> 12-band multispectral TIFF image</li>
            <li><b>Processing:</b> Deep learning model analyzes spectral signatures</li>
            <li><b>Output:</b> Immature, Mature, or Overmature classification</li>
        </ul>
        
        <p><b>5. Shape Classification (RGB)</b></p>
        <ul>
            <li><b>Input:</b> Image of durian</li>
            <li><b>Processing:</b> YOLO classification model</li>
            <li><b>Output:</b> Regular or Irregular shape classification</li>
        </ul>
        
        <h3>Workflow Steps</h3>
        <ol>
            <li>Click <b>"Manual Entry"</b> button on the Dashboard</li>
            <li>In the dialog that opens, select files for desired analyses (at least one required)</li>
            <li>Click <b>"Confirm"</b> to start processing</li>
            <li>System automatically navigates to <b>Reports</b> tab</li>
            <li>Models process inputs in parallel using available GPU</li>
            <li>View comprehensive results with:
                <ul>
                    <li>Overall grade (A/B/C)</li>
                    <li>Individual model results with confidence scores</li>
                    <li>Annotated images and visualizations</li>
                </ul>
            </li>
            <li>Click <b>"Export PDF"</b> to save detailed report</li>
        </ol>
        
        <h3>Understanding the Report</h3>
        <ul>
            <li><b>Overall Grade</b> - Combined assessment: A (best), B (good), C (acceptable)</li>
            <li><b>Analysis ID</b> - Unique identifier stored in database for future reference</li>
            <li><b>Individual Results</b> - Each model's prediction with confidence percentage</li>
            <li><b>Visualizations</b> - Annotated images, spectrograms, and Grad-CAM explanations</li>
            <li><b>Processing Time</b> - Total time to complete all analyses</li>
        </ul>
        
        <h3>Grade Calculation</h3>
        <p>Overall grade is determined by combining results from all available analyses:</p>
        <ul>
            <li><b>Grade A:</b> Premium quality - optimal ripeness, no defects, ideal maturity, regular shape</li>
            <li><b>Grade B:</b> Good quality - acceptable ripeness, minor defects, good maturity</li>
            <li><b>Grade C:</b> Standard quality - mixed indicators, some defects, acceptable maturity</li>
        </ul>
        
        <h3>Tips for Best Results</h3>
        <ul>
            <li>Use high-quality images (1920x1080 or higher resolution)</li>
            <li>Ensure good lighting and avoid shadows on durian</li>
            <li>Record audio in a quiet environment with consistent knocking force</li>
            <li>Position durian clearly in the center of images</li>
            <li>Use proper file formats: JPG/PNG for images, WAV for audio, TIFF for multispectral</li>
        </ul>
        """
        return self._create_scrollable_content(content)
    
    def _create_getting_started(self) -> QWidget:
        """Create the getting started help tab."""
        content = """
        <h2>Getting Started with DuDONG</h2>
        
        <h3>Dashboard Overview</h3>
        <p>The main dashboard is your control center for all durian analysis:</p>
        <ul>
            <li><b>System Status Panel</b> - View status of all AI models (Ripeness, Quality, Defect, Maturity)</li>
            <li><b>Quick Actions Panel</b> - Two main buttons:
                <ul>
                    <li><b>Auto Analyze Durian</b> - Automatically detects and captures from camera applications</li>
                    <li><b>Manual Entry</b> - Manually select files from different camera sources</li>
                </ul>
            </li>
            <li><b>Recent Results Panel</b> - View and reload your last 5 analyses</li>
            <li><b>System Information Panel</b> - Monitor performance: uptime, throughput, processing time, and model accuracy</li>
            <li><b>Live Feeds Panel</b> - Placeholder for future camera integration</li>
        </ul>
        
        <h3>Quick Start Workflow</h3>
        <ol>
            <li>Click <b>"Manual Entry"</b> on the Dashboard (Auto mode requires running camera apps)</li>
            <li>Select data from available camera sources in the dialog:
                <ul>
                    <li>DSLR Side View (optional) - Image for defect detection</li>
                    <li>DSLR Top View (optional) - Image for locule counting</li>
                    <li>Multispectral TIFF (optional) - For maturity classification</li>
                    <li>Audio WAV (optional) - For ripeness classification</li>
                </ul>
            </li>
            <li>At least one input is required. All other inputs are optional.</li>
            <li>Click <b>Confirm</b> to start analysis</li>
            <li>View comprehensive results in the <b>Reports</b> tab</li>
        </ol>
        
        <h3>Navigation</h3>
        <p>The application has two main tabs:</p>
        <ul>
            <li><b>Dashboard</b> - Main overview and quick action buttons</li>
            <li><b>Reports</b> - Detailed analysis results and PDF export</li>
        </ul>
        <p><i>Note: Ripeness, Quality, and Maturity tabs are available for individual model testing.</i></p>
        
        <h3>Understanding Results</h3>
        <ul>
            <li><b>Overall Grade</b> - A/B/C classification based on all analysis results</li>
            <li><b>Ripeness</b> - Audio-based classification: Unripe, Ripe, or Overripe</li>
            <li><b>Quality</b> - Defect detection: No Defects, Minor Defects, or Reject</li>
            <li><b>Maturity</b> - Multispectral-based classification: Immature, Mature, or Overmature</li>
            <li><b>Shape</b> - Shape classification: Regular or Irregular</li>
            <li><b>Locule Count</b> - Number of segments detected in top view</li>
        </ul>
        """
        return self._create_scrollable_content(content)
    
    def _create_system_info(self) -> QWidget:
        """Create the system requirements tab."""
        content = """
        <h2>System Requirements</h2>
        
        <h3>Minimum Requirements</h3>
        <ul>
            <li><b>Operating System:</b> Windows 10/11, Linux, or macOS</li>
            <li><b>Python:</b> 3.9 or higher</li>
            <li><b>RAM:</b> 8GB minimum, 16GB recommended</li>
            <li><b>Storage:</b> 10GB free space (includes models and database)</li>
            <li><b>Display:</b> 1920x1080 resolution or higher for optimal UI</li>
        </ul>
        
        <h3>Recommended Configuration</h3>
        <ul>
            <li><b>GPU:</b> NVIDIA GPU with CUDA 12.8 support (highly recommended)</li>
            <li><b>VRAM:</b> 4GB VRAM or more for fast processing</li>
            <li><b>RAM:</b> 32GB for batch processing multiple analyses</li>
            <li><b>CPU:</b> Multi-core processor (8+ cores) for parallel processing</li>
            <li><b>SSD:</b> NVMe SSD for faster model loading</li>
        </ul>
        
        <h3>GPU Acceleration Setup</h3>
        <p>For optimal performance with NVIDIA GPU:</p>
        <ol>
            <li>Install latest NVIDIA GPU drivers</li>
            <li>Install CUDA Toolkit 12.8</li>
            <li>Install cuDNN 9.x for CUDA 12.x</li>
            <li>Verify installation: Check System Info panel shows GPU status as "Active"</li>
        </ol>
        
        <h3>Required Dependencies</h3>
        <ul>
            <li><b>PyQt5</b> - GUI framework</li>
            <li><b>TensorFlow 2.17+</b> - Deep learning (audio model)</li>
            <li><b>PyTorch</b> - Deep learning (YOLO models)</li>
            <li><b>Ultralytics YOLO</b> - Object detection and segmentation</li>
            <li><b>OpenCV 4.10+</b> - Image processing</li>
            <li><b>NumPy</b> - Numerical computations</li>
            <li><b>SciPy</b> - Signal processing</li>
            <li><b>Matplotlib</b> - Visualization</li>
            <li><b>Librosa</b> - Audio analysis</li>
            <li><b>Pillow</b> - Image handling</li>
        </ul>
        
        <h3>Model Files Required</h3>
        <p>All model files must be present in the project directory:</p>
        <ul>
            <li><b>models/audio/best_model_mel_spec_grouped.keras</b> - Ripeness audio model</li>
            <li><b>best.pt</b> - Defect detection model (YOLOv8)</li>
            <li><b>locule.pt</b> - Locule segmentation model (YOLOv8)</li>
            <li><b>models/multispectral/maturity/final_model.pt</b> - Maturity classification model</li>
            <li><b>shape.pt</b> - Shape classification model (YOLOv8)</li>
        </ul>
        
        <h3>Database Setup</h3>
        <ul>
            <li><b>Location:</b> data/database.db</li>
            <li><b>Automatic:</b> Database is created automatically on first run</li>
            <li><b>Storage:</b> Stores all analysis results, input files, and visualizations</li>
            <li><b>Size:</b> Grows with number of analyses (typically 100MB per 1000 analyses)</li>
        </ul>
        
        <h3>Disk Space Estimates</h3>
        <ul>
            <li><b>Model files:</b> ~2GB</li>
            <li><b>Application:</b> ~500MB</li>
            <li><b>Database:</b> Grows with analyses (~100MB per 1000 analyses)</li>
            <li><b>Temporary files:</b> ~100MB</li>
            <li><b>Total:</b> Plan for 10GB+ free space for safe operation</li>
        </ul>
        
        <h3>Performance Tips</h3>
        <ul>
            <li><b>GPU:</b> Use GPU for 5-10x faster processing (if available)</li>
            <li><b>Memory:</b> Close other applications to free RAM</li>
            <li><b>SSD:</b> Install on SSD for faster model loading</li>
            <li><b>Cooling:</b> Ensure adequate ventilation for GPU during batch processing</li>
            <li><b>Batch:</b> Process multiple analyses sequentially, not simultaneously</li>
        </ul>
        
        <h3>Troubleshooting System Issues</h3>
        <ul>
            <li><b>GPU Not Detected:</b> Check CUDA installation and PyTorch GPU support</li>
            <li><b>Out of Memory:</b> Close other applications or process smaller batches</li>
            <li><b>Slow Processing:</b> Enable GPU acceleration or reduce image resolution</li>
            <li><b>Models Not Loading:</b> Verify model files exist and have correct permissions</li>
            <li><b>Database Errors:</b> Check disk space and file system permissions</li>
        </ul>
        
        <h3>Checking System Status</h3>
        <p>In the Dashboard, the <b>System Info Panel</b> displays:</p>
        <ul>
            <li>Application uptime</li>
            <li>Daily analysis count</li>
            <li>Average processing time</li>
            <li>Model accuracy statistics</li>
            <li>GPU status (in status bar)</li>
            <li>Number of loaded models</li>
        </ul>
        """
        return self._create_scrollable_content(content)
    
    def _create_troubleshooting(self) -> QWidget:
        """Create the troubleshooting tab."""
        content = """
        <h2>Troubleshooting</h2>
        
        <h3>Common Issues</h3>
        
        <h4>1. Models Not Loading at Startup</h4>
        <p><b>Problem:</b> System Status shows models as "offline" or displays error messages</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Verify all model files exist in correct locations</li>
            <li>Check file permissions (models should be readable)</li>
            <li>Ensure sufficient disk space (at least 10GB free)</li>
            <li>Try deleting and re-downloading model files</li>
            <li>Check console output for specific error messages</li>
        </ul>
        
        <h4>2. GPU Not Detected</h4>
        <p><b>Problem:</b> Status bar shows "GPU: N/A" instead of "GPU: Active"</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Install/update NVIDIA GPU drivers to latest version</li>
            <li>Install CUDA Toolkit 12.8 (matching TensorFlow/PyTorch versions)</li>
            <li>Reinstall PyTorch with CUDA support: pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128</li>
            <li>Verify CUDA availability in Python: <code>import torch; print(torch.cuda.is_available())</code></li>
            <li>Check GPU memory usage with nvidia-smi command</li>
        </ul>
        
        <h4>3. "Manual Entry" Dialog Won't Open</h4>
        <p><b>Problem:</b> Clicking Manual Entry button has no effect</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Ensure no processing is currently active</li>
            <li>Try clicking the button again (sometimes needs 2 clicks)</li>
            <li>Restart the application</li>
            <li>Check console for error messages</li>
        </ul>
        
        <h4>4. Processing Hangs or Freezes</h4>
        <p><b>Problem:</b> Application becomes unresponsive during analysis</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Wait longer (first run can take 30+ seconds for model loading)</li>
            <li>Close other memory-heavy applications</li>
            <li>Reduce image resolution or use smaller files</li>
            <li>Check available RAM (needs at least 4GB free)</li>
            <li>If truly frozen, force close and restart</li>
        </ul>
        
        <h4>5. Reports Tab Shows "No Analysis Yet"</h4>
        <p><b>Problem:</b> After clicking Confirm, Reports tab doesn't update with results</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Wait for processing to complete (check status bar)</li>
            <li>Verify at least one input file was selected</li>
            <li>Check console for model processing errors</li>
            <li>Try with a different input file</li>
            <li>Ensure input files are valid and uncorrupted</li>
        </ul>
        
        <h4>6. Inaccurate Predictions</h4>
        <p><b>Problem:</b> Results don't match expected output</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Verify input quality (good lighting, clear images, quality audio)</li>
            <li>Follow input guidelines (resolution, format, positioning)</li>
            <li>Use consistent data format and preprocessing</li>
            <li>Try multiple samples to verify consistency</li>
            <li>Report systematic errors to development team with examples</li>
        </ul>
        
        <h4>7. PDF Export Fails</h4>
        <p><b>Problem:</b> "Export PDF" button doesn't work or file doesn't save</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Ensure reportlab library is installed: <code>pip install reportlab</code></li>
            <li>Check disk space for output file</li>
            <li>Verify write permissions in destination folder</li>
            <li>Try saving to a different location (e.g., Documents folder)</li>
            <li>Close any open PDF files that might have the same name</li>
        </ul>
        
        <h4>8. "Processing" Status Won't Clear</h4>
        <p><b>Problem:</b> Status bar shows "Processing" but nothing is happening</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Wait a full minute (models can take time)</li>
            <li>Check if only one model failed to respond</li>
            <li>Try restarting the application</li>
            <li>Check console for worker thread errors</li>
        </ul>
        
        <h4>9. Audio File Won't Process</h4>
        <p><b>Problem:</b> Selected WAV file causes error or crash</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Verify file is valid WAV format (not corrupted)</li>
            <li>Ensure sample rate is 44.1kHz or higher</li>
            <li>Try re-exporting the file from audio software</li>
            <li>Use ffmpeg to convert: <code>ffmpeg -i input.wav -acodec pcm_s16le -ar 44100 output.wav</code></li>
            <li>Check file size (should be under 100MB)</li>
        </ul>
        
        <h4>10. Image Processing Errors</h4>
        <p><b>Problem:</b> Image file causes crash or error message</p>
        <p><b>Solutions:</b></p>
        <ul>
            <li>Verify image format (JPG, PNG, or BMP only)</li>
            <li>Check image resolution (should be 1920x1080 or higher)</li>
            <li>Try re-saving image with image editor</li>
            <li>Ensure image is not corrupted: open in viewer first</li>
            <li>Convert format if needed: <code>ffmpeg -i input.png -q:v 5 output.jpg</code></li>
        </ul>
        
        <h3>Advanced Troubleshooting</h3>
        
        <h4>Checking Logs</h4>
        <ul>
            <li>Console output shows real-time processing logs</li>
            <li>Look for "[Error]" or "[Exception]" messages</li>
            <li>Save console output for debugging</li>
            <li>Report with full error stack trace to development team</li>
        </ul>
        
        <h4>Database Issues</h4>
        <ul>
            <li><b>Problem:</b> "Database error" when loading analyses</li>
            <li><b>Solution:</b> Database corrupted - back up data/database.db and delete it</li>
            <li>Application will recreate fresh database on next run</li>
            <li>Previous analyses will be lost (unless backup exists)</li>
        </ul>
        
        <h4>Memory Issues</h4>
        <ul>
            <li>Monitor RAM usage in System Info panel</li>
            <li>If approaching maximum, close other applications</li>
            <li>Reduce batch size or process one analysis at a time</li>
            <li>Consider upgrading system RAM</li>
        </ul>
        
        <h3>Getting Help</h3>
        <p>If problems persist:</p>
        <ul>
            <li>Check the full documentation in each help tab</li>
            <li>Review system requirements and verify compliance</li>
            <li>Try reproducing the issue with sample data</li>
            <li>Collect console output and error messages</li>
            <li>Contact AIDurian development team with:
                <ul>
                    <li>Detailed description of the problem</li>
                    <li>Steps to reproduce</li>
                    <li>Console output/error messages</li>
                    <li>System information (OS, Python version, GPU info)</li>
                    <li>Input files if possible</li>
                </ul>
            </li>
        </ul>
        
        <h3>Performance Optimization</h3>
        <ul>
            <li><b>First Run:</b> Models are cached after first load, subsequent runs are faster</li>
            <li><b>GPU Warmup:</b> First GPU inference can be slow, later ones are faster</li>
            <li><b>Batch Processing:</b> Process multiple files sequentially for best performance</li>
            <li><b>Resource Monitoring:</b> Watch System Info for bottlenecks</li>
        </ul>
        """
        return self._create_scrollable_content(content)