How virtualbrainlab/urchin works
Major Components
• Python API (Urchin):
– Manages data (for example, the “atlas” folder holds JSON structure files and ontological functions) and rendering instructions.
– Exposes functions that analysis scripts use (e.g., urchin.setup()).
– Contains tests and configuration/build files (pyproject.toml, setup.cfg) to ensure package correctness.
• Unity Rendering Client:
– Located in UnityClient, it is a complete Unity project including scenes, prefabs, shaders, plugins, and scripts.
– Integrates the Urchin API for Unity (via the vbl.urchin package found under Packages) to receive and process render instructions.
– Organizes several UI elements (control panels, camera prefabs) and low-level rendering components (shaders, materials, render textures).
• Communication/Integration Layer:
– Although not explicitly a separate “service,” the integration between your Python analysis environment and the Unity renderer is central.
– Look for modules like client.py in API and client integration implementations in Unity (e.g., Client_SocketIO.cs and Client_ZeroMQ.cs) that suggest communication layers using protocols such as SocketIO or ZeroMQ.
– This layer is responsible for the command/response/event mechanism that links API calls with renderer actions.
Relationships and Interactions
• The user’s analysis scripts call the Urchin Python API functions.
• Within the Python API, helper modules (e.g., atlas, renderer) process data and issue render commands.
• These commands are sent through the communication layer (likely over network sockets or messaging queues) to interact with the Unity client.
• The Unity client receives these messages, which then trigger behaviours in the scene (via managers, UI scripts, camera controllers, etc.) that update the rendered scene in real time.
Architectural Patterns and Key Design Principles
• Separation of Concerns: The project divides responsibilities between data processing/command issuing (Python API) and high-performance rendering/user interaction (Unity).
• Modular Architecture: Notice how both the API and the Unity client are split into many fine-grained modules (e.g., managers, behaviors in Unity; separate submodules in “oursin”).
• Communication Middleware: Use of separate client classes (for SocketIO and ZeroMQ) suggests a loosely coupled, message-based communication design.
• Extensibility: The rich folder structure, presence of tests, and clear package division (with distinct “oursin” and “vbl.urchin”) point toward a design that is intended to be modular and extensible.
Technologies and Frameworks
• Python – for the analytical API and core library.
• Unity (with C# scripting), including Unity’s Addressable Assets, Scene Management, and Shader Graph features – for rendering and UI.
• Communication libraries such as ZeroMQ or SocketIO (as indicated by client implementations in both Python and Unity).
• “User Analysis Scripts / Python Environment”
• “Communication Layer” – Illustrate the use of messaging protocols (SocketIO, ZeroMQ).
• The flow from User Scripts to the API.
• API sending commands/data to the Unity client through the communication middleware.
• Optionally, any feedback loop from Unity back to the API or logging components.
• Differentiate between Python modules (which might be represented as, say, blue blocks) and Unity components (which might be green blocks).
• Component is clearly named and annotated (e.g., “Atlas Data Module – loads structure JSON files”).
Detail over Breadth
• Aim for a level of granularity that exposes all essential components without oversimplification:
• Similarly, for the Unity client, highlight key systems such as UI, camera control, scene management, and communication handlers.
Happy diagramming!