voxel

tit.atlas.voxel

Voxel (volumetric) atlas discovery and region listing.

VoxelAtlasManager

VoxelAtlasManager(freesurfer_mri_dir: str = '', seg_dir: str = '')

Discovers and queries volumetric atlas files.

All discovery methods use the same canonical VOXEL_ATLAS_FILES list so that the analyzer, flex-search, and NIfTI viewer show identical atlases.

Parameters:

Name	Type	Description	Default
freesurfer_mri_dir	str	Path to FreeSurfer mri/ directory.	''
seg_dir	str	Path to m2m_{subject}/segmentation/ directory.	''

Source code in tit/atlas/voxel.py

def __init__(self, freesurfer_mri_dir: str = "", seg_dir: str = "") -> None:
    self.freesurfer_mri_dir = freesurfer_mri_dir
    self.seg_dir = seg_dir

list_atlases

list_atlases() -> list[tuple[str, str]]

Discover available voxel atlas files for a subject.

Checks FreeSurfer mri/ for VOXEL_ATLAS_FILES and segmentation/ for labeling.nii.gz. Used by analyzer tab, flex subcortical tab, and NIfTI viewer.

Returns:

Type	Description
list[tuple[str, str]]	List of (display_name, full_path) tuples.

Source code in tit/atlas/voxel.py

def list_atlases(self) -> list[tuple[str, str]]:
    """Discover available voxel atlas files for a subject.

    Checks FreeSurfer mri/ for VOXEL_ATLAS_FILES and segmentation/
    for labeling.nii.gz.  Used by analyzer tab, flex subcortical tab,
    and NIfTI viewer.

    Returns:
        List of (display_name, full_path) tuples.
    """
    results: list[tuple[str, str]] = []

    if self.freesurfer_mri_dir and os.path.isdir(self.freesurfer_mri_dir):
        for name in VOXEL_ATLAS_FILES:
            path = os.path.join(self.freesurfer_mri_dir, name)
            if os.path.isfile(path):
                results.append((name, path))

    if self.seg_dir:
        labeling = os.path.join(self.seg_dir, "labeling.nii.gz")
        if os.path.isfile(labeling):
            results.append(("labeling.nii.gz", labeling))

    return results

list_regions

list_regions(atlas_path: str) -> list[str]

List regions in a voxel atlas using mri_segstats.

Caches the label file next to the atlas so subsequent calls are fast.

Returns:

Type	Description
list[str]	Sorted list of "RegionName (ID: N)" strings.

Source code in tit/atlas/voxel.py

def list_regions(self, atlas_path: str) -> list[str]:
    """List regions in a voxel atlas using mri_segstats.

    Caches the label file next to the atlas so subsequent calls are fast.

    Returns:
        Sorted list of "RegionName (ID: N)" strings.
    """
    atlas_bname = os.path.splitext(os.path.basename(atlas_path))[0]
    if atlas_bname.endswith(".nii"):
        atlas_bname = os.path.splitext(atlas_bname)[0]
    labels_file = os.path.join(
        os.path.dirname(atlas_path), f"{atlas_bname}_labels.txt"
    )

    if not os.path.isfile(labels_file):
        cmd = [
            "mri_segstats",
            "--seg",
            atlas_path,
            "--excludeid",
            "0",
            "--ctab-default",
            "--sum",
            labels_file,
        ]
        subprocess.run(cmd, check=True, capture_output=True)

    regions: list[str] = []
    in_header = True
    with open(labels_file) as fh:
        for line in fh:
            if in_header and not line.startswith("#"):
                in_header = False
            if not in_header and line.strip():
                parts = line.strip().split()
                if len(parts) >= 5:
                    name = " ".join(parts[4:])
                    seg_id = parts[1]
                    regions.append(f"{name} (ID: {seg_id})")

    return sorted(set(regions))

detect_mni_atlases staticmethod

detect_mni_atlases(atlas_dir: str) -> list[str]

Detect available MNI atlases in an assets directory.

Parameters:

Name	Type	Description	Default
atlas_dir	str	Path to the atlas resources directory.	required

Returns:

Type	Description
list[str]	List of full paths to found MNI atlas files.

Source code in tit/atlas/voxel.py

@staticmethod
def detect_mni_atlases(atlas_dir: str) -> list[str]:
    """Detect available MNI atlases in an assets directory.

    Args:
        atlas_dir: Path to the atlas resources directory.

    Returns:
        List of full paths to found MNI atlas files.
    """
    if not os.path.isdir(atlas_dir):
        return []
    return [
        os.path.join(atlas_dir, p)
        for p in MNI_ATLAS_FILES
        if os.path.isfile(os.path.join(atlas_dir, p))
    ]

find_labeling_lut

find_labeling_lut() -> str | None

Find the LUT file for the SimNIBS labeling atlas.

Returns:

Type	Description
str | None	Path to labeling_LUT.txt if it exists, else None.

Source code in tit/atlas/voxel.py

def find_labeling_lut(self) -> str | None:
    """Find the LUT file for the SimNIBS labeling atlas.

    Returns:
        Path to labeling_LUT.txt if it exists, else None.
    """
    lut_path = os.path.join(self.seg_dir, "labeling_LUT.txt")
    return lut_path if os.path.isfile(lut_path) else None