# cos526-project-ss-yz/cos526-project architecture

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

- Interactive diagram: https://gitdiagram.com/cos526-project-ss-yz/cos526-project
- Repository: https://github.com/cos526-project-ss-yz/cos526-project

## Overview

##### Project type and purpose
- This is a research‐grade Python pipeline for “Zero‐Shot Point Cloud Completion with 3D Diffusion Priors.”
- It ingests partial 3D scans (Redwood, ShapeNet, nuScenes), preprocesses them, runs a zero‐shot completion using a pretrained diffusion model (Hunyuan3D-v2), and evaluates/visualizes results.

##### File structure
Top level:
- Scripts & notebooks:
– prepare_data.py, preparedata_nuscenes.py – data ingestion & preprocessing
– shape_completion_pipeline_nuscenes.py – core completion pipeline
– shape_completion_pipeline_demo_*.ipynb – interactive demos (Redwood, ShapeNet)
– register_results.ipynb, camera_vis.ipynb, densityplotcheck.py – evaluation & visualization
- Data folders:
– for_inputs/… – raw partial scans (masks & world planes)
– for_GT/… – ground‐truth masks & transformations
– frames_data_full/… – downloaded full Redwood frames (subfolder per sample)
- Utils:
– utils/depth_utils.py, chamfer_python.py, register_utils.py, gd_register_utils.py – common math, registration, geometry helpers
- Environment & configuration:
– create_env.sh, .gitignore, README.md

##### README for additional insights
- Prerequisites: PyTorch, diffusers, transformers, Open3D, PYG, plus Hunyuan3D-v2 as an external dependency
- Usage steps: download data, run prepare_data.py, then launch the notebooks to perform zero‐shot completion on different datasets.

##### Elements to include for clarity
– Blue for data storage
– Green for processing scripts
– Orange for model inference
– Purple for utilities
– Yellow for notebooks/visualization

##### Detail
- Every essential artifact (scripts, data folders, utils, external dependencies)
- Don’t over‐complicate—use the file tree to enumerate components
- Keep the flow linear and labeled, reflecting exactly how you’d run prepare_data.py → pipeline → notebooks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        Raw["Raw Partial Scans"]:::data
        GT["Ground-Truth Scans"]:::data
        Frames["Full Redwood Frames"]:::data
    end

    %% Data Preparation Layer
    subgraph "Data Preparation Layer"
        Prep1["prepare_data.py"]:::process
        Prep2["preparedata_nuscenes.py"]:::process
    end

    %% Utility Modules
    subgraph "Utility Modules"
        DU["depth_utils.py"]:::utils
        CP["chamfer_python.py"]:::utils
        RU["register_utils.py"]:::utils
        GDU["gd_register_utils.py"]:::utils
    end

    %% Core Completion Pipeline
    subgraph "Core Completion Pipeline"
        CoreScript["shape_completion_pipelinenuscenes.py"]:::model
        DemoSN["shape_completion_pipeline_demo_shapenet.ipynb"]:::notebook
        DemoFinal["shape_completion_pipeline_demo_final.ipynb"]:::notebook
        DemoNS["nuscenespipelineupdated.ipynb"]:::notebook
        ExtModel["Hunyuan3D-v2 Diffusion Model"]:::external
        Libs["PyTorch3D, diffusers/transformers, Open3D, PYG"]:::external
    end

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        EvalReg["register_results.ipynb"]:::notebook
        EvalCam["camera_vis.ipynb"]:::notebook
        EvalDen["densityplotcheck.py"]:::process
    end

    %% Environment & Configuration
    subgraph "Env & Config"
        Env["create_env.sh"]:::process
        Readme["README.md"]:::process
        Gitignore[".gitignore"]:::process
    end

    %% Connections
    Raw -->|"raw scans"| Prep1
    GT -->|"ground-truth"| Prep1
    Frames -->|"frames data"| Prep2
    Prep1 -->|"processed point clouds"| CoreScript
    Prep2 -->|"processed point clouds"| CoreScript

    DU --> CoreScript
    CP --> CoreScript
    RU --> CoreScript
    GDU --> CoreScript

    CoreScript -->|"inference"| ExtModel
    CoreScript -->|"uses libs"| Libs

    CoreScript -->|"completed meshes"| EvalReg
    CoreScript -->|"completed meshes"| EvalCam
    CoreScript -->|"completed meshes"| EvalDen

    %% Click Events - Data Sources
    click Raw "https://github.com/cos526-project-ss-yz/cos526-project/tree/main/for_inputs/"
    click GT "https://github.com/cos526-project-ss-yz/cos526-project/tree/main/for_GT/"
    click Frames "https://github.com/cos526-project-ss-yz/cos526-project/tree/main/frames_data_full/"

    %% Click Events - Data Preparation Layer
    click Prep1 "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/prepare_data.py"
    click Prep2 "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/preparedata_nuscenes.py"

    %% Click Events - Utility Modules
    click DU "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/utils/depth_utils.py"
    click CP "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/utils/chamfer_python.py"
    click RU "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/utils/register_utils.py"
    click GDU "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/utils/gd_register_utils.py"

    %% Click Events - Core Completion Pipeline
    click CoreScript "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/shape_completion_pipelinenuscenes.py"
    click DemoSN "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/shape_completion_pipeline_demo_shapenet.ipynb"
    click DemoFinal "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/shape_completion_pipeline_demo_final.ipynb"
    click DemoNS "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/nuscenespipelineupdated.ipynb"

    %% Click Events - Evaluation & Visualization
    click EvalReg "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/register_results.ipynb"
    click EvalCam "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/camera_vis.ipynb"
    click EvalDen "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/densityplotcheck.py"

    %% Click Events - Env & Config
    click Env "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/create_env.sh"
    click Readme "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/README.md"
    click Gitignore "https://github.com/cos526-project-ss-yz/cos526-project/blob/main/.gitignore"

    %% Styles
    classDef data fill:#CEF1FF,stroke:#0366d6,color:#0366d6;
    classDef process fill:#E6FFEA,stroke:#0b6623,color:#0b6623;
    classDef model fill:#FFEFD5,stroke:#ff8c00,color:#ff8c00;
    classDef utils fill:#F5E6FF,stroke:#800080,color:#800080;
    classDef notebook fill:#FFF5CC,stroke:#cccc00,color:#cccc00;
    classDef external fill:#F0F0F0,stroke:#666666,color:#666666;
```
