Feat: Splashscreen & Implement lazy loading for heavy dependencies (#39)

* Refactor: Implement lazy loading for heavy dependencies in ImagePipeline and MainWindow

* New splashscreen, refactor some classes to be imported in the future

* Add app icon PNG to build artifacts for Windows and macOS

* Refactor splash screen handling and improve loading message display

* Remove unused splash message handling and related code

* Refactor splash screen handling to initialize QApplication and display splash earlier in the main function

* Update src/main.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* ruff format

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: duartebarbosadev

.github/workflows/release-build.yml

@@ -142,6 +142,7 @@ jobs:
             --hidden-import core.build_info `
             --add-data "src/ui/dark_theme.qss;." `
             --add-data "assets/app_icon.ico;." `
+            --add-data "assets/app_icon.png;." `
             --hidden-import pyexiv2 `
             --hidden-import PyQt6.QtCore `
             --hidden-import PyQt6.QtGui `
@@ -181,6 +182,7 @@ jobs:
             --hidden-import core.build_info \
             --add-data src/ui/dark_theme.qss:. \
             --add-data assets/app_icon.ico:. \
+            --add-data assets/app_icon.png:. \
             --hidden-import PyQt6.QtCore \
             --hidden-import PyQt6.QtGui \
             --hidden-import PyQt6.QtWidgets \

src/core/similarity_engine.py

@@ -6,9 +6,6 @@
 from PyQt6.QtCore import QObject, pyqtSignal
 import numpy as np  # Import numpy for array manipulation
 from sklearn.cluster import DBSCAN
-from sklearn.metrics.pairwise import (
-    cosine_similarity,
-)  # Import for similarity calculation
 
 from core.image_pipeline import ImagePipeline
 from .app_settings import (
@@ -385,8 +382,17 @@ def cluster_embeddings(self, embeddings: Dict[str, List[float]]):
                     [embeddings[path] for path in paths_in_group], dtype=np.float32
                 )
 
-                # Calculate pairwise cosine similarities
-                pairwise_similarities = cosine_similarity(group_embeds)
+                # Lazy import for cosine_similarity to defer sklearn.metrics loading
+                try:
+                    from sklearn.metrics.pairwise import cosine_similarity
+                except ImportError as e:
+                    logger.error(f"Failed to import cosine_similarity: {e}")
+                    pairwise_similarities = np.array(
+                        [[1.0]]
+                    )  # Fallback for single item or error
+                else:
+                    # Calculate pairwise cosine similarities
+                    pairwise_similarities = cosine_similarity(group_embeds)
 
                 # We want the average of the upper triangle (excluding diagonal which is 1.0)
                 upper_triangle_indices = np.triu_indices(

src/main.py

@@ -1,9 +1,9 @@
 import sys
 import os
+import time
 
 # Ensure the 'src' directory is on sys.path when executing as a script
 SRC_DIR = os.path.dirname(__file__)
-
 if SRC_DIR and SRC_DIR not in sys.path:
     sys.path.insert(0, SRC_DIR)
 
@@ -16,19 +16,13 @@
     # If we can't initialize pyexiv2, log the error but don't prevent app startup
     print(f"Warning: Failed to initialize pyexiv2: {e}")
 
-import logging  # noqa: E402  # Must be after pyexiv2 initialization
-import time  # noqa: E402
+import logging  # noqa: E402
 import argparse  # noqa: E402
 import traceback  # noqa: E402  # For global exception handler
-from PyQt6.QtWidgets import (  # noqa: E402
-    QApplication,
-    QMessageBox,
-)  # QMessageBox for global exception handler
-from PyQt6.QtGui import QIcon  # noqa: E402
 
-from ui.main_window import MainWindow  # noqa: E402
-from ui.app_controller import AppController  # noqa: E402
-from pillow_heif import register_heif_opener  # noqa: E402
+from PyQt6.QtCore import Qt, QTimer  # noqa: E402
+from PyQt6.QtWidgets import QApplication, QMessageBox, QSplashScreen  # noqa: E402
+from PyQt6.QtGui import QIcon, QPixmap  # noqa: E402
 
 
 def load_stylesheet(filename: str = "src/ui/dark_theme.qss") -> str:
@@ -53,13 +47,9 @@ def load_stylesheet(filename: str = "src/ui/dark_theme.qss") -> str:
         candidates = [
             os.path.join(
                 base_dir, "dark_theme.qss"
-            ),  # we bundle at top-level in frozen builds
-            os.path.join(
-                base_dir, filename
-            ),  # e.g., src/ui/dark_theme.qss inside frozen or source
-            os.path.abspath(
-                filename
-            ),  # direct path from CWD when running from repo root
+            ),  # bundled at top-level in frozen builds
+            os.path.join(base_dir, filename),  # e.g., src/ui/dark_theme.qss
+            os.path.abspath(filename),  # direct path from CWD
         ]
 
         for path in candidates:
@@ -119,9 +109,7 @@ def global_exception_handler(exc_type, exc_value, exc_traceback):
             error_box.setIcon(QMessageBox.Icon.Critical)
             error_box.setWindowTitle("Application Error")
             error_box.setText(main_error_text)
-            error_box.setDetailedText(
-                error_message_details
-            )  # Full traceback for expert users/reporting
+            error_box.setDetailedText(error_message_details)  # Full traceback
             error_box.setStandardButtons(QMessageBox.StandardButton.Ok)
             error_box.exec()
         except Exception as e_msgbox:
@@ -196,6 +184,31 @@ def apply_app_identity(app: QApplication, main_window=None) -> None:
 def main():
     """Main application entry point."""
 
+    # Create QApplication early for splash screen
+    app = QApplication(sys.argv)
+
+    # --- Splash: show immediately (no text), then set message after it’s visible ---
+    splash_total_start = time.perf_counter()
+
+    splash_path = os.path.join(
+        os.path.dirname(os.path.dirname(__file__)), "assets", "app_icon.png"
+    )
+    splash_pix = QPixmap(splash_path).scaled(
+        400,
+        300,
+        Qt.AspectRatioMode.KeepAspectRatio,
+        Qt.TransformationMode.FastTransformation,
+    )
+    splash = QSplashScreen(splash_pix)
+
+    # Show the splash immediately (no text yet)
+    splash.show()
+    app.processEvents()  # should be fast; no text/layout yet
+
+    from pillow_heif import register_heif_opener  # noqa: E402
+
+    register_heif_opener()
+
     # --- Enable Faulthandler for crash analysis ---
     import faulthandler
 
@@ -220,8 +233,6 @@ def main():
     except Exception:
         pass
 
-    register_heif_opener()
-
     # Parse command-line arguments
     parser = argparse.ArgumentParser(description="PhotoSort")
     parser.add_argument("--folder", type=str, help="Open specified folder at startup")
@@ -283,11 +294,10 @@ def main():
             "File logging disabled. To enable, set PHOTOSORT_ENABLE_FILE_LOGGING=true."
         )
 
-        # --- Suppress verbose third-party loggers ---
+    # --- Suppress verbose third-party loggers ---
     logging.getLogger("PIL").setLevel(logging.INFO)
     logging.getLogger("PIL.PngImagePlugin").setLevel(logging.INFO)
     logging.getLogger("PIL.TiffImagePlugin").setLevel(logging.INFO)
-    # You might also want to set it for the more general Image module if logs still appear
     logging.getLogger("PIL.Image").setLevel(logging.INFO)
     # --- End Suppress verbose third-party loggers ---
 
@@ -299,6 +309,9 @@ def main():
     main_start_time = time.perf_counter()
     logging.info("Application starting...")
 
+    from ui.main_window import MainWindow
+    from ui.app_controller import AppController
+
     # Handle clear-cache argument
     if args.clear_cache:
         clear_application_caches_start_time = time.perf_counter()
@@ -307,23 +320,6 @@ def main():
             f"Caches cleared via command line in {time.perf_counter() - clear_application_caches_start_time:.4f}s"
         )
 
-    app_instantiation_start_time = time.perf_counter()
-    app = QApplication(sys.argv)
-    logging.debug(
-        f"QApplication instantiated in {time.perf_counter() - app_instantiation_start_time:.4f}s"
-    )
-
-    # Load and apply the stylesheet
-    stylesheet_load_start_time = time.perf_counter()
-    stylesheet = load_stylesheet()
-    if stylesheet:
-        app.setStyleSheet(stylesheet)
-        logging.debug(
-            f"Stylesheet loaded and applied in {time.perf_counter() - stylesheet_load_start_time:.4f}s"
-        )
-    else:
-        logging.warning("Stylesheet not found. Using default style.")
-
     mainwindow_instantiation_start_time = time.perf_counter()
     window = MainWindow(initial_folder=args.folder)
     apply_app_identity(app, window)
@@ -336,6 +332,26 @@ def main():
     logging.debug(
         f"MainWindow shown in {time.perf_counter() - window_show_start_time:.4f}s"
     )
+    splash.finish(window)
+    logging.debug(
+        f"Splashscreen finished in {time.perf_counter() - splash_total_start:.4f}s"
+    )
+
+    # Defer stylesheet loading to after splash finish to avoid blocking startup
+    stylesheet_load_start = time.perf_counter()
+
+    def apply_stylesheet():
+        stylesheet = load_stylesheet()
+        if stylesheet:
+            app.setStyleSheet(stylesheet)
+        logging.debug(
+            f"Stylesheet applied in {time.perf_counter() - stylesheet_load_start:.4f}s"
+        )
+
+    QTimer.singleShot(
+        0,
+        apply_stylesheet,
+    )
 
     logging.info(
         f"Application setup complete in {time.perf_counter() - main_start_time:.4f}s. Entering event loop."

src/ui/main_window.py

@@ -72,7 +72,6 @@
 from ui.helpers.statusbar_utils import build_status_bar_info
 from ui.helpers.index_lookup_utils import find_proxy_index_for_path
 
-# build_presentation now used only inside DeletionMarkController
 from ui.controllers.deletion_mark_controller import DeletionMarkController
 from ui.controllers.file_deletion_controller import FileDeletionController
 from ui.controllers.rotation_controller import RotationController