# tcisne/ct2fea architecture

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

- Interactive diagram: https://gitdiagram.com/tcisne/ct2fea
- Repository: https://github.com/tcisne/ct2fea

## Overview

##### Project Type and Purpose
- The CT2FEA project is a specialized conversion pipeline that takes CT image stacks (TIFF format) as input and generates Finite Element Analysis (FEA) models.
- It supports both command-line and GUI modes, and it includes advanced image processing, segmentation, mesh generation, and material assignment—with a focus on performance using GPU acceleration (CUDA/OpenCL).

##### Main Components to Identify
a. User Interface Layer:
- CLI (represented by cli.py, __main__.py, and main.py)
- GUI module within the io/ directory (io/gui.py)
b. Configuration Management:
- config.py and external configuration files (like config.json) that drive processing parameters
c. Image Input and I/O Handling:
- io/file_io.py for loading CT stacks
- Additional visualization in utils/interactive_vis.py and utils/visualization.py
d. Image Processing Pipeline:
- Processing modules in the processing/ folder (ct_processing.py, denoising.py, segmentation.py) that deal with CT image normalization, denoising (using Gaussian, NLM, TV), and segmentation (bone and pore detection).
e. Mesh Generation:
- Modules in meshing/ (fea_writer.py, mesh_quality.py, voxel_mesher.py) that create hexahedral meshes, perform mesh quality analysis, and export to Abaqus INP format.
f. Material Assignment:
- The materials/ directory, subdivided into:
- Linear materials (materials/linear.py)
- Nonlinear models (materials/nonlinear/) including hyperelastic and plasticity models
- GPU-accelerated material calculations via materials/gpu/ (material_mapping.py)
g. Acceleration and Performance:
- The acceleration/ folder contains modules (cuda_kernels.py and opencl_utils.py) for supporting GPU acceleration through CUDA and OpenCL.
h. Utility and Support:
- General-purpose utilities for logging, error handling, parallel processing, profiling, and validation in the utils/ folder.
i. Testing:
- A tests/ directory that verifies the functionality across processing, meshing, and material assignments.

##### Relationships and Data Flow
- Start at the UI layer: the __main__.py or cli.py module receives and validates user input (configuration, file paths, and option flags).
- The configuration (from config.py or JSON files) is then used to set up the processing pipeline.
- Input CT data is loaded via the I/O layer (io/file_io.py) and possibly visualized using utils/interactive_vis.py.
- The loaded CT data flows into the processing modules (processing/ct_processing.py, denoising.py, segmentation.py) where image pre-processing and segmentation operations occur.
- Post-processing data is then passed to the meshing modules (meshing/voxel_mesher.py) which generate FEA meshes and perform quality checks (via mesh_quality.py) with output managed by fea_writer.py.
- In parallel or subsequently, material models are applied using modules in materials/ (linear, nonlinear, and GPU-specific material mapping). GPU acceleration support is chosen based on configuration and implemented using modules in the acceleration/ directory.
- Various utilities (logging, error handling, parallel processing, and profiling) support all stages.
- Finally, outputs are either exported (exporting meshes and quality reports) or rendered for interactive visualization.

##### Architectural Patterns
- The system architecture follows a pipeline structure with clear separation of concerns: each processing stage is encapsulated in its dedicated module.
- The design supports both synchronous CLI-based processing and interactive GUI mode.
- It emphasizes performance through the optional use of GPU acceleration.
- Extensibility is catered for via modular design in materials, processing, and meshing, allowing future extension or swapping of algorithms.

