Support arbitrary patch configurations with dynamic cut handling

[Copilot]

The template system hardcoded expectations for exactly 5 cuts with specific anatomical names (calcarine, medial1-3, temporal) and required a medial wall. This prevented creating patches for arbitrary brain regions like isolated occipital or temporal patches.

Changes

Dynamic cut extraction

• Core functions (ensure_continuous_cuts, refine_cuts_with_geodesic) now iterate over all keys in vertex_dict except reserved mwall key
• Removed hardcoded cut_names = ["calcarine", "medial1", "medial2", "medial3", "temporal"] in favor of [k for k in vertex_dict.keys() if k != "mwall"]

Flexible template processing

• merge_small_components(): Added optional max_cuts parameter (default None = keep all cuts)
• classify_cuts_anatomically(): Falls back to generic names (cut1, cut2, etc.) when anatomical classification not applicable
• identify_surface_components(): Added max_cuts and classify_anatomically parameters

Topology validation

• New validate_patch_topology() function checks single connected component, disk topology (one boundary loop), and reasonable patch size
• Returns validation status, issues list, and topology metrics

API exports

• Exported key functions in __init__.py for programmatic use: validate_patch_topology, ensure_continuous_cuts, refine_cuts_with_geodesic, etc.

Usage

from autoflatten.utils import save_json
from autoflatten import validate_patch_topology

# Create template with arbitrary cut names
template = {
    "lh_mwall": [100, 101, 102],  # optional, can be empty
    "lh_occipital_boundary": [1, 2, 3, 4, 5],
    "lh_ventral_cut": [10, 11, 12],
}
save_json("occipital_patch.json", template)

# Validate before flattening
is_valid, issues, info = validate_patch_topology(
    vertex_dict, subject="sub-01", hemi="lh"
)

Use custom template: autoflatten subject --template-file occipital_patch.json

See examples/custom_patch_example.py for comprehensive examples.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Extend template logic to allow other patches/regions</issue_title>
<issue_description>Currently we expect the template/patch to have the medial wall removed + 5 cuts as in the fully flattened cortical surface. These are three medial cuts, one temporal, and one occipital. However, this is not strictly necessary. We could be more flexible with the templates to allow arbitrary patches to be generated. For example, we could have a template for the occipital pole, a template for the temporal pole, etc. This would also allow users to create a single patch on fsaverage, which can then be applied to any subject. (We would just need to add/expose a subcommand/function to generate a json template from a patch.)

Implementing this shouldn't require too much work: just making sure that we don't hardcode expected cuts/medial walls. Plus some additional checks on the patch topology.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Extend template logic to allow other patches/regions #38

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.