From 65ed2d1c7988ea4052cc143a9978300241e0ff98 Mon Sep 17 00:00:00 2001 From: Jack Gallant Date: Thu, 9 Jul 2026 14:26:42 -0700 Subject: [PATCH] docs: correct the sulcus install instructions, which destroyed existing sulci The roidraw page (#656) said to "merge the fragment into the subject's overlays.svg". Doing that literally means appending a second layer -- and SVGOverlay.__init__ keys its layers by inkscape:label: self.layers[layer.name] = layer so the appended layer replaces the subject's own. Every sulcus already in that file becomes invisible to pycortex, quickflat, and the WebGL viewer. The right instruction is to copy the individual shape groups into the subject's existing #sulci_shapes group, which this adds as a warning plus a worked example. Two other corrections, both from pycortex-roidraw v0.4.1: - The export is no longer a bare fragment. It is a standalone SVG document that declares the svg and inkscape namespaces; the old fragment used the inkscape: prefix without declaring it, so no XML parser would open it. - The exported sulci_labels layer is empty, and the page now says why: pycortex derives each sulcus's label position from its path geometry at load (Shape.get_labelpos, one per path), and writes data-ptidx itself via SVGOverlay.set_coords. A element without x/y made Labels.__init__ raise TypeError on float(text.get('x')). Docs-only. Every API call in the new example was checked against the source: db.get_overlay(subject), SVGOverlay.__getattr__ -> svg.sulci, Overlay.__getitem__ -> svg.sulci['CS'], and make_figure(..., with_sulci=True). Co-Authored-By: Claude Opus 4.8 --- docs/roidraw.rst | 68 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 11 deletions(-) diff --git a/docs/roidraw.rst b/docs/roidraw.rst index 30bb5e56..1d643dc9 100644 --- a/docs/roidraw.rst +++ b/docs/roidraw.rst @@ -8,8 +8,8 @@ stroke is fitted to a smooth, re-editable bezier curve, drawn as a colored outli 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. +JSON vertex set. Sulci are **open** curves that carry no vertex data and export as a standalone SVG +whose ``sulci`` layer is 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. @@ -23,8 +23,8 @@ to **any** pycortex viewer — a static ``make_static`` export or a freshly gene 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. + by pycortex's own machinery (``quickflat``'s sulci overlay, the WebGL viewer, Inkscape) once + their shape groups are copied into a subject's overlay file — see :ref:`installing-drawn-sulci`. Adding it to a viewer --------------------- @@ -76,15 +76,61 @@ vertex indices, an ordered boundary ring, a label vertex, and the editable bezie 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. +**Export sulci (SVG)** writes a standalone ``sulci.svg`` document whose ``sulci`` layer is in +pycortex's own overlay format: open, unfilled ```` elements, 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. 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. +display geometry. The ``sulci_labels`` layer is deliberately left empty — pycortex derives each +sulcus's label position from its path geometry when the overlay is loaded, so no label needs to be +written. Sulcus export is one-way: sulci are not re-imported from SVG. + +.. _installing-drawn-sulci: + +Installing drawn sulci into a subject +------------------------------------- + +.. warning:: + + Copy the ```` groups out of the exported file's ``sulci_shapes`` group and + into the **existing** ``sulci_shapes`` group of the subject's ``overlays.svg``. + + Do **not** append the whole ```` layer. ``SVGOverlay`` keys its layers by + ``inkscape:label``, so a second layer labelled ``sulci`` replaces the subject's own in + ``SVGOverlay.layers`` — every sulcus already in that file becomes invisible to pycortex. + +So, given an exported ``sulci.svg`` containing a group for the central sulcus: + +.. code-block:: xml + + + + + + + + + + + + + + + + +paste that one ```` group inside the subject's own +````, alongside the sulci already there. Then:: + + import cortex + svg = cortex.db.get_overlay('S1') + svg.sulci['CS'] # the drawn sulcus, parsed + cortex.quickflat.make_figure(volume, with_sulci=True) + +The paths' coordinates are already in the overlay's own coordinate system, so nothing needs to be +rescaled. Inkscape can also open the exported file directly. Full documentation ------------------