From b88159ec6eed3b4b2a3c9e6eebdd6dc2dab29ebd Mon Sep 17 00:00:00 2001 From: Jack Gallant Date: Thu, 9 Jul 2026 00:47:07 -0700 Subject: [PATCH 1/2] docs: document in-browser sulcus drawing pycortex-roidraw v0.4.0 draws sulci as well as ROIs. Unlike its ROI vertex-set JSON, sulci export as overlays.svg markup -- open, unfilled paths in a sulci layer, one inkscape-labeled group per name, same-named strokes merged one path per hemisphere. So drawn sulci ARE read by pycortex's own machinery once the fragment is merged into a subject's overlay file, which the note now says. Co-Authored-By: Claude Fable 5 --- docs/roidraw.rst | 89 ++++++++++++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 34 deletions(-) diff --git a/docs/roidraw.rst b/docs/roidraw.rst index eb4e169f..30bb5e56 100644 --- a/docs/roidraw.rst +++ b/docs/roidraw.rst @@ -1,11 +1,15 @@ -In-browser ROI drawing -====================== +In-browser ROI and sulcus drawing +================================= `pycortex-roidraw `_ is a drop-in add-on that -lets you draw, edit, and export ROIs directly in a pycortex WebGL viewer — no Inkscape and no -re-generation of the viewer required. You lasso a region on the flattened cortical surface; the -stroke is fitted to a smooth, re-editable bezier curve, drawn as a white outline and label baked -into the surface, and exported to a portable JSON file. +lets you draw, edit, and export ROIs and sulci directly in a pycortex WebGL viewer — no Inkscape +and no re-generation of the viewer required. You draw on the flattened cortical surface; the +stroke is fitted to a smooth, re-editable bezier curve, drawn as a colored outline and label baked +into the surface. + +ROIs are **closed** curves that carry per-hemisphere vertex membership and export to a portable +JSON vertex set. Sulci are **open** curves that carry no vertex data and export as an +``overlays.svg`` fragment — the same representation pycortex already uses for sulci. It ships as a single self-contained bundle (``roidraw.bundle.js``, CSS included) that can be added to **any** pycortex viewer — a static ``make_static`` export or a freshly generated dynamic viewer. @@ -18,6 +22,10 @@ to **any** pycortex viewer — a static ``make_static`` export or a freshly gene ``get_roi_masks`` and friends. Use it for quick interactive annotation in the viewer; use the Inkscape workflow when you need ROI masks in the pycortex Python API. + Drawn **sulci** are different: they are exported as ``overlays.svg`` markup, so they *are* read + by pycortex's own machinery (``quickflat``'s sulci overlay, the WebGL viewer, Inkscape) once the + fragment is merged into a subject's overlay file. + Adding it to a viewer --------------------- @@ -35,35 +43,48 @@ Adding it to a viewer integration. The project also provides a ``bake.py`` helper that injects the bundle and the two script tags into an existing static viewer non-destructively. -Drawing and editing ROIs ------------------------- - -A **Display / Draw** toggle is added at the top of the viewer. Switch to **Draw** and the brain -flattens and an ROI panel appears. - -============== ============================================================================ -Gesture Action -============== ============================================================================ -drag Lasso a region, name it, and fit it to a smooth bezier drawn on the surface -scroll wheel Zoom (to draw fine detail) -shift + drag Pan the surface -shift + click Inspect the voxel under the cursor -esc Cancel the current lasso (or finish editing) -============== ============================================================================ - -Click **✎ edit** next to an ROI in the panel to reveal its bezier anchors and tangent handles: +Drawing and editing +------------------- + +A **Display / Draw** toggle is added at the top of the viewer. Switch to **Draw**: the brain +flattens and a draw panel appears. A ``ROI | Sulcus`` selector at the top of the panel chooses what +a plain drag draws. + +================= ========================================================================= +Gesture Action +================= ========================================================================= +drag (ROI) Lasso a region, name it, and fit it to a smooth closed bezier +drag (Sulcus) Trace along the sulcus, name it, and fit it to a smooth open bezier +scroll wheel Zoom (to draw fine detail) +shift + drag Pan the surface +shift + click Inspect the voxel under the cursor +esc Cancel the current stroke (or finish editing) +================= ========================================================================= + +Click **✎ edit** next to any shape in the panel to reveal its bezier anchors and tangent handles: drag anchors and handles to reshape the curve, double-click the curve to insert an anchor, -double-click an anchor to toggle smooth/corner, and press ``Delete`` to remove one. Vertex -membership is re-derived from the bezier on every change, so the exported vertex set always -matches the curve you see. - -Export format -------------- - -The panel's **Export JSON** button writes a ``rois.json`` file holding, per ROI, the -per-hemisphere subject vertex indices, an ordered boundary ring, a label vertex, and the editable -bezier (control points in view-independent flat-UV coordinates). It re-imports — here or in any -viewer on the same surface — to the exact same outline, ready to re-edit. +double-click an anchor to toggle smooth/corner, and press ``Delete`` to remove one. An open curve's +endpoints show a single handle each and are always corners. For an ROI, vertex membership is +re-derived from the bezier on every change, so the exported vertex set always matches the curve you +see; a sulcus has no membership, and its label instead follows the curve. + +Export formats +-------------- + +**Export ROIs (JSON)** writes a ``rois.json`` file holding, per ROI, the per-hemisphere subject +vertex indices, an ordered boundary ring, a label vertex, and the editable bezier (control points +in view-independent flat-UV coordinates). It re-imports — here or in any viewer on the same +surface — to the exact same outline, ready to re-edit. + +**Export sulci (SVG)** writes a ``sulci.svg`` fragment in pycortex's own overlay format: open, +unfilled ```` elements in a ``sulci`` layer, one inkscape-labeled group per named sulcus. +Trace a sulcus on each hemisphere and give both strokes the same name, and they merge into a single +group with one ```` per hemisphere — exactly how a hand-authored sulcus such as ``CaS`` is +stored. Merge the fragment into the subject's ``overlays.svg`` and ``quickflat``, the WebGL viewer, +and Inkscape all read it. + +Sulci carry no vertex data, matching pycortex: there is no ``get_sulci_verts``, and sulci are +display geometry. Sulcus export is one-way — they are not re-imported from SVG. Full documentation ------------------ From be24e546056bf1b831790aa7af0c700656bfd738 Mon Sep 17 00:00:00 2001 From: Jack Gallant Date: Thu, 9 Jul 2026 00:47:25 -0700 Subject: [PATCH 2/2] docs: refresh the rois.rst cross-link title The seealso block hardcoded the roidraw page's old title as link text. Co-Authored-By: Claude Fable 5 --- docs/rois.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rois.rst b/docs/rois.rst index b9593059..e0444369 100644 --- a/docs/rois.rst +++ b/docs/rois.rst @@ -5,6 +5,6 @@ pycortex supports a method of defining surface ROIs using Inkscape. The ROIs are .. seealso:: - To draw ROIs interactively in the WebGL viewer (without Inkscape), see - :doc:`In-browser ROI drawing `. + To draw ROIs and sulci interactively in the WebGL viewer (without Inkscape), see + :doc:`In-browser ROI and sulcus drawing `.