Add scene gallery with GIF previews, incremental C++ preview generator, and desktop-scene capture script

CMakeLists.txt

@@ -113,10 +113,12 @@ endif()
 
 
 
-
 # Adding plugins
 add_subdirectory(plugins)
 
+# Collect the list of matrix plugin targets published by register_plugin()
+get_property(MATRIX_PLUGIN_TARGETS GLOBAL PROPERTY MATRIX_PLUGIN_TARGETS)
+
 # Add an executable with the above sources
 add_executable(${PROJECT_NAME}
     ${SOURCES}
@@ -252,6 +254,64 @@ if(NOT ENABLE_EMULATOR AND NOT ENABLE_DESKTOP)
     endif()
 endif()
 
+# ---------------------------------------------------------------------------
+# preview_gen: headless scene-preview GIF generator (emulator builds only)
+# ---------------------------------------------------------------------------
+if(ENABLE_EMULATOR)
+    # Tunable preview parameters - override on the command line as needed.
+    set(PREVIEW_FPS    "15"  CACHE STRING "Frames per second for scene preview GIFs")
+    set(PREVIEW_FRAMES "90"  CACHE STRING "Total frames per scene preview GIF (90 @ 15fps = 6 s)")
+    set(PREVIEW_WIDTH  "128" CACHE STRING "Preview GIF width (pixels)")
+    set(PREVIEW_HEIGHT "128" CACHE STRING "Preview GIF height (pixels)")
+
+    set(_PREVIEW_LIB_PATH
+        "${CMAKE_BINARY_DIR}/shared/matrix:${CMAKE_BINARY_DIR}/shared/common:${CMAKE_BINARY_DIR}/vcpkg_installed/${VCPKG_TARGET_TRIPLET}/lib"
+    )
+
+    add_executable(preview_gen
+        ${CMAKE_CURRENT_SOURCE_DIR}/src_preview_gen/main.cpp
+    )
+
+    target_compile_features(preview_gen PRIVATE cxx_std_23)
+    target_compile_definitions(preview_gen PRIVATE ENABLE_EMULATOR)
+
+    target_link_libraries(preview_gen PRIVATE
+        SharedToolsCommon
+        SharedToolsMatrix
+        spdlog::spdlog
+        nlohmann_json::nlohmann_json
+        unofficial::graphicsmagick::graphicsmagick
+        rpi_rgb_led_matrix::rpi-rgb-led-matrix
+        ${CMAKE_DL_LIBS}
+    )
+
+    # Install the binary itself so users can manually generate/regenerate previews
+    install(TARGETS preview_gen
+        DESTINATION .
+    )
+
+    # Install scene previews from the git-tracked scene_previews/ directory
+    # Previews are committed to git and deployed as-is, not auto-generated
+    # during the build. Use ./scripts/generate_scene_previews.sh to regenerate.
+
+    # Install to web directory (for web interface access)
+    if(NOT ENABLE_DESKTOP)
+        install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/scene_previews/"
+            DESTINATION web/scene_previews
+            OPTIONAL
+            FILES_MATCHING PATTERN "*.gif"
+        )
+    endif()
+
+    # Install to root for server access (e.g., /scene_preview endpoint)
+    # This maintains backward compatibility with the server's /scene_preview endpoint
+    install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/scene_previews/"
+        DESTINATION scene_previews
+        OPTIONAL
+        FILES_MATCHING PATTERN "*.gif"
+    )
+endif()
+
 #Cross Comp https://forum.grin.mw/t/building-grin-for-raspberry-pi4/7916
 
 if(NOT SKIP_WEB_BUILD AND NOT ENABLE_DESKTOP)
@@ -331,7 +391,6 @@ if(NOT ENABLE_DESKTOP)
         LIBRARY DESTINATION . # .so/.dylib (Unix)
     )
 
