Princeton Tracer Master Guide

WebKnossos Current

WebKnossos is the primary annotation platform for volume segmentation tasks. It supports skeleton and volume annotations, 3D mesh visualization, and collaborative workflows.

Key Features

• Volume annotation with brush tools
• 3D mesh generation (right-click on segment)
• Interpolation for quick annotation across slices
• SAM2 AI-assisted segmentation (experimental)

Essential Keyboard Shortcuts

Key	Action
.	Toggle between all views and current view
Ctrl+Shift+O	Toggle volume opacity (Tampermonkey)
Ctrl+Shift+E	Toggle EM layer opacity (Tampermonkey)
Right-click segment	Generate 3D mesh / Quick rename

Access URLs

• webknossos.org
• wk.zetta.ai

Neuroglancer Current

Web-based viewer for volumetric data, primarily used for synapse annotation and verification.

Synapse Annotation Controls

Action	Control	Description
Mark Axon	Left Click	Place red point on presynaptic side
Mark Dendrite	Right Click	Place blue point on postsynaptic side
Zoom	Ctrl+Scroll	Zoom in/out
3D Rotate	Ctrl+Left Click	Rotate 3D view

Synapse Verification Workflow

1. Locate synapse in volume
2. Identify axon bouton (presynaptic)
3. Identify dendrite spine/trunk (postsynaptic)
4. Place red point on axon, blue point on dendrite
5. Verify using 3D mesh and 2D EM stack
6. Save and proceed to next segment

tracer_tools Library Current

Python library for programmatic access to CAVE and Neuroglancer.

Installation

cd tracer_tools
pip install -e .
pip install caveclient cloudvolume pandas nglui

Core Functions

Function	Purpose
coords_to_root(coords, datastack)	Get root ID from coordinates
root_to_coords(root_ids, datastack)	Get coordinates for root IDs
update_root_ids(ids, datastack)	Update outdated root IDs
build_ng_link(root_ids, datastack)	Generate Neuroglancer link
get_synapse_counts(root_ids, datastack)	Get pre/post synapse counts

CLI Examples

# Get coordinates for root IDs
python scripts/get_coords_cli.py --datastack brain_and_nerve_cord --ids 720575941471915328

# Update outdated IDs
python scripts/update_ids_cli.py --datastack brain_and_nerve_cord --with-coords

# Process Google Sheet
python scripts/sheets_coords_oauth.py --sheet "SHEET_ID" --update-ids

Tampermonkey Scripts Current

Browser userscripts to enhance WebKnossos functionality.

Available Scripts

Script	Shortcut	Function
Volume Opacity Toggle	Ctrl+Shift+O	Toggle volume layer opacity
Pattern Opacity Toggle	Ctrl+Shift+P	Toggle pattern opacity
EM Opacity Toggle	Ctrl+Shift+E	Toggle EM layer opacity
Quick Rename	Right-click	Rename segments from context menu
Keyboard Shortcuts	Various	Additional keyboard shortcuts for renaming

Installation

1. Install Tampermonkey browser extension
2. Open Tampermonkey dashboard
3. Click "+" tab or "Import from file"
4. Import the .user.js files from tampermonkey-scripts/
5. Reload WebKnossos

Debug: All scripts log to console with [WK ...] prefix. Open DevTools (F12) to see logs.

Task Handling SOP Current

Standard Operating Procedure for Ground Truth Task Management

Owner: Benjamin Silverman | Created: Nov 5, 2025

Roles

• Task Owner: Responsible for overall task coordination
• Tester(s): First to work on new task types, provide feedback
• Team Members: Execute tasks following established protocols

Workflow Phases

Key Principles

• Variability Expected: First attempts may need adjustment
• Test Before Scale: Always test with subset before full deployment
• Document Changes: All protocol changes must be recorded
• Inclusive Communication: All team members should be informed of changes

Protocol Guidelines Current

Source: Tommy Macrina's Directives (August - September 2025) via #putracers Slack

Mitochondria Segmentation

1.1 Individual Segmentation Required

Each mitochondrion must be assigned a separate segment ID and color. Do not paint all mitochondria with the same segment.

