Scribbler: erase brush, mask refinement, radial-subtracted panels and cross-grid mask regridding

[samlange04]

Proposal: Scribbler erase brush, mask refinement, radial-subtracted panels and cross-grid mask regridding

I have been using al.Scribbler / ag.Scribbler heavily to draw extra-galaxies and arc masks for an HST lens sample, and hit a set of limitations and defects that I have fixed in a pipeline of my own. I would like to contribute them back, and this discussion is to agree the scope before I open the pull requests (per the contribution guide).

Problems

• The Scribbler can only add to a mask. The second colour segment (2) has no meaning, so an overshooting stroke means starting over, and a saved mask can never be reopened and adjusted.
• Moving the mouse outside the image axes raises TypeError inside add_patch (xdata is None there).
• On the second GUI opened in one process the brush circle stops following the cursor, because the motion handler never requests a redraw.
• Brush resizing by a fixed pixel step makes moving between 1 px detail and thick outskirts strokes take dozens of key presses.
• A circle centred on pixel 0 is silently dropped by the rasteriser (if not center[0] treats 0.0 as missing).
• On most galaxy-scale lenses the arcs are invisible under the deflector's light until its azimuthally averaged radial profile is removed, so a mask drawn against the raw image either clips them or is drawn blind. A contaminant, on the other hand, is best judged against the real sky.
• Multi-wavelength datasets carry one mask per waveband on grids of different pixel scale (e.g. cosmos_web_ring F150W 0.03"/px vs F277W 0.06"/px), with no way to transfer a mask between them.

Proposed changes (all backwards compatible)

PyAutoGalaxy, PR 1: erase brush and mask refinement

• Segment 2 (red) becomes an ERASE brush. New mask_from() returns (proposal | added) & ~erased; show_mask() is unchanged.
• New proposal= argument: an existing boolean mask is outlined over the image and refined rather than redrawn.
• = / - resize the brush multiplicatively (default 1.4x per press, 1 px floor).
• The off-axes TypeError, the missing redraw, and the pixel-0 rasteriser bug are fixed.
• Figure build and event loop are split so the callbacks are unit-testable under Agg. New test_autogalaxy/gui/test_scribbler.py.

PyAutoGalaxy, PR 2 (after PR 1): radial-subtracted side-by-side panels and cross-grid regridding

• New autogalaxy/gui/display_util.py (pure numpy): per-radius median subtraction with an exclude mask, a 1 px mask outline, side-by-side panel compositing, and nearest-neighbour regridding of a boolean mask between uniform grids by arcsec coordinates.
• Scribbler(subtract_radial=True) shows [radial-subtracted | as-observed]; strokes on either panel fold back onto the image grid.
• Scribbler(positions=...) marks positions with dark crosses while painting.

autolens_workspace and autogalaxy_workspace (docs, one PR each per library PR)

• gui/mask.py and gui/mask_extra_galaxies.py use mask_from(), document the keys, and gain an opt-in refine-existing-mask section. The extra-galaxies guide mask grows from 3.0" to 4.0" with a note that it is better to draw too large than too small.
• Following PR 2: a multi-wavelength extra-galaxies example (mask_extra_galaxies_multi.py), an optional arc-mask GUI (mask_arcs.py), and a gui/README.md on the recommended mask-up order and where each product belongs.

Questions for maintainers

1. Is autogalaxy/gui/display_util.py an acceptable home for the regridding helper for now? Its long-term home is probably autoarray.mask, but the GUI is currently its only caller.
2. The workspace scripts will import mask_2d_regridded_from from autogalaxy.gui.display_util directly. If a re-export through autolens is preferred that is a one-line PyAutoLens change.
3. The workspace PRs depend on the library PR of the same name. Since I am contributing from forks, their CI will run against library main and fail until the library PR merges. I will open them as drafts and mark them ready once the library side is in, unless you prefer another arrangement.

