Urchin
Organization
Urchin is organized into three parts. A client, server, and renderer. The only client right now is the Python API, but in the future we may build other APIs (MATLAB, R). The Server is a Node.js server that echoes messages between clients and renderers. The Renderer is a Unity app that can run either as a standalone desktop build or in the browser.
Virtual environment
To develop for Urchin you will need to run a local copy of the client, server, and Unity builds. For the Python API you will need a new virtual environment with unityneuro
installed in editable mode.
To setup the venv go into the API folder and run:
python -m venv urchin-venv
urchin-venv/Scripts/activate
pip install -e .
Adding new functionality
To add a new render function you need three pieces:
Update
API/urchin/renderer.py
to include the new function and add documentationAdd the
socket.io
call to the set of calls inServer/server.js
Add the new functionality to the UnityClient in
Client.cs
and in your manager class
Before deploying you should add a new test script in Examples/basic
which runs your new functionality and makes sure that it works.
Urchin (API/unityneuro/render.py)
The Urchin calls are mostly very simple, they just take input data from the user, sanitize it (or not, most of them don’t do this yet) and send it off with a message header to the server.
Make sure to add documentation to all of your new renderer functions so it’s clear what they take as input.
Server (Server/server.js)
The server calls just echo the data from the sender (API) to the receiver (Unity). Copy any of the existing calls and replace the message headers. Please keep the server organized.
Unity (Client.cs and your manager code)
Your code in Unity should be separated into two layers. All socket messages should be received in the Client.cs
class and then passed on to a XXManager.cs
. The Client
handles all socket communication, while the Manager
handles all of the Unity local content. Keep managers separated by functionality (e.g. ProbeManager
, NeuronManager
, LineRendererManager
, etc).
Testing your code
To test your code locally, run the server on your local machine by navigating to the Server/
folder and running node server.js
. Then, run client in standalone localhost mode:
urn.setup(localhost=True, standalone=True)
You should see the client connect with your username as ID on the server window.
Finally, run the Unity renderer app in the editor. You may need to manually set your username as the ID in the app if it doesn’t detect it automatically (either via code in Client.cs
or by pressing I
and opening the ID input window).
Deployment
Deploying the client
The client is accessed by users in two ways: either through the web server or through a standalone desktop app which we include in each minor version release. To deploy a new client you need to take a few steps.
If you changed the Addressable assets or updated to a new version of Unity you need to re-build the assets. Do this for each build target separately. Then copy the
UnityClient/ServerData
folder to thehtdocs/UMData
subfolder on the server.Build the WebGL target build, then copy this to the
htdocs/UMRenderer
subfolder on the server.Build the Windows target build, compress to zip, and attach this to the next release version. Or, if you are hotfixing a previous release, update the hotfix version number and swap the new build for the previous one.
Uploading to the server
The server runs Apache, the htdocs file is at C:/Apache24/htdocs
. Ask Dan for the login details. You can copy files locally onto the data server or copy them through google drive or slack.
Pushing the Pypi package
Push to the real server
py -m build
py -m twine upload dist/*
Deploying the server
On Heroku
Every time the github repository is pushed the Heroku server will re-build. You will get back a 503 server response if there are errors in the code running on Heroku.