spacr 1.0.7__py3-none-any.whl → 1.1.0__py3-none-any.whl

spacr/gui_utils.py

@@ -9,7 +9,7 @@ import psutil
 from PIL import Image, ImageTk
 from screeninfo import get_monitors
 
-from .gui_elements import AnnotateApp, spacrEntry, spacrCheck, spacrCombo
+from .gui_elements import spacrEntry, spacrCheck, spacrCombo
 
 try:
     ctypes.windll.shcore.SetProcessDpiAwareness(True)
@@ -18,7 +18,20 @@ except AttributeError:
 
 def initialize_cuda():
     """
-    Initializes CUDA in the main process by performing a simple GPU operation.
+    Initializes CUDA for the main process if a compatible GPU is available.
+
+    This function checks if CUDA is available on the system. If it is, it allocates
+    a small tensor on the GPU to ensure that CUDA is properly initialized. A message
+    is printed to indicate whether CUDA was successfully initialized or if it is not
+    available.
+
+    Note:
+        This function is intended to be used in environments where CUDA-enabled GPUs
+        are present and PyTorch is installed.
+
+    Prints:
+        - "CUDA initialized in the main process." if CUDA is available and initialized.
+        - "CUDA is not available." if no compatible GPU is detected.
     """
     if torch.cuda.is_available():
         # Allocate a small tensor on the GPU
@@ -28,6 +41,27 @@ def initialize_cuda():
         print("CUDA is not available.")
 
 def set_high_priority(process):
+    """
+    Sets the priority of a given process to high.
+
+    On Windows systems, the process priority is set to HIGH_PRIORITY_CLASS.
+    On Unix-like systems, the process priority is adjusted to a higher level
+    by setting its niceness value to -10.
+
+    Args:
+        process (psutil.Process): The process whose priority is to be adjusted.
+
+    Raises:
+        psutil.AccessDenied: If the current user does not have permission to change
+                             the priority of the process.
+        psutil.NoSuchProcess: If the specified process does not exist.
+        Exception: For any other errors encountered during the operation.
+
+    Notes:
+        - This function requires the `psutil` library to interact with system processes.
+        - Adjusting process priority may require elevated privileges depending on the
+          operating system and user permissions.
+    """
     try:
         p = psutil.Process(process.pid)
         if os.name == 'nt':  # Windows
@@ -43,10 +77,49 @@ def set_high_priority(process):
         print(f"Failed to set high priority for process {process.pid}: {e}")
 
 def set_cpu_affinity(process):
+    """
+    Set the CPU affinity for a given process to use all available CPUs.
+
+    This function modifies the CPU affinity of the specified process, allowing
+    it to run on all CPUs available on the system.
+
+    Args:
+        process (psutil.Process): A psutil.Process object representing the process
+                                  whose CPU affinity is to be set.
+
+    Raises:
+        psutil.NoSuchProcess: If the process does not exist.
+        psutil.AccessDenied: If the process cannot be accessed due to insufficient permissions.
+        psutil.ZombieProcess: If the process is a zombie process.
+    """
     p = psutil.Process(process.pid)
     p.cpu_affinity(list(range(os.cpu_count())))
     
 def proceed_with_app(root, app_name, app_func):
+    """
+    Prepares the application window to load a new app by clearing the current 
+    content frame and initializing the specified app.
+
+    Args:
+        root (tk.Tk or tk.Toplevel): The root window or parent container that 
+            contains the content frame.
+        app_name (str): The name of the application to be loaded (not used in 
+            the current implementation but could be useful for logging or 
+            debugging purposes).
+        app_func (callable): A function that initializes the new application 
+            within the content frame. It should accept the content frame as 
+            its only argument.
+
+    Behavior:
+        - Destroys all widgets in the `content_frame` attribute of `root` 
+          (if it exists).
+        - Calls `app_func` with `root.content_frame` to initialize the new 
+          application.
+
+    Note:
+        Ensure that `root` has an attribute `content_frame` that is a valid 
+        tkinter container (e.g., a `tk.Frame`) before calling this function.
+    """
     # Clear the current content frame
     if hasattr(root, 'content_frame'):
         for widget in root.content_frame.winfo_children():
