tracertools — Function Catalog
A jump-board for the functions in Jay Gager's tracertools Python library. Find a tool for a task, then follow the source link for its full definition, arguments, and examples.
tracertools is Jay Gager's utility library for connectomics proofreading — a collection of Python functions that wrap CAVE, cloudvolume/cloudfiles, neuroglancer (Spelunker), and gspread for common tasks against datastacks like BANC, FlyWire/FAFB, and others. Install it editable (pip install -e .) and import it as import tracertools as tt, then call functions like tt.get_current_seg_ids(...).
Upstream repo: github.com/jaybgager/tracertools. Ben keeps a synced fork at github.com/BunPrinceton/tracertools.
This page is a catalog / jump-board only — a one-line description plus a source link per function. The GitHub README has the robust descriptions, argument tables, worked examples, and a glossary of terms. All functions live in a single module, src/tracertools/utils.py (re-exported by __init__.py), so every source link points into that file at the function's line.
Not the same as the experimental _ben variants. These are the canonical tracertools functions maintained by Jay. Ben's experimental scripts and modified _ben variants live in a separate repo, BunPrinceton/tracer-tools-extensions, and are catalogued on the Experimental Tools page.
get_ family · 22 functions
Read-only lookups — pull segment IDs, skeletons, meshes, synapse/volume metrics, CAVE tables, datastack metadata, and the tracer-format config for a datastack.
| Function | Description | Source |
|---|---|---|
get_anno_array_from_state_file | Numpy array of point coordinates from a point-annotation layer in a local neuroglancer JSON state file. | source ↗ |
get_bones | Viewer-resolution endpoint pairs ("bones") for each edge of a nanometer-resolution osteoid skeleton. | source ↗ |
get_cable_lengths | Total skeleton edge length (cable length) for each segment in a list. | source ↗ |
get_cave_stacks | List of all datastacks currently available through the CAVE service. | source ↗ |
get_cave_stack_info | Official published metadata dictionary for a datastack. | source ↗ |
get_cave_stack_tables | List of all backend CAVE tables available for a datastack. | source ↗ |
get_cave_table | Full data for a CAVE table as a pandas DataFrame. | source ↗ |
get_cave_table_info | Metadata dictionary for a specific CAVE table. | source ↗ |
get_config | Tracer-format config dictionary for a supported datastack (resolutions, table/column names, source URLs, viewer defaults). | source ↗ |
get_current_seg_ids | Best-guess current IDs for a list of stale segment IDs, tracked through splits/merges via supervoxels. | source ↗ |
get_json_state_from_url | Neuroglancer JSON state (as a Python dict) derived from a shortened share URL. | source ↗ |
get_mesh_triangles | (n,3,3) array of face-vertex coordinates for a precomputed neuroglancer mesh in a volume. | source ↗ |
get_original_seg_ids | IDs of all segments that contributed pieces to a segment's current version. | source ↗ |
get_roots_from_points | Segment (or supervoxel) IDs at a list of point coordinates. | source ↗ |
get_seg_3d_volume | 3D volume of a segment in cubic micrometers, summed from its L2 nodes. | source ↗ |
get_seg_changelog | Official CAVE tabular changelog for a segment as a pandas DataFrame. | source ↗ |
get_seg_details | Current ID, 3D volume, cable length, and synapse count for each segment in a list. | source ↗ |
get_seg_edits | Tracer-format edit history for a segment as a DataFrame (one row per edit). | source ↗ |
get_seg_from_sv | Current segment ID that a known supervoxel belongs to. | source ↗ |
get_seg_skeletons | Osteoid-format skeleton objects for a list of segment IDs. | source ↗ |
get_svs_from_seg | All supervoxel IDs belonging to a segment. | source ↗ |
get_supported_configs | Names of all datastacks that have a tracer-format config (see get_config). | source ↗ |
make_ family · 11 functions
Constructors — build neuroglancer links and annotation layers, generate meshes/OBJs/point clouds from annotations, and package precomputed volumes (local or on a bucket).
| Function | Description | Source |
|---|---|---|
make_anno_layer | Build a neuroglancer-format annotation-layer dictionary from a list of annotations (point, line, etc.), optionally linked to segments. | source ↗ |
make_bucket_volume_from_obj | Convert a local OBJ into a legacy-format precomputed neuroglancer mesh volume on a remote cloudfiles bucket. BANC only | source ↗ |
make_color_list | Generate N visually distinct, eye-friendly hex colors spaced around the color wheel (for coloring segments/layers). | source ↗ |
make_edits_link | Neuroglancer link showing all edits for a segment as line annotations, plus the current segmentation (cyan) and largest original ancestor (red). | source ↗ |
make_local_volume_from_obj | Build a legacy-format single-resolution precomputed neuroglancer mesh volume from an OBJ, stored on your local machine. | source ↗ |
make_mesh_from_points | Build a mesh from a set of points — convex hull or alpha-shape shrinkwrap (uses internal _alpha_shape_3d helper). | source ↗ |
make_ng_link | Generate a neuroglancer link for a config-supported datastack, optionally adding segment IDs and extra layers. | source ↗ |
make_objs_from_state_file | Convex-hull OBJ meshes generated from every point-annotation layer in a local JSON state file (one OBJ per layer). | source ↗ |
make_point_cloud_from_state_file | Point-cloud OBJ file from a point-annotation layer in a neuroglancer JSON state file. | source ↗ |
make_volume_mesh_from_state_file | Convex-hull precomputed neuroglancer mesh volume from a point-annotation layer. not Windows-safe | source ↗ |
make_volume_packaging | Create the local folder/file structure (an image folder) to hold a neuroglancer volume; used by other make_ functions. | source ↗ |
bucket_ family · 10 functions
Remote storage — read from and write to cloudfiles-managed buckets (upload, download, move, rename, delete, copy). Write operations need write access to the bucket.
| Function | Description | Source |
|---|---|---|
bucket_convert_colons | Convert colons in file names to a Windows-safe placeholder (___) and back — needed for legacy neuroglancer mesh volumes. | source ↗ |
bucket_copy_folder | Copy a folder and its contents from one location on a bucket to another. | source ↗ |
bucket_delete_file | Delete a single file on a bucket. | source ↗ |
bucket_delete_folder | Delete a folder and everything in it; prompts for a typed confirmation before deleting. | source ↗ |
bucket_download_file | Download a file from a bucket to a local folder (defaults to ~/Downloads). | source ↗ |
bucket_download_folder | Download a whole folder and its contents from a bucket to a local folder. | source ↗ |
bucket_move_file | Move a file between folders on a bucket. | source ↗ |
bucket_rename_file | Rename a file in place on a bucket. | source ↗ |
bucket_upload_file | Upload a local file to a bucket folder, creating folders as needed. | source ↗ |
bucket_upload_folder | Upload a local folder and its contents to a bucket (last path segment names the destination folder). | source ↗ |
calc_ family · 6 functions
Spatial math — distances, centroids, bounding boxes, and line/skeleton-vs-mesh intersection geometry.
| Function | Description | Source |
|---|---|---|
calc_3d_distance | Euclidean distance between two 3D points at a given voxel resolution. | source ↗ |
calc_avg_point_coords | Average (centroid) coordinates of a list of points. | source ↗ |
calc_bbox_corners_from_center | Corner coordinates of a bounding box from a center point and x/y/z dimensions. | source ↗ |
calc_line_triangle_intersect | Intersection point of a line segment and a triangular plane (Möller–Trumbore), or None. | source ↗ |
calc_seg_mesh_intersect | Whether (or where) each segment's skeleton intersects a given neuroglancer mesh. | source ↗ |
calc_skeleton_mesh_intersect | All points where a skeleton's bones intersect a mesh's triangles (or None). | source ↗ |
gsheet_ family · 5 functions
Google Sheets I/O via gspread. All require an OAuth token set up beforehand (see the README's Google Sheet Functions note).
| Function | Description | Source |
|---|---|---|
gsheet_add_column | Append a list as a new column (first empty column) to a Google Sheet tab. | source ↗ |
gsheet_add_row | Append a list as a new row (first empty row) to a Google Sheet tab. | source ↗ |
gsheet_add_seg_details | Compute neuron details (volume, cable length, synapse counts, proofread status) for segment IDs in a sheet and write them back. | source ↗ |
gsheet_get_col_as_list | Read a column from a Google Sheet tab as a Python list. | source ↗ |
gsheet_get_tab_as_df | Read a Google Sheet tab as a pandas DataFrame. | source ↗ |
check_ family · 2 functions
Boolean status checks over a list of segment IDs.
count_ family · 2 functions
Tallies over segments — synapses and per-user supervoxel contributions.
triage_ family · 1 function
Proofreading triage against known rough-data regions ("swamps").
| Function | Description | Source |
|---|---|---|
triage_segs | Skeletonize a list of segments and flag those passing through known rough spots for a datastack. WIP / nonfunctional | source ↗ |
Other utilities · 3 functions
Single-function verbs that don't share a family: coordinate conversion, local hosting, and skeleton visualization.
| Function | Description | Source |
|---|---|---|
convert_coord_res | Convert a point's coordinates between two voxel resolutions. | source ↗ |
host_ng_volume_locally | Locally serve a precomputed neuroglancer volume for testing. | source ↗ |
visualize_skeletons | Render segment skeletons in a microviewer/VTK window with a cable-thickness heatmap. | source ↗ |