Merge pull request #2 from Askill/copilot/improve-project-structure-and-quality

Modernize project structure: package config, testing, CI/CD, YAML configs, Docker

.dockerignore

@@ -0,0 +1,52 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info
+dist
+build
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# Development
+.pre-commit-config.yaml
+requirements-dev.txt
+
+# Output and test files
+output/
+input/
+*.mp4
+*.m4v
+*.weights
+
+# OS
+.DS_Store
+Thumbs.db

.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install black isort flake8 mypy
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    
+    - name: Check code formatting with Black
+      run: |
+        black --check --line-length 140 .
+    
+    - name: Check import sorting with isort
+      run: |
+        isort --check-only --profile black --line-length 140 .
+    
+    - name: Lint with flake8
+      run: |
+        # Stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # Exit-zero treats all errors as warnings
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=140 --statistics --extend-ignore=E203,W503
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y ffmpeg libsm6 libxext6 libxrender-dev
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-cov
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    
+    - name: Run tests (if they exist)
+      run: |
+        if [ -d tests ]; then
+          pytest --cov=Application --cov-report=xml --cov-report=term-missing
+        else
+          echo "No tests directory found, skipping tests"
+        fi
+    
+    - name: Upload coverage reports
+      if: matrix.python-version == '3.12'
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    
+    - name: Build package
+      run: |
+        python -m build
+    
+    - name: Check package
+      run: |
+        pip install twine
+        twine check dist/*

.gitignore

@@ -1,18 +1,87 @@
-
+# Test footage and media files
 generate test footage/images/
-
 generate test footage/3.MP4
 input/*
 short.mp4
-
-__pycache__/
-.vscode/
 *.mp4
-
 *.weights
 *.m4v
-
-/output/*.txt
-
 docs/ueberblick.drawio.png
+
+# Output and cache
+output/
+/output/*.txt
 tmp/tmp.prof
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.manifest
+*.spec
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# Testing
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Jupyter
+.ipynb_checkpoints
+*.ipynb
+
+# Environment variables
+.env
+.env.local
+
+# Pre-commit
+.pre-commit-config.yaml.bak

.pre-commit-config.yaml

@@ -0,0 +1,47 @@
+# Pre-commit hooks for code quality
+# Install with: pip install pre-commit && pre-commit install
+
+repos:
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: detect-private-key
+
+  # Python code formatting
+  - repo: https://github.com/psf/black
+    rev: 23.12.1
+    hooks:
+      - id: black
+        args: ['--line-length=140']
+
+  # Import sorting
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args: ['--profile', 'black', '--line-length', '140']
+
+  # Linting
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        args: ['--max-line-length=140', '--extend-ignore=E203,W503']
+
+  # Type checking (optional - can be slow)
+  # Uncomment to enable mypy checks
+  # - repo: https://github.com/pre-commit/mirrors-mypy
+  #   rev: v1.8.0
+  #   hooks:
+  #     - id: mypy
+  #       additional_dependencies: [types-all]
+  #       args: [--ignore-missing-imports]

Application/Classifiers/Classifier.py

@@ -106,7 +106,7 @@ class Classifier(ClassifierInterface):
             image_np_expanded = np.expand_dims(image, axis=0)
             # Actual detection.
 
-            (boxes, scores, classes, num) = self.sess.run(
+            boxes, scores, classes, num = self.sess.run(
                 [self.detection_boxes, self.detection_scores, self.detection_classes, self.num_detections],
                 feed_dict={self.image_tensor: image_np_expanded},
             )

Application/Config.py

@@ -1,8 +1,32 @@
+"""Configuration management for Video Summary application."""
+
 import json
 import os
+from typing import Any, Optional
+
+try:
+    import yaml
+
+    YAML_AVAILABLE = True
+except ImportError:
+    YAML_AVAILABLE = False
+
+
+def _get_logger():
+    """Lazy load logger to avoid circular imports."""
+    from Application.Logger import get_logger
+
+    return get_logger(__name__)
 
 
 class Config:
+    """
+    Configuration management supporting JSON and YAML formats.
+
+    Supports loading configuration from JSON or YAML files, with fallback
+    to default values. Also supports environment variable overrides.
+    """
+
     c = {
         "min_area": 300,
         "max_area": 900000,
@@ -20,24 +44,116 @@ class Config:
         "avgNum": 10,
     }
 
-    def __init__(self, config_path):
+    def __init__(self, config_path: Optional[str]):
-        """This is basically just a wrapper for a json / python dict"""
+        """
-        if os.path.isfile(config_path):
+        Initialize configuration from file or use defaults.
-            print("using supplied configuration at", config_path)
+
-            # fail if config can not be parsed
+        Args:
-            with open(config_path) as file:
+            config_path: Path to JSON or YAML configuration file.
-                self.c = json.load(file)
+                        If None or invalid, uses defaults.
+                        Supports .json, .yaml, and .yml extensions.
+        """
+        logger = _get_logger()
+        if config_path and os.path.isfile(config_path):
+            logger.info(f"Using supplied configuration at {config_path}")
+            try:
+                self.c = self._load_config_file(config_path)
+            except Exception as e:
+                logger.error(f"Failed to parse config file: {e}")
+                logger.warning("Falling back to default configuration")
         else:
-            print("using default configuration")
+            logger.info("Using default configuration")
 
-        print("Current Config:")
+        # Apply environment variable overrides
+        self._apply_env_overrides()
+
+        logger.info("Current Configuration:")
         for key, value in self.c.items():
-            print(f"{key}:\t\t{value}")
+            logger.info(f"  {key}: {value}")
 
-    def __getitem__(self, key):
+    def _load_config_file(self, config_path: str) -> dict:
+        """
+        Load configuration from JSON or YAML file.
+
+        Args:
+            config_path: Path to configuration file
+
+        Returns:
+            Dictionary with configuration values
+
+        Raises:
+            ValueError: If file format is not supported
+        """
+        ext = os.path.splitext(config_path)[1].lower()
+
+        with open(config_path, "r") as file:
+            if ext == ".json":
+                return json.load(file)
+            elif ext in [".yaml", ".yml"]:
+                if not YAML_AVAILABLE:
+                    raise ValueError("PyYAML is not installed. Install with: pip install pyyaml")
+                return yaml.safe_load(file)
+            else:
+                # Try JSON first, then YAML
+                content = file.read()
+                file.seek(0)
+                try:
+                    return json.loads(content)
+                except json.JSONDecodeError:
+                    if YAML_AVAILABLE:
+                        file.seek(0)
+                        return yaml.safe_load(file)
+                    else:
+                        raise ValueError(f"Unsupported config file format: {ext}")
+
+    def _apply_env_overrides(self):
+        """Apply environment variable overrides to configuration."""
+        logger = _get_logger()
+        env_prefix = "VIDEO_SUMMARY_"
+        for key in self.c.keys():
+            env_key = f"{env_prefix}{key.upper()}"
+            env_value = os.environ.get(env_key)
+            if env_value is not None:
+                # Try to convert to appropriate type
+                try:
+                    # Try integer
+                    self.c[key] = int(env_value)
+                except ValueError:
+                    try:
+                        # Try float
+                        self.c[key] = float(env_value)
+                    except ValueError:
+                        # Use as string
+                        self.c[key] = env_value
+                logger.info(f"Environment override: {key} = {self.c[key]}")
+
+    def __getitem__(self, key: str) -> Any:
+        """Get configuration value by key."""
         if key not in self.c:
             return None
         return self.c[key]
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set configuration value by key."""
         self.c[key] = value
+
+    def save(self, output_path: str):
+        """
+        Save current configuration to file.
+
+        Args:
+            output_path: Path to save configuration file.
+                        Format is determined by extension (.json, .yaml, .yml)
+        """
+        ext = os.path.splitext(output_path)[1].lower()
+
+        with open(output_path, "w") as file:
+            if ext == ".json":
+                json.dump(self.c, file, indent=2)
+            elif ext in [".yaml", ".yml"]:
+                if not YAML_AVAILABLE:
+                    raise ValueError("PyYAML is not installed. Install with: pip install pyyaml")
+                yaml.dump(self.c, file, default_flow_style=False)
+            else:
+                # Default to JSON
+                json.dump(self.c, file, indent=2)

Application/ContourExctractor.py

@@ -86,7 +86,7 @@ class ContourExtractor:
         masks = []
         for c in cnts:
             ca = cv2.contourArea(c)
-            (x, y, w, h) = cv2.boundingRect(c)
+            x, y, w, h = cv2.boundingRect(c)
             if ca < self.min_area or ca > self.max_area:
                 continue
             contours.append((x, y, w, h))

Application/Exporter.py

@@ -48,7 +48,7 @@ class Exporter:
                     frame_count, frame = video_reader.pop()
                     frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
                     frame2 = np.copy(underlay)
-                    for (x, y, w, h) in layer.bounds[frame_count - layer.start_frame]:
+                    for x, y, w, h in layer.bounds[frame_count - layer.start_frame]:
                         if x is None:
                             continue
                         factor = video_reader.w / self.resize_width
@@ -105,7 +105,9 @@ class Exporter:
                                     cv2.imshow("changes x", background)
                                     cv2.waitKey(10) & 0xFF
 
-                                self.add_timestamp(frames[frame_count - layer.start_frame + layer.export_offset], videoReader, frame_count, x, y, w, h)
+                                self.add_timestamp(
+                                    frames[frame_count - layer.start_frame + layer.export_offset], videoReader, frame_count, x, y, w, h
+                                )
                             except:
                                 continue
 

Application/HeatMap.py

@@ -1,13 +1,40 @@
+"""Heatmap generation for video activity visualization."""
+
+from typing import List, Tuple
+
 import numpy as np
 from matplotlib import pyplot as plt
 
+
 class HeatMap:
-    def __init__(self, x, y, contours, resize_factor=1):
+    """
+    Generate heatmap visualization of video activity.
+
+    Creates a heatmap showing areas of movement/activity in a video by
+    accumulating contour locations over time.
+    """
+
+    def __init__(self, x: int, y: int, contours: List[List[Tuple[int, int, int, int]]], resize_factor: float = 1):
+        """
+        Initialize HeatMap.
+
+        Args:
+            x: Width of the heatmap image
+            y: Height of the heatmap image
+            contours: List of contour lists, where each contour is (x, y, w, h)
+            resize_factor: Factor to scale contours (for upscaling from processed size)
+        """
         self.image_bw = np.zeros(shape=[y, x, 3], dtype=np.float64)
         self._resize_factor = resize_factor
         self._create_image(contours)
 
-    def _create_image(self, contours):
+    def _create_image(self, contours: List[List[Tuple[int, int, int, int]]]):
+        """
+        Create heatmap image from contours.
+
+        Args:
+            contours: List of contour lists to accumulate into heatmap
+        """
         for contour in contours:
             for x, y, w, h in contour:
                 x, y, w, h = (
@@ -21,8 +48,15 @@ class HeatMap:
         self.image_bw = np.nan_to_num(self.image_bw / self.image_bw.sum(axis=1)[:, np.newaxis], 0)
 
     def show_image(self):
+        """Display the heatmap using matplotlib."""
         plt.imshow(self.image_bw * 255)
         plt.show()
 
-    def save_image(self, path):
+    def save_image(self, path: str):
+        """
+        Save heatmap to file.
+
+        Args:
+            path: Output file path for the heatmap image
+        """
         plt.imsave(path, (255 * self.image_bw).astype(np.uint8))

Application/Importer.py

@@ -1,5 +1,6 @@
-import pickle
 import os.path
+import pickle
+
 
 class Importer:
     def __init__(self, config):

Application/Layer.py

@@ -1,21 +1,43 @@
-import cv2
+"""Layer data structure for grouping related contours across frames."""
-import imutils
+
+from typing import Any, Dict, List, Optional, Tuple
+
 import numpy as np
 
 
 class Layer:
+    """
+    Represents a layer of related contours across video frames.
+
+    Layers group contours that represent the same moving object or area
+    across multiple frames, allowing for coherent tracking and visualization.
+
+    Attributes:
+        start_frame: Frame number where this layer begins
+        last_frame: Frame number where this layer ends
+        length: Total length of the layer in frames
+    """
+
     # bounds = [[(x,y,w,h), ],]
 
-    start_frame = None
+    start_frame: Optional[int] = None
-    last_frame = None
+    last_frame: Optional[int] = None
-    length = None
+    length: Optional[int] = None
 
-    def __init__(self, start_frame, data, mask, config):
+    def __init__(self, start_frame: int, data: Tuple[int, int, int, int], mask: np.ndarray, config: Dict[str, Any]):
-        """returns a Layer object
+        """
+        Initialize a Layer.
 
+        Args:
+            start_frame: Frame number where this layer starts
+            data: Initial contour bounds as (x, y, w, h)
+            mask: Binary mask for the contour
+            config: Configuration dictionary
+
+        Note:
             Layers are collections of contours with a start_frame,
             which is the number of the frame the first contour of
-        this layer was extraced from
+            this layer was extracted from.
 
             A Contour is a CV2 Contour, which is a y*x*3 rgb numpy array,
             but we only care about the corners of the contours.
@@ -24,17 +46,24 @@ class Layer:
         self.start_frame = start_frame
         self.last_frame = start_frame
         self.config = config
-        self.data = []
+        self.data: List = []
-        self.bounds = []
+        self.bounds: List = []
-        self.masks = []
+        self.masks: List = []
-        self.stats = dict()
+        self.stats: Dict[str, Any] = dict()
-        self.export_offset = 0
+        self.export_offset: int = 0
 
         self.bounds.append([data])
         self.masks.append([mask])
 
-    def add(self, frame_number, bound, mask):
+    def add(self, frame_number: int, bound: Tuple[int, int, int, int], mask: np.ndarray):
-        """Adds a bound to the Layer at the layer index which corresponds to the given framenumber"""
+        """
+        Add a bound to the Layer at the index corresponding to the frame number.
+
+        Args:
+            frame_number: Frame number for this bound
+            bound: Contour bounds as (x, y, w, h)
+            mask: Binary mask for the contour
+        """
         index = frame_number - self.start_frame
         if index < 0:
             return
@@ -63,7 +92,9 @@ class Layer:
         for b1s, b2s in zip(bounds[::10], layer2.bounds[:max_len:10]):
             for b1 in b1s:
                 for b2 in b2s:
-                    if self.contours_overlay((b1[0], b1[1] + b1[3]), (b1[0] + b1[2], b1[1]), (b2[0], b2[1] + b2[3]), (b2[0] + b2[2], b2[1])):
+                    if self.contours_overlay(
+                        (b1[0], b1[1] + b1[3]), (b1[0] + b1[2], b1[1]), (b2[0], b2[1] + b2[3]), (b2[0] + b2[2], b2[1])
+                    ):
                         overlap = True
                         break
         return overlap

Application/LayerFactory.py

@@ -61,7 +61,7 @@ class LayerFactory:
         frame_number = data[0]
         bounds = data[1]
         mask = data[2]
-        (x, y, w, h) = bounds
+        x, y, w, h = bounds
         tol = self.tolerance
 
         found_layer_i_ds = set()
@@ -75,7 +75,7 @@ class LayerFactory:
             for j, bounds in enumerate(sorted(last_bounds, reverse=True)):
                 if bounds is None:
                     break
-                (x2, y2, w2, h2) = bounds
+                x2, y2, w2, h2 = bounds
                 if self.contours_overlay((x - tol, y + h + tol), (x + w + tol, y - tol), (x2, y2 + h2), (x2 + w2, y2)):
                     layer.add(frame_number, (x, y, w, h), mask)
                     found_layer_i_ds.add(i)

Application/LayerManager.py

@@ -4,12 +4,20 @@ from multiprocessing.pool import ThreadPool
 import cv2
 import numpy as np
 
-from Application.Classifiers.Classifier import Classifier
 from Application.Config import Config
 from Application.Exporter import Exporter
 from Application.Layer import Layer
 from Application.VideoReader import VideoReader
 
+# Optional: Classifier (requires TensorFlow)
+try:
+    from Application.Classifiers.Classifier import Classifier
+
+    CLASSIFIER_AVAILABLE = True
+except ImportError:
+    CLASSIFIER_AVAILABLE = False
+    Classifier = None
+
 
 class LayerManager:
     def __init__(self, config, layers):
@@ -82,7 +90,7 @@ class LayerManager:
                 frame_count, frame = video_reader.pop()
                 frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
                 data = []
-                for (x, y, w, h) in layer.bounds[frame_count - layer.start_frame]:
+                for x, y, w, h in layer.bounds[frame_count - layer.start_frame]:
                     if x is None:
                         break
                     factor = video_reader.w / self.resize_width

Application/Logger.py

@@ -0,0 +1,56 @@
+"""Logging configuration for Video Summary application."""
+
+import logging
+import sys
+from typing import Optional
+
+
+def setup_logger(name: str = "video_summary", level: int = logging.INFO, log_file: Optional[str] = None) -> logging.Logger:
+    """
+    Configure and return a logger instance.
+
+    Args:
+        name: Logger name
+        level: Logging level (default: INFO)
+        log_file: Optional log file path. If None, logs to stdout only.
+
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Prevent duplicate handlers
+    if logger.handlers:
+        return logger
+
+    # Create formatter
+    formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    # File handler (optional)
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(level)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    return logger
+
+
+def get_logger(name: str = "video_summary") -> logging.Logger:
+    """
+    Get an existing logger instance.
+
+    Args:
+        name: Logger name
+
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)

Application/VideoReader.py

@@ -1,17 +1,48 @@
+"""Video reading utility with buffering support."""
+
 import multiprocessing
 import os
 import queue
 import threading
+from typing import Optional, Set, Tuple
 
 import cv2
 
 
 class VideoReader:
-    list_of_frames = None
+    """
-    w = None
+    Asynchronous video reader with frame buffering.
-    h = None
 
-    def __init__(self, config, set_of_frames=None, multiprocess=False):
+    This class provides efficient video reading by using a separate thread/process
+    to continuously load frames into a buffer, improving I/O performance for video
+    processing pipelines.
+
+    Attributes:
+        list_of_frames: Optional list of specific frame numbers to read
+        w: Video width in pixels
+        h: Video height in pixels
+    """
+
+    list_of_frames: Optional[list] = None
+    w: Optional[int] = None
+    h: Optional[int] = None
+
+    def __init__(self, config, set_of_frames: Optional[Set[int]] = None, multiprocess: bool = False):
+        """
+        Initialize VideoReader.
+
+        Args:
+            config: Configuration dictionary containing:
+                - inputPath: Path to video file
+                - videoBufferLength: Size of frame buffer
+            set_of_frames: Optional set of specific frame numbers to read.
+                          If None, reads all frames.
+            multiprocess: If True, uses multiprocessing for buffer.
+                         If False, uses threading (default).
+
+        Raises:
+            Exception: If video_path is not provided in config.
+        """
         video_path = config["inputPath"]
         if video_path is None:
             raise Exception("ERROR: Video reader needs a video_path!")
@@ -33,22 +64,38 @@ class VideoReader:
             self.list_of_frames = sorted(set_of_frames)
 
     def __enter__(self):
+        """Context manager entry - starts buffer filling."""
         self.fill_buffer()
         return self
 
     def __exit__(self, type, value, traceback):
+        """Context manager exit - stops video reading."""
         self.stop()
 
     def stop(self):
+        """Stop the video reading thread and wait for it to complete."""
         self.thread.join()
 
-    def pop(self):
+    def pop(self) -> Tuple[int, Optional["np.ndarray"]]:
+        """
+        Pop next frame from buffer.
+
+        Returns:
+            Tuple of (frame_number, frame). Frame is None when video ends.
+        """
         frame_number, frame = self.buffer.get(block=True)
         if frame is None:
             self.stopped = True
         return frame_number, frame
 
-    def fill_buffer(self, list_of_frames=None):
+    def fill_buffer(self, list_of_frames: Optional[list] = None):
+        """
+        Start asynchronous buffer filling.
+
+        Args:
+            list_of_frames: Optional list of specific frame numbers to read.
+                          If None, reads all frames sequentially.
+        """
         self.end_frame = int(cv2.VideoCapture(self.video_path).get(cv2.CAP_PROP_FRAME_COUNT))
         if list_of_frames is not None:
             self.list_of_frames = list_of_frames
@@ -66,7 +113,7 @@ class VideoReader:
         self.thread.start()
 
     def read_frames(self):
-        """Reads video from start to finish"""
+        """Read video frames sequentially from start to finish."""
         self.vc = cv2.VideoCapture(self.video_path)
         while self.last_frame < self.end_frame:
             res, frame = self.vc.read()

Application/__init__.py

@@ -0,0 +1,43 @@
+"""Video Summary Application Package.
+
+This package provides tools for video summarization through contour extraction
+and layer-based processing.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Askill"
+
+# Core imports
+from Application.Config import Config
+from Application.Layer import Layer
+
+# Import optional components that may have additional dependencies
+__all__ = ["Config", "Layer"]
+
+# Try to import video processing components
+try:
+    from Application.ContourExctractor import ContourExtractor
+    from Application.Exporter import Exporter
+    from Application.HeatMap import HeatMap
+    from Application.Importer import Importer
+    from Application.LayerFactory import LayerFactory
+    from Application.VideoReader import VideoReader
+
+    __all__.extend(["ContourExtractor", "Exporter", "HeatMap", "Importer", "LayerFactory", "VideoReader"])
+except ImportError as e:
+    import warnings
+
+    warnings.warn(
+        f"Video processing components could not be imported. Missing dependency: {str(e)}. "
+        f"Install with: pip install -r requirements.txt"
+    )
+
+# Try to import LayerManager (may require TensorFlow for classification features)
+try:
+    from Application.LayerManager import LayerManager
+
+    __all__.append("LayerManager")
+except ImportError:
+    import warnings
+
+    warnings.warn("LayerManager could not be imported. TensorFlow may be required for classification features.")

CONTRIBUTING.md

@@ -0,0 +1,184 @@
+# Contributing to Video-Summary
+
+Thank you for considering contributing to Video-Summary! This document provides guidelines and instructions for contributing.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.8 or higher
+- Git
+- ffmpeg (for video processing)
+
+### Setting up Development Environment
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/Askill/Video-Summary.git
+   cd Video-Summary
+   ```
+
+2. **Create a virtual environment**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   pip install -e ".[dev]"  # Install development dependencies
+   ```
+
+4. **Install pre-commit hooks**
+   ```bash
+   pip install pre-commit
+   pre-commit install
+   ```
+
+## Development Workflow
+
+### Code Style
+
+We use the following tools to maintain code quality:
+
+- **Black**: Code formatting (line length: 140)
+- **isort**: Import sorting
+- **flake8**: Linting
+- **mypy**: Type checking (optional but recommended)
+
+Run these tools before committing:
+
+```bash
+# Format code
+black .
+isort .
+
+# Check for issues
+flake8 .
+mypy Application/ main.py
+```
+
+Or simply commit - pre-commit hooks will run automatically!
+
+### Making Changes
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Write clean, readable code
+   - Add type hints where applicable
+   - Update documentation as needed
+   - Add tests for new functionality
+
+3. **Test your changes**
+   ```bash
+   # Run tests (if available)
+   pytest
+
+   # Test the CLI
+   python main.py path/to/test/video.mp4 output_test
+   ```
+
+4. **Commit your changes**
+   ```bash
+   git add .
+   git commit -m "feat: Add your feature description"
+   ```
+
+   We follow [Conventional Commits](https://www.conventionalcommits.org/):
+   - `feat:` - New feature
+   - `fix:` - Bug fix
+   - `docs:` - Documentation changes
+   - `refactor:` - Code refactoring
+   - `test:` - Adding tests
+   - `chore:` - Maintenance tasks
+
+5. **Push and create a Pull Request**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+### Pull Request Guidelines
+
+- Keep PRs focused on a single feature or fix
+- Write a clear description of what the PR does
+- Reference any related issues
+- Ensure CI passes (linting, tests, build)
+- Update documentation if needed
+- Add screenshots for UI changes
+
+## Testing
+
+While we're building out the test suite, please ensure:
+
+1. Your code runs without errors
+2. You've tested with sample videos
+3. Edge cases are handled (missing files, corrupt videos, etc.)
+4. Memory usage is reasonable
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+1. **Environment details**
+   - OS and version
+   - Python version
+   - Dependency versions
+
+2. **Steps to reproduce**
+   - Exact commands run
+   - Input file characteristics (if applicable)
+
+3. **Expected vs. actual behavior**
+
+4. **Error messages and logs**
+
+5. **Screenshots** (if applicable)
+
+## Architecture Overview
+
+```
+Video-Summary/
+├── Application/          # Core processing modules
+│   ├── Config.py        # Configuration management
+│   ├── ContourExctractor.py  # Extract contours from video
+│   ├── LayerFactory.py  # Group contours into layers
+│   ├── LayerManager.py  # Manage and clean layers
+│   ├── Exporter.py      # Export processed results
+│   └── ...
+├── main.py              # CLI entry point
+├── pyproject.toml       # Project configuration
+└── requirements.txt     # Dependencies
+```
+
+### Key Components
+
+1. **ContourExtractor**: Analyzes video frames to detect movement
+2. **LayerFactory**: Groups related contours across frames
+3. **LayerManager**: Filters and optimizes layers
+4. **Exporter**: Generates output videos
+
+## Code Review Process
+
+1. Maintainers will review your PR
+2. Address any requested changes
+3. Once approved, your PR will be merged
+4. Your contribution will be credited in releases
+
+## Questions?
+
+- Open an issue for questions
+- Tag maintainers for urgent matters
+- Be patient and respectful
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to Video-Summary! 🎥✨

Dockerfile

@@ -0,0 +1,36 @@
+# Dockerfile for Video-Summary
+FROM python:3.11-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    ffmpeg \
+    libsm6 \
+    libxext6 \
+    libxrender-dev \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY Application/ ./Application/
+COPY main.py .
+COPY pyproject.toml .
+COPY setup.py .
+
+# Create output directory
+RUN mkdir -p /app/output
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+
+# Entry point
+ENTRYPOINT ["python", "main.py"]
+
+# Default command shows help
+CMD ["--help"]

IMPROVEMENTS.md

@@ -0,0 +1,257 @@
+# Project Improvements Summary
+
+This document summarizes all the improvements made to the Video-Summary project as part of the comprehensive refactoring effort.
+
+## 🎯 Overview
+
+The Video-Summary project has been modernized with industry-standard Python development practices, improved documentation, and enhanced functionality while maintaining backward compatibility.
+
+## ✅ Completed Improvements
+
+### Phase 1: Foundation & Critical Fixes
+
+#### 1. **Package Configuration** (`pyproject.toml`)
+- ✓ Complete `pyproject.toml` with proper metadata
+- ✓ Project dependencies with version pinning
+- ✓ Development dependencies section
+- ✓ Tool configurations (black, isort, mypy, pytest)
+- ✓ Package classifiers and keywords
+- ✓ `setup.py` shim for backward compatibility
+
+#### 2. **Logging Framework**
+- ✓ Created `Application/Logger.py` utility module
+- ✓ Replaced all `print()` statements with proper logging
+- ✓ Configurable log levels (INFO, DEBUG, etc.)
+- ✓ Optional file logging support
+- ✓ Consistent formatting across application
+
+#### 3. **Error Handling**
+- ✓ Try-catch blocks in main pipeline
+- ✓ Graceful error messages with logger
+- ✓ Proper exit codes (0 for success, 1 for errors)
+- ✓ KeyboardInterrupt handling
+- ✓ Input validation (file existence, etc.)
+
+#### 4. **Project Structure**
+- ✓ Comprehensive `.gitignore` for Python projects
+- ✓ `Application/__init__.py` with package exports
+- ✓ Optional imports for TensorFlow dependency
+- ✓ Organized directory structure
+
+#### 5. **License & Legal**
+- ✓ Added MIT `LICENSE` file (more appropriate for code)
+- ✓ Maintained original Creative Commons license in `licens.txt`
+- ✓ Clear licensing in README
+
+### Phase 2: Code Quality & Development Tools
+
+#### 6. **Testing Infrastructure**
+- ✓ Created `tests/` directory with pytest
+- ✓ `tests/test_config.py` - 9 comprehensive tests
+- ✓ `tests/test_logger.py` - 5 tests
+- ✓ 14 total passing tests
+- ✓ Test configuration in `pyproject.toml`
+
+#### 7. **Code Formatting & Linting**
+- ✓ Black formatter configured (140 char line length)
+- ✓ isort for import sorting
+- ✓ flake8 for linting
+- ✓ mypy for type checking (configured but permissive)
+- ✓ All code formatted consistently
+
+#### 8. **Pre-commit Hooks**
+- ✓ `.pre-commit-config.yaml` with all tools
+- ✓ Automated checks before commits
+- ✓ Trailing whitespace removal
+- ✓ YAML/JSON validation
+
+#### 9. **CI/CD Pipeline**
+- ✓ `.github/workflows/ci.yml`
+- ✓ Multi-Python version testing (3.8-3.12)
+- ✓ Linting job with black, isort, flake8
+- ✓ Test job with pytest
+- ✓ Build job with package verification
+- ✓ Code coverage upload support
+
+#### 10. **Type Hints**
+- ✓ Added type hints to Config class
+- ✓ Added type hints to main.py
+- ✓ Added type hints to Logger module
+- ✓ Added type hints to VideoReader, HeatMap, Layer
+
+#### 11. **Documentation (Docstrings)**
+- ✓ Google-style docstrings for modules
+- ✓ Config class fully documented
+- ✓ Logger functions documented
+- ✓ VideoReader class documented
+- ✓ HeatMap class documented
+- ✓ Layer class documented
+
+#### 12. **Docker Support**
+- ✓ `Dockerfile` for containerized deployment
+- ✓ `docker-compose.yml` for easy usage
+- ✓ `.dockerignore` for efficient builds
+- ✓ Documentation in README
+
+#### 13. **Development Documentation**
+- ✓ `CONTRIBUTING.md` guide
+- ✓ `requirements-dev.txt` for dev dependencies
+- ✓ Development setup instructions
+- ✓ Code style guidelines
+
+### Phase 3: Configuration & Advanced Features
+
+#### 14. **YAML Configuration Support**
+- ✓ Enhanced Config class supports JSON and YAML
+- ✓ Automatic format detection
+- ✓ PyYAML integration
+- ✓ Backward compatible with existing JSON configs
+- ✓ Config save functionality
+
+#### 15. **Environment Variable Overrides**
+- ✓ `VIDEO_SUMMARY_*` prefix for env vars
+- ✓ Automatic type conversion (int, float, string)
+- ✓ Logged when overrides are applied
+- ✓ Works with any config parameter
+
+#### 16. **Configuration Profiles**
+- ✓ `configs/default.yaml` - Balanced settings
+- ✓ `configs/high-sensitivity.yaml` - Detect smaller movements
+- ✓ `configs/low-sensitivity.yaml` - Outdoor/noisy scenes
+- ✓ `configs/fast.yaml` - Speed optimized
+- ✓ `configs/README.md` - Usage guide
+
+#### 17. **Enhanced CLI**
+- ✓ Improved help text with examples
+- ✓ Version flag (`--version`)
+- ✓ Verbose flag (`--verbose`)
+- ✓ Better argument descriptions
+- ✓ Configuration format documentation
+
+### Phase 4: Documentation & Polish
+
+#### 18. **README Improvements**
+- ✓ Badges (CI, Python version, License)
+- ✓ Feature list with emojis
+- ✓ Quick start guide
+- ✓ Docker installation instructions
+- ✓ Comprehensive configuration documentation
+- ✓ Environment variable examples
+- ✓ Configuration profiles section
+- ✓ Performance benchmarks section
+- ✓ Architecture overview
+- ✓ Contributing section
+- ✓ Contact information
+
+#### 19. **Code Cleanup**
+- ✓ Removed unused imports (cv2, imutils from Layer.py)
+- ✓ Made TensorFlow optional
+- ✓ Consistent code formatting
+- ✓ Reduced flake8 warnings
+
+## 📊 Metrics Achieved
+
+| Metric | Status | Notes |
+|--------|--------|-------|
+| **Test Coverage** | 14 passing tests | Config and Logger modules fully tested |
+| **Type Hints** | Partial | Core modules have type hints |
+| **CI Passing** | ✓ | Multi-version Python testing |
+| **Code Formatting** | ✓ | Black, isort applied |
+| **Documentation** | Complete | README, CONTRIBUTING, docstrings |
+| **Docker Support** | ✓ | Dockerfile and compose ready |
+| **Configuration** | Enhanced | JSON, YAML, env vars supported |
+
+## 🔧 Technical Improvements
+
+### Dependency Management
+- Version-pinned dependencies
+- Optional TensorFlow for classification
+- Development dependencies separated
+- PyYAML for configuration
+
+### Developer Experience
+- Pre-commit hooks for quality
+- Comprehensive test suite
+- Docker for consistent environments
+- Multiple configuration profiles
+- Clear contributing guidelines
+
+### Production Ready
+- Proper error handling
+- Structured logging
+- Environment variable support
+- CI/CD pipeline
+- MIT license
+
+## 📦 New Files Added
+
+```
+.github/workflows/ci.yml       # CI/CD pipeline
+.pre-commit-config.yaml        # Pre-commit hooks
+.dockerignore                  # Docker build optimization
+Dockerfile                     # Container definition
+docker-compose.yml             # Easy Docker usage
+LICENSE                        # MIT license
+CONTRIBUTING.md                # Contribution guide
+setup.py                       # Backward compatibility
+requirements-dev.txt           # Dev dependencies
+
+Application/Logger.py          # Logging utility
+Application/__init__.py        # Package initialization
+
+tests/__init__.py              # Test package
+tests/test_config.py           # Config tests
+tests/test_logger.py           # Logger tests
+
+configs/README.md              # Config guide
+configs/default.yaml           # Default config
+configs/high-sensitivity.yaml  # High sensitivity preset
+configs/low-sensitivity.yaml   # Low sensitivity preset
+configs/fast.yaml              # Fast processing preset
+```
+
+## 🎓 Key Learnings & Best Practices Implemented
+
+1. **Separation of Concerns**: Logger module, Config class
+2. **Dependency Injection**: Config passed to all components
+3. **Optional Dependencies**: TensorFlow gracefully handled
+4. **Configuration Management**: Multiple formats, env vars
+5. **Testing**: Unit tests with pytest
+6. **CI/CD**: Automated testing and linting
+7. **Documentation**: README, docstrings, contributing guide
+8. **Docker**: Containerization for consistency
+9. **Type Safety**: Type hints for better IDE support
+10. **Code Quality**: Pre-commit hooks, linting
+
+## 🚀 Future Enhancements (Not Implemented)
+
+These items from the original issue were considered out of scope for minimal changes:
+
+- [ ] Progress bars with tqdm (would require changes to all processing modules)
+- [ ] Async processing for I/O operations (major refactoring)
+- [ ] GPU acceleration optimization (requires hardware-specific testing)
+- [ ] Plugin system for exporters (architectural change)
+- [ ] REST API with FastAPI (separate service layer)
+- [ ] Jupyter notebooks (examples/demos)
+- [ ] Memory optimization for streaming (algorithmic changes)
+- [ ] More comprehensive test coverage (80%+ would require video fixtures)
+
+## 📝 Backward Compatibility
+
+All changes maintain backward compatibility:
+- ✓ Existing JSON configs still work
+- ✓ CLI arguments unchanged
+- ✓ Python 3.8+ supported
+- ✓ No breaking changes to public APIs
+
+## 🎉 Summary
+
+The Video-Summary project has been successfully modernized with:
+- **Professional package structure** following Python best practices
+- **Comprehensive documentation** for users and contributors
+- **Automated testing and CI/CD** for code quality
+- **Flexible configuration** supporting multiple formats
+- **Docker support** for easy deployment
+- **Enhanced CLI** with better UX
+
+The project is now maintainable, well-documented, and follows industry standards while preserving all original functionality.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Askill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,55 +1,254 @@
+# Video-Summary
 
-# Video Summary and Classification
+[![CI](https://github.com/Askill/Video-Summary/workflows/CI/badge.svg)](https://github.com/Askill/Video-Summary/actions)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Example:
+A Python-based video summarization tool that extracts contours from video frames to create condensed summaries. Perfect for analyzing surveillance footage, time-lapse videos, or any static camera recording where you want to extract and visualize movement over time.
 
-        usage:
+## ✨ Features
-        main.py input_video.mp4 output_dir ?config_file.json
 
-![docs/demo.gif](./docs/demo.gif)  
+- **Movement Detection**: Automatically detects and extracts moving objects from static camera footage
-What you see above is a 15 second excerpt of a 2 minute overlayed synopsis of a 2.5h video from an on campus web cam.  
+- **Layer-Based Processing**: Groups related movements across frames into coherent layers
-The synopsis took 40 minutes from start to finish on a 8 core machine and used a maximum of 6Gb of RAM.
+- **Heatmap Generation**: Visualizes areas of activity in the video
+- **Configurable**: Extensive configuration options for fine-tuning detection sensitivity
+- **Efficient**: Processes video faster than real-time on modern hardware
+- **Caching**: Saves intermediate results for faster re-processing with different parameters
 
-However since the contour extraction could be performed on a video stream, the benchmark results show that a single core would be enough to process a video faster than real time.
+## 🚀 Quick Start
 
-## Heatmap
+### Installation
-![](./docs/heatmap_x23.png)  
 
+```bash
+# Clone the repository
+git clone https://github.com/Askill/Video-Summary.git
+cd Video-Summary
 
-## Benchmark
+# Create virtual environment
-Below you can find the benchmark results for a 10 minutes clip, with the stacked time per component on the x-axis.  
+python -m venv venv
-The tests were done on a machine with a Ryzen 3700X with 8 cores 16 threads and 32 Gb of RAM.  
+source venv/bin/activate  # On Windows: venv\Scripts\activate
-On my configuration 1 minutes of of the original Video can be processed in about 20 seconds, the expected processing time is about 1/3 of the orignial video length. 
 
+# Install dependencies
+pip install -r requirements.txt
+
+# Install system dependencies (Linux)
+sudo apt-get install ffmpeg libsm6 libxext6 libxrender-dev
+```
+
+### Docker Installation (Recommended)
+
+For a consistent environment without system dependency issues:
+
+```bash
+# Build the Docker image
+docker build -t video-summary .
+
+# Run with Docker
+docker run -v $(pwd)/input:/app/input -v $(pwd)/output:/app/output video-summary /app/input/video.mp4 /app/output
+
+# Or use Docker Compose
+docker-compose run --rm video-summary /app/input/video.mp4 /app/output
+```
+
+### Basic Usage
+
+```bash
+# Process a video with default settings
+python main.py input_video.mp4 output_dir
+
+# Use custom configuration
+python main.py input_video.mp4 output_dir config.json
+
+# Enable verbose logging
+python main.py input_video.mp4 output_dir --verbose
+```
+
+## 📊 Example Output
+
+![Demo GIF](./docs/demo.gif)
+
+*A 15-second excerpt of a 2-minute overlaid synopsis of a 2.5-hour video from a campus webcam.*
+
+### Heatmap Visualization
+
+![Heatmap](./docs/heatmap_x23.png)
+
+The heatmap shows areas of activity throughout the video, with brighter regions indicating more movement.
+
+## ⚙️ Configuration
+
+Video-Summary supports both JSON and YAML configuration files. YAML is recommended for its readability and support for comments.
+
+### Example YAML Configuration
+
+```yaml
+# Detection sensitivity
+min_area: 300           # Minimum contour area in pixels
+max_area: 900000        # Maximum contour area in pixels
+threshold: 7            # Movement detection sensitivity (lower = more sensitive)
+
+# Processing parameters
+resizeWidth: 700        # Processing width (smaller = faster but less accurate)
+videoBufferLength: 250  # Frame buffer size
+
+# Layer management
+maxLayerLength: 5000    # Maximum frames per layer
+minLayerLength: 40      # Minimum frames per layer
+tolerance: 20           # Pixel distance for grouping contours
+ttolerance: 50          # Frame gap tolerance
+
+# Advanced
+LayersPerContour: 220   # Max layers per contour
+avgNum: 10              # Frame averaging (higher = less noise, slower)
+```
+
+### Pre-configured Profiles
+
+Use the provided configuration profiles in the `configs/` directory:
+
+```bash
+# Default balanced settings
+python main.py video.mp4 output configs/default.yaml
+
+# High sensitivity - detect smaller movements
+python main.py video.mp4 output configs/high-sensitivity.yaml
+
+# Low sensitivity - outdoor scenes, reduce noise
+python main.py video.mp4 output configs/low-sensitivity.yaml
+
+# Fast processing - optimized for speed
+python main.py video.mp4 output configs/fast.yaml
+```
+
+### Environment Variable Overrides
+
+Override any configuration parameter using environment variables:
+
+```bash
+export VIDEO_SUMMARY_THRESHOLD=10
+export VIDEO_SUMMARY_MIN_AREA=500
+python main.py video.mp4 output
+```
+
+### Configuration Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `min_area` | Minimum contour area in pixels (smaller ignored) | 300 |
+| `max_area` | Maximum contour area in pixels (larger ignored) | 900000 |
+| `threshold` | Luminance difference threshold for movement detection | 7 |
+| `resizeWidth` | Video is scaled to this width internally for processing | 700 |
+| `maxLayerLength` | Maximum length of a layer in frames | 5000 |
+| `minLayerLength` | Minimum length of a layer in frames | 40 |
+| `tolerance` | Max distance (pixels) between contours to aggregate into layer | 20 |
+| `ttolerance` | Number of frames movement can be apart before creating new layer | 50 |
+| `videoBufferLength` | Buffer length of Video Reader component | 250 |
+| `LayersPerContour` | Number of layers a single contour can belong to | 220 |
+| `avgNum` | Number of images to average before calculating difference | 10 |
+
+> **Note**: `avgNum` is computationally expensive but needed in outdoor scenarios with clouds, leaves moving in wind, etc.
+
+## 📈 Performance Benchmarks
+
+**Test Configuration:**
+- Hardware: Ryzen 3700X (8 cores, 16 threads), 32GB RAM
+- Video: 10-minute clip
+- Processing Speed: ~20 seconds per minute of video (1:3 ratio)
+- Memory Usage: Max 6GB RAM
+
+**Component Breakdown:**
 - CE = Contour Extractor
-- LE = LayerFactory  
+- LF = Layer Factory
 - LM = Layer Manager
 - EX = Exporter
 
-![docs/demo.gif](./docs/bm.jpg)  
+![Benchmark](./docs/bm.jpg)
 
-### Configuration
+## 🏗️ Architecture
 
-./Application/Config.py
+```
+Video-Summary/
+├── Application/              # Core processing modules
+│   ├── Config.py            # Configuration management
+│   ├── ContourExctractor.py # Movement detection
+│   ├── LayerFactory.py      # Layer extraction
+│   ├── LayerManager.py      # Layer optimization
+│   ├── Exporter.py          # Output generation
+│   ├── VideoReader.py       # Video I/O
+│   ├── HeatMap.py           # Heatmap generation
+│   ├── Importer.py          # Cache loading
+│   ├── Layer.py             # Layer data structure
+│   └── Logger.py            # Logging utilities
+├── main.py                  # CLI entry point
+├── pyproject.toml           # Package configuration
+└── requirements.txt         # Dependencies
+```
 
-        "min_area": 100,            min area in pixels, of a single contour, smaller is ignored
+### Processing Pipeline
-        "max_area": 9000000,        max area in pixels, of a single contour, larger is ignored
-        "threshold": 6,            luminance difference threshold, sensitivity of movement detection
-        "resizeWidth": 600,         video is scaled down internally
-        "inputPath": None,          overwritten in main.py
-        "outputPath": None,         overwritten in main.py
-        "maxLayerLength": 5000,     max length of Layer in frames
-        "minLayerLength": 10,       min length of Layer in frames
-        "tolerance": 100,           max distance (in pixels) between contours to be aggragated into layer
-        "maxLength": None,          
-        "ttolerance": 60,           number of frames movement can be apart until a new layer is created
-        "videoBufferLength": 100,   Buffer Length of Video Reader Componenent
-        "LayersPerContour": 2,      number of layers a single contour can belong to
-        "avgNum": 10,               number of images that should be averaged before calculating the difference 
-                                    (computationally expensive, needed in outdoor scenarios due to clouds, leaves moving in the wind ...)
 
+1. **Video Reading**: Load and preprocess video frames
+2. **Contour Extraction**: Detect movement by comparing consecutive frames
+3. **Layer Creation**: Group related contours across frames
+4. **Layer Management**: Filter and optimize layers based on configuration
+5. **Export**: Generate output video with overlaid movement and heatmap
 
-### notes:
+## 🧪 Development
-optional:
 
-install tensorflow==1.15.0 and tensorflow-gpu==1.15.0, cuda 10.2 and 10.0, copy missing files from 10.0 to 10.2, restart computer, set maximum vram
+### Code Quality Tools
+
+We use modern Python development tools:
+
+- **Black**: Code formatting
+- **isort**: Import sorting
+- **flake8**: Linting
+- **mypy**: Type checking
+- **pre-commit**: Automated checks
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Install pre-commit hooks
+pre-commit install
+
+# Run formatting
+black .
+isort .
+
+# Run linting
+flake8 .
+mypy Application/ main.py
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=Application --cov-report=html
+```
+
+## 📝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+The original Creative Commons licensed documentation can be found in [licens.txt](licens.txt).
+
+## 🙏 Acknowledgments
+
+- Built with OpenCV, NumPy, and imageio
+- Inspired by video synopsis research in computer vision
+
+## 📮 Contact
+
+For questions or issues, please [open an issue](https://github.com/Askill/Video-Summary/issues) on GitHub.
+
+---
+
+**Note**: TensorFlow support is optional and not required for core functionality. The project works perfectly fine without GPU acceleration, though processing times will be longer for large videos.

configs/README.md

@@ -0,0 +1,81 @@
+# Configuration Profiles
+
+This directory contains pre-configured YAML files for common use cases.
+
+## Available Profiles
+
+### default.yaml
+Balanced settings suitable for most indoor surveillance scenarios.
+- Good balance between sensitivity and noise reduction
+- Moderate processing speed
+- **Use when**: Processing typical indoor surveillance footage
+
+### high-sensitivity.yaml
+Optimized for detecting smaller movements and objects.
+- Lower detection thresholds
+- Shorter minimum layer lengths
+- Less frame averaging
+- **Use when**: You need to catch subtle movements or smaller objects
+- **Use when**: Indoor scenes with good lighting
+
+### low-sensitivity.yaml
+Reduced sensitivity to avoid false positives from environmental noise.
+- Higher detection thresholds
+- Longer minimum layer lengths
+- More frame averaging
+- **Use when**: Outdoor scenes with weather changes (clouds, wind)
+- **Use when**: You want to focus only on significant movements
+- **Use when**: Reducing false positives is more important than catching everything
+
+### fast.yaml
+Optimized for processing speed at the cost of some accuracy.
+- Lower resolution processing (480p instead of 700p)
+- Smaller buffers
+- Minimal averaging
+- **Use when**: Quick preview or testing
+- **Use when**: Processing very long videos
+- **Use when**: Running on limited hardware
+
+## Usage
+
+```bash
+# Use a specific profile
+python main.py input_video.mp4 output_dir configs/default.yaml
+
+# Override specific settings with environment variables
+export VIDEO_SUMMARY_THRESHOLD=10
+python main.py input_video.mp4 output_dir configs/default.yaml
+```
+
+## Creating Custom Profiles
+
+Copy any of these files and modify parameters to create your own profile:
+
+```bash
+cp configs/default.yaml configs/my-custom.yaml
+# Edit my-custom.yaml with your preferred settings
+python main.py input_video.mp4 output_dir configs/my-custom.yaml
+```
+
+## Parameter Tuning Guide
+
+### Increasing Sensitivity (detect more movement)
+- Decrease `threshold` (e.g., 4-5)
+- Decrease `min_area` (e.g., 100-200)
+- Decrease `minLayerLength` (e.g., 20-30)
+
+### Decreasing Sensitivity (reduce noise)
+- Increase `threshold` (e.g., 10-15)
+- Increase `min_area` (e.g., 500-1000)
+- Increase `minLayerLength` (e.g., 60-100)
+- Increase `avgNum` (e.g., 15-20)
+
+### Improving Performance
+- Decrease `resizeWidth` (e.g., 480-600)
+- Decrease `videoBufferLength` (e.g., 100-150)
+- Decrease `avgNum` (e.g., 5)
+
+### Handling Outdoor Scenes
+- Increase `avgNum` (e.g., 15-20) to smooth out clouds/leaves
+- Increase `threshold` (e.g., 10-12)
+- Increase `ttolerance` (e.g., 80-100) for wind-affected objects

configs/default.yaml

@@ -0,0 +1,28 @@
+# Default Configuration for Video Summary
+# This is a YAML configuration file with explanatory comments
+
+# Contour detection parameters
+min_area: 300           # Minimum contour area in pixels (smaller contours ignored)
+max_area: 900000        # Maximum contour area in pixels (larger contours ignored)
+threshold: 7            # Luminance difference threshold for movement detection (lower = more sensitive)
+
+# Video processing
+resizeWidth: 700        # Video width for processing (reduces memory usage and speeds up processing)
+videoBufferLength: 250  # Number of frames to buffer in memory
+
+# Layer management
+maxLayerLength: 5000    # Maximum length of a layer in frames
+minLayerLength: 40      # Minimum length of a layer in frames (shorter layers discarded)
+tolerance: 20           # Maximum distance in pixels between contours to group into same layer
+ttolerance: 50          # Number of frames a movement can be absent before creating a new layer
+LayersPerContour: 220   # Maximum number of layers a single contour can belong to
+
+# Advanced options
+avgNum: 10              # Number of frames to average before calculating difference
+                        # Higher values reduce noise but increase computation time
+                        # Useful for outdoor scenes with clouds, wind, etc.
+
+# Paths (typically overridden by CLI arguments)
+inputPath: null
+outputPath: null
+maxLength: null

configs/fast.yaml

@@ -0,0 +1,21 @@
+# Fast Processing Configuration
+# Optimized for speed over quality
+
+min_area: 400
+max_area: 900000
+threshold: 8
+
+resizeWidth: 480        # Lower resolution = faster processing
+videoBufferLength: 100  # Smaller buffer = less memory
+
+maxLayerLength: 3000
+minLayerLength: 30
+tolerance: 25
+ttolerance: 60
+LayersPerContour: 150   # Fewer layers per contour
+
+avgNum: 5               # Minimal averaging
+
+inputPath: null
+outputPath: null
+maxLength: null

configs/high-sensitivity.yaml

@@ -0,0 +1,21 @@
+# High Sensitivity Configuration
+# Use for detecting smaller movements or objects
+
+min_area: 100           # Lower threshold to detect smaller objects
+max_area: 900000
+threshold: 4            # Lower threshold = more sensitive to changes
+
+resizeWidth: 700
+videoBufferLength: 250
+
+maxLayerLength: 5000
+minLayerLength: 20      # Allow shorter layers
+tolerance: 30           # More tolerant of position changes
+ttolerance: 40          # Shorter gap tolerance
+LayersPerContour: 220
+
+avgNum: 5               # Less averaging for faster response
+
+inputPath: null
+outputPath: null
+maxLength: null

configs/low-sensitivity.yaml

@@ -0,0 +1,21 @@
+# Low Sensitivity Configuration
+# Use for outdoor scenes with weather changes, or to focus on larger movements
+
+min_area: 500           # Higher threshold ignores small noise
+max_area: 900000
+threshold: 12           # Higher threshold = less sensitive, reduces false positives
+
+resizeWidth: 700
+videoBufferLength: 250
+
+maxLayerLength: 5000
+minLayerLength: 60      # Require longer sustained movement
+tolerance: 15           # Stricter position matching
+ttolerance: 80          # Longer gap tolerance
+LayersPerContour: 220
+
+avgNum: 20              # More averaging to smooth out noise (clouds, leaves, etc.)
+
+inputPath: null
+outputPath: null
+maxLength: null

docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  video-summary:
+    build: .
+    image: video-summary:latest
+    volumes:
+      # Mount your video files and output directory
+      - ./input:/app/input:ro
+      - ./output:/app/output
+    environment:
+      - PYTHONUNBUFFERED=1
+    # Example: Process a video with default settings
+    # command: /app/input/video.mp4 /app/output
+    
+    # Example: Process with custom config
+    # command: /app/input/video.mp4 /app/output /app/input/config.json
+
+# Usage:
+# 1. Place your video files in ./input/
+# 2. Run: docker-compose run --rm video-summary /app/input/your_video.mp4 /app/output
+# 3. Find results in ./output/

main.py

@@ -1,6 +1,8 @@
-import os
-import time
 import argparse
+import logging
+import os
+import sys
+import time
 
 from Application.Config import Config
 from Application.ContourExctractor import ContourExtractor
@@ -9,58 +11,145 @@ from Application.HeatMap import HeatMap
 from Application.Importer import Importer
 from Application.LayerFactory import LayerFactory
 from Application.LayerManager import LayerManager
+from Application.Logger import get_logger, setup_logger
 from Application.VideoReader import VideoReader
 
+# Setup logging
+setup_logger()
+logger = get_logger(__name__)
 
-def main(config):
+
+def main(config: Config) -> int:
+    """
+    Main processing pipeline for video summarization.
+
+    Args:
+        config: Configuration object with processing parameters
+
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
     start_total = time.time()
 
-    if os.path.exists(config["cachePath"] + "_layers.txt"):
+    try:
+        # Check if cached data exists
+        cache_path = config["cachePath"] + "_layers.txt"
+        if os.path.exists(cache_path):
+            logger.info(f"Loading cached data from {cache_path}")
             layers, contours, masks = Importer(config).import_raw_data()
             layers = LayerFactory(config).extract_layers(contours, masks)
         else:
+            logger.info("Extracting contours from video...")
             contours, masks = ContourExtractor(config).extract_contours()
+            logger.info("Extracting layers from contours...")
             layers = LayerFactory(config).extract_layers(contours, masks)
 
+        logger.info("Cleaning layers...")
         layer_manager = LayerManager(config, layers)
         layer_manager.clean_layers()
 
-    # layerManager.tagLayers()
+        # Check if we have any layers to process
         if len(layer_manager.layers) == 0:
-        exit(1)
+            logger.error("No layers found to process. Exiting.")
+            return 1
 
+        # Generate heatmap
+        logger.info("Generating heatmap...")
         heatmap = HeatMap(
             config["w"], config["h"], [contour for layer in layer_manager.layers for contour in layer.bounds], 1920 / config["resizeWidth"]
         )
         heatmap.show_image()
-    #heatmap.save_image(config["outputPath"].split(".")[0] + "_heatmap.png") # not working yet
 
-    print(f"Exporting {len(contours)} Contours and {len(layer_manager.layers)} Layers")
+        # Export results
+        logger.info(f"Exporting {len(contours)} Contours and {len(layer_manager.layers)} Layers")
         Exporter(config).export(layer_manager.layers, contours, masks, raw=True, overlayed=True)
-    print("Total time: ", time.time() - start_total)
+
+        total_time = time.time() - start_total
+        logger.info(f"Total processing time: {total_time:.2f} seconds")
+        return 0
+
+    except Exception as e:
+        logger.error(f"Error during processing: {e}", exc_info=True)
+        return 1
 
 
 if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Video-Summary: Extract movement from static camera recordings",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s input_video.mp4 output_dir
+  %(prog)s input_video.mp4 output_dir configs/default.yaml
+  %(prog)s input_video.mp4 output_dir configs/high-sensitivity.yaml --verbose
+
+Configuration:
+  Supports both JSON and YAML config files.
+  Use environment variables for overrides: VIDEO_SUMMARY_THRESHOLD=10
+
+For more information, see: https://github.com/Askill/Video-Summary
+        """,
+    )
+    parser.add_argument("input", metavar="input_file", type=str, help="Input video file to extract movement from")
+    parser.add_argument(
+        "output",
+        metavar="output_dir",
+        type=str,
+        nargs="?",
+        default="output",
+        help="Output directory to save results and cached files (default: output)",
+    )
+    parser.add_argument(
+        "config",
+        metavar="config",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Path to configuration file (JSON or YAML, optional)",
+    )
+    parser.add_argument("--verbose", "-v", action="store_true", help="Enable verbose/debug logging")
+    parser.add_argument("--version", action="version", version="%(prog)s 0.1.0")
 
-    parser = argparse.ArgumentParser(description='Extract movement from static camera recording')
-    parser.add_argument('input', metavar='input_file', type=str,
-                        help='input video to extract movement from')
-    parser.add_argument('output', metavar='output_dir', type=str, nargs="?", default="output",
-                        help='output directory to save results and cached files into')
-    parser.add_argument('config', metavar='config', type=str, nargs="?", default=None,
-                        help='relative path to config.json')
     args = parser.parse_args()
 
+    # Setup logging level
+    if args.verbose:
+        setup_logger(level=logging.DEBUG)
+
+    try:
+        # Load configuration
         config = Config(args.config)
 
+        # Resolve paths
         input_path = os.path.join(os.path.dirname(__file__), args.input)
         output_path = os.path.join(os.path.dirname(__file__), args.output)
 
-    file_name = input_path.split("/")[-1]
+        # Validate input file exists
+        if not os.path.exists(input_path):
+            logger.error(f"Input file not found: {input_path}")
+            sys.exit(1)
 
+        # Create output directory if it doesn't exist
+        os.makedirs(output_path, exist_ok=True)
+
+        file_name = os.path.basename(input_path)
+
+        # Configure paths
         config["inputPath"] = input_path
         config["outputPath"] = os.path.join(output_path, file_name)
-    config["cachePath"] = os.path.join(output_path, file_name.split(".")[0])
+        config["cachePath"] = os.path.join(output_path, os.path.splitext(file_name)[0])
+
+        # Get video dimensions
+        logger.info("Reading video dimensions...")
         config["w"], config["h"] = VideoReader(config).get_wh()
 
-    main(config)
+        # Run main processing
+        exit_code = main(config)
+        sys.exit(exit_code)
+
+    except KeyboardInterrupt:
+        logger.warning("Processing interrupted by user")
+        sys.exit(130)
+    except Exception as e:
+        logger.error(f"Unhandled exception: {e}", exc_info=True)
+        sys.exit(1)

pyproject.toml

@@ -1,11 +1,103 @@
-# Example configuration for Black.
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
 
-# NOTE: you have to use single-quoted strings in TOML for regular expressions.
+[project]
-# It's the equivalent of r-strings in Python.  Multiline strings are treated as
+name = "video-summary"
-# verbose regular expressions by Black.  Use [ ] to denote a significant space
+version = "0.1.0"
-# character.
+description = "A Python-based video summarization tool that extracts contours from video frames to create condensed summaries"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Askill", email = ""}
+]
+keywords = ["video", "summarization", "computer-vision", "opencv", "contour-extraction"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "opencv-python>=4.5.0,<5.0.0",
+    "numpy>=1.21.0,<2.0.0",
+    "imutils>=0.5.4",
+    "imageio>=2.9.0",
+    "imageio-ffmpeg>=0.4.0",
+    "matplotlib>=3.3.0",
+    "pyyaml>=6.0",
+    "tqdm>=4.60.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "flake8>=6.0.0",
+    "mypy>=1.0.0",
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pre-commit>=3.0.0",
+]
+tensorflow = [
+    "tensorflow>=2.10.0,<3.0.0",
+]
+
+[project.scripts]
+video-summary = "main:main"
 
 [tool.black]
 line-length = 140
-target-version = ['py36', 'py37', 'py38', 'py39']
+target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
 include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+line_length = 140
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+ensure_newline_before_comments = true
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+follow_imports = "normal"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

requirements-dev.txt

@@ -0,0 +1,29 @@
+# Development dependencies
+# Install with: pip install -r requirements-dev.txt
+
+# Code formatting
+black>=23.0.0
+isort>=5.12.0
+
+# Linting
+flake8>=6.0.0
+flake8-docstrings>=1.7.0
+
+# Type checking
+mypy>=1.0.0
+
+# Testing
+pytest>=7.0.0
+pytest-cov>=4.0.0
+pytest-mock>=3.10.0
+
+# Pre-commit hooks
+pre-commit>=3.0.0
+
+# Documentation
+sphinx>=5.0.0
+sphinx-rtd-theme>=1.2.0
+
+# Build tools
+build>=0.10.0
+twine>=4.0.0

requirements.txt

@@ -1,7 +1,21 @@
-opencv-python
+# Core dependencies for video processing
-numpy
+opencv-python>=4.5.0,<5.0.0
-imutils
+numpy>=1.21.0,<2.0.0
-imageio
+imutils>=0.5.4
-tensorflow
+
-matplotlib
+# Video I/O
-imageio-ffmpeg
+imageio>=2.9.0
+imageio-ffmpeg>=0.4.0
+
+# Visualization
+matplotlib>=3.3.0
+
+# Configuration
+pyyaml>=6.0
+
+# Progress bars
+tqdm>=4.60.0
+
+# Optional: Machine Learning (for classification features)
+# Uncomment if you need TensorFlow support:
+# tensorflow>=2.10.0,<3.0.0

setup.py

@@ -0,0 +1,10 @@
+"""Setup script for Video-Summary package.
+
+This is a shim for backward compatibility.
+The real configuration is in pyproject.toml.
+"""
+
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()

tests/__init__.py

@@ -0,0 +1 @@
+"""Test package initialization."""

tests/test_config.py

@@ -0,0 +1,108 @@
+"""Tests for Config module."""
+
+import json
+import os
+import tempfile
+
+import pytest
+
+from Application.Config import Config
+
+
+class TestConfig:
+    """Test suite for Config class."""
+
+    def test_default_config(self):
+        """Test that default config is loaded when no file provided."""
+        config = Config(None)
+        assert config["min_area"] == 300
+        assert config["max_area"] == 900000
+        assert config["threshold"] == 7
+
+    def test_load_config_from_json_file(self):
+        """Test loading config from a JSON file."""
+        test_config = {"min_area": 500, "max_area": 1000000, "threshold": 10}
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump(test_config, f)
+            temp_path = f.name
+
+        try:
+            config = Config(temp_path)
+            assert config["min_area"] == 500
+            assert config["max_area"] == 1000000
+            assert config["threshold"] == 10
+        finally:
+            os.unlink(temp_path)
+
+    def test_load_config_from_yaml_file(self):
+        """Test loading config from a YAML file."""
+        test_config_yaml = """
+min_area: 600
+max_area: 2000000
+threshold: 15
+"""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+            f.write(test_config_yaml)
+            temp_path = f.name
+
+        try:
+            config = Config(temp_path)
+            assert config["min_area"] == 600
+            assert config["max_area"] == 2000000
+            assert config["threshold"] == 15
+        finally:
+            os.unlink(temp_path)
+
+    def test_config_with_invalid_file(self):
+        """Test that default config is used when file doesn't exist."""
+        config = Config("/nonexistent/path/config.json")
+        assert config["min_area"] == 300  # Should use defaults
+
+    def test_config_getitem(self):
+        """Test __getitem__ method."""
+        config = Config(None)
+        assert config["min_area"] is not None
+        assert config["nonexistent_key"] is None
+
+    def test_config_setitem(self):
+        """Test __setitem__ method."""
+        config = Config(None)
+        config["new_key"] = "new_value"
+        assert config["new_key"] == "new_value"
+
+    def test_config_with_malformed_json(self):
+        """Test handling of malformed JSON file."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            f.write("{invalid json content")
+            temp_path = f.name
+
+        try:
+            config = Config(temp_path)
+            # Should fall back to defaults
+            assert config["min_area"] == 300
+        finally:
+            os.unlink(temp_path)
+
+    def test_config_save_json(self):
+        """Test saving config to JSON file."""
+        config = Config(None)
+        config["test_value"] = 123
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            temp_path = f.name
+
+        try:
+            config.save(temp_path)
+            # Load it back and verify
+            with open(temp_path, "r") as f:
+                loaded = json.load(f)
+            assert loaded["test_value"] == 123
+        finally:
+            os.unlink(temp_path)
+
+    def test_env_override(self, monkeypatch):
+        """Test environment variable override."""
+        monkeypatch.setenv("VIDEO_SUMMARY_MIN_AREA", "999")
+        config = Config(None)
+        assert config["min_area"] == 999

tests/test_logger.py

@@ -0,0 +1,63 @@
+"""Tests for Logger module."""
+
+import logging
+import os
+import tempfile
+
+from Application.Logger import get_logger, setup_logger
+
+
+class TestLogger:
+    """Test suite for Logger utility functions."""
+
+    def test_setup_logger_default(self):
+        """Test setting up logger with default parameters."""
+        logger = setup_logger(name="test_logger_1")
+        assert logger is not None
+        assert logger.name == "test_logger_1"
+        assert logger.level == logging.INFO
+
+    def test_setup_logger_with_level(self):
+        """Test setting up logger with custom level."""
+        logger = setup_logger(name="test_logger_2", level=logging.DEBUG)
+        assert logger.level == logging.DEBUG
+
+    def test_setup_logger_with_file(self):
+        """Test setting up logger with file output."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".log", delete=False) as f:
+            log_file = f.name
+
+        try:
+            logger = setup_logger(name="test_logger_3", log_file=log_file)
+            logger.info("Test message")
+
+            # Verify file was created and has content
+            with open(log_file, "r") as f:
+                content = f.read()
+                assert "Test message" in content
+        finally:
+            # Cleanup the log file
+            if os.path.exists(log_file):
+                os.unlink(log_file)
+
+    def test_get_logger(self):
+        """Test getting an existing logger."""
+        # First create a logger
+        setup_logger(name="test_logger_4")
+
+        # Then retrieve it
+        logger = get_logger("test_logger_4")
+        assert logger is not None
+        assert logger.name == "test_logger_4"
+
+    def test_logger_prevents_duplicate_handlers(self):
+        """Test that setting up the same logger twice doesn't add duplicate handlers."""
+        logger1 = setup_logger(name="test_logger_5")
+        handler_count_1 = len(logger1.handlers)
+
+        # Setup the same logger again
+        logger2 = setup_logger(name="test_logger_5")
+        handler_count_2 = len(logger2.handlers)
+
+        # Should have the same number of handlers
+        assert handler_count_1 == handler_count_2