##### Detailed Representation
- Create component rectangles with obvious labels:
- "CLI/GUI Interface" connecting to "Configuration Module"
- "File I/O" connects to "CT Data Loading"
- "Image Processing" (with nodes for denoising and segmentation)
- "Mesh Generation" (with nodes for voxel meshing and quality analysis)
- "Material Assignment" (with subdivisions for linear and nonlinear models, plus GPU-specific processing)
- "GPU Acceleration" (highlighting acceleration modules for CUDA and OpenCL)
- "Utilities" (logging, error handling, parallel, profiling)
- "Test Suite" (as a side component for quality assurance)
- Optionally, indicate configuration paths where components receive runtime parameters (from config.py and JSON configuration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI_Interface["CLI Interface"]:::ui
        GUI_Interface["GUI Interface"]:::ui
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config_Module["Configuration Module"]:::config
    end

    %% I/O and Visualization Layer
    subgraph "I/O & Visualization Layer"
        CT_IO["CT Image I/O"]:::io
        Viz_Utils["Visualization Utilities"]:::io
    end

    %% Image Processing Pipeline
    subgraph "Image Processing Pipeline"
        CT_Processing["CT Image Processing"]:::processing
        Denoising["Denoising"]:::processing
        Segmentation["Segmentation"]:::processing
    end

    %% Mesh Generation Layer
    subgraph "Mesh Generation Layer"
        Voxel_Meshing["Voxel Meshing"]:::meshing
        Mesh_Quality["Mesh Quality Analysis"]:::meshing
        FEA_Writer["FEA Writer"]:::meshing
    end

    %% Material Assignment Layer
    subgraph "Material Assignment Layer"
        Linear_Materials["Linear Materials"]:::material
        Nonlinear_Materials["Nonlinear Materials"]:::material
        GPU_Materials["GPU-Accelerated Materials"]:::material
    end

    %% Acceleration and Performance Layer
    subgraph "Acceleration Layer"
        CUDA_Kernels["CUDA Kernels"]:::acceleration
        OpenCL_Utils["OpenCL Utils"]:::acceleration
    end

    %% Utilities and Support Layer
    subgraph "Utilities & Support"
        Utilities["Utilities & Support"]:::utilities
    end

    %% Testing Suite
    Testing["Testing Suite"]:::testing

    %% Connections & Data Flow
    CLI_Interface -->|"triggers"| Config_Module
    GUI_Interface -->|"triggers"| Config_Module
    Config_Module -->|"loads"| CT_IO
    Config_Module -->|"configures"| Utilities
    CT_IO -->|"provides data"| CT_Processing
    CT_IO -->|"visualized by"| Viz_Utils
    CT_Processing -->|"preprocesses"| Denoising
    Denoising -->|"segments"| Segmentation
    Segmentation -->|"feeds"| Voxel_Meshing
    Voxel_Meshing -->|"checks quality"| Mesh_Quality
    Mesh_Quality -->|"exports data"| FEA_Writer
    FEA_Writer -->|"assigns"| Linear_Materials
    FEA_Writer -->|"assigns"| Nonlinear_Materials
    FEA_Writer -->|"assigns"| GPU_Materials
    CT_Processing -->|"optional GPU"| CUDA_Kernels
    CT_Processing -->|"optional GPU"| OpenCL_Utils
    GPU_Materials -->|"uses"| CUDA_Kernels
    GPU_Materials -->|"uses"| OpenCL_Utils
    Utilities ---|"supports"| CT_Processing
    Utilities ---|"supports"| Voxel_Meshing
    Utilities ---|"supports"| FEA_Writer
    Utilities ---|"supports"| GPU_Materials
    Testing ---|"validates"| CT_Processing
    Testing ---|"validates"| Mesh_Quality
    Testing ---|"validates"| Nonlinear_Materials

    %% Click Events
    click CLI_Interface "https://github.com/tcisne/ct2fea/blob/main/__main__.py"
    click CLI_Interface "https://github.com/tcisne/ct2fea/blob/main/cli.py"
    click CLI_Interface "https://github.com/tcisne/ct2fea/blob/main/main.py"
    click GUI_Interface "https://github.com/tcisne/ct2fea/blob/main/io/gui.py"
    click Config_Module "https://github.com/tcisne/ct2fea/blob/main/config.py"
    click CT_IO "https://github.com/tcisne/ct2fea/blob/main/io/file_io.py"
    click Viz_Utils "https://github.com/tcisne/ct2fea/blob/main/utils/interactive_vis.py"
    click Viz_Utils "https://github.com/tcisne/ct2fea/blob/main/utils/visualization.py"
    click CT_Processing "https://github.com/tcisne/ct2fea/blob/main/processing/ct_processing.py"
    click Denoising "https://github.com/tcisne/ct2fea/blob/main/processing/denoising.py"
    click Segmentation "https://github.com/tcisne/ct2fea/blob/main/processing/segmentation.py"
    click Voxel_Meshing "https://github.com/tcisne/ct2fea/blob/main/meshing/voxel_mesher.py"
    click Mesh_Quality "https://github.com/tcisne/ct2fea/blob/main/meshing/mesh_quality.py"
    click FEA_Writer "https://github.com/tcisne/ct2fea/blob/main/meshing/fea_writer.py"
    click Linear_Materials "https://github.com/tcisne/ct2fea/blob/main/materials/linear.py"
    click Nonlinear_Materials "https://github.com/tcisne/ct2fea/blob/main/materials/nonlinear/hyperelatic.py"
    click Nonlinear_Materials "https://github.com/tcisne/ct2fea/blob/main/materials/nonlinear/plasticity.py"
    click GPU_Materials "https://github.com/tcisne/ct2fea/blob/main/materials/gpu/material_mapping.py"
    click CUDA_Kernels "https://github.com/tcisne/ct2fea/blob/main/acceleration/cuda_kernels.py"
    click OpenCL_Utils "https://github.com/tcisne/ct2fea/blob/main/acceleration/opencl_utils.py"
    click Utilities "https://github.com/tcisne/ct2fea/tree/main/utils/"
    click Testing "https://github.com/tcisne/ct2fea/tree/main/tests/"

    %% Styles
    classDef ui fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef config fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef io fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef processing fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef meshing fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef material fill:#fff5cc,stroke:#333,stroke-width:2px;
    classDef acceleration fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef utilities fill:#e6e6ff,stroke:#333,stroke-width:2px;
    classDef testing fill:#e6ffe6,stroke:#333,stroke-width:2px;
```
