# leihui6/pcqa architecture

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

- Interactive diagram: https://gitdiagram.com/leihui6/pcqa
- Repository: https://github.com/leihui6/pcqa

## Overview

##### Project Type and Purpose
- This repository is a specialized scientific/industrial tool focused on assessing the quality of 3D point clouds. It integrates data acquired from 3D scanning (both practical scanning and synthesis) with subsequent processing, quality score estimation, and visualization.
- The README indicates that the primary goal is to map a subset of points into a 2D distribution, evaluate the quality of the point cloud, and then output the quality scores. The project includes demo scripts, Jupyter notebook examples, and visualization support through both custom code and external tools like CloudCompare.

##### Analyzing the File Structure
- Top-Level Files/Folders: Notice directories such as:
- “dataset”: Contains subfolders for “practical_scanning”, “scanning_repository” (zipped data), and “synethsis” (likely for simulation or additional data generation).
- “src”: Contains the core Python scripts, organized by functionalities into data files, model definitions (e.g. DeepFit.py, ThreeDmFVNet.py), utility functions (under “src/utils”), and demonstration scripts (like “pcqa_demo.py”, “n-jet_fitting.py”).
- “img” directory includes visualization images.
- “requirements.txt” and the environment instructions in the README indicate dependency management.
- The structure points to a separation between datasets, core implementations, and presentation/demo scripts, which is common in research code where data processing and algorithm implementations are clearly delineated.

##### Key Architectural Components to Capture
a. Data Acquisition & Input:
- “dataset” folder: This holds both practical scanning products and simulated/synthesized data.
- Input data formats include CAD files (e.g. SLDPRT, STL), point cloud representations (.xyz), and reference files.

b. Preprocessing & Feature Extraction:
- The “n-jet_fitting.py” script and associated utilities (e.g., normal estimation in “src/utils”) represent the initial steps of processing the point cloud data.
- Preprocessing transforms the raw input (from various dataset formats) into structured data that can be used for quality evaluation.

c. Quality Score Estimation:
- Core components here are “pcqa_demo.py” and “QualityScoreEstimation.ipynb”. This is where the 2D mapping and computation of the quality score are executed.
- The “src/models” folder (including files like DeepFit.py and ThreeDmFVNet.py) indicates that deep learning modules may be part of the estimation process.

d. Utilities and Helper Functions:
- The “src/utils” directory collects auxiliary processes: for normal estimation, file IO (plyfile.py), visualization routines, dataset handling, and other lower-level tasks.

e. Visualization:
- There is also integration with external visualization tools such as CloudCompare (mentioned in README), which should be noted as an external dependency/component.

- Data Input Layer: Dataset (practical scanning, simulation, scanning repository), input file formats.
- Preprocessing Module: n-jet fitting, normalization, geometric feature extraction (via utilities – normal estimation, eulerangles, etc.).
- Quality Score Estimation Module: Core scripts (pcqa_demo.py and QualityScoreEstimation.ipynb) along with deep learning models (DeepFit, ThreeDmFVNet).
- Visualization & Output Module: Quality score output files (e.g., sample_quality_score_ours.txt) and conversion scripts (quality2color.py) as well as external tools like CloudCompare.
- Dependencies among components:
- That the “src/utils” directory supports both preprocessing and quality estimation.
- Integration with machine learning libraries such as PyTorch (from the requirements and environment instructions).

##### Architectural Patterns & Design Principles
- Modularity: Each major task (data input, preprocessing, quality estimation, and visualization) is encapsulated in its own module or set of scripts.
- If applicable, show that the system is designed to be extensible (e.g., new datasets or additional quality assessment methods could be integrated).

## Diagram (Mermaid)

```mermaid
flowchart TD
    D1["Data Input (Dataset)"]:::data

    subgraph "Preprocessing & Feature Extraction"
        P1["n-jet Fitting (src/n-jet_fitting.py)"]:::preprocess
        P2["Utility Functions (src/utils/)"]:::preprocess
    end

    subgraph "Quality Score Estimation"
        Q1["Demo Script (src/pcqa_demo.py)"]:::estimation
        Q2["Notebook (src/QualityScoreEstimation.ipynb)"]:::estimation
        subgraph "Deep Learning Models"
            M1["DeepFit (src/models/DeepFit.py)"]:::estimation
            M2["ThreeDmFVNet (src/models/ThreeDmFVNet.py)"]:::estimation
        end
    end

    subgraph "Visualization & Output"
        V1["Visualization (src/quality2color.py)"]:::visualization
        V2["Image Assets (img/)"]:::visualization
    end

    E1["CloudCompare (External)"]:::external
    E2["PyTorch Library (External)"]:::external

    D1 --> P1
    D1 --> P2
    P1 --> Q1
    P2 --> Q1
    P1 --> Q2
    P2 --> Q2
    Q1 --> M1
    Q1 --> M2
    Q1 --> V1
    Q2 --> V1
    V1 --> V2
    V1 --> E1
    Q1 --> E2

    classDef data fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef preprocess fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef estimation fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef visualization fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    click D1 "https://github.com/leihui6/pcqa/tree/main/dataset/"
    click P1 "https://github.com/leihui6/pcqa/blob/main/src/n-jet_fitting.py"
    click P2 "https://github.com/leihui6/pcqa/tree/main/src/utils/"
    click Q1 "https://github.com/leihui6/pcqa/blob/main/src/pcqa_demo.py"
    click Q2 "https://github.com/leihui6/pcqa/blob/main/src/QualityScoreEstimation.ipynb"
    click M1 "https://github.com/leihui6/pcqa/blob/main/src/models/DeepFit.py"
    click M2 "https://github.com/leihui6/pcqa/blob/main/src/models/ThreeDmFVNet.py"
    click V1 "https://github.com/leihui6/pcqa/blob/main/src/quality2color.py"
    click V2 "https://github.com/leihui6/pcqa/tree/main/img/"
```
