feat(compositing): add reusable alpha "over" array primitive (alpha_over)

[MAfarrag]

Context

cleopatra is the ecosystem's render engine, but there is currently no shared primitive for alpha compositing
— stacking a semi-transparent image over another (the Porter-Duff "over" operator). As a result the same small
formula is being written independently in higher layers:

• pyramids-eo implements it privately in composites/overlay.py (alpha_overlay) for its day/night composite.
• digital-earth assembles RGB/HSV composites (scene/maps/raster.py) and will need the same "over" math.

These copies will drift over time (edge cases: RGBA-over-RGBA premultiplication, divide-by-zero on zero output
alpha). Since "over" is a pure drawing operation with no GIS/EO knowledge, cleopatra — the leaf render package
everything else depends on — is its natural home.

Problem / Current Behaviour

cleopatra has no array-level compositing helper. glyphs/base/ holds glyph, animation, and hillshade, but
nothing for combining two image arrays by alpha. Downstream packages therefore reinvent it.

Affected locations

File	Symbol	Notes
src/cleopatra/glyphs/base/	—	new compositing.py module goes here
src/cleopatra/glyphs/base/__init__.py	module docstring	list the new submodule

Steps to Reproduce / Motivation Example

# Desired: one shared primitive any glyph or downstream compositor can call.
import numpy as np
from cleopatra.glyphs.base.compositing import alpha_over

fg = np.array([[[1.0]], [[0.0]], [[0.0]], [[0.5]]])  # red, alpha 0.5  -> (4, H, W)
bg = np.array([[[0.0]], [[0.0]], [[1.0]]])           # blue            -> (3, H, W)
alpha_over(fg, bg).round(2).ravel().tolist()
# [0.5, 0.0, 0.5]   # 50/50 red-over-blue

Proposed Solution

Add src/cleopatra/glyphs/base/compositing.py with a NumPy-only alpha_over:

def alpha_over(foreground: np.ndarray, background: np.ndarray) -> np.ndarray:
    """Composite a (4, H, W) RGBA foreground over a (3|4, H, W) RGB(A) background (Porter-Duff "over").

    - RGB background  -> 3-band result: fg_rgb * fg_a + bg_rgb * (1 - fg_a)
    - RGBA background -> 4-band result with out_a = fg_a + bg_a * (1 - fg_a),
      premultiplied blend, divide-by-zero guarded where out_a == 0.
    """

Import convention follows the package (no re-export at package roots):
from cleopatra.glyphs.base.compositing import alpha_over.

Once this lands, pyramids-eo and digital-earth can delegate their array-level "over" to it (pyramids-eo keeps
only the thin Dataset-metadata wrapper, which cleopatra cannot host since it has no pyramids dependency).

Out of Scope

• Any pyramids Dataset / geotransform-aware wrapper (stays in pyramids-eo).
• Other blend modes (multiply, screen, etc.) — this issue is only the "over" operator.
• Refactoring digital-earth / pyramids-eo to consume it (follow-up in those repos).

Effort Estimate

Size: XS
Rationale: one small pure-NumPy function plus a focused unit test; no dependencies or API-surface changes.

Definition of Done

• cleopatra.glyphs.base.compositing.alpha_over implemented (RGB and RGBA background paths)
• divide-by-zero guarded where output alpha is 0; input validation on array shapes
• unit tests cover RGB-over, RGBA-over, half-transparent blend, and shape-error cases
• glyphs/base/__init__.py docstring lists the new submodule
• all existing tests continue to pass

[MAfarrag]

Verdict: don't add this to cleopatra as-is — redirect it

The primitive itself is fine (correct "over" math, XS, zero deps), and the anti-drift motivation is real. But it does
not fit cleopatra's scope, and the strongest reason is concrete: cleopatra cannot use alpha_over through any of
its own functionality, and its own rendering would never call it.

It fails cleopatra's own boundary heuristic (SCOPE.md)

#	Question	alpha_over
1	Input is in-memory NumPy?	yes
2	Output is a matplotlib Figure/Axes/artist?	no — returns a NumPy array
3	Builds on Glyph + the shared colour/colorbar/legend pipeline?	no — standalone pure function
4	numpy + matplotlib only?	yes

The rule is "if any is no, it probably belongs in a different package." It's a pure array→array image op, not a
plotting helper.

The decisive point: no cleopatra-internal consumer

cleopatra does all layering with matplotlib at draw time, never by flattening arrays:

• add_relief / add_tiles / the new ecmwf-dark relief backdrop are all ax.imshow(..., alpha=…, zorder=…) — the
  renderer composites the stacked imshow artists; nothing pre-composites arrays.
• The RGB path (ArrayGlyph / RgbBands) hands a single array to imshow — there is no second layer to blend.
• The only array-level blend we have, hillshade, uses matplotlib.colors.LightSource.blend_overlay/soft_light/hsv
  (illumination shading) — not alpha "over".
• A grep for the "over" math (* (1 - a), premultiply, out_a, alpha_over) across src/ returns nothing.

So if this lands, alpha_over has zero callers inside cleopatra — it would be dead code here, shipped purely for
downstream. A primitive the host package never exercises is the textbook sign it belongs one layer down.

A tell in the proposed API

The signature is band-first (4, H, W) / (3, H, W) — the rasterio/GDAL convention. cleopatra is channel-last
(H, W, C) (see reference.relief() and imshow). The primitive is written in the downstream raster dialect, which
is further evidence its natural audience is the EO packages, not cleopatra's plotting layer.

Where the demand actually comes from (EO, not plotting)

• pyramids-eo — composites/true_color_night.py calls it as alpha_overlay(night_ir_rgba, black_marble): overlay
  night-IR clouds (transparent between clouds) on the Black Marble city lights so the lights show through, then
  cross-fade with the day image by solar-zenith-angle. Pure EO compositing.
• digital-earth — scene/maps/raster.py builds RGB/HSV composites with nodata transparency and would use "over" to
  lay them over a base. It already depends on cleopatra for the RgbBands render.

Both consumers use band-first arrays and are EO pipelines; the over math is domain-free, but its callers aren't.

Recommendation

1. Preferred: put it in hpc-utils (already a core dependency of cleopatra and reachable by the downstream
   repos). A pure-NumPy, no-matplotlib array op is a generic array utility — that's its natural home, and cleopatra's
   "NumPy in → matplotlib artist out" charter stays clean.
2. Or keep the single correct copy where it already lives and works (pyramids-eo/composites/overlay.py) and have
   digital-earth import it from there.
3. Only if we consciously decide cleopatra should become the ecosystem's shared render-primitive home, then accept
   it as a documented exception (the way tiles/reference are called out in SCOPE.md) — and in that case fix the
   convention to channel-last (H, W, C) and ideally wire one real internal consumer so it isn't dead weight.

Leaning strongly to (1). Closing thought: the fact that we can't use this via cleopatra alone is exactly why it
shouldn't live in cleopatra.