editmamei 1.7.0 → 1.8.0

package/dist/backends/gimp/bridge/lib.py

@@ -181,10 +181,146 @@ BIT_DEPTHS = (8, 16)
 # SOURCE document already is (crop/rotate/flip only ever shrink-or-preserve the existing canvas,
 # so they don't need this; resize is the one op that can grow it arbitrarily from a tiny source).
 MAX_RESIZE_SIDE_PX = 30_000
-MAX_RESIZE_MEGAPIXELS = 250
+_DEFAULT_MAX_RESIZE_MEGAPIXELS = 250
+
+
+def megapixel_cap_from_env(raw, default=_DEFAULT_MAX_RESIZE_MEGAPIXELS):
+    """A host-supplied (`EM_GIMP_MAX_MEGAPIXELS`) ceiling that can only LOWER `default` -- a memory-
+    constrained host (e.g. a small container) tightens every pixel-growing op's cap this way. Anything
+    that is not a finite positive number below `default` (unset, empty, junk, NaN/inf, zero/negative,
+    or an attempt to RAISE it) is ignored and `default` is returned unchanged."""
+    if not raw:
+        return default
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return default
+    if not math.isfinite(value) or value <= 0 or value >= default:
+        return default
+    return value
+
+
+MAX_RESIZE_MEGAPIXELS = megapixel_cap_from_env(os.environ.get('EM_GIMP_MAX_MEGAPIXELS'))
 
 MAX_FEATHER_PX = 1000
 
