# ikomia-dev/fisheyemodel architecture

> Architecture diagram of the GitHub repository ikomia-dev/fisheyemodel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ikomia-dev/fisheyemodel
- Repository: https://github.com/ikomia-dev/fisheyemodel

## Overview

##### Project Type and Purpose
- This project is a specialized Python application for calibrating and undistorting images from FishEye cameras using OpenCV.
- Its main functionalities include:
– Calibrating a FishEye camera by detecting distortion using a chessboard pattern.
– Generating a model (a calibration file containing intrinsic/extrinsic parameters).
– Correcting (undistorting) images based on the generated model.
- The README details command-line interfaces for calibration (via calibrate.py) and image correction (via undistort.py).

##### Analyzing the File Structure
- Top-level Files/Scripts:
– calibrate.py: Script to perform camera calibration using a folder of chessboard images.
– undistort.py: Script to undistort a given image based on a calibration file.
– evaluate.py: Likely used to assess the calibration or undistortion results.
- Package Directory “UndistortFishEye”:
– Contains multiple Python files:
▫ UndistortFishEye.py: Potentially a main module for the FishEye-related operations.
▫ UndistortFishEye_process.py: Likely manages the calibration or undistortion processes in a modular, possibly reusable way.
▫ UndistortFishEye_widget.py: Suggests a user interface component, perhaps for interactive calibration or image display.
▫ fisheye_module.py: Contains the core functions or classes supporting the calibration and undistort algorithms.
▫ __init__.py: Indicates that the directory is a Python package.
- Additional Files:
– .idea folder for IDE-specific settings.
– LICENSE and README.md for documentation and legal information.

##### Core Components and Their Roles
- Calibration Component:
– Entrypoint: calibrate.py.
– Function: Processes a set of images (from a folder), extracts calibration data using a chessboard pattern, runs the OpenCV calibration algorithm, and outputs calibration parameters to a file (e.g., calibration.txt).
- Undistortion Component:
– Entrypoint: undistort.py.
– Function: Uses the calibration model (file) and a source image to compute and save the corrected (undistorted) version of the image.
- Evaluation Component:
– Possibly represented by evaluate.py, which may assess the performance or quality of calibration/undistortion.
- Core Module/Library:
– Found in the UndistortFishEye package – this module encapsulates the main calibration and undistortion functionality.
– Submodules like UndistortFishEye_process.py and fisheye_module.py abstract and implement the core algorithms.
- User Interface Component:

##### Relationships and Interactions
- Input and Output Flow:
– The calibration process begins with input images (chessboard or known-pattern images).
– calibrate.py detects features and computes calibration parameters; the output (calibration file) serves as input for subsequent processes.
– undistort.py accepts an image and calibration file, processes it, and outputs an undistorted image.
- Dependency on External Libraries:
– OpenCV: The project leverages OpenCV (version 4.0 or above) for image processing, chessboard detection, calibration computations, and image undistortion.
- Internal Module Interactions:
– The main scripts (calibrate.py, undistort.py, evaluate.py) likely import and utilize functions from the UndistortFishEye package (e.g., fisheye_module.py) for modularity.
– The widget (UndistortFishEye_widget.py) may interface with process routines provided by UndistortFishEye_process.py to manage GUI-triggered events.

##### Architectural Patterns and Design Details
- Modularity: Separation between scripts handling specific user operations (command-line calibration vs. undistortion) and core functions packaged inside UndistortFishEye.
- Command-line Interface (CLI) and potential GUI: The project provides scripts for automation and hints at an interactive UI (widget) for user-friendly operation.
- Clear separation of concerns: Calibration logic, undistortion processing, evaluation, and user interface components are logically separated into different files and submodules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Nodes
    I1["Input: Chessboard Images"]:::data
    I2["Input: Source Image"]:::data
    D1["Calibration Model File"]:::data

    %% External Dependency
    O1["OpenCV (>=4.0)"]:::external

    %% CLI Scripts Subgraph
    subgraph "CLI Scripts"
        C1["Calibration Script (calibrate.py)"]:::cli
        C2["Undistortion Script (undistort.py)"]:::cli
        C3["Evaluation Script (evaluate.py)"]:::cli
    end

    %% Core Library Subgraph
    subgraph "Core Library"
        L1["Core Library Module (UndistortFishEye.py)"]:::core
        L2["Core Process Submodule (UndistortFishEye_process.py)"]:::core
        L3["Core Functionality Module (fisheye_module.py)"]:::core
    end

    %% UI Components Subgraph
    subgraph "UI Components"
        U1["User Interface Component (UndistortFishEye_widget.py)"]:::ui
    end

    %% Data Flow
    I1 -->|"provides"| C1
    C1 -->|"generates"| D1
    D1 -->|"feeds"| C2
    I2 -->|"provides"| C2
    D1 -->|"evaluatedBy"| C3

    %% Internal Module Usage
    C1 -->|"uses"| L1
    C2 -->|"uses"| L1
    C3 -->|"uses"| L1

    L1 -->|"delegatesTo"| L2
    L1 -->|"delegatesTo"| L3

    %% UI Interaction with Core Process
    U1 -->|"triggers"| L2

    %% External Dependency usage
    O1 -->|"provides"| L3

    %% Click Events
    click C1 "https://github.com/ikomia-dev/fisheyemodel/blob/master/calibrate.py"
    click C2 "https://github.com/ikomia-dev/fisheyemodel/blob/master/undistort.py"
    click C3 "https://github.com/ikomia-dev/fisheyemodel/blob/master/evaluate.py"
    click L1 "https://github.com/ikomia-dev/fisheyemodel/blob/master/UndistortFishEye/UndistortFishEye.py"
    click L2 "https://github.com/ikomia-dev/fisheyemodel/blob/master/UndistortFishEye/UndistortFishEye_process.py"
    click L3 "https://github.com/ikomia-dev/fisheyemodel/blob/master/UndistortFishEye/fisheye_module.py"
    click U1 "https://github.com/ikomia-dev/fisheyemodel/blob/master/UndistortFishEye/UndistortFishEye_widget.py"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef ui fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#78281F,stroke-width:2px;
    classDef data fill:#D7BDE2,stroke:#512E5F,stroke-width:2px;
```