-
     # Install fonts to fonts directory
     install(FILES
         "${RPI_RGB_LED_MATRIX_FONTS_DIR}/7x13.bdf"

README.md

@@ -322,6 +322,85 @@ Test your scenes without physical hardware using our SDL2-based emulator:
 
 Perfect for development, testing, and demonstrations!
 
+#### **Scene Preview GIFs**
+
+The web interface shows animated GIF previews for each scene in the gallery. Previews are **committed to git** in the `scene_previews/` directory and deployed with the application.
+
+**Generate all scene previews:**
+```bash
+# Build the emulator first
+cmake --preset emulator
+cmake --build --preset emulator --target install
+
+# Generate previews (outputs to scene_previews/)
+./scripts/generate_scene_previews.sh --all
+```
+
+**Generate specific scenes:**
+```bash
+./scripts/generate_scene_previews.sh --scenes "WaveScene,ColorPulseScene,FractalScene"
+```
+
+**Generate from a list file:**
+```bash
+# Create a file with scene names (one per line, # for comments)
+cat > my_scenes.txt << EOF
+WaveScene
+ColorPulseScene
+# FractalScene  (commented out)
+EOF
+
+./scripts/generate_scene_previews.sh --list my_scenes.txt
+```
+
+**Customize preview parameters:**
+```bash
+./scripts/generate_scene_previews.sh --all \
+  --fps 20 \
+  --frames 120 \
+  --width 128 \
+  --height 128
+```
+
+**Commit previews to git:**
+```bash
+git add scene_previews/
+git commit -m "Update scene previews"
+```
+
+**Desktop-dependent scenes** (VideoScene, AudioSpectrumScene, ShadertoyScene, etc.) cannot be generated headlessly and must be captured manually:
+```bash
+# 1. Start the emulator (non-headless) and the desktop app
+./scripts/run_emulator.sh &
+./desktop_build/bin/led-matrix-desktop &
+
+# 2. Capture desktop-dependent scene previews
+./scripts/capture_desktop_preview.sh --api-url http://localhost:8080
+
+# Options:
+#   --scenes AudioSpectrumScene,ShadertoyScene   # specific scenes only
+#   --duration 8                                 # capture 8 seconds per scene
+#   --output ./scene_previews                    # output directory
+```
+
+**Full deploy workflow:**
+```bash
+# 1. Generate/update previews (outputs to scene_previews/)
+./scripts/generate_scene_previews.sh --all
+
+# 2. Commit previews to git
+git add scene_previews/
+git commit -m "Update scene previews"
+
+# 3. Cross-compile and deploy
+cmake --preset cross-compile
+cmake --build <build_dir>
+cmake --build <build_dir> --target install
+
+# Or use the build_upload.sh helper script
+./scripts/build_upload.sh
+```
+
 ### 🌐 **Web App Development**
 
 Run the development server in minutes:
@@ -408,7 +487,7 @@ By default, the main index page will redirect you to the web controller (located
 |--------|----------|-------------|
 | `GET` | `/status` | System status and current state |
 | `GET` | `/get_curr` | Current scene information |
-| `GET` | `/list_scenes` | Available scenes and plugins |
+| `GET` | `/list_scenes` | Available scenes and plugins (includes `has_preview` and `needs_desktop` per scene) |
 | `GET` | `/toggle` | Toggle display on/off |
 | `GET` | `/skip` | Skip to next scene |
 
@@ -428,6 +507,9 @@ By default, the main index page will redirect you to the web controller (located
 | `GET` | `/list` | Available local images |
 | `GET` | `/image?url=<url>` | Fetch and display remote image |
 | `GET` | `/list_providers` | Available image providers |
+| `GET` | `/scene_preview?name=<scene_name>` | Preview GIF for a scene (if available) |
+
+> **Scene Previews:** GIF files are pre-generated and committed to git in the `scene_previews/` directory. They are deployed to `<install_dir>/scene_previews/` and accessible via the `/scene_preview?name=<scene_name>` endpoint. To generate or update previews, use the `./scripts/generate_scene_previews.sh` script. After generating, commit the GIFs to git before deploying. The `/list_scenes` endpoint includes `has_preview` (bool) and `needs_desktop` (bool) fields per scene.
 
 ### ⚙️ **System Control**