+# gimp_modify_selection's expand/contract/border radius cap -- much lower than MAX_FEATHER_PX.
+# `Gimp.Selection.grow`/`shrink`/`border` are morphological (structuring-element) operations whose
+# cost scales with the radius, unlike `feather` (a GEGL blur, flat ~0.5s regardless of radius on a
+# 24MP image, measured live). This is the cap for a document at or below MORPHOLOGY_BASELINE_MP;
+# a bigger document gets a SMALLER cap -- see `effective_morphology_px`.
+MAX_MORPHOLOGY_PX = 150
+
+# Measured live at px=150 (border, the most expensive of the three): ~30s at 24MP (6016x4000),
+# ~73.5s at 100MP (14000x7143), and a GIMP session OUTRIGHT TIMEOUT past 180s at ~217MP
+# (30000x7228, this bridge's own largest allowed document -- MAX_RESIZE_SIDE_PX/
+# MAX_RESIZE_MEGAPIXELS). Cost does not scale linearly with megapixels (100MP was only ~2.45x the
+# 24MP cost for a ~4.17x bigger image), but it very much does not fit inside
+# gimp_modify_selection's budget either, so the cap itself has to shrink as the document grows.
+MORPHOLOGY_BASELINE_MP = 24.0
+# A document-size floor so a huge document still gets a meaningfully large morphology radius
+# rather than being squeezed to single-digit pixels.
+MIN_MORPHOLOGY_PX = 10
+
+
+def effective_morphology_px(width, height):
+    """The actual expand/contract/border cap for a `width`x`height` document: `MAX_MORPHOLOGY_PX`
+    at or below `MORPHOLOGY_BASELINE_MP`, shrinking as 1/megapixels above it (simple and, per the
+    live measurements on `MAX_MORPHOLOGY_PX`'s own comment, SAFELY conservative -- the real cost
+    curve is sub-linear in megapixels, so this reduces the cap by more than the measured cost
+    alone would require). Verified live at the two points that matter: at ~100MP the scaled cap
+    (36px) cost ~11.8s; at ~217MP (this bridge's largest allowed document) the scaled cap (17px)
+    cost ~27.2s -- both comfortably inside gimp_modify_selection's 45s budget with its own margin,
+    even though a large document also carries a substantial FIXED per-call cost that shrinking
+    `px` alone cannot remove (measured ~13-17s of that 27.2s at ~217MP comes from px=5 alone,
+    i.e. just handling a document that size, before any morphology radius is even considered)."""
+    megapixels = (width * height) / 1_000_000.0
+    if megapixels <= MORPHOLOGY_BASELINE_MP:
+        return MAX_MORPHOLOGY_PX
+    scaled = MAX_MORPHOLOGY_PX * MORPHOLOGY_BASELINE_MP / megapixels
+    return max(MIN_MORPHOLOGY_PX, min(MAX_MORPHOLOGY_PX, round(scaled)))
+
+
+# gimp_transform_layer's scale/scale_x_percent/scale_y_percent bound -- generous enough for any
+# real use (100x in either direction) while still keeping a single call's resulting layer size
+# bounded alongside validate_resize_dims' own check on the actual pixel dimensions.
+TRANSFORM_LAYER_MIN_SCALE_PERCENT = 1
+TRANSFORM_LAYER_MAX_SCALE_PERCENT = 10_000
+
+# gimp_transform_layer's `interpolation` choices -- the GIMP resampling filters this bridge
+# exposes, by name. The gi-dependent mapping to the real `Gimp.InterpolationType` enum members
+# lives in ops.py (this module stays gi-free).
+TRANSFORM_LAYER_INTERPOLATIONS = ('none', 'linear', 'cubic', 'nohalo', 'lohalo')
+
+# gimp_transform_layer's `free` op: offset_x/offset_y bound -- a sanity ceiling on the final
+# absolute translation, well past MAX_RESIZE_SIDE_PX (30000) so any real placement fits, but
+# tight enough that a wildly out-of-range value is refused here rather than only by the derived
+# predicted-origin check (`_validated_move_offset`) it also feeds into.
+TRANSFORM_LAYER_MAX_OFFSET_PX = 100_000
+
+# gimp_transform_layer's own op -> the field names that op reads, the same role
+# `type_fields`/`FILTER_COMMON_KEYS` play for gimp_add_adjustment/gimp_add_effect above --
+# `reject_foreign_transform_fields` refuses any OTHER declared field a caller sent (e.g. a
+# PS-style flat `delta_x`, or `skew_h_degrees` on op=scale), so a typo validates instead of
+# silently being ignored by that op's own handler.
+TRANSFORM_LAYER_COMMON_KEYS = frozenset(('image', 'op', 'layer', 'layer_id', 'interpolation'))
+
+TRANSFORM_LAYER_OP_FIELDS = {
+    'fit': ('mode',),
+    'scale': ('scale_percent', 'scale_x_percent', 'scale_y_percent'),
+    'move': ('delta', 'absolute', 'center_on'),
+    'rotate': ('degrees',),
+    'flip': ('axis',),
+    'skew': ('skew_h_degrees', 'skew_v_degrees'),
+    'free': ('scale_x_percent', 'scale_y_percent', 'degrees', 'offset_x', 'offset_y'),
+}
+
+
+def reject_foreign_transform_fields(op, args):
+    """Refuse any field `op` does not read -- the gimp_transform_layer analogue of
+    `reject_foreign_fields` above, over `TRANSFORM_LAYER_OP_FIELDS` instead of the filter-type
+    tables. `op`'s own schema is flat (one property per name across every op), so without this a
+    field meant for a DIFFERENT op (`skew_h_degrees` on op=scale, or PS's flat `delta_x` instead
+    of this tool's nested `delta`) validates, is ignored by that op's own handler, and silently
+    does nothing. None values are ignored (an omitted field)."""
+    own = TRANSFORM_LAYER_OP_FIELDS.get(op, ())
+    foreign = sorted(
+        k for k, v in args.items()
+        if v is not None and k not in TRANSFORM_LAYER_COMMON_KEYS and k not in own
+    )
+    if foreign:
+        raise ValueError(
+            "op '%s' does not use field(s) %s; its fields are: %s"
+            % (op, ', '.join(foreign), ', '.join(own) or '(none)')
+        )
+
+
+def ceil_with_margin(value):
+    """`value` rounded UP to the next whole pixel, plus one more -- the conservative integer a
+    cap check validates against for a float `transformed_bounds` predicts, matching the extra
+    pixel GIMP's own ADJUST transform-resize can add by rounding each edge of a rotated/sheared
+    bounding box outward independently (floor the min edge, ceil the max edge), which can land
+    the ACTUAL resulting integer width/height one pixel past a plain `ceil` of the float width.
+    Never used for the transform's own corner coordinates (those stay exact floats) -- only for
+    deciding whether to refuse BEFORE any pixel moves."""
+    return int(math.ceil(value)) + 1
+
+
+def transform_layer_precision_bucket(precision_nick):
+    """`Gimp.Precision.value_nick` (e.g. 'u8-non-linear', 'u16-perceptual', 'float-linear')
+    bucketed into the '8'/'16'/'32' strings `validate_document_dims`'s own
+    `DOCUMENT_MEGAPIXEL_CAP` is keyed by -- gimp_transform_layer validates a layer's predicted
+    size against the SAME precision-aware cap gimp_create_document does, rather than always
+    assuming 8-bit. u16 and half bucket to '16' (2 bytes/channel); every other precision (u32,
+    float, double) buckets to '32' (4+ bytes/channel, the most conservative bucket) -- this
+    bridge has no DOCUMENT_MEGAPIXEL_CAP entry finer than that."""
+    nick = precision_nick.lower()
+    if nick.startswith('u8'):
+        return '8'
+    if nick.startswith('u16') or nick.startswith('half'):
+        return '16'
+    return '32'
+
 
 def require(args, name):
     """Fetch a required field from an op's `args`, raising ValueError naming it -- the
@@ -270,7 +406,7 @@ def validate_resize_dims(width, height):
         raise ValueError('width and height must each be at most %d px' % MAX_RESIZE_SIDE_PX)
     megapixels = (width * height) / 1_000_000.0
     if megapixels > MAX_RESIZE_MEGAPIXELS:
-        raise ValueError('resize target must be at most %d MP' % MAX_RESIZE_MEGAPIXELS)
+        raise ValueError('resize target must be at most %g MP' % MAX_RESIZE_MEGAPIXELS)
     return width, height
 
 
@@ -281,7 +417,13 @@ def validate_resize_dims(width, height):
 # that picks its own bit depth up front (`open`/`resize`/etc. all work on whatever precision an
 # already-open image happens to be), so it is the one place this DoS floor needs to vary by
 # precision rather than assuming 8-bit throughout.
-DOCUMENT_MEGAPIXEL_CAP = {'8': MAX_RESIZE_MEGAPIXELS, '16': 125, '32': 60}
+# A lowered EM_GIMP_MAX_MEGAPIXELS scales the 16/32-bit caps down with the 8-bit one, never above
+# their own defaults.
+DOCUMENT_MEGAPIXEL_CAP = {
+    '8': MAX_RESIZE_MEGAPIXELS,
+    '16': min(125, MAX_RESIZE_MEGAPIXELS / 2),
+    '32': min(60, MAX_RESIZE_MEGAPIXELS / 4),
+}
 
 
 def validate_document_dims(width, height, precision='8'):
@@ -295,14 +437,182 @@ def validate_document_dims(width, height, precision='8'):
     cap = DOCUMENT_MEGAPIXEL_CAP[precision]
     megapixels = (width * height) / 1_000_000.0
     if megapixels > cap:
-        raise ValueError('a %s-bit document must be at most %d MP' % (precision, cap))
+        raise ValueError(
+            '%s %s-bit document must be at most %g MP'
+            % ('an' if precision == '8' else 'a', precision, cap)
+        )
     return width, height
 
 
+def validate_group_total_pixels(sizes, precision='8'):
+    """A GROUP transform allocates every non-group descendant's own result buffer, so the SUM of
+    their predicted pixel counts (`sizes`: (width, height) pairs) must fit the same
+    precision-aware megapixel ceiling `validate_document_dims` applies to a single layer."""
+    cap = DOCUMENT_MEGAPIXEL_CAP[precision]
+    megapixels = sum(w * h for w, h in sizes) / 1_000_000.0
+    if megapixels > cap:
+        raise ValueError(
+            "the group's layers would total %.1f MP after this transform; the %s-bit limit is %d MP"
+            % (megapixels, precision, cap)
+        )
+
+
 def validate_feather_px(value):
     return validate_range('feather_px', value, 0.0, MAX_FEATHER_PX)
 
 
+# ---- match_layer: statistics transfer as per-channel curves ---------------------------------
+#
+# Everything here is pure (no gi). Means and standard deviations are in GIMP's own histogram
+# units (0-255 in the image's perceptual encoding, the same space a gimp:curves filter works in).
+
+MATCH_TAG = 'match_layer'
+MATCH_MODES = ('both', 'color', 'tone')
+MATCH_REFERENCES = ('surround', 'below')
+MATCH_DEFAULT_STRENGTH = 70.0
+MATCH_MIN_PIXELS = 500
+MATCH_GAIN_MIN = 0.5
+MATCH_GAIN_MAX = 2.0
+MATCH_MAX_EDGE_CONTRACT_PX = 20
+MATCH_MAX_EDGE_FEATHER_PX = 50
+MATCH_SURROUND_MIN_PX = 16
+MATCH_SURROUND_MAX_PX = 400
+# A std-dev below this (0-255 units) is treated as a flat region: its contrast ratio is
+# meaningless, so the gain stays 1 and only the mean moves.
+MATCH_FLAT_SD = 0.5
+# Spacing of the helper points that keep a clamped curve on its line (see match_curve_points).
+MATCH_CURVE_STEP = 16.0
+# Measuring runs on a copy of the layer's region scaled so its long side is at most this: means
+# and spreads survive the downscale, and growing the surround ring stays cheap at any size.
+MATCH_MEASURE_MAX_SIDE = 2048
+
+
+def default_surround_px(layer_width, layer_height):
+    """About 12% of the layer's longer side, clamped to 16..400 px."""
+    px = int(round(0.12 * max(layer_width, layer_height)))
+    return max(MATCH_SURROUND_MIN_PX, min(MATCH_SURROUND_MAX_PX, px))
+
+
+def validate_match_args(args, layer_width, layer_height):
+    """The validated, defaulted `match_layer` options as a dict:
+    match/strength/reference/surround_px/edge_contract_px/edge_feather_px. `strength` is returned
+    as a 0..1 fraction under `s` as well."""
+    match = validate_choice('match', args.get('match') or 'both', MATCH_MODES)
+    reference = validate_choice('reference', args.get('reference') or 'surround', MATCH_REFERENCES)
+    strength = args.get('strength')
+    strength = validate_range(
+        'strength', MATCH_DEFAULT_STRENGTH if strength is None else strength, 0.0, 100.0
+    )
+    surround = args.get('surround_px')
+    surround = (
+        default_surround_px(layer_width, layer_height)
+        if surround is None
+        else validate_int_range('surround_px', surround, 1, MATCH_SURROUND_MAX_PX)
+    )
+    contract = args.get('edge_contract_px')
+    contract = validate_int_range(
+        'edge_contract_px', 0 if contract is None else contract, 0, MATCH_MAX_EDGE_CONTRACT_PX
+    )
+    feather = args.get('edge_feather_px')
+    feather = validate_int_range(
+        'edge_feather_px', 0 if feather is None else feather, 0, MATCH_MAX_EDGE_FEATHER_PX
+    )
+    return {
+        'match': match, 'reference': reference, 'strength': strength, 's': strength / 100.0,
+        'surround_px': surround, 'edge_contract_px': contract, 'edge_feather_px': feather,
+    }
+
+
+def match_transfer(mu_src, sd_src, mu_ref, sd_ref, s):
+    """The Reinhard-style linear map moving the source's mean/std toward the reference's, scaled
+    by `s` (0..1): out = (in - mu_src) * gain + mu_src + shift, with
+    gain = clamp(1 + (sd_ref / sd_src - 1) * s, 0.5, 2.0) and shift = (mu_ref - mu_src) * s.
+    A flat source (or reference) keeps gain 1. Returns {gain, shift, mean_after, std_after};
+    the `_after` values ignore the 0-255 clamp of the curve."""
+    if sd_src < MATCH_FLAT_SD or sd_ref < MATCH_FLAT_SD:
+        ratio = 1.0
+    else:
+        ratio = sd_ref / sd_src
+    gain = max(MATCH_GAIN_MIN, min(MATCH_GAIN_MAX, 1.0 + (ratio - 1.0) * s))
+    shift = (mu_ref - mu_src) * s
+    return {
+        'gain': gain, 'shift': shift,
+        'mean_after': mu_src + shift, 'std_after': sd_src * gain,
+    }
+
+
+def match_curve_points(mu_src, gain, shift):
+    """The transfer map as gimp:curves [input, output] points (0-255, strictly ascending input).
+    The line y = gain * (x - mu_src) + mu_src + shift is clamped to 0..255. Unclamped it is just
+    its two endpoints (a two-point curve is exactly straight; gain 1 and shift 0 gives
+    [[0, 0], [255, 255]]). Where the line meets the clamp, a point is added there and helper
+    points every MATCH_CURVE_STEP along the sloped part: GIMP draws a smooth spline through the
+    points, and without the helpers it bows away from the line (measured: ~6 levels at the
+    middle of a clamped curve)."""
+    def y_at(x):
+        return gain * (x - mu_src) + mu_src + shift
+
+    def clamp(y):
+        return max(0.0, min(255.0, y))
+
+    y0, y1 = y_at(0.0), y_at(255.0)
+    xs = [0.0, 255.0]
+    if y0 < 0.0 or y1 > 255.0:
+        # y is strictly increasing (gain > 0): it crosses 0 once and 255 once.
+        low = 0.0 if y0 >= 0.0 else mu_src - (mu_src + shift) / gain
+        high = 255.0 if y1 <= 255.0 else mu_src + (255.0 - mu_src - shift) / gain
+        knots = [x for x in (low, high) if MATCH_CURVE_STEP / 4 < x < 255.0 - MATCH_CURVE_STEP / 4]
+        xs.extend(knots)
+        # Helpers fill the sloped part [low, high] only, kept clear of the knots.
+        x = MATCH_CURVE_STEP * (int(low // MATCH_CURVE_STEP) + 1)
+        while x < 255.0:
+            if low + MATCH_CURVE_STEP / 4 < x < high - MATCH_CURVE_STEP / 4 and x > MATCH_CURVE_STEP / 4:
+                xs.append(float(x))
+            x += MATCH_CURVE_STEP
+    xs = sorted(set(xs))
+    return [[round(x, 2), round(clamp(y_at(x)), 2)] for x in xs]
+
+
+def match_measure_scale(width, height):
+    """The factor (0 < f <= 1) a measuring copy of a `width` x `height` region is scaled by."""
+    longest = max(width, height)
+    return 1.0 if longest <= MATCH_MEASURE_MAX_SIDE else MATCH_MEASURE_MAX_SIDE / float(longest)
+
+
+def match_scaled_px(px, factor):
+    """A pixel distance on a copy scaled by `factor`, never below 1 for a non-zero distance."""
+    return 0 if px <= 0 else max(1, int(round(px * factor)))
+
+
+def match_full_res_count(count, factor):
+    """A pixel count measured on a copy scaled by `factor`, as the full-resolution count."""
+    return int(round(count / (factor * factor)))
+
+
+def histogram_scale(nick):
+    """What a Drawable.histogram mean/std must be multiplied by to read 0-255: GIMP reports them
+    in 0-255 for 8-bit precisions and in 0-1 for every higher one."""
+    return 1.0 if nick.startswith('u8') else 255.0
+
+
+def is_linear_precision(nick):
+    """Whether a GIMP precision nick ('u8-non-linear', 'float-linear', ...) stores linear light."""
+    return nick.endswith('-linear') and not nick.endswith('-non-linear')
+
+
+def match_roi(layer_x, layer_y, layer_width, layer_height, canvas_width, canvas_height, pad):
+    """The layer's box grown by `pad` and clipped to the canvas, as (x, y, width, height); None
+    when the layer's own box does not touch the canvas."""
+    if (layer_x >= canvas_width or layer_y >= canvas_height
+            or layer_x + layer_width <= 0 or layer_y + layer_height <= 0):
+        return None
+    x0 = max(0, layer_x - pad)
+    y0 = max(0, layer_y - pad)
+    x1 = min(canvas_width, layer_x + layer_width + pad)
+    y1 = min(canvas_height, layer_y + layer_height + pad)
+    return x0, y0, x1 - x0, y1 - y0
+
+
 _HEX_COLOR_RE = re.compile(r'^#[0-9a-fA-F]{6}$')
 
 # gimp_canvas's fill choices: the same white/black/transparent LAYER_FILLS a new layer gets, plus
@@ -319,6 +629,57 @@ def validate_canvas_fill(value):
     )
 
 
+def validate_hex_color(name, value):
+    """A '#rrggbb' hex color -- the same `_HEX_COLOR_RE` gimp_canvas's own fill validates against,
+    reused here so a color field never silently reaches `Gegl.Color.new` with a string it cannot
+    parse (which would otherwise fall back to black)."""
+    if not isinstance(value, str) or not _HEX_COLOR_RE.fullmatch(value):
+        raise ValueError('%s must be a "#rrggbb" hex color, got %r' % (name, value))
+    return value
+
+
+def _round_half_up(value):
+    """Round half away from zero, unlike Python's builtin `round()` (round-half-to-even:
+    `round(0.5) == 0`, `round(2.5) == 2`) -- surprising for a user-facing pixel radius, where
+    "4.5 px" should become 5, not 4."""
+    return math.floor(value + 0.5) if value >= 0 else math.ceil(value - 0.5)
+
+
+def validate_positive_px(name, value, max_px=MAX_FEATHER_PX):
+    """A strictly positive pixel radius (expand/contract/border/feather). Rounds half-up to the
+    nearest whole pixel FIRST, then refuses anything that is not strictly positive or exceeds
+    max_px -- so a value that ROUNDS to 0 (e.g. 0.3) is refused, same as an outright 0 or
+    negative, rather than silently accepted as a no-op radius."""
+    rounded = int(_round_half_up(float(value)))
+    if not 0 < rounded <= max_px:
+        raise ValueError('%s must round to a value greater than 0 and at most %s' % (name, max_px))
+    return rounded
+
+
+# load_mask's own DoS floor on a SOURCE mask image's dimensions. Checked right after
+# `Gimp.file_load` decodes the file (GIMP's Python environment has no cheap way to read a PNG/
+# JPEG header's own width/height without decoding -- GdkPixbuf is not bound in this environment),
+# so it bounds the IN-MEMORY size before the heavier work that follows (alpha compositing, scale,
+# flatten), not the decode itself. Reuses the same cap `validate_resize_dims` applies to a resize
+# target, since both are "how big a single in-memory image may get" limits.
+def validate_loaded_mask_dims(width, height):
+    return validate_resize_dims(width, height)
+
+
+def compute_mask_paste_rect(ox, oy, tw, th, img_width, img_height):
+    """Where a `tw`x`th` mask (already scaled to its target -- the whole image, or one layer's own
+    bounds, at offset `(ox, oy)`) actually lands inside the `img_width`x`img_height` canvas: the
+    intersection of [ox, ox+tw) x [oy, oy+th) with [0, img_width) x [0, img_height). Pure and
+    gi-free so the off-canvas cases (a negative offset, or a layer hanging off the right/bottom
+    edge) are unit-tested without GIMP. Returns (x0, y0, x1, y1); x1 <= x0 or y1 <= y0 means the
+    mask lands ENTIRELY off-canvas (nothing to paste -- the channel stays all-black there)."""
+    x0 = max(0, ox)
+    y0 = max(0, oy)
+    x1 = min(img_width, ox + tw)
+    y1 = min(img_height, oy + th)
+    return x0, y0, x1, y1
+
+
 # gimp_canvas's anchor grid -> the fraction of the GROWTH (new size minus old size) that lands
 # BEFORE the existing content on each axis. 0.0 pins that edge (no padding there); 1.0 puts all
 # the padding there instead; 0.5 splits it evenly. Keyed by the full 3x3 grid a Photoshop-style
@@ -350,6 +711,69 @@ def canvas_anchor_offset(anchor, old_width, old_height, new_width, new_height):
     )
 
 