1.2 Oversegmentation Directive

The original task description stating "do NOT oversegment mitochondria" was incorrect and should be disregarded. Mitochondria must be oversegmented individually.

1.3 Membrane Handling

Do NOT paint mitochondrial membranes. Leave a visible border/gap around each mitochondrion to represent the membrane boundary.

Myelin Segmentation

2.1 Inner Boundary (Cell Interface)

No padding between myelin and the cell it ensheathes. The myelin segment should directly contact the inner cell.

2.2 Myelin-to-Myelin Contact

No padding between adjacent myelin segments. Myelin segments may touch each other.

2.3 Outer Boundary (Adjacent Cells)

Myelin should approach but not touch the membranes of neighboring cells. Maintain a small gap between myelin exterior and other cell membranes.

Summary: Inner = touch cell, Middle = touch other myelin, Outer = gap from neighbors

Upsampled Image Handling

3.1 Two-Pass Labeling Approach

Recommended workflow:

1. First pass: Paint annotations on the original image (thicker sections)
2. Second pass: Copy labels onto the upsampled image and connect objects naturally

3.2 Multi-Resolution Viewing

Working exclusively from upsampled images can be misleading. Always cross-reference with original image data.

3.3 Handling Artifacts ("Hallucinations")

Artificial structures in upsampled data should be ignored. Focus on anatomically sensible structures. From spot checks, tracers have done well ignoring hallucinations.

Ambiguous Cases & Edge Cases

4.1 Uncertain Organelles

When uncertain whether an object is a mitochondrion (vs. peroxisome, lysosome, etc.), segment it as a mitochondrion. Objects can be removed during review if needed.

4.2 EM Damage Regions

For EM damage handling:

• If damage is inside the segment, label it as the segment it's in
• If damage is on the border, follow team consensus for handling

WebKnossos Tools & Techniques

6.1 Interpolation Tool

The volume interpolation feature is particularly useful for objects perpendicular to the sectioning plane in higher z-resolution data. May require manual cleanup. Works best with:

• Large, simple round segments with minimal movement between slices
• 2 slice gaps (5-6 slice gaps may cause confusion with size changes)

6.2 3D Mesh Visualization

• Right-click on any segment to generate a 3D mesh
• Press . (period) to toggle between all views and view under cursor
• Useful for quality control and identifying errors

6.3 SAM2 AI Segmentation (Experimental)

New AI-assisted segmentation available on experimental server (ranl.zetta.ai:9000):

• Most effective for larger, convex cross-sections without many intercellular objects
• Adjust confidence threshold and erosion parameters for optimal results
• Can use existing segment annotations as hints for consistency

Verification Procedures Current

Mandatory Peer Review

Before marking tasks as finished, at least one other team member must inspect your work. Prioritize sharing areas where you struggled.

Sharing Annotations for Review

1. Navigate to Tasks in WebKnossos
2. Search for tasks under the relevant project
3. Click the plus symbol (+) for the task
4. Select "Actions" button (right side)
5. Choose "View"

Verification Checklist

• Cell segmentation complete (use VAST/Omni inspection)
• Borders checked for accuracy
• No mergers or splitters
• No missing segments
• Synapse labeling verified
• Mitochondria properly labeled
• Semantic segmentation complete
• Vesicle clouds labeled
• Myelin properly segmented

Ground Truth Checklist Current

Extracellular Space & Boundaries

• Use 1 segment for all extracellular space
• Use 1 segment for objects that connect 20 slices outside the boundaries
• Parallel plane boundaries should be given the area they need - careful not to over-color them and allow space for the boundary
• When segmenting thin lines of glial or extracellular space, it's ok to bend the parallel boundary rule and segment darker than normal areas (so long as you believe they are part of those objects)

Invaginations & Internal Objects

• Be cognizant of invaginations - use a keen eye when investigating internal objects such as organelles/ER
• Keep an eye on the borders of your volume and always check for small segments that just barely pass by - these are important and should be segmented

Dust, Defects & Fat Globules