@@ -59,6 +132,31 @@ def proceed_with_app(root, app_name, app_func):
     app_func(root.content_frame)
 
 def load_app(root, app_name, app_func):
+    """
+    Load a new application into the GUI framework.
+
+    This function handles the transition between applications in the GUI by 
+    clearing the current canvas, canceling scheduled tasks, and invoking 
+    exit functionality for specific applications if necessary.
+
+    Args:
+        root: The root object of the GUI, which contains the canvas, 
+              after_tasks, and other application state.
+        app_name (str): The name of the application to load.
+        app_func (callable): The function to initialize the new application.
+
+    Behavior:
+        - Clears the current canvas if it exists.
+        - Cancels all scheduled `after` tasks associated with the root object.
+        - If the current application has an exit function and the new app is 
+          not "Annotate" or "make_masks", the exit function is invoked before 
+          proceeding to the new application.
+        - Proceeds to load the new application using the provided `app_func`.
+
+    Note:
+        The `proceed_with_app` function is used internally to finalize the 
+        transition to the new application.
+    """
     # Clear the canvas if it exists
     if root.canvas is not None:
         root.clear_frame(root.canvas)
@@ -184,139 +282,83 @@ def create_input_field(frame, label_text, row, var_type='entry', options=None, d
 
 def process_stdout_stderr(q):
     """
-    Redirect stdout and stderr to the queue q.
+    Redirects the standard output (stdout) and standard error (stderr) streams
+    to a queue for processing.
+
+    This function replaces the default `sys.stdout` and `sys.stderr` with
+    instances of `WriteToQueue`, which write all output to the provided queue.
+
+    :param q: A queue object where the redirected output will be stored.
+    :type q: queue.Queue
     """
     sys.stdout = WriteToQueue(q)
     sys.stderr = WriteToQueue(q)
 
 class WriteToQueue(io.TextIOBase):
     """
-    A custom file-like class that writes any output to a given queue.
-    This can be used to redirect stdout and stderr.
+    A file-like object that redirects writes to a queue.
+
+    :param q: The queue to write output to.
+    :type q: queue.Queue
     """
     def __init__(self, q):
         self.q = q
     def write(self, msg):
+        """
+        Write string to stream.
+
+        :param msg: The string message to write.
+        :type msg: str
+        :returns: Number of characters written.
+        :rtype: int
+        """
         if msg.strip():  # Avoid empty messages
             self.q.put(msg)
     def flush(self):
+        """
+        Flush write buffers, if applicable.
+
+        This is a no-op in this implementation.
+        """
         pass
 
 def cancel_after_tasks(frame):
+    """
+    Cancels all scheduled 'after' tasks associated with a given frame.
+
+    This function checks if the provided frame object has an attribute 
+    named 'after_tasks', which is expected to be a list of task IDs 
+    scheduled using the `after` method (e.g., in a Tkinter application). 
+    If such tasks exist, it cancels each of them using the `after_cancel` 
+    method and then clears the list.
+
+    Args:
+        frame: An object (typically a Tkinter widget) that may have an 
+               'after_tasks' attribute containing scheduled task IDs.
+
+    Raises:
+        AttributeError: If the frame does not have the required methods 
+                        (`after_cancel` or `after_tasks` attribute).
+    """
     if hasattr(frame, 'after_tasks'):
         for task in frame.after_tasks:
             frame.after_cancel(task)
         frame.after_tasks.clear()
 
-def annotate(settings):
-    from .settings import set_annotate_default_settings
-    settings = set_annotate_default_settings(settings)
-    src  = settings['src']
-
-    db = os.path.join(src, 'measurements/measurements.db')
-    conn = sqlite3.connect(db)
-    c = conn.cursor()
-    c.execute('PRAGMA table_info(png_list)')
-    cols = c.fetchall()
-    if settings['annotation_column'] not in [col[1] for col in cols]:
-        c.execute(f"ALTER TABLE png_list ADD COLUMN {settings['annotation_column']} integer")
-    conn.commit()
-    conn.close()
-
-    root = tk.Tk()
-    
-    root.geometry(f"{root.winfo_screenwidth()}x{root.winfo_screenheight()}")
-    
-    db_path = os.path.join(settings['src'], 'measurements/measurements.db')
-
-    app = AnnotateApp(root,
-                      db_path=db_path,
-                      src=settings['src'],
-                      image_type=settings['image_type'],
-                      channels=settings['channels'],
-                      image_size=settings['img_size'],
-                      annotation_column=settings['annotation_column'],
-                      normalize=settings['normalize'],
-                      percentiles=settings['percentiles'],
-                      measurement=settings['measurement'],
-                      threshold=settings['threshold'],
-                      normalize_channels=settings['normalize_channels'])
-    
-    app.load_images()
-    root.mainloop()
-
-def generate_annotate_fields(frame):
-    from .settings import set_annotate_default_settings
-    from .gui_elements import set_dark_style
-
-    style_out = set_dark_style(ttk.Style())
-    font_loader = style_out['font_loader']
-    font_size = style_out['font_size'] - 2
-
-    vars_dict = {}
-    settings = set_annotate_default_settings(settings={})
-    
-    for setting in settings:
-        vars_dict[setting] = {
-            'entry': ttk.Entry(frame),
-            'value': settings[setting]
-        }
-
-    # Arrange input fields and labels
-    for row, (name, data) in enumerate(vars_dict.items()):
-        tk.Label(
-            frame,
-            text=f"{name.replace('_', ' ').capitalize()}:",
-            bg=style_out['bg_color'],
-            fg=style_out['fg_color'],
-            font=font_loader.get_font(size=font_size)
-        ).grid(row=row, column=0)
-
-        value = data['value']
-        if isinstance(value, list):
-            string_value = ','.join(map(str, value))
-        elif isinstance(value, (int, float, bool)):
-            string_value = str(value)
-        elif value is None:
-            string_value = ''
-        else:
-            string_value = value
-
-        data['entry'].insert(0, string_value)
-        data['entry'].grid(row=row, column=1)
-
-    return vars_dict
+def load_next_app(root):
+    """
+    Loads the next application by invoking the function stored in the `next_app_func` 
+    attribute of the provided `root` object. If the current root window has been 
+    destroyed, a new root window is initialized before invoking the next application.
 
-def run_annotate_app(vars_dict, parent_frame):
-    settings = {key: data['entry'].get() for key, data in vars_dict.items()}
-    settings['channels'] = settings['channels'].split(',')
-    settings['img_size'] = list(map(int, settings['img_size'].split(',')))  # Convert string to list of integers
-    settings['percentiles'] = list(map(int, settings['percentiles'].split(',')))  # Convert string to list of integers
-    settings['normalize'] = settings['normalize'].lower() == 'true'
-    settings['normalize_channels'] = settings['channels'].split(',')
-    settings['rows'] = int(settings['rows'])
-    settings['columns'] = int(settings['columns'])
-    settings['measurement'] = settings['measurement'].split(',')
-    settings['threshold'] = None if settings['threshold'].lower() == 'none' else int(settings['threshold'])
-
-    # Clear previous content instead of destroying the root
-    if hasattr(parent_frame, 'winfo_children'):
-        for widget in parent_frame.winfo_children():
-            widget.destroy()
-
-    # Start the annotate application in the same root window
-    annotate_app(parent_frame, settings)
-
-# Global list to keep references to PhotoImage objects
-global_image_refs = []
-
-def annotate_app(parent_frame, settings):
-    global global_image_refs
-    global_image_refs.clear()
-    root = parent_frame.winfo_toplevel()
-    annotate_with_image_refs(settings, root, lambda: load_next_app(root))
+    Args:
+        root (tk.Tk): The current root window object, which contains the attributes 
+                      `next_app_func` (a callable for the next application) and 
+                      `next_app_args` (a tuple of arguments to pass to the callable).
 
-def load_next_app(root):
+    Raises:
+        tk.TclError: If the root window does not exist and needs to be reinitialized.
+    """
     # Get the next app function and arguments
     next_app_func = root.next_app_func
     next_app_args = root.next_app_args
@@ -335,38 +377,30 @@ def load_next_app(root):
             new_root.title("SpaCr Application")
             next_app_func(new_root, *next_app_args)
 
-def annotate_with_image_refs(settings, root, shutdown_callback):
-    from .settings import set_annotate_default_settings
-
-    settings = set_annotate_default_settings(settings)
-    src = settings['src']
-
-    db = os.path.join(src, 'measurements/measurements.db')
-    conn = sqlite3.connect(db)
-    c = conn.cursor()
-    c.execute('PRAGMA table_info(png_list)')
-    cols = c.fetchall()
-    if settings['annotation_column'] not in [col[1] for col in cols]:
-        c.execute(f"ALTER TABLE png_list ADD COLUMN {settings['annotation_column']} integer")
-    conn.commit()
-    conn.close()
-
-    screen_width = root.winfo_screenwidth()
-    screen_height = root.winfo_screenheight()
-    root.geometry(f"{screen_width}x{screen_height}")
+def convert_settings_dict_for_gui(settings):
+    """
+    Convert a dictionary of settings into a format suitable for GUI rendering.
 
-    app = AnnotateApp(root, db, src, image_type=settings['image_type'], channels=settings['channels'], image_size=settings['img_size'], annotation_column=settings['annotation_column'], normalize=settings['normalize'], percentiles=settings['percentiles'], measurement=settings['measurement'], threshold=settings['threshold'], normalize_channels=settings['normalize_channels'], outline=settings['outline'], outline_threshold_factor=settings['outline_threshold_factor'], outline_sigma=settings['outline_sigma'])
+    Each key in the input dictionary is mapped to a tuple of the form:
+    (input_type, options, default_value), where:
+    
+    - input_type (str): The type of GUI element. One of:
+        * 'combo' for dropdown menus
+        * 'check' for checkboxes
+        * 'entry' for entry fields
+    - options (list or None): A list of selectable options for 'combo' types, or None for other types.
+    - default_value: The current or default value to be displayed in the GUI.
 
-    # Set the canvas background to black
-    root.configure(bg='black')
+    Special keys are mapped to pre-defined configurations with known option sets
+    (e.g., 'metadata_type', 'channels', 'model_type').
 
-    # Store the shutdown function and next app details in the root
-    root.current_app_exit_func = lambda: [app.shutdown(), shutdown_callback()]
+    :param settings: Dictionary where keys are setting names and values are their current values.
+    :type settings: dict
 
-    # Call load_images after setting up the root window
-    app.load_images()
+    :return: Dictionary mapping setting names to tuples for GUI rendering.
+    :rtype: dict
+    """
 
-def convert_settings_dict_for_gui(settings):
     from torchvision import models as torch_models
     torchvision_models = [name for name, obj in torch_models.__dict__.items() if callable(obj)]
     chans = ['0', '1', '2', '3', '4', '5', '6', '7', '8', None]
@@ -419,10 +453,21 @@ def convert_settings_dict_for_gui(settings):
     
     return variables
 
-
 def spacrFigShow(fig_queue=None):
     """
-    Replacement for plt.show() that queues figures instead of displaying them.
+    Displays the current matplotlib figure or adds it to a queue.
+
+    This function retrieves the current matplotlib figure using `plt.gcf()`. 
+    If a `fig_queue` is provided, the figure is added to the queue. 
+    Otherwise, the figure is displayed using the `show()` method. 
+    After the figure is either queued or displayed, it is closed using `plt.close()`.
+
+    Args:
+        fig_queue (queue.Queue, optional): A queue to store the figure. 
+                                           If None, the figure is displayed instead.
+
+    Returns:
+        None
     """
     fig = plt.gcf()
     if fig_queue:
@@ -436,7 +481,7 @@ def function_gui_wrapper(function=None, settings={}, q=None, fig_queue=None, imp
     """
     Wraps the run_multiple_simulations function to integrate with GUI processes.
     
-    Parameters:
+    Args:
     - settings: dict, The settings for the run_multiple_simulations function.
     - q: multiprocessing.Queue, Queue for logging messages to the GUI.
     - fig_queue: multiprocessing.Queue, Queue for sending figures to the GUI.
@@ -461,8 +506,45 @@ def function_gui_wrapper(function=None, settings={}, q=None, fig_queue=None, imp
         plt.show = original_show
         
 def run_function_gui(settings_type, settings, q, fig_queue, stop_requested):
-    
-    from .core import generate_image_umap, preprocess_generate_masks
+    """
+    Executes a specified processing function in the GUI context based on `settings_type`.
+
+    This function selects and runs one of the core `spaCR` processing functions 
+    (e.g., segmentation, measurement, classification, barcode mapping) based on the 
+    provided `settings_type` string. It wraps the execution with a logging mechanism 
+    to redirect stdout/stderr to the GUI console and handles exceptions cleanly.
+
+    Args
+    ----------
+    settings_type : str
+        A string indicating which processing function to execute. Supported values include:
+        'mask', 'measure', 'classify', 'train_cellpose', 'ml_analyze', 'cellpose_masks',
+        'cellpose_all', 'map_barcodes', 'regression', 'recruitment', 'analyze_plaques', 'convert'.
+
+    settings : dict
+        A dictionary of parameters required by the selected function.
+
+    q : multiprocessing.Queue
+        Queue for redirecting standard output and errors to the GUI console.
+
+    fig_queue : multiprocessing.Queue
+        Queue used to transfer figures (e.g., plots) from the worker process to the GUI.
+
+    stop_requested : multiprocessing.Value
+        A shared value to signal whether execution has completed or was interrupted.
+
+    Raises
+    ------
+    ValueError
+        If an invalid `settings_type` is provided.
+
+    Notes
+    -----
+    - Redirects stdout/stderr to the GUI using `process_stdout_stderr`.
+    - Catches and reports any exceptions to the GUI queue.
+    - Sets `stop_requested.value = 1` when the task finishes (whether successful or not).
+    """
+    from .core import preprocess_generate_masks
     from .spacr_cellpose import identify_masks_finetune, check_cellpose_models
     from .submodules import analyze_recruitment
     from .ml import generate_ml_scores, perform_regression
@@ -506,9 +588,6 @@ def run_function_gui(settings_type, settings, q, fig_queue, stop_requested):
     elif settings_type == 'recruitment':
         function = analyze_recruitment
         imports = 1
-    elif settings_type == 'umap':
-        function = generate_image_umap
-        imports = 1
     elif settings_type == 'analyze_plaques':
         function = analyze_plaques
         imports = 1
@@ -529,7 +608,7 @@ def hide_all_settings(vars_dict, categories):
     """
     Function to initially hide all settings in the GUI.
 
-    Parameters:
+    Args:
     - categories: dict, The categories of settings with their corresponding settings.
     - vars_dict: dict, The dictionary containing the settings and their corresponding widgets.
     """
@@ -551,6 +630,32 @@ def hide_all_settings(vars_dict, categories):
     return vars_dict
 
 def setup_frame(parent_frame):
+    """
+    Set up the main GUI layout within the given parent frame.
+
+    This function initializes a dark-themed, resizable GUI layout using `PanedWindow` 
+    containers. It organizes the layout into left-hand settings, central vertical content, 
+    and bottom horizontal panels. It also sets initial sash positions and layout weights.
+
+    Args
+    ----------
+    parent_frame : tk.Frame
+        The parent Tkinter frame to populate with the GUI layout.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - parent_frame (tk.Frame): The modified parent frame with the layout initialized.
+        - vertical_container (tk.PanedWindow): Top container in the right-hand area for main content.
+        - horizontal_container (tk.PanedWindow): Bottom container for additional widgets.
+        - settings_container (tk.PanedWindow): Left-hand container for GUI settings.
+    
+    Notes
+    -----
+    - Uses `set_dark_style` and `set_element_size` from `gui_elements` to theme and size widgets.
+    - Dynamically positions the sash between the left and right panes to 25% of the screen width.
+    """
     from .gui_elements import set_dark_style, set_element_size
 
     style = ttk.Style(parent_frame)
@@ -599,8 +704,29 @@ def setup_frame(parent_frame):
 
     return parent_frame, vertical_container, horizontal_container, settings_container
 
-
 def download_hug_dataset(q, vars_dict):
+    """
+    Downloads a dataset and settings files from the Hugging Face Hub and updates the provided variables dictionary.
+
+    Args:
+        q (queue.Queue): A queue object used for logging messages during the download process.
+        vars_dict (dict): A dictionary containing variables to be updated. If 'src' is present in the dictionary,
+                          the third element of 'src' will be updated with the downloaded dataset path.
+
+    The function performs the following steps:
+        1. Downloads a dataset from the Hugging Face Hub using the specified repository ID and subfolder.
+        2. Updates the 'src' variable in `vars_dict` with the local path of the downloaded dataset, if applicable.
+        3. Logs the dataset download status to the provided queue.
+        4. Downloads settings files from another repository on the Hugging Face Hub.
+        5. Logs the settings download status to the provided queue.
+
+    Notes:
+        - The dataset is downloaded to a local directory under the user's home directory named "datasets".
+        - Any exceptions during the download process are caught and logged to the queue.
+
+    Raises:
+        None: All exceptions are handled internally and logged to the queue.
+    """
     dataset_repo_id = "einarolafsson/toxo_mito"
     settings_repo_id = "einarolafsson/spacr_settings"
     dataset_subfolder = "plate1"
@@ -771,6 +897,31 @@ def display_gif_in_plot_frame(gif_path, parent_frame):
     update_frame(0)
     
 def display_media_in_plot_frame(media_path, parent_frame):
+    """
+    Display a media file (MP4, AVI, or GIF) in a Tkinter frame, playing it on repeat 
+    while fully filling the frame and maintaining the aspect ratio.
+
+    Args:
+        media_path (str): The file path to the media file (MP4, AVI, or GIF).
+        parent_frame (tk.Frame): The Tkinter frame where the media will be displayed.
+
+    Behavior:
+        - For MP4 and AVI files:
+            - Uses OpenCV to read and play the video.
+            - Resizes and crops the video to fully fill the parent frame while maintaining aspect ratio.
+            - Plays the video on repeat.
+        - For GIF files:
+            - Uses PIL to read and play the GIF.
+            - Resizes and crops the GIF to fully fill the parent frame while maintaining aspect ratio.
+            - Plays the GIF on repeat.
+
+    Raises:
+        ValueError: If the file format is not supported (only MP4, AVI, and GIF are supported).
+
+    Notes:
+        - The function clears any existing widgets in the parent frame before displaying the media.
+        - The parent frame is configured to expand and adapt to the media's aspect ratio.
+    """
     """Display an MP4, AVI, or GIF and play it on repeat in the parent_frame, fully filling the frame while maintaining aspect ratio."""
     # Clear parent_frame if it contains any previous widgets
     for widget in parent_frame.winfo_children():
@@ -915,8 +1066,7 @@ def display_media_in_plot_frame(media_path, parent_frame):
     else:
         raise ValueError("Unsupported file format. Only .mp4, .avi, and .gif are supported.")
 
-def print_widget_structure(widget, indent=0):
-    """Recursively print the widget structure."""
+def print_widget_structure(widget, indent=0):    
     # Print the widget's name and class
     print(" " * indent + f"{widget}: {widget.winfo_class()}")