Image Visualization =================== OpenIMC provides comprehensive image visualization capabilities for exploring IMC data, including multiple viewing modes, segmentation overlays, scaling options, and comparison tools. Overview -------- The image visualization system in OpenIMC allows you to: - Load and display IMC images with efficient caching - Select and view multiple channels simultaneously - Switch between different viewing modes (Grid, RGB, Grayscale) - Overlay segmentation masks with multiple display options - Apply custom scaling, denoising, and spillover correction - Zoom and navigate images - Compare multiple acquisitions side-by-side Image Loading and Caching -------------------------- **Image Cache:** OpenIMC uses an in-memory cache to store loaded images, improving performance when switching between channels or acquisitions. - **Cache Key**: Images are cached by acquisition ID and channel name - **Automatic Prefetching**: When an acquisition is selected, all channels are prefetched in the background - **Cache Management**: Cache is automatically cleared when switching files or acquisitions - **Thread-Safe**: Cache operations are thread-safe to support background loading **Loading Process:** 1. Check cache for existing image 2. If not cached, load from MCD/OME-TIFF file 3. Apply denoising (if enabled) 4. Apply normalization (if configured) 5. Store in cache for future use Channel Selection ----------------- **Selecting Channels:** - **Channel List**: Use the checkbox list to select one or more channels - **Search**: Use the search box to filter channels by name - **Select All**: Use "Select All" button to select all visible channels - **Deselect All**: Use "Deselect All" button to clear selection **Auto-Selection:** - When switching acquisitions, previously selected channels are automatically re-selected if they exist in the new acquisition - DNA channels (DNA1, DNA2) are auto-selected on initial file load if available Viewing Modes ------------- OpenIMC supports three viewing modes: **1. Grid Mode** (default for multiple channels) - Displays each selected channel in a separate subplot - Useful for comparing multiple channels side-by-side - Each channel can have independent scaling - Enable with "Grid view for multiple channels" checkbox **2. RGB Composite Mode** - Combines selected channels into a single RGB image - Assign channels to Red, Green, and Blue color components - Supports multiple channels per color (averaged or combined) - Useful for visualizing co-expression patterns - Enable by unchecking "Grid view for multiple channels" **3. Grayscale Mode** - Converts RGB composite to grayscale (mean across channels) - Or displays individual channels in grayscale colormap - Useful for printing or when color is not needed - Enable with "Grayscale mode" checkbox **Switching Modes:** - Toggle "Grid view" checkbox to switch between Grid and RGB modes - Toggle "Grayscale mode" checkbox to enable/disable grayscale - View automatically refreshes when mode changes Segmentation Overlays --------------------- **Enabling Overlays:** - Check "Show segmentation overlay" to display segmentation masks - Overlays are applied to all displayed channels - Requires loaded segmentation masks (from segmentation or loaded from file) **Overlay Modes:** 1. **Mask Mode** (default): - Displays segmentation masks as semi-transparent colored overlays - Each cell is colored based on its mask value - Useful for visualizing cell boundaries and spatial distribution 2. **Outline Mode**: - Displays only the cell outlines (contours) - Red outlines overlaid on the image - Useful for precise cell boundary visualization without obscuring image details 3. **Cluster Mode**: - Colors cells by their cluster assignment (if clustering has been performed) - Shows cluster colors with legend - Can display cluster mask only (without channel overlay) when no channels are selected - Useful for visualizing spatial distribution of cell types **Switching Overlay Modes:** - Use the "Mode" dropdown in the overlay controls - Mode is applied immediately to all displayed images - Cluster mode is only available if clustering has been performed Scale Bar --------- **Adding Scale Bar:** - Check "Show scale bar" to display a scale bar on images - Configure length in micrometers (default: 10 μm) - Scale bar is automatically positioned in the bottom-right corner **Parameters:** - **Length (μm)**: Physical length of the scale bar in micrometers - **Pixel Size**: Automatically detected from image metadata or can be manually set - **Position**: Automatically positioned to avoid overlap with image content **Usage:** - Essential for publication-quality figures - Helps readers understand spatial scale - Works in both Grid and RGB modes Custom Scaling -------------- **What is Custom Scaling?** Custom scaling allows you to adjust the intensity range (min/max values) used for displaying each channel. This controls how pixel intensities are mapped to display colors. **How it Works:** 1. **Default Range**: Uses the full intensity range of the image (min to max) 2. **Manual Scaling**: Set custom min/max values to focus on specific intensity ranges 3. **Per-Channel Scaling**: Each channel can have independent scaling values 4. **RGB Color Scaling**: In RGB mode, each color component (Red, Green, Blue) can be scaled independently **Scaling Methods:** - **Default**: Full image range (min to max) - **Manual**: Set custom min/max values - **Arcsinh**: Apply arcsinh transformation with configurable cofactor (useful for high dynamic range data) **Using Custom Scaling:** 1. Enable "Custom scaling" checkbox 2. Select channel or RGB color from dropdown 3. Adjust min/max spinboxes or use "Default range" button 4. For arcsinh: check "Arcsinh" and set cofactor (default: 10.0) 5. Scaling is applied immediately **Tips:** - Lower min values increase brightness - Higher max values increase contrast - Arcsinh helps visualize data with very high dynamic range - In RGB mode, scaling affects the intensity of each color component Denoising --------- **What is Denoising?** Denoising removes noise and artifacts from images to improve visualization quality. Denoising is applied per-channel and operates on raw pixel intensities before normalization. **Denoising Methods:** 1. **Hot Pixel Removal**: - **Median 3x3**: Replace hot pixels with median of 3x3 neighborhood - **>N SD above local median**: Remove pixels more than N standard deviations above local median 2. **Speckle Smoothing**: - **Gaussian**: Apply Gaussian blur (configurable sigma) - **Non-local means**: Advanced denoising (slower but better quality) 3. **Background Subtraction**: - **White top-hat**: Remove bright background structures - **Black top-hat**: Remove dark background structures - **Rolling ball**: Approximate rolling ball background subtraction **Using Denoising:** 1. Enable "Enable denoising" checkbox 2. Select channel from dropdown 3. Configure each denoising method (hot pixel, speckle, background) 4. Set processing order (Hot → Speckle → Background recommended) 5. Click "Apply to all channels" to use same settings for all channels 6. Denoising is applied automatically when viewing images **Important Notes:** - Denoising is **visualization-only** and does not affect feature extraction - Settings are saved per-channel - Requires scikit-image package - Processing order matters: hot pixels first, then speckle, then background Spillover Correction (Visualization) ------------------------------------- **What is Spillover Correction?** Spillover correction compensates for signal leakage between channels due to spectral overlap. In visualization mode, this is applied on-the-fly to show how images would look after correction. **Important Warning:** .. warning:: **Spillover correction in visualization is for preview only.** To actually correct your data, you must apply spillover correction during feature extraction. Visualization correction does not modify the underlying data. **Using Spillover Correction:** 1. Load a spillover matrix CSV file (via File → Load Spillover Matrix or Analysis → Generate Spillover Matrix) 2. Enable "Spillover correction" checkbox 3. Select correction method: - **NNLS** (Non-Negative Least Squares): Recommended, ensures non-negative results - **PGD** (Projected Gradient Descent): Alternative method 4. Correction is applied automatically when viewing images **How it Works:** 1. Loads all selected channels with denoising only 2. Applies spillover correction using the loaded matrix 3. Applies normalization/scaling to corrected images 4. Displays corrected images **Limitations:** - Only affects visualization, not actual data - Requires loaded spillover matrix - Matrix channels must match image channels - Correction is computationally intensive for many channels Zoom Functionality ------------------ **Zooming:** - **Mouse Wheel**: Scroll to zoom in/out - **Navigation Toolbar**: Use zoom tools in matplotlib toolbar - **Zoom to Rectangle**: Click and drag to zoom to selected region - **Pan**: Click and drag to pan when zoomed in **Zoom Preservation:** - Zoom level is automatically preserved when: - Switching between channels (if same acquisition) - Toggling viewing modes - Changing overlay settings - Applying scaling or denoising **Reset Zoom:** - Click "Reset Zoom" button to return to full image view - Or use navigation toolbar "Home" button **Synchronized Zoom (Grid Mode):** - In grid mode, zooming one channel zooms all channels to the same region - Useful for comparing channels at the same spatial location Comparison Mode --------------- **Opening Comparison Mode:** - Click "Comparison mode" button in the main window - Opens a dialog for side-by-side comparison of multiple acquisitions **Features:** - **Multi-Acquisition Selection**: Select multiple acquisitions to compare - **Channel Selection**: Choose channel to display across all acquisitions - **Synchronized Viewing**: All acquisitions display the same channel - **Individual Scaling**: Each acquisition can have independent scaling - **Overlay Support**: Segmentation overlays can be enabled - **Grayscale Mode**: Optional grayscale display **Use Cases:** - Compare the same ROI across different conditions - Compare different ROIs from the same sample - Quality control across acquisitions - Batch visualization **Controls:** - Select acquisitions from list (multi-select) - Choose channel from dropdown - Adjust scaling per acquisition - Toggle overlay and grayscale options - Export individual or all images Exporting Images ---------------- **Saving Figures:** - Use File → Save Figure or right-click on image - Opens save dialog with options: - **Format**: PNG, PDF, SVG, EPS, TIFF - **DPI**: Resolution (default: 300 for publication quality) - **Transparent Background**: Optional - **Font Size**: Adjust text size in saved figure **Suggested Filenames:** - Automatically generates filename based on: - File/slide name - Acquisition/ROI name - Selected channels - Viewing mode (RGB or Grid) **Export Options:** - **Single Image**: Current view - **All Channels**: Export all channels in grid (via "Show all channels" button) - **Comparison Mode**: Export individual or all comparison images Tips and Best Practices ----------------------- 1. **Performance**: - Use grid mode for comparing many channels - Use RGB mode for visualizing co-expression - Cache improves performance when switching channels 2. **Visualization Quality**: - Adjust scaling to highlight features of interest - Use denoising for noisy images - Apply arcsinh for high dynamic range data 3. **Segmentation Overlays**: - Use Outline mode for precise boundary visualization - Use Cluster mode to visualize cell type distribution - Use Mask mode for general cell visualization 4. **Scale Bar**: - Always include scale bar in publication figures - Verify pixel size is correct for your data 5. **Spillover Correction**: - Remember: visualization correction is preview only - Apply correction during feature extraction for actual data correction 6. **Comparison Mode**: - Use for quality control across acquisitions - Adjust scaling individually for each acquisition - Export side-by-side comparisons for presentations 7. **Export**: - Use high DPI (300+) for publication figures - PNG for general use, PDF/SVG for vector graphics - Adjust font sizes for readability in saved figures