#!/usr/bin/env python3
"""Deterministic DERIVED terrain reconstruction, never a generator-return asset.

The authentic opaque ordinary Source controls geometry and low-frequency colour.
A bounded, coherent fine+midscale parent texture is retained as tone modulation. Material
boundaries use the engine's ScaleNx4 shape, and interpolation never mixes material
families. This flattens generated colour/lighting drift while retaining coherent material structure.
No asset registration, frame policy, game Source or parent image is modified.
Requires NumPy and Pillow; run with the bundled dependency Python.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import math
import os
from pathlib import Path
import stat
import struct
import sys
import numpy as np
import PIL
from PIL import Image

METHOD = 'source-broad-material-guidance-coherent-parent-fine-mid-logtexture-v1'
DEFAULTS = dict(output_side=512, source_sigma=3.0, residual_sigma_fine=0.65,
                residual_sigma_coarse=10.0, residual_percentile=80.0,
                texture_log_gain=dict(gray=0.38, olive=0.55, soil=0.34, rim=0.06))
FAMILY_NAMES = ('gray', 'olive', 'soil', 'rim')

def read_regular(path):
    p = Path(path).absolute()
    fd = os.open(p, os.O_RDONLY | os.O_NOFOLLOW)
    try:
        a = os.fstat(fd)
        if not stat.S_ISREG(a.st_mode):
            raise ValueError('input must be a regular file')
        with os.fdopen(fd, 'rb', closefd=False) as f:
            data = f.read()
        b = os.fstat(fd)
        if (a.st_dev, a.st_ino, a.st_size, a.st_mtime_ns) != (b.st_dev, b.st_ino, b.st_size, b.st_mtime_ns):
            raise ValueError('input changed during read')
    finally:
        os.close(fd)
    return data, dict(path=str(p), sha256=hashlib.sha256(data).hexdigest(),
                      size=a.st_size, mtime_ns=a.st_mtime_ns, mode=a.st_mode)

def decode_source(data):
    if len(data) < 20:
        raise ValueError('short Source PIC')
    header = struct.unpack_from('<5i', data)
    kind, count, offset, width, height = header
    if (kind, count, offset) != (1, 1, 0) or not (1 <= width <= 128 and 1 <= height <= 128):
        raise ValueError('this tool supports a single uncompressed Source PIC only')
    if len(data) != 20 + width * height:
        raise ValueError('Source payload size mismatch')
    indices = np.frombuffer(data[20:], dtype=np.uint8).reshape(height, width).copy()
    if np.any(indices >= 240):
        raise ValueError('only fully opaque ordinary Source indices0..239 are supported')
    return indices

def palette_rgb(data):
    if len(data) != 768:
        raise ValueError('palette must contain256 three-channel6-bit entries')
    a = np.minimum(np.frombuffer(data, np.uint8).reshape(256, 3).astype(np.uint16), 63)
    return ((a << 2) | (a >> 4)).astype(np.uint8)

def material_families(indices):
    """Explicit supported Raptor palette families; no per-asset painted mask."""
    a = np.asarray(indices)
    out = np.full(a.shape, -1, dtype=np.int8)
    out[a < 32] = 0
    out[(a >= 60) & (a <= 63)] = 1
    out[((a >= 192) & (a <= 223)) | (a == 239)] = 2
    out[(a >= 224) & (a <= 238)] = 3
    if np.any(out < 0):
        raise ValueError('Source contains unsupported material family')
    return out

def scale_nx(indices, factor):
    """Exact Scale2x/3x; Scale4x is two Scale2x passes, as render::upscale."""
    a = np.asarray(indices)
    if factor == 1:
        return a.copy()
    if factor == 4:
        return scale_nx(scale_nx(a, 2), 2)
    if factor not in (2, 3) or a.ndim != 2:
        raise ValueError('ScaleNx factor must be1..4 on a plane')
    h, w = a.shape
    p = np.pad(a, 1, mode='edge')
    out = np.empty((h * factor, w * factor), dtype=a.dtype)
    for y in range(h):
        for x in range(w):
            nw, n, ne, west, c, east, sw, south, se = p[y:y+3, x:x+3].flatten().tolist()
            cells = [c] * (factor * factor)
            if n != south and west != east:
                if factor == 2:
                    cells = [west if west == n else c, east if n == east else c,
                             west if west == south else c, east if south == east else c]
                else:
                    cells = [west if west == n else c,
                             n if (west == n and c != ne) or (n == east and c != nw) else c,
                             east if n == east else c,
                             west if (west == n and c != sw) or (west == south and c != nw) else c,
                             c,
                             east if (n == east and c != se) or (south == east and c != ne) else c,
                             west if west == south else c,
                             south if (west == south and c != se) or (south == east and c != sw) else c,
                             east if south == east else c]
            out[y*factor:(y+1)*factor, x*factor:(x+1)*factor] = np.array(cells).reshape(factor, factor)
    return out

def gaussian(a, sigma):
    a = np.asarray(a, dtype=np.float64)
    if not math.isfinite(sigma) or sigma <= 0:
        raise ValueError('sigma must be finite and positive')
    radius = int(math.ceil(3 * sigma))
    q = np.arange(-radius, radius + 1, dtype=np.float64)
    k = np.exp(-0.5 * (q / sigma) ** 2)
    k /= k.sum()
    b = a
    for axis in (0, 1):
        padding = [(0, 0)] * a.ndim
        padding[axis] = (radius, radius)
        p = np.pad(b, padding, mode='edge')
        b = np.zeros_like(a)
        for i, weight in enumerate(k):
            sl = [slice(None)] * a.ndim
            sl[axis] = slice(i, i + a.shape[axis])
            b += weight * p[tuple(sl)]
    return b

def resize_float(a, size):
    a = np.asarray(a, np.float32)
    if a.ndim == 3:
        return np.stack([resize_float(a[..., i], size) for i in range(a.shape[2])], -1)
    return np.asarray(Image.fromarray(a).resize(size, Image.Resampling.BILINEAR), np.float64)

def validate_parameters(p, source_shape):
    if set(p) != set(DEFAULTS):
        raise ValueError('unknown or missing reconstruction parameter')
    side = p['output_side']
    if type(side) is not int or not 4 * max(source_shape) <= side <= 2048 or side % (4 * max(source_shape)):
        raise ValueError('output must be an integer expansion of SourceNx4, at least4x')
    for name in ('source_sigma', 'residual_sigma_fine', 'residual_sigma_coarse'):
        if type(p[name]) not in (int, float) or not math.isfinite(p[name]) or not 0 < p[name] <= 16:
            raise ValueError('invalid smoothing parameter')
    if p['residual_sigma_fine'] >= p['residual_sigma_coarse']:
        raise ValueError('fine band must be narrower than coarse band')
    q = p['residual_percentile']
    if type(q) not in (int, float) or not math.isfinite(q) or not 50 <= q <= 100:
        raise ValueError('invalid residual percentile')
    if set(p['texture_log_gain']) != set(FAMILY_NAMES):
        raise ValueError('all material residual amplitudes required')
    for v in p['texture_log_gain'].values():
        if type(v) not in (int, float) or not math.isfinite(v) or not 0 <= v <= 0.7:
            raise ValueError('invalid bounded log-texture gain')

def reconstruct(indices, palette, generated_rgb, parameters=None):
    p = json.loads(json.dumps(DEFAULTS if parameters is None else parameters))
    a = np.asarray(indices)
    if a.ndim != 2 or a.shape[0] != a.shape[1] or a.size == 0 or np.any(a >= 240) or np.any(a < 0):
        raise ValueError('square opaque ordinary Source required')
    validate_parameters(p, a.shape)
    guide_indices = scale_nx(a, 4)
    labels = material_families(guide_indices)
    guide = np.asarray(palette)[guide_indices].astype(np.float64)
    side = p['output_side']
    factor = side // labels.shape[0]
    owners = np.repeat(np.repeat(labels, factor, 0), factor, 1)
    base = np.zeros((side, side, 3), dtype=np.float64)
    quiet = np.ones((side, side), dtype=np.float64)
    guide_luma = guide @ np.array([0.2126, 0.7152, 0.0722])
    for family in np.unique(labels):
        mask = (labels == family).astype(np.float64)
        weights = resize_float(gaussian(mask, p['source_sigma']), (side, side))
        numerator = resize_float(gaussian(guide * mask[..., None], p['source_sigma']), (side, side))
        field = numerator / np.maximum(weights[..., None], 1e-12)
        base[owners == family] = field[owners == family]
        if family == 2:
            second = resize_float(gaussian(guide_luma**2 * mask, p['source_sigma']), (side, side)) / np.maximum(weights, 1e-12)
            first = field @ np.array([0.2126, 0.7152, 0.0722])
            std = np.sqrt(np.maximum(second-first**2, 0))
            # Calm Source soil (e.g.20400right) receives less texture strength.
            # This map is derived from Source variance, never hand-painted.
            quiet[owners == family] = (0.35+0.65*np.clip(std/8.0,0,1))[owners == family]
    raw = np.asarray(generated_rgb)
    if raw.ndim != 3 or raw.shape[2] != 3 or raw.dtype != np.uint8:
        raise ValueError('generated input must be RGB uint8')
    parent = np.asarray(Image.fromarray(raw).resize((side, side), Image.Resampling.LANCZOS), np.float64)
    luma = parent @ np.array([0.2126, 0.7152, 0.0722])
    band = gaussian(luma, p['residual_sigma_fine']) - gaussian(luma, p['residual_sigma_coarse'])
    texture = np.zeros_like(band)
    normalizers = {}
    for family in np.unique(owners):
        area = owners == family
        centered = band-band[area].mean()
        divisor = max(float(np.percentile(np.abs(centered[area]),p['residual_percentile'])),1.0)
        texture[area] = np.tanh(centered[area]/divisor)
        normalizers[FAMILY_NAMES[int(family)]] = divisor
    strengths = np.array([p['texture_log_gain'][n]for n in FAMILY_NAMES])[owners]*quiet
    gain = np.exp(strengths*texture)
    output = np.clip(np.rint(base*gain[...,None]),0,255).astype(np.uint8)
    base8 = np.clip(np.rint(base),0,255).astype(np.uint8)
    metrics = dict(method=METHOD, source_shape=list(a.shape),output_shape=list(output.shape),
        sourceNx4_indices_sha256=hashlib.sha256(guide_indices.astype('<u2').tobytes()).hexdigest(),
        geometry_material_labels_sha256=hashlib.sha256(owners.tobytes()).hexdigest(),
        material_output_pixels={FAMILY_NAMES[int(i)]:int((owners==i).sum())for i in np.unique(owners)},
        coherent_parent_band_std=float(band.std()),per_family_normalizers=normalizers,
        actual_tone_gain_min=float(gain.min()),actual_tone_gain_max=float(gain.max()),
        pixels_changed_from_Source_guided_base=int(np.any(output!=base8,axis=2).sum()),
        mean_absolute_parent_tone_modulation=float(np.abs(output.astype(float)-base8).mean()),
        Source_derived_soil_quiet_strength_min=float(quiet[owners==2].min())if np.any(owners==2)else None,
        Source_derived_soil_quiet_strength_max=float(quiet[owners==2].max())if np.any(owners==2)else None,
        output_RGB_sha256=hashlib.sha256(output.tobytes()).hexdigest(),output_is_derived_not_untouched=True,
        limits='Source masks/broad tones/rims; actual coherent generated fine+midscale luminance is hue-preserving multiplicative texture. No random noise; large generated hue/illumination drift discarded. Not material/context approval.')

    return output, base8, owners, metrics

def main(argv=None):
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument('--recipe', required=True)
    ap.add_argument('--output', required=True)
    args = ap.parse_args(argv)
    recipe_path = Path(args.recipe).absolute()
    recipe_bytes, recipe_pin = read_regular(recipe_path)
    recipe = json.loads(recipe_bytes)
    if recipe.get('method') != METHOD or not isinstance(recipe.get('frames'), list) or not recipe['frames']:
        raise ValueError('wrong method or empty recipe')
    def recipe_input(binding):
        path = Path(binding['path'])
        if not path.is_absolute():
            path = recipe_path.parent / path
        return read_regular(path)
    palette_bytes, palette_pin = recipe_input(recipe['palette'])
    if palette_pin['sha256'] != recipe['palette']['sha256']:
        raise ValueError('palette identity mismatch')
    palette = palette_rgb(palette_bytes)
    prepared = []
    seen = set()
    for row in recipe['frames']:
        asset = row['asset']
        if not isinstance(asset, str) or len(asset) != 5 or any(c not in '0123456789abcdef' for c in asset) or asset in seen:
            raise ValueError('invalid or duplicate asset')
        seen.add(asset)
        source, source_pin = recipe_input(row['Source'])
        parent_bytes, parent_pin = recipe_input(row['parent_raw'])
        if source_pin['sha256'] != row['Source']['sha256'] or parent_pin['sha256'] != row['parent_raw']['sha256']:
            raise ValueError('source or parent identity mismatch')
        indices = decode_source(source)
        import io
        parent = Image.open(io.BytesIO(parent_bytes))
        if parent.convert('RGBA').getchannel('A').getextrema() != (255, 255):
            raise ValueError('parent must be wholly opaque; no alpha repair')
        crop = row['crop']
        if not isinstance(crop, list) or len(crop) != 4 or any(type(v) is not int for v in crop):
            raise ValueError('crop must be four exact integers')
        x, y, w, h = crop
        if min(x, y) < 0 or w <= 0 or h <= 0 or x+w > parent.width or y+h > parent.height:
            raise ValueError('crop outside untouched parent')
        raw = np.array(parent.convert('RGB').crop((x, y, x+w, y+h)))
        derived, base, labels, metrics = reconstruct(indices, palette, raw, recipe['parameters'])
        prepared.append((asset, derived, base, labels, metrics, source_pin, parent_pin, crop))
    out = Path(args.output).absolute()
    out.mkdir(exist_ok=False)
    tool_bytes, tool_pin = read_regular(__file__)
    results = []
    for asset, derived, base, labels, metrics, source_pin, parent_pin, crop in prepared:
        image_path = out / f'{asset}-DERIVED-source-guided-material-v1.png'
        Image.fromarray(derived).save(image_path)
        Image.fromarray(base).save(out / f'{asset}-SOURCE-GUIDED-BASE-diagnostic.png')
        Image.fromarray(labels.astype(np.uint8)).save(out / f'{asset}-SOURCE-NX4-FAMILY-geometry-diagnostic.png')
        _, output_pin = read_regular(image_path)
        results.append(dict(asset=asset, output=output_pin, Source=source_pin, parent_raw=parent_pin,
                            parent_crop=crop, recipe=recipe_pin, tool=tool_pin,
                            parameters=recipe['parameters'], metrics=metrics,
                            lineage='DERIVED scripted cleanup; generator-return parent remains untouched'))
    for record in [recipe_pin, palette_pin] + [p for t in prepared for p in (t[5], t[6])]:
        _, now = read_regular(record['path'])
        if now != record:
            raise ValueError('input changed across cleanup')
    runtime = dict(python=sys.version, executable=sys.executable,
                   numpy=np.__version__, Pillow=PIL.__version__, platform=sys.platform)
    execution = dict(status='success', method=METHOD,
                     recipe_sha256=recipe_pin['sha256'], tool_sha256=tool_pin['sha256'],
                     source_sha256={r['asset']: r['Source']['sha256'] for r in results},
                     parent_raw_sha256=sorted({r['parent_raw']['sha256'] for r in results}),
                     output_sha256={r['asset']: r['output']['sha256'] for r in results},
                     runtime=runtime)
    (out / 'DERIVED-LINEAGE-AND-ACTUAL-RECONSTRUCTION-METRICS.json').write_text(
        json.dumps(dict(status='DERIVED_OUTPUTS_NOT_MATERIAL_APPROVAL', method=METHOD,
                        recipe=recipe_pin, tool=tool_pin, palette=palette_pin, frames=results,
                        execution=execution, runtime=runtime), indent=2, sort_keys=True) + '\n')
    print(json.dumps(dict(output=str(out), frames=len(results), method=METHOD), indent=2))

if __name__ == '__main__':
    main()