feat: image↔source mapping regions, clumps, subplot_mappings (P1)

[Jammy2211]

Closes #515. Phase 1 of the image-source-mappings epic (PyAutoMind ledger draft/feature/autoarray/image_source_mappings_epic.md).

Summary

Restores image-plane ↔ source-plane mapping visualization, which was hollowed out by 0cb75ebd (2025-07-21) and the 2026-03 plotter removal: subplot_mappings had been computing peak source pixels and discarding them. This PR adds plotting-agnostic mapping objects, source clump finding on the mesh, a generic arcsec-polygon regions= overlay, and rewrites subplot_mappings as the one-look figure of how each bright source clump maps to its multiple images, colour-matched across both planes.

• New autoarray/inversion/mappings/ package: ImageRegion (one connected image-plane region: slim indexes, mask, arcsec boundary loops, centre, area(), brightest_coordinate_from, centroid_from, flux_from) and Mapping (source pixels + source polygons + the image regions they map to); helpers for mesh-graph connected components, image regions from the mapping matrix, and pixel-edge boundary tracing.
• Inversion.source_clumps_from / Inversion.mappings_from: threshold × max, connected components over Mapper.neighbors, min-pixel filter, brightest-first, explicit pix_indexes bypass. Mapper.mappings_from for bare mappers (tutorial use).
• regions / region_colors / region_alpha / region_labels on plot_array and plot_inversion_reconstruction; subplot_image_and_mapper passes them through.
• subplot_mappings rewritten (2×2, matched colours, numbered clumps). Config: total_mappings, mappings_threshold, mappings_min_pixels replace the dead total_mappings_pixels (still read as a fallback).

Design constraints honoured (see issue): image regions are built from mapping_matrix, not slim_indexes_for_pix_indexes (which returns sub-slim indexes); overlays are arcsec polygons because plot_array crops via zoom_array before drawing; Delaunay clumps are drawn as Voronoi cells.

API Changes

Additive only.

• aa.Mapping, aa.ImageRegion (new, exported from autoarray).
• Inversion.source_clumps_from(mapper_index=0, threshold=0.5, min_pixels=3, total_clumps=None, pix_indexes=None), Inversion.mappings_from(mapper_index=0, weight_threshold=0.0, **clump_kwargs).
• Mapper.mappings_from(pix_indexes, weight_threshold=0.0, min_pixels=1).
• plot_array(..., regions=None, region_colors=None, region_alpha=0.25, region_labels=None); same on plot_inversion_reconstruction; subplot_image_and_mapper(..., regions=None, region_colors=None, region_labels=None).
• subplot_mappings(inversion, pixelization_index=0, ..., threshold=None, min_pixels=None, total_clumps=None, pix_indexes=None, weight_threshold=0.0) — existing positional/keyword usage unchanged; figure content changes from a plain 2×2 to the mapping figure.
• Config visualize/general.yaml inversion: keys total_mappings, mappings_threshold, mappings_min_pixels; total_mappings_pixels deprecated (fallback for one release).

Downstream

• Workspace scripts calling subplot_mappings(inversion=..., pixelization_index=0) (autolens_workspace imaging/group/interferometer/multi_galaxy pixelization/fit.py) keep working and now produce the promised mapping figure. Prose updates land in Phase 3.
• Phase 2 (PyAutoLens: ShapeSolver engine, fit-level subplot_mappings, brightest multiple-image positions) builds on ImageRegion/Mapping and must wait for this to merge and release.

Test plan

• pytest test_autoarray/inversion test_autoarray/plot — new tests for connected components, image regions from a bimodal mapping matrix, closed contours, brightest/centroid, source_clumps_from (two peaks / low threshold / passthrough / truncation / all-negative), regions= overlays, subplot_mappings rectangular + Delaunay + pix_indexes.
• Full pytest test_autoarray.
• Visual check: subplot_mappings on a two-peak synthetic reconstruction renders two colours, each clump's images outlined in the same colour in both image panels.

🤖 Generated with Claude Code

https://claude.ai/code/session_01V2ujRnmqc3jGh82hZAQ9iJ