# gitzhcode/zspace_3dpslicer architecture

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

- Interactive diagram: https://gitdiagram.com/gitzhcode/zspace_3dpslicer
- Repository: https://github.com/gitzhcode/zspace_3dpslicer

## Overview

##### Project Type and Purpose
- This is a C++-based CAD toolkit/library (zSpace 3DPSlicer) embedded within the proprietary zSpace ALICE visualization platform.
- It provides SDF-based mesh slicing capabilities for large-scale 3D concrete printing workflows.
- The project is not a web app or microservice suite—it’s a native library plus a desktop visualization/demo executable.

##### High‐Level Component Breakdown
a. Core Library (zTsSDFSlicer)
- JSON I/O module: parses input meshes (half-edge structures via JSON) and writes slicing results back to JSON.
- Geometry engine: employs half-edge mesh data structures, weighted plane interpolations, geodesics, Boolean operations and SDF computations.
- Print‐block generator: assembles cross-section profiles into continuous print paths, supports thickness/infill patterns, cable slots.

b. ALICE Viewer Front-End (zspace_alice)
- Graphics Layer: OpenGL (via freeglut, GLEW) + gl2ps for on-screen rendering and printing to PostScript/PDF.
- Controller: wires UI events to the slicer library API (calls setFromJSON(), computePrintBlocks(), exportJSON()).

c. Data and Dependencies
- Sample Data: JSON files, demonstration meshes in “documentation/Assets”
- External Libraries: Eigen (linear algebra), OpenNURBS, nlohmann/json, SQLite, polyClipper, freeglut, GLEW, gl2ps, libGizmo.

##### Interactions and Data Flow
1. User loads a mesh in the ALICE Viewer front-end.
2. Viewer serializes mesh to JSON → passes JSON to zTsSDFSlicer.
3. Slicer core:
– Builds half-edge mesh → computes SDF and cross-sections → refines with Booleans → generates print blocks.
– Outputs slicing data → JSON.
4. Viewer reads JSON output → renders slices, print paths; optional export to files/SQL.
5. gl2ps can capture printouts; SQLite may store run metadata if enabled.

##### Architectural Patterns & Design Principles
- Modular library + host application separation.
- Clear Model (mesh,SDF) – View (OpenGL) – Controller (event wiring) layering in ALICE Viewer.
- Data-oriented design: JSON as interchange format between modules.
- Plugin‐style dependency injection: Slicer core does not depend on UI/GL components.