The branches are ready on my forks (samlange04/PyAutoGalaxy, samlange04/autolens_workspace, samlange04/autogalaxy_workspace, branches feature/scribbler-erase-and-review and feature/scribbler-radial-panels-regrid). I will open the first PyAutoGalaxy PR now and link it here.

[samlange04]

PRs for the first step (erase brush and mask refinement) are open:

• Library: feat(gui): Scribbler erase brush, proposal outline, multiplicative brush resize PyAutoGalaxy#635
• autolens_workspace docs (draft until #635 merges): docs(gui): document the Scribbler erase brush and a refine-existing-mask route autolens_workspace#579
• autogalaxy_workspace docs (draft until #635 merges): docs(gui): document the Scribbler erase brush and a refine-existing-mask route autogalaxy_workspace#251

The radial-panels and regridding step will follow as separate PRs once these are in, since the branches build on them.

[Jammy2211]

Thanks for the write-up and the three PRs, this is a nice piece of work. I have reviewed #635 and the docs PRs; there was one visible bug (the proposal outline was drawn mirrored under the default imshow_origin: upper config) plus two small flow issues in the workspace scripts, and I pushed fixes for all of them onto your branches so you can test them directly. Details are on each PR. Once you are happy with #635 you can merge it yourself; the docs PRs I will merge after the next PyAutoGalaxy release.

On your questions:

1. autogalaxy/gui/display_util.py is fine as the home for now, provided the regridding helper is pure numpy with no GUI or matplotlib imports at module level, so it can move to autoarray.mask later without touching callers. When PR 2 lands I would like the regridding function to take and return plain boolean arrays plus (shape, pixel_scales, origin) per grid rather than Mask2D objects, for the same reason.
2. Please add the re-export. Workspace scripts speak al. / ag., and a direct from autogalaxy.gui.display_util import ... in autolens_workspace would be the only import of its kind there. One line in autogalaxy/__init__.py next to Scribbler and the matching line in autolens/__init__.py; I am happy to do the PyAutoLens side if you would rather keep PR 2 to one repo.
3. Drafts are the right arrangement, with one correction: the workspace smoke CI installs the released library, not main, so the docs PRs stay red until the next PyAutoGalaxy release rather than until #635 merges. Keep them draft and I will merge them after that release. Same arrangement for PR 2 and its docs.

[Jammy2211]

Thanks Sam. Quick status for anyone following: wave 1 is done. PyAutoGalaxy#635 shipped in autogalaxy 2026.10.2.1, and the two docs PRs (autolens_workspace#579, autogalaxy_workspace#251) merged today. Thank you for testing my fixups so carefully.

On wave 2: I'm happy with the white/black brushes and the arcsinh default, your accessibility reasoning is convincing, so no need to split them out; we'll flag the change in the release notes. Rather than ask for another round I pushed a few small commits onto #641 (a brush-bleed fix near panel edges, the ag. export, a warning when norm= is ignored) and onto #583 (use the public al. name), and opened PyAutoLens#770 for the al. re-export. Plan from here: merge #641 and #770, cut a release, then approve CI on the docs drafts and merge them.

[Jammy2211]

Closing the loop on this proposal. Everything in the write-up is now released:

• Wave 1 (erase brush, mask refinement, proposal outline): feat(gui): Scribbler erase brush, proposal outline, multiplicative brush resize PyAutoGalaxy#635, autogalaxy 2026.10.2.1.
• Wave 2 (radial-subtracted panels, cross-grid mask regridding, white/black brushes, arcsinh default): feat(gui): Scribbler radial-subtracted side-by-side panels; cross-grid mask regrid PyAutoGalaxy#641 and the al. re-export feat: re-export mask_2d_regridded_from as al.mask_2d_regridded_from PyAutoLens#770, both in the 2026.10.7.1 releases; the docs PRs autolens_workspace#579/#583 and autogalaxy_workspace#251/#254 are merged.

All of it is in the current 2026.10.18.1 release. Thank you @samlange04 for carrying this through two rounds of review so carefully. Marking this as the answer and closing as resolved; if a wave 3 takes shape, a new thread or a comment here is enough.