• If dust/defects are (nearly) fully contained within a single cell, then color over them
• If dust/defects span multiple cells and are small enough that it's easy to draw an imaginary boundary between the involved cells, then do so
• If they are large enough that drawing an imaginary boundary is not easy, create a separate "defect mask" that can safely cover the dust or defects
• For fat globules (or ER-membrane swirling), color them separately and as accurately as possible

Myelin & Special Structures

• Myelin should be its own segment
• Always check with the project leader when you have questions and keep a collection of images to help illustrate tough areas you want clarification for
• Be mindful that these rules change - it's always a good idea to ask for help if you aren't sure about something

Task Verification Procedures Current

How to verify ground truth tasks - Seung Lab

Cell Segmentation - VAST Inspection

1. Check borders: Spend a few minutes cycling up and down through the stack to get a sense of how accurate the coloring is close to the borders. If there's significant bleeding (coloring over the border) or undercoloring (not coloring all the way to the border), make a note of the affected segments.
2. Check for mergers & splits: Inspect each segment one-by-one: select a segment, then scroll through the relevant portion of the stack. If a segment is improperly joined with another segment, make a note. If a segment is not properly merged with another segment, make a note.
3. Check for missing segments: Cycle through the entire stack paying careful attention to areas without any segments. If there's a segment that was missed, make a note of it.
4. Decide whether to verify:
   • If there are no border issues, no mergers or splits, and no missed segments - verify the task. Let the original annotator know they did a good job.
   • If there are issues - do not verify the task. Let the original annotator know where they need to make corrections.

Cell Segmentation - Omni Inspection

Cycle through all segments and inspect that for each:

• Check that it doesn't contain a merge error
• Check that it's not part of a split error
• Check that there's no undercoloring
• Check that there's no overcoloring
• Check that there's no hanging pixels that weren't erased completely
• Check that well-identified neighboring segments aren't totally skipped

Other Task Types (To Be Documented)

• Synapse labeling
• Mitochondria labeling
• Semantic segmentation
• Vesicle cloud labeling
• Myelin labeling

Appeal Process

If you disagree with verification feedback, acquire assistance from a Verified Researcher for a second opinion.

Synapse Annotation Training

Synapses are identified by vesicle clouds and synaptic clefts. Key structures:

Presynaptic Side (Axon)

• Contains vesicle clouds (clusters of small dark circles)
• T-bar structures (fly synapses)
• Active zone at membrane

Postsynaptic Side (Dendrite)

• Postsynaptic density (PSD) - dark line along membrane
• Spine or trunk structure

Neuroglancer Synapse Workflow

Step-by-step guide for synapse annotation in Neuroglancer

Action	Control	Description
Focus view on point	Right Click	Centers the view on clicked location
Rotate/Move view	Left Click	Rotates in 3D, drag and move in 2D
Zoom	Ctrl+Scroll	Zoom in/out
Place/Erase Synapse	Hold Ctrl+Left Click	Place or remove synapse points
Highlight Segment	Double Left Click	Highlight the selected segment
Toggle Alpha	2	Toggle transparency
Scroll EM slides	Scroll Wheel	Navigate through slices
Step through slides	. and ,	Individual slice navigation

Annotation Procedure

1. Inspect AI annotations first: Review each synapse the AI identified to make sure they were properly labeled and points are well placed
2. Always annotate Axon first: Red point places first (presynaptic), blue point second (postsynaptic). Axon = Red, Dendrite = Blue
3. Navigate to synapses: Use the "Synapses" dropdown menu at the top to quickly jump to each annotation, or right-click on them in 2D or 3D
4. For Axons: Look at the 3D mesh and focus on any boutons - boutons may have more than one synapse
5. For Dendrites: First look through all visible spine heads in the 3D mesh, then scroll through the 2D EM stack to find any synapses along the trunk the AI might have missed
6. Save your work: Hit "Save edges" when confident all synapses are correct, then "Next Segment"
7. Non-neuronal structures: If you find glia, blood cells, or other non-neuronal structures, click "Delete All Points" from the Synapses menu, then save

Synapse Identification Tips

