Pinpoint is under active development, there is no requirement to maintain backwards compatibility with version changes. We are aiming for a 1.0.0 release timed with SfN 2022.
The Trajectory Planner is built out of a single main repository which holds the Unity codebase. Code that is shared across multiple VBL projects is stored in the vbl-core repository which you should add to the main repo as a git submodule. The full pull sequence for the entire repository is:
git clone https://github.com/dbirman/NPTrajectoryPlanner git submodule add https://github.com/dbirman/vbl-core Assets/vbl-core
If you use Github Desktop the
vbl-core repository will automatically be pulled. If you are working on multiple VBL projects you should add the repository as a separate repo in Desktop and give it an alias, e.g.
Most of the VBL assets are shared across projects, these are accessed from a shared Addressables Storage repository. Assets in this repository are accessed via the
AddressablesRemoteLoader class in
vbl-core, see here.
When contributing to a VBL project you should avoid modifying the main scenes, except to add or remove Prefab objects. Merges between scenes are very difficult to handle in git and should be avoided.
The trajectory planner runs out of a central class
TP_TrajectoryPlannerManager which coordinates loading the main functionality of the planner. Most of the code uses a hub-and-spoke model where other components will communicate with the manager but not with each other, to reduce the likelihood of creating deadlocks.
At the core of the planner is the Allen CCF annotation dataset. You can learn more about the dataset on the Allen’s documentation page. We use the 25 um atlas which has dimensions 528 x 320 x 456, the
nrrd file downloaded from the Allen.
The 3D models are controlled via the CCFModelControl component. Models are loaded from the shared addressables system and the mesh is saved locally to render the models.
Probe models are stored as prefabs and instantiated by the tpmanager. Each probe is controlled by a TP_ProbeController component which handles probe movement. When a probe is moved it updates its associated probe panel prefabs, which are run by the TP_ProbePanel and TP_ProbeUIManager components. The probe panels are interpolated using a custom shader which is a variant of the Inplane Slice shader.
Each probe has a TP_ProbeInsertion that defines the tip position in CCF AP/ML/DV and the probe angles in Phi/Theta/Spin. The ProbeController component handles interpolating the brain surface position that a probe is going through as well as the depth required to reach the target insertion coordinate.
When a [CoordinateTransform] is active in Pinpoint the ProbeController class modifies the tip and brain surface coordinates accordingly. Rotations are more complex – (and not currently functional), but to deal with rotations the ProbeController will eventually interpolate the tip and surface coordinates and then back out the corresponding angles needed to reach these points.
Collisions are handled by checking the overlap between all of the Probe
Collider componenets against all of the Colliders in the scene.
Rigs are a collection of 3D models stored as a prefab and marked as an addressable asset. These are loaded by the TP_ToggleRigs component, which also handles adding their corresponding colliders to the collision checks.
Building new features and fixing bugs
We use Github Issues to track development. Any changes you make should first be posted as an issue and flagged either as a bug or a feature and assigned to the relevant developer. When you complete adding a new feature you should either merge it to the corresponding development branch (if it’s minor) or submit a pull request (if it’s a major feature change). In either case, you should link to the relevant commit in the issue.
When a bug/feature is closed it should be added to the incremental update list on the next Release page, or added to the current release as a hotfix.
The Trajectory Planner can build to WebGL (primary), Windows, and Linux. Building to Mac is more complex than we can handle right now.
Any assets that don’t need to be immediately loaded with the trajectory planner should be marked as Addressable and loaded asynchronously.
If you modified the Addressables assets you need to re-build these and deploy them on the asset server before you build to targets. In the Addressables Groups window go to Build > New Build > Default Build Script, or use Build > Update a Previous Build if you only modified existing assets but did not add new ones.
Remote Build and Load Paths
Addressables should be built to the remote build and load paths, which should point to
http://data.virtualbrainlab.org/NPTraj/[BuildTarget] respectively. These can be modified in the Addressables Profiles window
WebGL builds function without extra steps, just zip the output directory, move it to the asset server, and swap it for the existing file. Note that there is an
.htaccess file in the
Build directory which needs to be manually copied to the new release.
Windows builds function without extra steps, just zip the output directory and upload it as either a hotfix to the Releases page (make sure to increment the hotfix number) or as a new release.
Linux builds function but you need to load the build on a Linux machine and mark the output file as executable.
Mac builds require extra steps to certify the build, we don’t have the capacity right now to deal with these.