Blender flattening support

[dmitry-mli]

Overview

Thank you for maintaining pycortex—i found it to be an invaluable tool for visualization of cortical data.

Please consider this PR that offers an extension the the flattening modes (+notebook, +docs, +video). Please provide your feedback and I will be happy to adjust the modification. Thank you!

cc @cmcneil @tysonnsa.

Why

1. While freesurfer mode has been used for a long time, it lacks debuggability and may require a number of iterations and a degree of patience in order to get things working. The new mode is added to timebox the flattening process by making it faster and more predictable by leveraging UV unwrap preview in Blender. This PR adds a 3rd mode of flattening that is based on Blender's UV unwrap. This mode will reduce time to flatten while producing decent quality unwraps.
2. Outdated dependencies. As I've been spinning up my flattening workflow, I kept running into dependency issues around Python, Blender, FreeSurfer with impacts ranging from just breaking to hard to debug symptoms. This PR fixes some of those and adds a new mode of flattening that relies on Blender over freesurfer.

What

• Implemented flattening logic that uses conformal UV unwrap in cortex.blender.blendlib.py. It follows the same selection as for the volume mesh. This is accessible via write_flat_patch.
  • To avoid confusion between the new flat patch write_flat_patch and the old one, renamed save_patch into write_volume_patch.
  • Renamed _get_pts_edges into _get_geometry for clarity. Added clarifying logging and elapsed time tracking. Extended docstring.
• Fix for Python 3.13+: allow blender access Python site directory to search for mda_xdrlib that was removed from Python 3.13.
• Refactored cortex.blender._call_blender to support non-code calls to Blender to reduces confusion and improves code clarity. Refactored fs_cutintofs_cut_initand added a newfs_cut_open` to improve clarity. Extended docstring.
• Rewrote cut_surface for clarity. Onboarded to recache flag to support forced generation.
• Record a tutorial video walking users through the process of cutting. Should follow the gallantlab.org approach to cutting.
• Add python notebook for the end-to-end rendering of fMRI.
• Update docs with the guidance.
  • Fixed the existing docs confusing ” and " which may result into code examples not running properly.
  • Retrofilled docs for some of the existing methods.
• Address the PR feedback.

Tutorial video

As different labs may approach cuts slightly differently, created and edited a tutorial video instruction that follows the style of gallantlab.org. The used anatomy was taken from Horikawa, T., Cowen, A. S., Keltner, D., & Kamitani, Y. (2020). The neural representation of visually evoked emotion is high-dimensional, categorical, and distributed across transmodal brain regions..

Docs update

Added a new section on the cuts. When rendered looks as follows:

[sjshim]

Tested on blender and the UV flattening works and shows up!
Please rebase your branch to main as this should address the tests that are failing.
Thank you!

[sjshim]

#577
This import statement wasn't working for me given that mda_xdrlib does not have Packer or Unpacker which is called later

[mvdoc]

@dmitry-mli I think this should be from mda_xdrlib import xdrlib. @sjshim fixed some other instances of this in #577. I'm surprised import mda_xdrlib as xdrlib worked for you within blender...mysteries of blender!

[sjshim]

The hard coded path throws errors on my Linux machine. Removing it correctly grabs path from config.

[mvdoc]

Agreed, it should be better not to hard code this and instead honor the settings in the config.cfg

pycortex/cortex/defaults.cfg

Lines 8 to 20 in c6b7de1

	[dependency_paths]
	# The following specify paths to the binary executable files
	# for external dependencies of pycortex. The default values
	# (just "inkscape" and "blender") should work on Linux,
	# since the binaries should already be on the system path if
	# blender and inkscape are installed.
	# For MacOS, unless you have done some manual configuration on
	# your own, these will need to be something like:
	# blender = /Applications/Blender/blender.app/Contents/MacOS/blender
	# inkscape = /Applications/Inkscape.app/Contents/MacOS/Inkscape
	# Windows is not currently supported.
	inkscape = inkscape
	blender = blender

but the issue here may be that these settings are not explained in the documentation...