SWENG25-ObjectPatternRecognizer-GrpA 1.1.0

Objekterkennungsbibliothek für SWENG25

SWENG25_ObjectPatternRecognizer_GrpA

A small Python application that uses a camera livestream to perform real-time object pattern recognition and color detection.
The main purpose of this project is to practice software engineering principles.

From our perspective, this includes:

1. Collaborating as a team on a shared software project using a version control system (Git/GitHub).
2. Writing proper documentation that is clear, structured, and maintainable.
3. Implementing unit tests to ensure code quality and reliability.

---

📦 Installation

You can install the latest version of the package from PyPI using:

pip install SWENG25-ObjectPatternRecognizer-GrpA

To install a specific version (for example, version 0.1.1):

pip install SWENG25-ObjectPatternRecognizer-GrpA==0.1.1

---

🚀 Usage

Once installed, you can interact with the package through the command line interface (CLI):

sweng25-objectpatternrecognizer-grpa

⚠️ Only Windows usage has been tested. Other operating systems may not work as expected.

Available Commands

The following command-line arguments are supported:

--config_path : str, optional
    Path to the JSON configuration file.
    Must be a valid .json file.

--source : {'camera', 'image'}, optional
    Input source type. Determines whether the program processes a live camera feed or a static image.

--image_path : str, optional
    Path to the image file used when --source=image.
    Must be a valid .png, .jpg, or .jpeg file.

--camera_index : int, optional
    Index of the camera device used when --source=camera.
    Typically 0 for the default webcam.

--headless : flag, optional
    If set, the application runs without GUI.

🧑‍💻 Development Process and Community Rules

Our project follows a collaborative, learning-focused development workflow inspired by professional software engineering practices.
The goal is not only to build a functioning system, but also to practice team collaboration, version control, documentation, testing, and CI/CD workflows.

---

👥 Team Responsibilities

Member	Main Responsibilities
Lenard	Configuration management, logging system, and output handling (including text-to-speech and processed image export).
Sascha	Main orchestration logic and core image processing (pattern recognition, color detection).
Fabian	Continuous Integration / Continuous Deployment (CI/CD), graphical user interface (GUI), and project documentation.

Each team member also writes unit tests for their components and contributes to code reviews.

---

🌿 Branching Model

We use a lightweight Git Flow model adapted to our small project size:

Branch	Purpose
main	Stable, production-ready code. Only merged after full review and tests.
development	Integration branch for tested features.
feature_<feature-name>	Development of new features or bug fixes.
doc_<topic>	For documentation updates and diagrams.

Branch Naming Convention

feature_<short-feature-name>
fix_<short-description>
doc_<topic>

Example:

feature_color-detection
fix_camera-stream-lag
doc_architecture-diagram

---

🔄 Pull Request & Review Workflow

Every pull request follows a three-person approval rule:

1. Developer A opens a PR for their feature/fix.
2. Developer B reviews and comments.
3. Developer C performs final approval and merges once CI/CD passes.

Each PR must include:

• Clear title and summary of changes
• Related issue link (if any)
• Unit test results or coverage info
• Updated documentation when applicable

---

🧭 Pull Request Workflow Diagram

flowchart TD
    A[Developer A<br/>creates Feature Branch] --> B[Implements & Commits Code]
    B --> C[Opens Pull Request to development]
    C --> D[Developer B Reviews PR]
    D -->|Request Changes| B
    D -->|Approve| E[Developer C Merges PR]
    E --> F[CI/CD Pipeline Runs Tests]
    F --> G{All Tests Passed?}
    G -->|Yes| H[Merge to main]
    G -->|No| I[Fix Issues and Reopen PR]

    classDef devNode fill:#fef3c7,stroke:#b45309,color:#92400e,font-weight:bold;
    classDef reviewNode fill:#dcfce7,stroke:#15803d,color:#166534,font-weight:bold;
    classDef ciNode fill:#dbeafe,stroke:#1e40af,color:#1e3a8a,font-weight:bold;
    classDef resultNode fill:#fef2f2,stroke:#b91c1c,color:#7f1d1d,font-weight:bold;

    class A,B devNode
    class D,E reviewNode
    class F,G ciNode
    class H,I resultNode

---

🧪 Testing and Quality Rules

• Unit tests for all modules in /tests using pytest.
• Minimum one test per module.

---

🗂️ Repository Structure

SWENG25_ObjectPatternRecognizer_GrpA/
│
├── .github/workflows/          # CI/CD configuration
├── doc/                        # Developer & architecture docs
├── output/                     # default output folder
│
├── sweng25_objectpatternrecognizer_grpa/
│   ├── __init__.py
│   ├── main.py
│   ├── gui/                    # Graphical interface
│   ├── image_processing/       # Pattern & color recognition
│   ├── source_handler/         # Camera & file input handling
│   ├── config_service/         # Configuration loading/saving
│   ├── output_handler/         # Logs, speech, processed images
│   ├── utils/                  # Helper functions
│   └── cli.py                  # CLI entry point
│
├── tests/                      # Unit & integration tests
├── .gitignore
├── pyproject.toml
├── README.md
└── setup.py

