Merge branch 'release/0.8.0'

* Complete implementation of enhacemente pipeline
* Partial target restructure for new enhacement modules
* Updates the corresponding documentation
* General TODO and dead code maintenance

Author: J. Cappelletto

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.18)
-project(videostrip VERSION 0.7.1 LANGUAGES CXX)
+project(videostrip VERSION 0.8.0 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -15,7 +15,8 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 # Build options
 # ==========================================
 option(BUILD_TESTS "Build unit/integration tests" ON)
-option(BUILD_GUI "Build GUI module" OFF)
+# option(BUILD_GUI "Build GUI module" OFF)
+option(BUILD_MANPAGE "Generate manpage for CLI tool (requires help2man)" OFF)
 
 
 message(STATUS "--------------------")
@@ -54,21 +55,45 @@ message(STATUS "OpenCV version: ${OpenCV_VERSION}")
 message(STATUS "OpenCV include dirs: ${OpenCV_INCLUDE_DIRS}")
 
 # ==========================================
-# Global include path (so <videostrip_core/...> works everywhere)
-# ==========================================
-# All headers live in subfolders inside ${CMAKE_SOURCE_DIR}
-include_directories(${CMAKE_SOURCE_DIR})
-
+# yaml-cpp detection. FetchContent fallback
 # ==========================================
-# Promoted to top-level as it is needed by multiple modules
-find_package(yaml-cpp QUIET)
-if(NOT yaml-cpp_FOUND)
-  message(STATUS "yaml-cpp not found; fetching...")
+find_package(yaml-cpp CONFIG)
+
+if (TARGET yaml-cpp)
+    message(STATUS "yaml-cpp found (CONFIG package)")
+    message(STATUS "yaml-cpp include dirs: ${yaml-cpp_INCLUDE_DIRS}")
+else()
+    message(STATUS "yaml-cpp not found (CONFIG package)")
+  message(STATUS ">>>> yaml-cpp not found; fetching source with FetchContent...")
   include(FetchContent)
-  FetchContent_Declare(yaml_cpp GIT_REPOSITORY https://github.com/jbeder/yaml-cpp.git GIT_TAG 0.8.0)
+
+  # Keep the fetched build small & static
+  set(YAML_BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
+  set(YAML_CPP_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+  set(YAML_CPP_BUILD_TOOLS OFF CACHE BOOL "" FORCE)
+  set(YAML_CPP_INSTALL     OFF CACHE BOOL "" FORCE)
+  # MSVC runtime per your project policy
+  set(YAML_MSVC_SHARED_RT  ON  CACHE BOOL "" FORCE)
+
+  FetchContent_Declare(yaml_cpp
+    GIT_REPOSITORY https://github.com/jbeder/yaml-cpp.git
+    GIT_TAG        0.8.0
+  )
   FetchContent_MakeAvailable(yaml_cpp)
 endif()
 
+# At this point, a target named 'yaml-cpp' must exist (from either path).
+# If not, abort with error.
+if(NOT TARGET yaml-cpp)
+  message(FATAL_ERROR "yaml-cpp target not found even after FetchContent; aborting.")
+endif()
+
+# ==========================================
+# Global include path (so <videostrip_core/...> works everywhere)
+# ==========================================
+# All headers live in subfolders inside ${CMAKE_SOURCE_DIR}
+include_directories(${CMAKE_SOURCE_DIR})
+
 # ==========================================
 # Add project modules (progressive build)
 # ==========================================
@@ -137,9 +162,6 @@ install(TARGETS videostrip_core
   LIBRARY DESTINATION lib
 )
 
-# TODO: Minimal manpage (optional). We do not have one yet, generate with help2man later.
-# install(FILES packaging/videostrip.1 DESTINATION share/man/man1)
-
 # Public headers (install only .hpp files from videostrip_core/)
 # If the headers live in subdirs (feature/, logging/), this will include them.
 install(DIRECTORY ${CMAKE_SOURCE_DIR}/videostrip_core/
@@ -154,6 +176,37 @@ install(FILES configs/sample_config.yaml
 install(FILES ${CMAKE_SOURCE_DIR}/README.md ${CMAKE_SOURCE_DIR}/LICENSE
   DESTINATION share/doc/videostrip
 )
+# -------------------------
+# Manpage generation (optional)
+# -------------------------
+if (BUILD_MANPAGE)
+    message(STATUS "Manpage generation enabled")
+    find_program(HELP2MAN_EXECUTABLE help2man)
+
+    if(HELP2MAN_EXECUTABLE)
+        # Create packaging dir if it does not exist
+        file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/packaging)
+        add_custom_command(
+            OUTPUT ${CMAKE_BINARY_DIR}/packaging/videostrip.1
+            COMMAND ${HELP2MAN_EXECUTABLE} --no-discard-stderr --output=${CMAKE_BINARY_DIR}/packaging/videostrip.1 $<TARGET_FILE:videostrip_cli>
+            DEPENDS videostrip_cli
+            COMMENT "Generating manpage for videostrip_cli"
+            VERBATIM
+        )
+
+        add_custom_target(manpage ALL
+            DEPENDS ${CMAKE_BINARY_DIR}/packaging/videostrip.1
+        )
+
+        install(FILES ${CMAKE_BINARY_DIR}/packaging/videostrip.1 DESTINATION share/man/man1)
+        else()
+        message(WARNING "help2man not found: manpage will not be generated automatically.")
+    endif()
+
+else()
+  message(STATUS "Manpage generation disabled")
+endif()
+
 
 # -------------------------
 # CPack configuration
@@ -175,20 +228,17 @@ set(CPACK_PACKAGE_FILE_NAME
 # Source + binary archives
 set(CPACK_GENERATOR "TGZ;ZIP;DEB")
 
-# Debian metadata (tune as you learn your shared libs)
+# Debian metadata (tune as we expand shared libs)
 set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Jose Cappelletto")           # required
 set(CPACK_DEBIAN_PACKAGE_SECTION "science")
 set(CPACK_DEBIAN_ARCHITECTURE ${CMAKE_SYSTEM_PROCESSOR})
 
 # Runtime deps if linking dynamically; keep minimal first, then refine with ldd
-# Example: 
 set(CPACK_DEBIAN_PACKAGE_DEPENDS "libstdc++6, libgcc-s1")
-# TODO: 
-# Add correct libraries from OpenCV
-# set(CPACK_DEBIAN_PACKAGE_DEPENDS "libopencv-core4.8, libopencv-imgcodecs4.8")
+# Automate depedencies based on linked shared libs
 set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
 # Avoid the classic error: ensure CPack knows the project
 set(CPACK_PACKAGE_FILE_NAME "videostrip-${PROJECT_VERSION}-${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_PROCESSOR}")
 
 include(CPack)
-# End of CPack configuration
+# End of CPack configuration

README.md

@@ -16,13 +16,16 @@ It produces **SfM-ready frame sets** and metadata for tools like **COLMAP, Meshr
 > * A **CLI application** for processing videos into frames + metadata.
 > * A **core library** exposing `VideoFrameExtractor` and related modules.
 > * A **metadata writer** for reproducible CSV + YAML outputs.
-> * CI/CD with unit tests for schema regression.
+> * CI/CD with unit tests for schema regression, running on Linux and Windows.
+> * A modular image enhacement pipeline (pre-export stage)
+> * Optional packaging system (DEB/TAR)
+> * Linux compatible documentation (manpages)
 
 **Short-term focus**: Consolidate usability, error resilience, and schema compliance before expanding to advanced feature modes (grid, enhancement, optical flow).
 
 ---
 
-## **Key Features (v0.4.0)**
+## **Key Features (v0.8.0)**
 
 * ✅ **CLI support** for video processing with YAML or CLI configs.
 * ✅ **Frame extraction with stride or overlap-based selection**.
@@ -31,7 +34,7 @@ It produces **SfM-ready frame sets** and metadata for tools like **COLMAP, Meshr
   * `frames.csv` — per-frame metadata.
   * `summary.yaml` — run summary + configuration snapshot.
 * ✅ **Deterministic file structure**: images/, features/, frames.csv, summary.yaml, run.log.
-* ⏳ **On-export frame enhancement** (future).
+* ✅ **On-export frame enhancement** (future).
 * ⏳ **Grid-based feature density normalization** (future).
 
 ---
@@ -67,7 +70,7 @@ git clone https://github.com/cappelletto/videostrip.git
 cd videostrip
 
 # Configure and build
-cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_MANPAGE=OFF -DBUILD_TESTS=OFF
 cmake --build build -j4
 ```
 
@@ -129,6 +132,73 @@ processing:
 
 ---
 
+## **Enhancement Pipeline (NEW)**
+TODO: extract this into a separate `docs/enhancement.md`.
+
+Starting with **v0.7.x**, videostrip supports an optional **image enhancement stage** that preprocesses frames before feature extraction. This improves contrast and uniformity in underwater imagery.
+
+### Supported enhancement steps
+
+* **Contrast & offset**
+  Linear transform per pixel: `alpha * I + beta`.
+  *Params*: `alpha` (gain), `beta` (offset).
+
+* **Gray-world white balance**
+  Scales RGB channels so that their mean matches the global mean.
+  *Params*: none.
+
+* **Gamma correction**
+  Applies a gamma LUT (`I_out = I_in^(1/gamma)`).
+  *Params*: `value` (gamma > 0).
+
+* **CLAHE (Contrast Limited Adaptive Histogram Equalization)**
+  Adaptive histogram equalization on luminance channel.
+  *Params*:
+
+  * `clip_limit` (float, default 2.0)
+  * `tile_grid` (two-element array, default `[8,8]`)
+  * `space` (one of `YCrCb`, `HSV`, `Lab`, `BGR`)
+    Channel is chosen implicitly: Y (YCrCb), V (HSV), L (Lab), all channels (BGR).
+
+### Minimal YAML configuration
+
+Add an `enhance` block at the top level of the config file:
+
+```yaml
+enhance:
+  enable: true
+  sequence:
+    - type: contrast
+      alpha: 1.10
+      beta: -5
+    - type: grayworld
+    - type: gamma
+      value: 1.05
+    - type: clahe
+      clip_limit: 2.0
+      tile_grid: [8, 8]
+      space: YCrCb
+```
+
+If no `enhance:` block is given but the legacy flag
+
+```yaml
+processing:
+  apply_enhancement: true
+```
+
+is set, a default sequence `{grayworld, clahe(YCrCb)}` will be applied.
+
+### CLI override
+
+You can also pass a shorthand string (for quick tests):
+
+```bash
+./videostrip_cli --enhance.sequence "contrast(alpha=1.1,beta=-5); grayworld; gamma(1.05); clahe(clip=2.0,grid=8x8,space=YCrCb)"
+```
+
+---
+
 ## **Schema v1 Contract**
 
 * **frames.csv** — columns: `frame_idx,timestamp_ms,output_image,feature_count,quality_score,georef`
@@ -144,13 +214,13 @@ Schema is locked at `v1`. Future changes will bump schema_version.
 ## **Roadmap**
 
 Near-term milestones:
-1. Add **frame enhancement filters** (CLAHE, WB).
-2. Introduce **grid-based feature normalization**.
-3. Expand **Windows CI/CD** coverage.
+1. Introduce **grid-based feature normalization**.
+2. Performance release by adding multithreading and GPU support.
 
 Long-term:
 * Optical flow / ECC overlap modes.
-* Batch manager & GUI front-end.
+* Cross-platform GUI for both pipeline configuration and dispatching.
+* Integration with Meshroom (node-base core library)
 
 ---
 

configs/sample_config.yaml

@@ -1,8 +1,8 @@
 version: 1
 
 input:
-  video: ./data/example_video.avi
-
+  # video: ./data/21062025_Lipa_WFC_P1_Mosaic_StereoL.MOV
+# 
 output:
   base_dir: ./_tmp_out
   images_dir: images
@@ -12,11 +12,25 @@ output:
   log: run.log
 
 processing:
-  feature_type: ORB
+  feature_type: KAZE
   image_format: png
   overlap_threshold: 0.75
-  max_skipped_frames: 4
-  apply_enhancement: false
+  max_skipped_frames: 5
+  apply_enhancement: true
   create_output_dirs: true
   enable_logging: true
   # overlap_mode: FEATURE  # (optional, harmless for now)
+
+enhance:
+  enable: true
+  sequence:
+    - type: contrast
+      alpha: 1.5
+      beta: 10
+    - type: grayworld
+    - type: gamma
+      value: 1.05
+    - type: clahe
+      clip_limit: 2.0
+      tile_grid: [8, 8]
+      space: YCrCb   # YCrCb | HSV | Lab | BGR

videostrip_cli/CMakeLists.txt

@@ -13,7 +13,7 @@ add_executable(videostrip_cli
 # - Project external folder for args.hxx
 # - Core module for headers.hpp and helper.hpp
 target_include_directories(videostrip_cli
-    PRIVATE
+    PUBLIC
         ${CMAKE_CURRENT_SOURCE_DIR}
         ${CMAKE_SOURCE_DIR}/external
         ${CMAKE_SOURCE_DIR}/videostrip_core

videostrip_cli/config_loader.cpp

@@ -4,6 +4,7 @@
 #include <yaml-cpp/yaml.h>
 
 #include <videostrip_cli/config_loader.hpp>
+#include <videostrip_core/enhance_yaml.hpp>
 
 namespace fs = std::filesystem;
 
@@ -98,6 +99,32 @@ bool load_yaml_config(const std::string& yaml_path,
         }
         normalize_output_paths(out, chosen_base);
 
+        // enhancement.* (authoritative block) 
+        // YAML::Node root["enhance"] is the standard way to access it.
+        // We still delegate parsing to core to avoid duplicating schema rules. For that we use the parseEnhanceConfig function.
+        std::string enhance_err;
+        auto enhance_cfg = videostrip::parseEnhanceConfig(root, enhance_err); // return type std::optional<EnhanceConfig>
+        if (!enhance_cfg.has_value()) {
+            // Check if the node was present but malformed
+            if (root["enhance"]) {
+                err = "Failed to parse enhance config: " + enhance_err;
+                return false;
+            }
+        }
+        else{
+            out.enhance = *enhance_cfg; //copy the content of the optional to the out config
+        }
+
+        // Check if we received the legacy flag for apply_enhancement
+        if (out.apply_enhancement && !root["enhance"]) {
+            // If so, enable a default enhancement sequence (GrayWorldWB)
+            out.enhance.enable = true;
+            // clear the sequence if any (should be empty anyway)
+            out.enhance.sequence.clear();
+            out.enhance.sequence.push_back({EnhanceType::GrayWorldWB, GrayWorldParams{}});
+            out.enhance.sequence.push_back({ EnhanceType::CLAHE, ClaheParams{2.0, {8,8}, ClaheSpace::YCrCb} });
+        }
+
         err.clear();
         return true;
     }
@@ -164,6 +191,7 @@ void merge_yaml_into(ExtractorConfig& dst, const ExtractorConfig& y)
     dst.apply_enhancement  = y.apply_enhancement;
     dst.create_output_dirs = y.create_output_dirs;
     dst.enable_logging     = y.enable_logging;
+    dst.enhance            = y.enhance;
 
     // Optional future field:
     // if (!y.overlap_mode.empty()) dst.overlap_mode = y.overlap_mode;

videostrip_cli/videostrip_cli.cpp

@@ -71,11 +71,15 @@ int main(int argc, char *argv[])
     if (config_file) {
         std::string err;
         ExtractorConfig y;
+        // Show in console we are loading a config
+        std::cout << "Loading config from " << args::get(config_file) << "\n";
         if (!videostrip::cli::load_yaml_config(args::get(config_file), y, err)) {
             std::cerr << "Config error: " << err << "\n";
             return 2;
         }
-        videostrip::cli::merge_yaml_into(config, y);
+        // TODO: Reevaluate either setting flags as optional (otherwise we can't tell if user set them or end using defaults)
+        // Or just avoid merging and always let CLI override YAML if present
+        videostrip::cli::merge_yaml_into(config, y); // Ensure 'config' is passed by reference in the function definition
     }
 
     // Input (CLI > YAML)
@@ -202,7 +206,7 @@ int main(int argc, char *argv[])
             });
 
         // Run
-        const bool ok = extractor.run();
+        const bool ok = extractor.run(); ///< this will run main videostrip_core loop: VideoFrameExtractor::run()
         std::cout << std::endl;
         if (!ok)
         {