# pvnkmrksk/matrexvr architecture

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

- Interactive diagram: https://gitdiagram.com/pvnkmrksk/matrexvr
- Repository: https://github.com/pvnkmrksk/matrexvr

## Overview

##### Project Type and Purpose
- The project is a Unity-based immersive simulation environment used in neuroscience research. It is designed to create naturalistic virtual reality settings to study collective behaviors (e.g., foraging in locusts) and integrates real-time control, sensor feedback, and data logging.
- It leverages VR hardware (LED panels, multi-camera viewports) plus external control via ZeroMQ (NetMQ library) to achieve closed-loop control and interactive simulations. It is also an open-source resource so that other researchers can extend or customize functionalities.

##### Main Components
- Unity Engine Core:
– This is the “heart” of the project; it manages scenes, game objects, physics, rendering, asset management (models, textures, prefabs, scenes).
– Represent all key asset folders (Scenes, Prefabs, Scripts, Models, Materials, Plugins) as part of this core.
- Simulation & Scene Components:
– Scenes and Prefabs: These include various environment setups (e.g., StressTest, Swarm, Choice, ControlScene) which simulate different experimental conditions.
– Scripts: Control logic that drives closed-loop control, object rotation (DrumRotator, SinusoidalGrating, Keyboard control, VR camera setup), and sensory input processing.
- Control & Communication Modules:
– Closed-Loop Control Module:
- Managed by scripts like ClosedLoop.cs, DrumRotator.cs, and Keyboard.cs which adjust object positions and rotations in real time.
- Detailed indications for directional control (pitch, yaw, roll) and step-wise rotational functionalities.
– ZMQ Listener and External Communication:
- ZmqListener.cs listens for external pose data via ZeroMQ, enabling integration between external sensor data and in-game object updates.
- NetMQ/ZeroMQ as the external messaging/dependency block interfacing with Unity.
- Data Logging & Analytics Subsystem:
– DataLogger.cs (plus various Scene and Master data logging scripts) captures sensor and object states.
– Shows buffering of log lines, generating CSV.GZ files, and connecting to various GameObjects.
- User Input/Interaction:
– Keyboard.cs: This script maps physical controls to in-game object movement and state toggling.
– Indicate the set of keyboard controls for both translation and closed-loop control toggles.
- External Configurations & Assets:
– StreamingAssets: Contains configuration JSON and Python scripts for permutation sequences or rotation configurations, which inform the simulation parameters.
– Mention additional support modules such as the 6-axis force-torque sensor simulation and 3D printable modules.

##### Relationships and Interactions
- The Scene & Prefab layer (which presents the visual and physical simulation)
- The Scripts layer (which provide behavior, control, and interactivity)
- Dependencies between the closed-loop control component and external communications (ZMQ listener receives data that drives scripts for object positioning and orientation).
- Keyboard Input module to both the closed-loop control components and the general simulation (indicating how user input can override or mix with external data).

##### Architectural Patterns and Design Principles
- Modularization: Each distinct subset (control, data logging, sensory input, scene management) is encapsulated—facilitating extensibility and easier troubleshooting.
- Use a layered approach:
- Presentation Layer: Visuals managed by Unity (Scenes, Prefabs, Cameras).
- Control Layer: All scripts that handle input (keyboard, ZMQ, closed-loop control).
- Data Management Layer: Data logging modules and configuration streaming (StreamingAssets).
- Integration of third-party libraries (NetMQ) that bridge external real-time communication with internal simulation mechanics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Unity Engine"
        subgraph "Scene & Asset Management"
            SM["Scene Manager: StressTest,ControlScene,Swarm,Choice"]:::unity
            PA["Prefabs & Assets"]:::unity
            MAT["Materials"]:::unity
        end
        subgraph "Script Modules"
            subgraph "Closed Loop Control"
                CL1["ClosedLoop.cs"]:::script
                CL2["DrumRotator.cs"]:::script
                CL3["Keyboard.cs"]:::script
            end
            SIM["Simulation Scripts: SinusoidalGrating,ViewportSetter"]:::script
        end
        DLOG["Data Logging (DataLogger.cs)"]:::data
    end

    ZMQ["NetMQ/ZeroMQ Listener (ZmqListener.cs)"]:::external
    STREAM["StreamingAssets & Configurations"]:::config

    %% Relationships within Unity Engine
    SM -->|"loads"| PA
    PA -->|"includes"| MAT

    %% External communication feeds into Closed Loop Control
    ZMQ -->|"feeds"| CL1
    %% Streaming configurations drive simulation script parameters
    STREAM -->|"configures"| SIM

    %% Control modules updating simulation and logging
    CL1 -->|"updates"| SIM
    CL1 -->|"logs"| DLOG
    SIM -->|"logs"| DLOG

    %% Styles
    classDef unity fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef script fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef data fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef config fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Click Events
    click SM "https://github.com/pvnkmrksk/matrexvr/tree/main/Assets/Scenes"
    click PA "https://github.com/pvnkmrksk/matrexvr/tree/main/Assets/Prefabs"
    click MAT "https://github.com/pvnkmrksk/matrexvr/tree/main/Assets/Materials"
    click CL1 "https://github.com/pvnkmrksk/matrexvr/blob/main/Assets/Scripts/ClosedLoop.cs"
    click CL2 "https://github.com/pvnkmrksk/matrexvr/blob/main/Assets/Scripts/Optomotor/DrumRotator.cs"
    click CL3 "https://github.com/pvnkmrksk/matrexvr/blob/main/Assets/Scripts/Keyboard.cs"
    click ZMQ "https://github.com/pvnkmrksk/matrexvr/blob/main/Assets/Scripts/ZmqListener.cs"
    click DLOG "https://github.com/pvnkmrksk/matrexvr/blob/main/Assets/Scripts/Loggers/DataLogger.cs"
    click STREAM "https://github.com/pvnkmrksk/matrexvr/tree/main/Assets/StreamingAssets"
```
