Urchin + Slice Trajectory Viewer

The viewer needs an IBL environment with Python 3.10 or newer and ONE-api 3.4 or newer. Older ONE versions can no longer query Alyx, so the subject list stays empty. In the lab this is iblenv3.11, the IBL alignment GUI's environment. If you have it, upgrade ONE there:

conda activate iblenv3.11
pip install "ONE-api>=3.4"

If you don't, create one (these commands have not yet been tested on a fresh machine):

conda create -n iblenv3.11 python=3.11
conda activate iblenv3.11
pip install ibllib "ONE-api>=3.4" qtpy pyqt5 oursin==1.0.0

Clone the repository to a folder of your choice:

git clone https://github.com/kimiline/ibl-probe-tools.git

This creates an ibl-probe-tools folder containing the GUI scripts and their .bat launchers.

Open trajectory_viewer_urchin.bat in Notepad. Replace the username kimil with your own Windows username on the Python path line:

C:\Users\YOUR_USERNAME\anaconda3\envs\iblenv3.11\python.exe "%~dp0trajectory_viewer_urchin.py"

If Anaconda is installed system-wide rather than per-user, the path may start with C:\ProgramData\anaconda3\ instead.

Double-click trajectory_viewer_urchin.bat. A login dialog will appear asking for your Alyx credentials. If you have previously logged in on this machine, it will connect automatically and skip the dialog.

1. In the Subject dropdown, select the mouse you want to view.
2. In the Session dropdown, select a recording session. Sessions are listed in date-ascending order.
3. Click Add Session to load that session's probe trajectories, or click Load All to load every session for that subject at once.
4. Repeat for additional subjects or sessions. Each loaded session appears in the probe tree below the controls.

To remove everything and start over, click Clear All.

Three slice panels are shown: coronal (AP slice), sagittal (ML slice), and horizontal (DV slice). Probe trajectories appear on each panel as faint lines, with a bright dot at the slice intersection.

The tree lists every loaded session, probe, and shank. Each entry has a color swatch on the right.

The Urchin 3D view is optional. Load probe sessions first, then:

1. In the Atlas dropdown (top bar), confirm CCF 25 µm is selected (the default).
2. Click 1. Open Urchin. A browser tab opens automatically at the Urchin renderer and the 3D brain loads. This takes a few seconds.
3. Once the status bar shows Urchin ready, loaded probe trajectories appear in the 3D view automatically.
4. Use the Brain alpha slider (top bar) to adjust the transparency of the grey brain surface.
5. Urchin opens looking down on the top of the brain, anterior at the top, the animal's right on screen-right. If you rotate the brain by dragging, click Reset view to return to this orientation.

After Urchin is open, use the Brain Regions section at the bottom of the sidebar to highlight CCF brain areas in the 3D view. Regions appear with their canonical Allen Brain Atlas colors as solid opaque meshes.

1. Type one or more CCF acronyms in the text box, separated by commas, for example: VISam, FN, CA1
2. Press Enter or click Add. The regions appear in the 3D view immediately.
3. To remove a single region, right-click its name in the list and choose Remove region.
4. To remove all highlighted regions at once, click Clear All Regions.

The lab uses a modified Lasagna that opens registered histology in the same orientation as the trajectory viewer. Install it once, in its own conda environment (not iblenv):

conda create -n lasagna python=3.11
conda activate lasagna
pip install git+https://github.com/kimiline/lasagna.git

To launch it:

conda activate lasagna
lasagna

To update to the latest version:

conda activate lasagna
pip install --upgrade --force-reinstall --no-deps git+https://github.com/kimiline/lasagna.git

1. Press Ctrl + Shift + O (or File > Load ingredient > Open multiple stacks) and select both channel files, e.g. STD_ds_KM_077_GR.tif and STD_ds_KM_077_RD.tif.
2. A dialog lists each file with a color. Colors are picked from the file name (GR green, RD red); change any that are wrong, then click OK.
3. The stacks open in surgeon's view, and the status bar confirms it. The file dialog remembers the last folder you used.

To open a single stack instead, press Ctrl + O.

Uploads go to the shared IBL Alyx database, not just your computer. The registration window checks every file first and shows exactly what it will write before anything is uploaded.

1. Save each traced points layer in Lasagna with the standard name, for example 2026-05-21_KM_077_001_probe00a_pts.csv.
2. On the Points tab, click Register tracks to Alyx... under the Name list. The first time, choose the iblenv3.11 python and then register_tracks_alyx.py; Lasagna remembers both.
3. The window lists every _pts.csv file in the folder, with a Status and Details for each. Tick the files to upload, or click Check all boxes for upload.
4. Click Upload checked tracks..., read the review screen, and confirm. If any track has warnings, tick the acknowledgement box first.
5. Check the result in the Alyx admin pages (experiments > trajectory estimates, search the subject). Each upload is also recorded in alyx_track_upload_log.csv next to the files.

Fixing shank labels on tracks already in Alyx

1. Open the subject's electrodetracks folder in the window and click Download from Alyx.... The stored tracks are saved, with their current labels, in a from_alyx folder inside it, separate from your original tracings.
2. Rename the files of the probe you are correcting, for example swap a with d and b with c, then click Re-check.
3. Only the renamed files become uploadable. Check that the shank-order warning is gone, then upload them together. Re-uploading replaces the old histology tracks, so any ephys alignment on those probes will need redoing.