+# EXIF Orientation (1-8) -> the steps that turn the stored pixels upright, in order. Each step is
+# 'cw90' / 'cw180' / 'cw270' (clockwise rotation), 'flip_h' (mirror left-right) or 'flip_v'
+# (mirror top-bottom). 1 (normal) needs none.
+EXIF_ORIENTATION_STEPS = {
+    1: (),
+    2: ('flip_h',),
+    3: ('cw180',),
+    4: ('flip_v',),
+    5: ('cw90', 'flip_h'),
+    6: ('cw90',),
+    7: ('cw90', 'flip_v'),
+    8: ('cw270',),
+}
+
+
+def parse_exif_orientation(raw):
+    """The EXIF Orientation value (1-8) from a metadata tag's raw value, or None when it is
+    missing, non-numeric or out of range -- a broken tag is ignored, never an error."""
+    try:
+        value = int(str(raw).strip())
+    except (TypeError, ValueError):
+        return None
+    return value if value in EXIF_ORIENTATION_STEPS else None
+
+
+def exif_orientation_steps(orientation):
+    """The upright-making steps for an EXIF Orientation value; () for None, 1 or anything else."""
+    return EXIF_ORIENTATION_STEPS.get(orientation, ())
+
+
+EXIF_ORIENTATION_TAG = 'Exif.Image.Orientation'
+
+
+def read_exif_orientation(metadata):
+    """The orientation (1-8) a GimpMetadata-like object carries, or None when `metadata` is None,
+    has no usable tag, or reading it raises."""
+    if metadata is None:
+        return None
+    try:
+        return parse_exif_orientation(metadata.try_get_tag_string(EXIF_ORIENTATION_TAG))
+    except Exception:
+        return None
+
+
+# Every tag a viewer may read orientation from; the EXIF one is the one this bridge applies.
+ORIENTATION_TAGS = (EXIF_ORIENTATION_TAG, 'Xmp.tiff.Orientation', 'Exif.Thumbnail.Orientation')
+
+
+def clear_exif_orientation(metadata):
+    """Removes the orientation tags from `metadata` (absent reads as normal); True when the EXIF
+    one was cleared. Clearing is used rather than writing 1: GIMP's metadata object can silently
+    ignore a write of that tag while still reporting success."""
+    cleared = False
+    for tag in ORIENTATION_TAGS:
+        try:
+            ok = bool(metadata.try_clear_tag(tag))
+        except Exception:
+            ok = False
+        if tag == EXIF_ORIENTATION_TAG:
+            cleared = ok
+    return cleared
+
+
 def pct_to_unit(name, value, lo=-100.0, hi=100.0):
     """User-facing -100..100 (or a narrower lo..hi) percent-like value -> the -1..1 unit
     GEGL/GIMP properties in this family use."""
