feat: add cortical region boundary contours (contours parameter)

[GalKepler]

Summary

Adds a contours parameter to plot_cortical for drawing atlas region boundary lines on the surface, with support for selective regions and per-region styling.

Changes

yabplot/mesh.py

• get_region_boundaries: new region_ids filter (draw outlines for specific regions only) and smooth_iterations (Laplacian smoothing on boundary line vertices to reduce triangular jaggedness — especially useful with proc_vertices='sharp').

yabplot/plotting.py

• New contours parameter on plot_cortical (replaces earlier draft's draw_contours + contour_regions).
• _build_contour_layers() helper resolves contours into a list of (lh_mesh, rh_mesh, kwargs) render groups, allowing multiple style groups per call.
• Smoothing auto-set to 10 iterations when proc_vertices='sharp', otherwise 0 (user-overridable).

docs/tutorials/plot_styling.ipynb

• Section 5 updated with all contours forms and a sharp-mode smoothing example.

API

# all regions, default style
plot_cortical(data, atlas='schaefer400', contours=True)

# all regions, custom global style
plot_cortical(data, atlas='schaefer400', contours={'color': 'white', 'line_width': 1.5})

# only regions with data (bool mask)
plot_cortical(data, atlas='schaefer400', contours=~np.isnan(data))

# specific regions by name
plot_cortical(data, atlas='schaefer400', contours=['region_A', 'region_B'])

# per-region style (only listed regions get contours)
plot_cortical(data, atlas='schaefer400', contours={
    'region_A': {'color': 'red',  'line_width': 3.0},
    'region_B': {'color': 'blue', 'line_width': 3.0},
})

# sharp mode — contours auto-smoothed (smooth_iterations=10)
plot_cortical(data, atlas='schaefer400', contours=True, proc_vertices='sharp')

# override smoothing manually
plot_cortical(data, atlas='schaefer400', contours={'smooth_iterations': 20})

contours disambiguation

type	detection	behavior
False / None	—	no contours
True	—	all regions, default style
dict with primitive values	values are not dicts	all regions, custom style
list / bool ndarray	—	those regions, default style
dict with dict values	all values are dicts	per-region style, only listed regions

Breaking changes

None — contours defaults to False.

🤖 Generated with Claude Code

[teanijarv]

Hi Gal, this is great addition and one that has been requested before too.

I just now made a commit where i made the proc_vertices='sharp' for plot_cortical() as the default option which makes the atlas regions more sharper and visually more appealing. However, currently running the contour options on it, these lines are a bit too poor in quality (see image below). Would you be able to try to make that the lines are similarly less jagged?

And some more minor things. Could you remove the Claude.md from .gitignore and also we could discuss whether two separate contour related parameters is the best approach or there could be ways to combine them into one - I'm open to having to parameters, but as this is a feature which most won't be using, then ideally it could maybe be combined to single parameter. Besides that, I haven't yet tried it out with more options than the notebook you provided, so I'm unsure if there would be more bugs.

But again, thanks for the PR, this is great work!