🗺️ Architecture

The system is designed following the C4 Model, which provides a structured way to describe software architecture at different levels of abstraction. Given the simplicity of this system, we focus on the Context and Container views. It was just necessary to draw one Component view.

System Overview

The core system, called the Object Pattern Recognizer (OPR), is responsible for processing images from various sources, detecting patterns, and producing processed outputs. The system interacts with multiple external entities, including users, cameras, and image files.

At a high level:

• Users interact with the system through a graphical interface or directly via the main orchestration logic.
• Cameras and Image Files serve as the sources of input data.
• The system processes the data to generate Processed Images or Text to Speach.
• System behavior, configuration, and events are captured in Config Files and Log Files for tracking and reproducibility.

This interaction can be visualized in the following Context Diagram:

flowchart TD
    user([User])
    system[[Object Pattern Recognizer]]
    camera([Camera])
    imageFile([Images])
    configFile([Config File])
    logFile([Log File])
    output([output])

    user --> system
    camera --> system
    imageFile --> system
    system --> logFile
    system --> configFile
    system --> output
    configFile --> system

    classDef userNode fill: #fef3c7,stroke: #b45309,color: #92400e,font-weight:bold;
    classDef inputNode fill: #dcfce7,stroke: #15803d,color: #166534,font-weight:bold;
    classDef systemNode fill: #dbeafe,stroke: #1e40af,color: #1e3a8a,font-size:16px,font-weight:bold;
    classDef outputNode fill: #fef2f2,stroke: #b91c1c,color: #7f1d1d,font-weight:bold;

    class user userNode
    class camera,imageFile inputNode
    class system systemNode
    class logFile,configFile,output outputNode

Internal Structure

Internally, the Object Pattern Recognizer is composed of several components, each with a distinct responsibility:

1. GUI (Graphical User Interface) – Provides a user-friendly interface for interacting with the system, including starting processing tasks and viewing results.
2. Main – Acts as the orchestration layer, coordinating the flow of data between input sources, processing modules, and outputs.
3. image_processing – Handles all image analysis and processing tasks, including pattern recognition and feature extraction.
4. source_handler – Manages data acquisition from cameras and image files, ensuring that inputs are correctly formatted for processing.
5. config_service – Reads and saves configuration settings, allowing the system to operate flexibly across different environments.
6. output_handler – Captures runtime events and system actions for debugging, monitoring, and audit purposes.

The relationships between these components and the user are shown in the Container Diagram below:

flowchart TD
    user([User])
    cam([Camera])
    img([Image])

    subgraph OPR["Object Pattern Recognition"]
        gui([GUI<br/>Handles user interaction])
        main([main<br/>Core orchestration logic])
        imgProc([image_processing<br/>Image processing module])
        sources([source_handler<br/>Handles camera and image input])
        output([output_handler<br>creats log, text to speach and processed images])
        config([config_service<br/>Loads and saves configuration])
    end

    user --> gui
    user --> main
    gui --> main
    main --> sources
    main --> imgProc
    main --> config
    main --> output
    cam --> sources
    img --> sources

    classDef userNode fill: #fef3c7,stroke: #b45309,color: #92400e,font-weight:bold;
    classDef inputNode fill: #dcfce7,stroke: #15803d,color: #166534,font-weight:bold;
    classDef systemNode fill: #dbeafe,stroke: #1e40af,color: #1e3a8a,font-size:16px,font-weight:bold;
    classDef outputNode fill: #fef2f2,stroke: #b91c1c,color: #7f1d1d,font-weight:bold;

    class user userNode
    class sources,img,cam inputNode
    class gui,main,imgProc systemNode
    class config,output outputNode

Output Handler

The output handler shown below contains multiple services, which are shown in the Component Diagram below.

flowchart TD
  main([main])

  %% verry uggly indet, better solutions welcome!
  subgraph OPR["              output_handler"]
        tts([tts_service<br>text to speach])
        log([log_service])
        image([image_service<br>saves processed images])
  end

  main --> image
  main --> tts
  main --> log

  classDef systemNode fill: #dbeafe,stroke: #1e40af,color: #1e3a8a,font-size:16px,font-weight:bold;
  classDef outputNode fill: #fef2f2,stroke: #b91c1c,color: #7f1d1d,font-weight:bold;

  class main systemNode
  class image,tts,log outputNode

Summary

The architecture ensures a clear separation of concerns:

• Input handling is managed by the Sources component.
• Processing is encapsulated in image_processing.
• Orchestration is centralized in Main.
• User interaction is provided by the GUI.
• Configuration and logging are handled by dedicated components, ensuring maintainability and traceability.

This modular structure allows the system to be easily extended or modified, for example by adding new image processing algorithms or supporting additional input sources, without impacting the rest of the architecture.

🧾 Additional Information

For more details, visit the project repository on GitHub:
🔗 SWENG25_ObjectPatternRecognizer_GrpA

Developer-specific documentation and setup guides can be found in the /doc folder.