##### Essential Elements
- Clear, unambiguous component names matching file structure (e.g., zTsSDFSlicer, ALICE Viewer).
- Notes on configuration/build: point out Premake script under zspace_alice/Alice/premake5.lua and Visual Studio solution.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Actor
    User["User / Demo Executable"]:::actor

    %% Input Layer
    subgraph "Input Meshes & Sample Data" 
        direction TB
        SampleData["Sample Meshes & JSON"]:::data
        Assets_zSpace["Assets/zSpace"]:::data
        Assets_zTs["Assets/zTsSDFSlicer"]:::data
        MD_zSpace["zSpace.md"]:::data
        MD_zTs["zTsSDFSlicer.md"]:::data
    end

    %% Core Library
    subgraph "zTsSDFSlicer (Core Library)"
        direction TB
        JSON_IO["JSON I/O Module"]:::data
        MeshEngine["Mesh & SDF Engine"]:::compute
        BlockGen["Print-block Generator"]:::compute
        JSON_Export["JSON Exporter"]:::data
    end

    %% Viewer Layer
    subgraph "ALICE Viewer Front-End (zspace_alice/Alice)"
        direction TB
        UI["UI Layer (ImGui + libGizmo)"]:::ui
        Controller["Controller / Glue Code"]:::ui
        Graphics["Graphics Layer (OpenGL/freeglut/GLEW + gl2ps)"]:::ui
        Screen["Screen / Render Target"]:::ui
    end

    %% CLI Future
    CLI["Command-Line Tool / Sketch"]:::ui

    %% External Dependencies
    subgraph "External Dependencies" 
        direction TB
        Eigen["Eigen"]:::external
        OpenNURBS["OpenNURBS"]:::external
        JSONLIB["nlohmann/json"]:::external
        SQLite["SQLite"]:::external
        PolyClip["polyClipper"]:::external
        FreeGLUT["freeglut"]:::external
        GLEW["GLEW"]:::external
        GL2PS["gl2ps"]:::external
        GizmoLib["libGizmo"]:::external
    end

    %% Connections
    User -->|"Load Mesh"| UI
    UI -->|"MeshJSON"| JSON_IO
    Controller -->|"setFromJSON()"| JSON_IO
    JSON_IO -->|"HalfEdgeMesh"| MeshEngine
    MeshEngine -->|"SDFData"| BlockGen
    BlockGen -->|"PrintPathsJSON"| JSON_Export
    JSON_Export -->|"exportJSON()"| Controller
    Controller -->|"invoke Rendering"| Graphics
    Graphics -->|"draw()"| Screen

    User -->|"Run CLI"| CLI
    CLI -->|"setFromJSON() etc."| JSON_IO

    %% Dotted arrows to dependencies
    JSON_IO -.-> JSONLIB
    MeshEngine -.-> Eigen
    MeshEngine -.-> PolyClip
    BlockGen -.-> PolyClip
    Graphics -.-> FreeGLUT
    Graphics -.-> GLEW
    Graphics -.-> GL2PS
    UI -.-> GizmoLib
    JSON_IO -.-> SQLite
    JSON_IO -.-> OpenNURBS

    %% Click Events
    click UI "https://github.com/gitzhcode/zspace_3dpslicer/blob/main/zspace_alice/Alice/src/alice/imgui_freeglut.h"
    click UI "https://github.com/gitzhcode/zspace_3dpslicer/blob/main/zspace_alice/Dependencies/libGizmo/include/IGizmo.h"
    click Controller "https://github.com/gitzhcode/zspace_3dpslicer/blob/main/zspace_alice/Alice/src/alice/Controller.h"
    click Graphics "https://github.com/gitzhcode/zspace_3dpslicer/blob/main/zspace_alice/Alice/src/alice/RenderMesh.h"
    click Graphics "https://github.com/gitzhcode/zspace_3dpslicer/tree/main/zspace_alice/Dependencies/freeglut"
    click Graphics "https://github.com/gitzhcode/zspace_3dpslicer/tree/main/zspace_alice/Dependencies/glew"
    click Graphics "https://github.com/gitzhcode/zspace_3dpslicer/tree/main/zspace_alice/Dependencies/gl2ps"
    click User "https://github.com/gitzhcode/zspace_3dpslicer/tree/main/zspace_alice/Alice"
    click SampleData "https://github.com/gitzhcode/zspace_3dpslicer/tree/main/documentation/Assets"
    click Assets_zSpace "https://github.com/gitzhcode/zspace_3dpslicer/tree/main/documentation/Assets/zSpace"
    click Assets_zTs "https://github.com/gitzhcode/zspace_3dpslicer/tree/main/documentation/Assets/zTsSDFSlicer"
    click MD_zSpace "https://github.com/gitzhcode/zspace_3dpslicer/blob/main/documentation/zSpace.md"
    click MD_zTs "https://github.com/gitzhcode/zspace_3dpslicer/blob/main/documentation/zTsSDFSlicer.md"
    click CLI "https://github.com/gitzhcode/zspace_3dpslicer/blob/main/zspace_alice/userSrc/sketch_3DPSlicer.cpp"

    %% Styles
    classDef data fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef compute fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef ui fill:#FFF3E0,stroke:#E65100,color:#BF360C
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#455A64
    classDef actor fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C,stroke-width:2px
    class User actor
    class Screen ui
    class SampleData,Assets_zSpace,Assets_zTs,MD_zSpace,MD_zTs data
    class JSON_IO,JSON_Export data
    class MeshEngine,BlockGen compute
    class Graphics,UI,Controller,CLI ui
    class Eigen,OpenNURBS,JSONLIB,SQLite,PolyClip,FreeGLUT,GLEW,GL2PS,GizmoLib external
```
