feat: allow different values per hemisphere (closes #58)

[AdityaGupta716]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

Users currently cannot visualise different values in each hemisphere — a region is treated as a single bilateral structure. This was requested in the [image.sc forum](https://forum.image.sc/t/allen-spinal-cord-atlas-is-off-axis/99539/4) for use cases like showing an injection affecting one hemisphere more than the other.

What does this PR do?

Allows users to pass a dict with "left" and/or "right" keys as a region value to visualise different colors per hemisphere:

bgh.Heatmap(
    values={
        "TH": 1.0,                             # bilateral (unchanged)
        "VISp": {"left": 0.8, "right": 0.2},  # per-hemisphere
        "MOp": {"left": 0.5},                  # left only
    },
    position=7000,
    orientation="frontal",
    format="2D",
).show()

Fully backwards compatible — scalar values behave exactly as before.

References

Closes #58

How has this PR been tested?

• 9 unit tests for the new parse_values() function covering all input combinations and error cases
• 7 integration tests covering both hemispheres, single side, mixed bilateral+per-hemisphere, 2D projection uniqueness, and backwards compatibility with existing scalar values
• All 54 tests passing, coverage at 74%
• End-to-end show() tested in both 2D and 3D modes

Implementation notes:

• Per-hemisphere regions are added as separate actors then manually cut with cut_with_plane() — bypasses brainrender's hemisphere= param which calls get_plane(), broken on numpy>=2.0
• Actors are renamed to REGION__left / REGION__right so the slicer produces unique segment keys (two actors with the same name would overwrite each other in the projected dict)
• Region names containing __ are now explicitly rejected as that pattern is reserved for internal hemisphere tracking
• vmin/vmax computed globally across all values for a consistent colormap scale

Is this a breaking change?

No. Scalar values work identically to before. The only new restriction is that region names containing __ are now rejected — no existing atlas acronym uses this pattern (verified across allen_mouse_25um, kim_mouse_25um, allen_human_500um).

Does this PR require an update to the documentation?

The values parameter in Heatmap.__init__ docstring has been updated to document the new dict syntax. A follow-up documentation PR to brainglobe.info showing a hemisphere-specific example would be useful.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality (unit & integration)
• The documentation has been updated to reflect any changes
• The code has been formatted with [pre-commit](https://pre-commit.com/)

[AdityaGupta716]

@adamltyson plz review

[codecov]

Codecov Report

❌ Patch coverage is 88.23529% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.06%. Comparing base (0fea8e1) to head (3cbceae).

Files with missing lines	Patch %	Lines
brainglobe_heatmap/heatmaps.py	88.23%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #114      +/-   ##
==========================================
+ Coverage   69.63%   73.06%   +3.43%     
==========================================
  Files           5        5              
  Lines         326      401      +75     
==========================================
+ Hits          227      293      +66     
- Misses         99      108       +9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[AdityaGupta716]

hi @adamltyson dropped the manual cutting workaround and bumped minimum to brainrender>=2.1.18. Now delegates hemisphere splitting entirely to add_brain_region(hemisphere=) directly.
Also fixed a few things found along the way:

Deprecated mpl.cm.get_cmap replaced with mpl.colormaps[name].resampled(n)
Colorbar tick labels for label_regions=True were floating without a FixedLocator — fixed
Added 22 new tests covering hemisphere cutting, plot branches, colorbar, error paths —heatmaps.py now at 97% coverage

Tested on both allen_mouse_25um and allen_cord_20um (the atlas from the image.sc thread).