• Look for vesicle clouds first - they indicate presynaptic terminals
• Find the synaptic cleft (gap between cells)
• Identify the PSD on the postsynaptic side
• For fly synapses, look for T-bar structures
• Use 3D mesh to verify connectivity

The Four Synapse Indicators

Synapses have 4 indicators, one of which is mandatory:

Indicator	Required?	Description
Dense cluster of vesicles	MANDATORY	Primary indicator - must be present
PSD (Postsynaptic Density)	2 of 3 needed	Dark line on dendrite side
Synaptic cleft	2 of 3 needed	Gap between cells
T-bar	2 of 3 needed	Structure in fly synapses

Synapse Types (Benjamin D. Silverman Classification)

Classic Synapse

Standard synapse structure with:

• Red = PSD
• Dark Blue = Spine head/dendrite
• Green dots = Vesicles
• Light Purple = Axon

Hand Type Synapse

Contiguous synapse where multiple PSDs share the same structure but are not continuous. All PSDs should be given the same segment ID if they connect to the same PSD within another slice.

Little Straggler Synapse

No PSD visible due to how slices were cut. The PSD is not shown even though you can tell it's a synapse. Cannot label these - you'll encounter these often once you develop an eye for synapses.

Pancake Synapse

Axon infiltrated by spine head - spine acts like a "hat" to the axon. PSD is squished and wider than normal. Annotate in a wide manner.

Slide Synapse

Axon synapsing with the shaft/trunk of a dendrite (not the spine). Even if PSD is split across slices, they are still one segment ID.

PSD vs Surfacing Neuron Shadow

PSDs and surfacing neuron shadows can look similar. Key differences:

• In a synapse, the darkened area is in the dendrite/postsynaptic body, not the axon
• Surfacing neurons lack the mandatory vesicle cluster indicator
• Check for synaptic cleft and T-bar to confirm

T-Bar Variations (Fly Synapses)

• Short T-Bars: Sometimes just dots
• Long T-Bars: Can "travel" across slices
• Longer T-bars are easier to identify

Vesicle Types

• Dense vesicles: Loads of tightly packed vesicles
• Sparse vesicles: Few vesicles (1-6) usually near boundaries - keep keen eye out for these!

PSD Tracing Guidance

When tracing a PSD, trace about halfway through to the boundary. Do not trace beyond the dark line cutting across like a "hamburger-style roll."

Vesicle Tracing Training

Vesicle Tracing Procedure

1. Setup: Open VAST, the EM you want, and create a new segmentation
2. Enable tools: Set auto-fill (checkbox labeled "Fill") and conditional painting (both in right-side options)
3. Set range: Good range for conditional painting is 0.00 - 0.34
4. Find clouds: Look for vesicle clouds and find the associated synapse
5. Skip orphans: If a cloud has no synapse, there is no need to trace it
6. Trace completely: Trace the whole cloud as long as it's continuous
7. Watch boundaries: Be careful of boundaries and other organelles that might get caught in conditional tracing

Vesicle Reviewing Procedure

1. Open the corresponding synapse segmentation for your EM volume
2. Check how many synapses have been traced vs how many vesicle clouds have been traced
3. If either segmentation has fewer segments, try to locate where you missed one (cloud or cleft)

Semantic Segmentation Training

Semantic labeling assigns meaningful categories to segments. This procedure creates ground truth semantic segmentations for ML training.

Workflow

1. Create and open the project in Omni (refer to How To VAST document on creating an Omni file from a VAST file)
2. Check the segment ID numbering - if IDs don't increment with size ordering, notify the project owner
3. Once confirmed, create a Google Sheet named appropriately for the dataset
4. In that sheet, list the classifiers for each segment ID
5. Go through the segment list and determine the classification for each
6. Record the classifier code for each segment

Standard Classification Codes

Code	Category	Description
0	Undefined	Not yet classified
1	Soma	Cell body
2	Axon	Presynaptic neuronal process
3	Dendrite	Postsynaptic neuronal process
5	Glia	Glial cells (astrocytes, etc.)
6	Unknown	Unable to classify with confidence
7	Epithelial Cell	Glia surrounding blood vessel
8	Blood Vessel	Vasculature
9	Myelin Sheath	Cell membrane of myelinated axon
99	Not Present	Segment not visible in volume