@@ -1358,6 +1782,155 @@ def validate_effect_transform(op_name, operation, filter_name, new_params):
             )
 
 
+
+# ---- gimp_transform_layer: pure geometry math (fit/fill scale, matrix composition, bounds) ----
+#
+# A layer-level affine transform (scale/rotate/skew/free), distinct from the whole-CANVAS
+# geometry ops above and from the direction/position-dependent EFFECT param remapping above.
+# `Item.transform_matrix` (ops.py) applies the given 3x3 matrix directly in ABSOLUTE
+# document-pixel coordinates -- verified live (GIMP 3.2.6): a matrix built by
+# `compose_layer_matrix` below, applied to a layer at a known offset, moved it to exactly the
+# bounding box this module's own `transformed_bounds` predicts for the same matrix and corners
+# (within floating-point rounding). So every matrix built here already carries whatever
+# translation is needed to anchor the transform at the layer's own center; there is no separate
+# "local" coordinate frame to convert into or out of first.
+
+
+def fit_scale_fraction(layer_width, layer_height, canvas_width, canvas_height, mode):
+    """The uniform scale fraction (1.0 = 100%) that makes a `layer_width` x `layer_height`
+    rectangle fit inside (mode='fit', letterbox -- the SMALLER of the two axis ratios) or fill
+    (mode='fill', cover -- the LARGER) a `canvas_width` x `canvas_height` canvas, preserving
+    aspect. `op_transform_layer`'s `fit` scales by this fraction and centers the result; fitting
+    an already-fitted layer computes a fraction of 1.0, a no-op scale -- what makes that op
+    idempotent."""
+    if mode not in ('fit', 'fill'):
+        raise ValueError("mode must be one of 'fit', 'fill'")
+    width_ratio = canvas_width / float(layer_width)
+    height_ratio = canvas_height / float(layer_height)
+    return min(width_ratio, height_ratio) if mode == 'fit' else max(width_ratio, height_ratio)
+
+
+def _mat_mul(a, b):
+    """3x3 matrix product, both `a` and `b` flat row-major 9-lists (the same layout
+    `Item.transform_matrix`'s own 9 positional args use), applied to a column vector [x,y,1] as
+    p' = a*(b*p) -- `b` is the transform applied FIRST."""
+    return [
+        a[0] * b[0] + a[1] * b[3] + a[2] * b[6],
+        a[0] * b[1] + a[1] * b[4] + a[2] * b[7],
+        a[0] * b[2] + a[1] * b[5] + a[2] * b[8],
+        a[3] * b[0] + a[4] * b[3] + a[5] * b[6],
+        a[3] * b[1] + a[4] * b[4] + a[5] * b[7],
+        a[3] * b[2] + a[4] * b[5] + a[5] * b[8],
+        a[6] * b[0] + a[7] * b[3] + a[8] * b[6],
+        a[6] * b[1] + a[7] * b[4] + a[8] * b[7],
+        a[6] * b[2] + a[7] * b[5] + a[8] * b[8],
+    ]
+
+
+def _mat_translate(tx, ty):
+    return [1.0, 0.0, tx, 0.0, 1.0, ty, 0.0, 0.0, 1.0]
+
+
+def _mat_scale(sx, sy):
+    return [sx, 0.0, 0.0, 0.0, sy, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_rotate(degrees):
+    theta = math.radians(degrees)
+    cos_t, sin_t = math.cos(theta), math.sin(theta)
+    return [cos_t, -sin_t, 0.0, sin_t, cos_t, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_shear_h(skew_h_degrees):
+    """A pure horizontal shear: x' = x - tan(skew_h_degrees)*y, y' = y -- determinant exactly 1
+    for any angle. Positive `skew_h_degrees` slants the top edge right (a point above center,
+    smaller y, moves toward +x) -- the convention `gimp_transform_layer`'s own schema documents,
+    and the one `ps_transform_layer`'s op=skew uses."""
+    return [1.0, -math.tan(math.radians(skew_h_degrees)), 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_shear_v(skew_v_degrees):
+    """A pure vertical shear: x' = x, y' = -tan(skew_v_degrees)*x + y -- determinant exactly 1
+    for any angle. Positive `skew_v_degrees` slants the left edge down (a point left of center,
+    smaller x, moves toward +y)."""
+    return [1.0, 0.0, 0.0, -math.tan(math.radians(skew_v_degrees)), 1.0, 0.0, 0.0, 0.0, 1.0]
+
+
+def _mat_determinant(m):
+    """The determinant of `m`'s linear (non-translation) 2x2 part -- the translation column
+    (indices 2, 5) never affects it. Zero means the transform collapses the rectangle to a line
+    or a point; negative means it mirrors (flips handedness) rather than purely scaling/
+    rotating/shearing it."""
+    return m[0] * m[4] - m[1] * m[3]
+
+
+# A composed matrix below this |determinant| is treated the same as an exact 0: numerically
+# indistinguishable from a transform that collapses the layer to a line, so refused outright
+# rather than handed to `Item.transform_matrix` to silently produce a degenerate result.
+TRANSFORM_LAYER_MIN_DETERMINANT = 1e-6
+
+
+def compose_layer_matrix(cx, cy, scale_x_percent, scale_y_percent, degrees,
+                          skew_h_degrees, skew_v_degrees, offset_x, offset_y):
+    """The 9 row-major coefficients for `Item.transform_matrix`: a scale (percent, 100 =
+    unchanged), then a skew (skew_h_degrees/skew_v_degrees, composed as two independent real
+    shears -- Sh_v . Sh_h, each with its OWN determinant of exactly 1, so the composed skew's
+    determinant is always exactly 1 too, for any angle), then a rotation (degrees, clockwise),
+    all anchored at the layer's own center (`cx`, `cy`, document pixels), followed by an absolute
+    translation (`offset_x`, `offset_y`). Never the single combined-shear matrix
+    [[1,-tan(h)],[-tan(v),1]] -- that matrix's OWN determinant is `1 - tan(h)*tan(v)`, which
+    reaches exactly 0 at h=v=45 (collapsing the rectangle to a line) and goes NEGATIVE past that
+    (silently mirroring it instead of shearing it). `op_transform_layer`'s `free` op calls this
+    directly (scale + degrees + offset, no skew); `skew` calls it with scale 100/100, degrees 0,
+    offset 0/0; `rotate`'s own bounds check (not its actual transform, which goes through
+    `Item.transform_rotate` instead -- see ops.py) reuses it with scale 100/100, skew 0/0, offset
+    0/0 purely to predict the post-rotation bounding box via `transformed_bounds`.
+
+    Raises if the FINAL composed matrix's determinant is below `TRANSFORM_LAYER_MIN_DETERMINANT`
+    or negative -- scale alone is already bounded away from both by its own 1..10000% range, but
+    this is the belt-and-braces check against the composed result as a whole, not just its own
+    skew component."""
+    m = _mat_translate(-cx, -cy)
+    m = _mat_mul(_mat_scale(scale_x_percent / 100.0, scale_y_percent / 100.0), m)
+    m = _mat_mul(_mat_shear_v(skew_v_degrees), _mat_mul(_mat_shear_h(skew_h_degrees), m))
+    m = _mat_mul(_mat_rotate(degrees), m)
+    m = _mat_mul(_mat_translate(cx, cy), m)
+    m = _mat_mul(_mat_translate(offset_x, offset_y), m)
+    det = _mat_determinant(m)
+    if not math.isfinite(det) or det < 0 or abs(det) < TRANSFORM_LAYER_MIN_DETERMINANT:
+        raise ValueError(
+            'this combination of scale/skew/rotate collapses or mirrors the layer (determinant '
+            '%.6g) instead of transforming it -- reduce the scale or skew and try again' % det
+        )
+    return m
+
+
+def transformed_bounds(matrix, x, y, width, height):
+    """The axis-aligned bounding box of a `width` x `height` rectangle at document-pixel origin
+    (`x`, `y`), after mapping each of its four corners through `matrix` (9 row-major
+    coefficients, `Item.transform_matrix`'s own layout) -- what the transformed layer's new
+    offsets/width/height will measure to. Used to validate a rotate/skew/free transform against
+    the same size cap `validate_resize_dims` enforces, BEFORE any pixel actually moves. Returns
+    (new_x, new_y, new_width, new_height)."""
+    corners = ((x, y), (x + width, y), (x, y + height), (x + width, y + height))
+    xs = [matrix[0] * cx + matrix[1] * cy + matrix[2] for cx, cy in corners]
+    ys = [matrix[3] * cx + matrix[4] * cy + matrix[5] for cx, cy in corners]
+    min_x, max_x = min(xs), max(xs)
+    min_y, max_y = min(ys), max(ys)
+    return min_x, min_y, max_x - min_x, max_y - min_y
+
+
+def validate_transformed_layer_size(width, height):
+    """Refuses a scale/fit whose rounded target is under 1px in either dimension. Without this
+    GIMP is handed a zero-size rectangle, returns nothing, and the caller reports a misleading
+    "lock-position or lock-content" failure for a layer that was never locked."""
+    if width < 1 or height < 1:
+        raise ValueError(
+            'the transform would shrink the layer to %dx%d px after rounding; use a larger scale'
+            % (width, height)
+        )
+
+
 def region_to_proxy_px(region, scale):
     """Map a document-pixel `region` dict into proxy-pixel integer bounds at the proxy's
     `scale` factor (0 < scale <= 1). Returns (x, y, width, height); width/height are at least
@@ -1370,6 +1943,13 @@ def region_to_proxy_px(region, scale):
     return x, y, w, h
 
 
+def visible_image_ids(all_ids, hidden_ids):
+    """The ids in `all_ids` that are real documents: every id in `hidden_ids` (the bridge's own
+    preview-proxy images, which are live GIMP images but not the user's) is dropped, order kept."""
+    hidden = set(hidden_ids)
+    return [i for i in all_ids if i not in hidden]
+
+
 def read_pgm(raw):
     """Decode minimal binary PGM (P5, maxval 255) bytes. Returns (width, height, data).
 
@@ -1986,3 +2566,252 @@ def metadata_strip_settings(fmt, prop_names):
     if fmt == 'tiff' and 'save-geotiff' in names:
         settings.append('save-geotiff')
     return settings
+
+
+# ---- text layers (gimp_text) -----------------------------------------------------------------
+
+TEXT_MAX_CHARS = 2000
+TEXT_MIN_FONT_PT = 1
+TEXT_MAX_FONT_PT = 1296
+TEXT_DEFAULT_FONT_PT = 24
+TEXT_FONT_LIST_CAP = 200
+FONT_SUGGESTION_LIMIT = 8
+DEFAULT_TEXT_FONT = 'Sans-serif'
+DEFAULT_RESOLUTION_PPI = 72.0
+
+# gimp_text's `alignment` enum is ps_text's. GIMP's own justification has only left / right /
+# center / fill, so the three "last line" variants Photoshop adds are refused rather than
+# approximated.
+TEXT_ALIGNMENTS = {'LEFT': 'left', 'CENTER': 'center', 'RIGHT': 'right', 'FULLYJUSTIFIED': 'fill'}
+TEXT_UNSUPPORTED_ALIGNMENTS = ('LEFTJUSTIFIED', 'CENTERJUSTIFIED', 'RIGHTJUSTIFIED')
+_JUSTIFICATION_TO_ALIGNMENT = {nick: name for name, nick in TEXT_ALIGNMENTS.items()}
+
+# Words that describe a face of a family rather than the family itself, used to tell "Arial" +
+# "Narrow Bold" (a face of the family) from an unrelated font whose name merely starts the same.
+_FONT_STYLE_WORDS = frozenset((
+    'regular', 'book', 'roman', 'normal', 'medium', 'bold', 'italic', 'oblique', 'light', 'thin',
+    'extralight', 'ultralight', 'semilight', 'semibold', 'demibold', 'extrabold', 'ultrabold',
+    'black', 'heavy', 'condensed', 'semicondensed', 'extracondensed', 'narrow', 'cond', 'expanded',
+    'semiexpanded', 'extra', 'ultra', 'semi', 'demi', 'variable',
+))
+_FONT_REGULAR_ORDER = ('regular', 'book', 'roman', 'normal', 'medium')
+
+
+def validate_text_content(value):
+    if not isinstance(value, str):
+        raise ValueError('text must be a string')
+    if value == '':
+        raise ValueError('text must not be empty')
+    if len(value) > TEXT_MAX_CHARS:
+        raise ValueError('text must be at most %d characters (got %d)' % (TEXT_MAX_CHARS, len(value)))
+    return value
+
+
+def validate_font_size_pt(value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError('font_size must be a number')
+    return validate_range('font_size', value, TEXT_MIN_FONT_PT, TEXT_MAX_FONT_PT)
+
+
+def validate_text_rgb(args):
+    """(r, g, b) ints 0..255 from `red`/`green`/`blue`, or None when none of the three is given.
+    Giving only some of them is refused rather than guessing the rest."""
+    given = [k for k in ('red', 'green', 'blue') if args.get(k) is not None]
+    if not given:
+        return None
+    if len(given) != 3:
+        raise ValueError('red, green and blue must all be given together (missing: %s)'
+                         % ', '.join(k for k in ('red', 'green', 'blue') if k not in given))
+    out = []
+    for key in ('red', 'green', 'blue'):
+        value = args[key]
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or int(value) != value:
+            raise ValueError('%s must be an integer 0..255' % key)
+        out.append(validate_int_range(key, value, 0, 255))
+    return tuple(out)
+
+
+def srgb_u8_to_linear(value):
+    """An 8-bit sRGB channel as the linear-light float GEGL's set_rgba expects."""
+    c = value / 255.0
+    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def linear_to_srgb_u8(value):
+    """A linear-light float channel (GEGL's get_rgba) as an 8-bit sRGB integer."""
+    v = min(1.0, max(0.0, value))
+    c = v * 12.92 if v <= 0.0031308 else 1.055 * v ** (1 / 2.4) - 0.055
+    return int(round(c * 255))
+
+
+def justification_nick(alignment):
+    """GIMP's justification nick ('left' | 'right' | 'center' | 'fill') for a ps_text-style
+    `alignment`; refuses the variants GIMP has no equivalent for, naming what is supported."""
+    if alignment in TEXT_UNSUPPORTED_ALIGNMENTS:
+        raise ValueError(
+            'alignment %s is not supported by GIMP text layers; use one of %s'
+            % (alignment, ', '.join(TEXT_ALIGNMENTS))
+        )
+    if alignment not in TEXT_ALIGNMENTS:
+        raise ValueError('alignment must be one of %s'
+                         % ', '.join(list(TEXT_ALIGNMENTS) + list(TEXT_UNSUPPORTED_ALIGNMENTS)))
+    return TEXT_ALIGNMENTS[alignment]
+
+
+def alignment_name(nick):
+    """The ps_text-style alignment name for a GIMP justification nick (None when unknown)."""
+    return _JUSTIFICATION_TO_ALIGNMENT.get(nick)
+
+
+def _resolution_ppi(ppi):
+    return float(ppi) if ppi and ppi > 0 else DEFAULT_RESOLUTION_PPI
+
+
+def pt_to_px(pt, ppi):
+    """Points -> pixels at the image's vertical resolution (1 pt = 1/72 in)."""
+    return pt * _resolution_ppi(ppi) / 72.0
+
+
+def px_to_pt(px, ppi):
+    return round(px * 72.0 / _resolution_ppi(ppi), 2)
+
+
+def unit_size_to_pt(size, unit_is_pixel, units_per_inch, ppi):
+    """A text layer's font size in points, whichever unit it is stored in: pixels convert through
+    the image resolution; any other unit through its own units-per-inch factor."""
+    if unit_is_pixel or not units_per_inch:
+        return px_to_pt(size, ppi)
+    return round(size / units_per_inch * 72.0, 2)
+
+
+def _font_tokens(name):
+    return re.sub(r'[-_]+', ' ', name).lower().split()
+
+
+def _font_key(name):
+    return ' '.join(_font_tokens(name))
+
+
+def font_suggestions(query, names, limit=FONT_SUGGESTION_LIMIT):
+    """Up to `limit` installed font names closest to `query`: names containing it (or contained
+    by it) first, then the nearest by spelling."""
+    import difflib
+    q = _font_key(query)
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    out = [n for n in ordered if q and (q in _font_key(n) or _font_key(n) in q)][:limit]
+    if len(out) < limit:
+        by_key = {}
+        for n in ordered:
+            by_key.setdefault(_font_key(n), n)
+        for key in difflib.get_close_matches(q, list(by_key), n=limit, cutoff=0.0):
+            if by_key[key] not in out:
+                out.append(by_key[key])
+            if len(out) >= limit:
+                break
+    return out[:limit]
+
+
+def resolve_font(query, names):
+    """Resolve a family ("Inter", "Open Sans") or full name ("Inter Bold") to an installed font
+    name, case- and spacing-insensitively. Returns (name, matched_by) with matched_by in
+    'name' | 'family+regular' | 'family'. Raises ValueError listing the closest installed names
+    when nothing matches."""
+    if not isinstance(query, str) or not query.strip():
+        raise ValueError('font_name must be a non-empty string')
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    q = _font_key(query)
+    for n in ordered:
+        if _font_key(n) == q:
+            return n, 'name'
+    q_sorted = sorted(q.split())
+    for n in ordered:
+        if sorted(_font_tokens(n)) == q_sorted:
+            return n, 'name'
+    for style in _FONT_REGULAR_ORDER:
+        wanted = q + ' ' + style
+        for n in ordered:
+            if _font_key(n) == wanted:
+                return n, 'family+regular'
+    family = [
+        n for n in ordered
+        if _font_key(n).startswith(q + ' ')
+        and all(t in _FONT_STYLE_WORDS for t in _font_key(n)[len(q) + 1:].split())
+    ]
+    if family:
+        return min(family, key=lambda n: (len(n), n.lower())), 'family'
+    suggestions = font_suggestions(query, ordered)
+    if not suggestions:
+        raise ValueError('no installed font matches %r (no fonts are installed)' % query[:100])
+    raise ValueError(
+        'no installed font matches %r. Closest installed names: %s' % (query[:100], ', '.join(suggestions))
+    )
+
+
+def pick_default_font(names):
+    """The font a text layer gets when none is named: GIMP's built-in generic sans if listed,
+    else the first installed name (None when there are none)."""
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    for n in ordered:
+        if _font_key(n) == _font_key(DEFAULT_TEXT_FONT):
+            return n
+    return ordered[0] if ordered else None
+
+
+def list_fonts(names, substring=None):
+    """(page, total) for gimp_inspect what=fonts: names sorted case-insensitively, filtered by a
+    case-insensitive substring, capped at TEXT_FONT_LIST_CAP; `total` counts every match."""
+    ordered = sorted(set(names), key=lambda n: n.lower())
+    if substring:
+        needle = substring.lower()
+        ordered = [n for n in ordered if needle in n.lower()]
+    return ordered[:TEXT_FONT_LIST_CAP], len(ordered)
+
+
+# Headroom on the small-size layout probe: glyph advances hinted at a few pixels round to whole
+# pixels, so scaling a probe up can undershoot the full-size layout.
+TEXT_ESTIMATE_MARGIN = 1.3
+
+
+def estimate_text_extent(probe_w, probe_h, probe_px, size_px, chars=0, lines=1, letter_spacing=0.0,
+                         line_spacing=0.0, indent=0.0):
+    """The (width, height) in px a text layer will render at `size_px`, from its layout measured
+    at `probe_px` (`probe_w` x `probe_h`), with headroom. Letter spacing, line spacing and indent
+    are absolute pixels that do not scale with the font, so each adds its full worst case: spacing
+    after every character and between every line, plus the indent. Never below 1x1."""
+    scale = size_px / float(probe_px)
+    width = math.ceil(probe_w * scale * TEXT_ESTIMATE_MARGIN) + chars * max(0.0, letter_spacing) + max(0.0, indent)
+    height = math.ceil(probe_h * scale * TEXT_ESTIMATE_MARGIN) + max(0, lines - 1) * max(0.0, line_spacing)
+    return max(1, int(math.ceil(width))), max(1, int(math.ceil(height)))
+
+
+def check_estimated_text_size(width, height):
+    """Refuses text whose estimated size (`estimate_text_extent`) is past the engine's size cap,
+    before anything is drawn at full size."""
+    try:
+        validate_resize_dims(width, height)
+    except ValueError as exc:
+        raise ValueError(
+            'the text would render as about %dx%d px, past the size limit (%s); use a smaller '
+            'font_size or less text' % (width, height, exc)
+        )
+
+
+TEXT_REPORT_MAX_CHARS = 200
+
+
+def text_for_report(text):
+    """(text, length, truncated) for reporting a layer's text: at most TEXT_REPORT_MAX_CHARS,
+    since a layer opened from a file can hold any amount."""
+    text = text or ''
+    return text[:TEXT_REPORT_MAX_CHARS], len(text), len(text) > TEXT_REPORT_MAX_CHARS
+
+
+def check_text_layer_size(width, height):
+    """Refuses a rendered text layer past the engine's size cap (`validate_resize_dims`)."""
+    try:
+        validate_resize_dims(width, height)
+    except ValueError as exc:
+        raise ValueError(
+            'the text would render as a %dx%d px layer, past the size limit (%s); use a smaller '
+            'font_size or less text' % (width, height, exc)
+        )