# semanticity-research/arch2s architecture

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

- Interactive diagram: https://gitdiagram.com/semanticity-research/arch2s
- Repository: https://github.com/semanticity-research/arch2s

## Overview

Based on our examination of both the file tree and the README, the ARCH2S project is a specialized, research-oriented framework for point cloud perception. It is designed to work with large-scale 3D architectural data (provided as point clouds) and serves as a benchmark and dataset for semantic segmentation in exterior architectural structures. The project is a hybrid system combining high-performance CUDA/C++ modules (for low-level point cloud operations) with high-level Python code that manages datasets, model training, preprocessing, and evaluation.

##### Main Components
- Libraries/CUDA Extensions:
– libs/pointgroup_ops
– libs/pointops
– libs/pointops2
These directories house the core computational libraries written in C++, CUDA, and wrapped in Python. They implement critical low-level operations like aggregation, attention, grouping, sampling, query, and more, which are essential for efficient point cloud processing.

- Core Framework (Pointception):
– pointcept
Under this package, there are modules for:
- Datasets: (preprocessing, builders, dataloaders) that define how raw point cloud data is ingested, processed, and augmented.
- Engines & Hooks: (in pointcept/engines and hooks) which orchestrate training, testing, evaluation, and other runtime behaviors.
- Models: (in pointcept/models) that include various deep neural network architectures – ranging from point transformers to sparse UNets, and additional models like point_group, point_prompt_training, etc.
- Utilities: (in pointcept/utils) responsible for logging, configuration, registry for managing modules, environment setup, and miscellaneous functions.

- Scripts and Tools:
– scripts
– tools
These provide command-line interfaces to run building, training, testing, and preprocessing jobs. They act as entry-points that tie together the different components of the system.

- External Dependencies & Environment Setup:
The README details the environment setup with specific versions of CUDA, PyTorch, and other libraries such as spconv, Open3D, tensorboard, etc. This should be captured as part of the system’s deployment and runtime environment.

##### Relationships and Interactions
- The high-performance libraries (pointops, pointops2, and pointgroup_ops) provide low-level functions that are directly used by higher-level operations in the “pointcept” modules, especially within the model implementations and dataset preprocessing scripts.
- The dataset module in pointcept uses preprocessing scripts to convert and label raw FBX models into point cloud data. This processed output is then used by the training engines.
- The engines and hooks orchestrate the training and evaluation pipelines by interacting with models, invoking dataset loaders, and using utility functions (like logging, optimization, and scheduling).
- Scripts in the “scripts” and “tools” directories allow users to initiate training, run tests, and perform data preparation, while implicitly linking back to the core libraries and pointcept framework.

##### Architectural Patterns and Design Principles
- Modular Structure: The clear separation between GPU-accelerated libraries (in libs) and high-level orchestration (in pointcept) demonstrates a layered design that isolates performance-critical components from business logic.
- Extensibility: The use of function wrappers, registry (in pointcept/utils/registry.py), and hooks facilitates easy integration of new model architectures, datasets, or training strategies.
- Data Flow: There is a clear data flow from raw data acquisition and preprocessing, then feeding into the training engine, model inference, and finally evaluation. Each stage is neatly compartmentalized.

##### Relevant Technologies
- Language Stack: Python for orchestration and high-level logic; C++/CUDA for performance-critical kernels.
- Frameworks/Libraries: PyTorch (for deep learning), CUDA/cuDNN (for GPU acceleration), spconv (for sparse convolution operations), Open3D (for 3D visualization/manipulation), and others as indicated in the README.
- Build Tools: Python’s setup.py is used to build the extensions (note the use of Ninja build files in the build directories).

##### Essential Elements
- Clear labeling of each major module/component based on the file hierarchy (e.g., “libs/pointops”, “pointcept/models”).
- Annotations about environmental specifics (e.g., PyTorch, CUDA, GPU configurations) if space allows.
- Ideally, include several layers/sub-systems:
- The lowest layer for custom CUDA operations,
- The middleware that bridges these operations with machine learning models,
- The top layer for orchestration and experiment management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Environment
    K["Runtime Environment<br/>(CUDA, PyTorch, spconv, Open3D)"]:::external

    %% CUDA Extensions Subgraph
    subgraph "CUDA Extensions"
        direction TB
        A["libs/pointgroup_ops"]:::cuda
        B["libs/pointops"]:::cuda
        C["libs/pointops2"]:::cuda
    end

    %% Pointception Framework Subgraph
    subgraph "Pointception Framework"
        direction TB
        %% Data Handling Subgroup
        subgraph "Data Handling"
            direction TB
            E["pointcept/datasets/preprocessing"]:::framework
            D["pointcept/datasets"]:::framework
        end

        F["pointcept/engines & hooks"]:::framework
        G["pointcept/models"]:::framework
        H["pointcept/utils<br/>(includes registry)"]:::framework
    end

    %% Scripts and Tools Subgraph
    subgraph "Scripts and Tools"
        direction TB
        I["scripts"]:::scripts
        J["tools"]:::scripts
    end

    %% Relationships and Data Flow
    %% External environment feeding CUDA Modules and Framework
    K -->|"provides GPU support"| A
    K -->|"provides GPU support"| B
    K -->|"provides GPU support"| C
    K -->|"runtime deps"| F

    %% CUDA Extensions to Framework: low-level ops support
    A -->|"lowLevelOps"| E
    B -->|"lowLevelOps"| E
    C -->|"lowLevelOps"| E
    
    %% Data Handling flow
    E -->|"prepareData"| D
    D -->|"feedData"| F

    %% Framework engine interactions
    F -->|"trains/infers"| G
    F -->|"configs/logs"| H

    %% Scripts and Tools integration
    I -->|"startPipeline"| F
    J -->|"dataConversion"| E

    %% Additional interaction: CUDA support for Models
    A -->|"GPU-Kernels"| G
    B -->|"GPU-Kernels"| G
    C -->|"GPU-Kernels"| G

    %% Click Events
    click A "https://github.com/semanticity-research/arch2s/tree/main/libs/pointgroup_ops"
    click B "https://github.com/semanticity-research/arch2s/tree/main/libs/pointops"
    click C "https://github.com/semanticity-research/arch2s/tree/main/libs/pointops2"
    click D "https://github.com/semanticity-research/arch2s/tree/main/pointcept/datasets"
    click E "https://github.com/semanticity-research/arch2s/tree/main/pointcept/datasets/preprocessing"
    click F "https://github.com/semanticity-research/arch2s/tree/main/pointcept/engines and pointcept/engines/hooks"
    click G "https://github.com/semanticity-research/arch2s/tree/main/pointcept/models"
    click H "https://github.com/semanticity-research/arch2s/tree/main/pointcept/utils"
    click I "https://github.com/semanticity-research/arch2s/tree/main/scripts"
    click J "https://github.com/semanticity-research/arch2s/tree/main/tools"

    %% Styles
    classDef cuda fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef framework fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef scripts fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