VAST Deprecated

Volume Annotation Software Tool - earlier annotation tool used for vesicle tracing and segmentation.

VAST Checklist

1. Save EM VAST file in root directory as [root folder name].vsv (e.g., Vol001_Raw.vsv)
2. Save VAST annotation file as [rootfoldername]_[annotation task type].vsseg
3. Save your work as you go along
4. Have your annotation reviewed (see verification policy)
5. Export with properties: .TIF (uncomp.), 24bit/px RGB-encoded, check "collapse labels as in current view"
6. Save images in directory named for annotation task type
7. Notify project owner that annotation has been exported
8. If cell segmentation, have project reviewed in Omni
9. Correct any errors reviewer catches
10. Re-export & re-omnify if necessary

VAST Workflow

Import EM Images

1. Go to File → Import EM Stack From Images
2. Navigate to project folder and enter the Raw folder
3. Select all .TIF images and hit Open
4. Hit OK to the pop-up windows
5. Save the EM file in the Raw folder with root folder name

Begin Segmentation

With fresh EM imported, hit the pencil button under File dropdown. Hit OK. Begin painting.

Welding and Collapsing Labels

To combine segments with different IDs: Drag segment 6 and drop it into segment 112 (or vice versa). This creates a segment sub-tree. Right-click parent segment → "weld segment sub tree" OR weld at export phase.

Exporting

1. Go to File → Export
2. Select .TIF (uncomp.) and 24bit/px RGB-encoded
3. Check "collapse labels as in current view"
4. Browse to the Segmentation folder and save

VAST Synapse Annotation & Review

Annotation

1. Begin new VAST project in desired dataset
2. Click pencil icon to spawn 16 new segments
3. Name segments for: cleft, axon/presynaptic site, dendrite/postsynaptic site, uncertain clefts
4. Trace all synaptic clefts, denoting pre/postsynaptic sites

Review

1. Open VAST project to review
2. Check segment by segment
3. Look for missed synapses using alpha adjustment
4. Cross-reference with vesicle cloud annotations if available

Omni Deprecated

Desktop annotation and proofreading software for 3D neuron reconstruction.

Omni Quick Start

1. Click the cursor button
2. Click either "two rectangles" (2D+3D) or "multicolored square" (all views)
3. Left-click segmentation1 in the left panel
4. Set Global Threshold (0.750-0.600 typical)
5. Set Auto Spread Threshold (0.350-0.500 typical)
6. Begin construction, joining, and validation of segments

Tracing Workflow

1. Left-click segment with largest Total Size in Working Tab
2. Press C to center on selected segment
3. Look for missing branches, pieces, spines, nubs, dust, mergers
4. Press J to Join All
5. Press V to Validate and move to Valid Tab

Omni Key Controls

Action	Control
Center on segment	C
Join All	J
Validate	V
Undo	Ctrl+Z
Deselect all except clicked	Ctrl+Right-click
Deselect only clicked	Ctrl+Shift+Right-click

Omni Troubleshooting

Auto Save

Omni saves what you "Join" and "Split". Periodically Join All to protect against crashes.

Crashes & Freezes

• If Omni won't close conventionally, use htop command in terminal
• Find Omni in process list (look for red numbers in VIRT column)
• Press F9 then Enter to kill

Common Issues

• If accidentally deselect everything: Ctrl+Z to undo
• Sometimes freezes resolve by waiting 1-2 minutes
• Moving/minimizing Omni window may unfreeze it

Omni Glossary

Term	Definition
Dust	Little voxel bits inside large dendrites/axons that aren't essential
Merger	AI mistake where it combined two non-connecting dendrites/axons
Segment	A collection of supervoxels
Supervoxel	Polyhedral part of 3D digital image, larger than normal voxel
Spine	Small membranous protrusion from dendrite that receives axon input
Unsplittable Merger	A merger that can't be corrected by a player

Eyewire Deprecated

Citizen science neuron tracing platform - browser-based game for neuron reconstruction. Replaced by professional annotation tools.