/**
 * @fileoverview GaussianTrainRunner — the SOVEREIGN executor for `compile_to_gaussian_train` jobs.
 *
 * Runs a `GaussianTrainJob` (emitted by @holoscript/core GaussianTrainCompiler) on our own
 * gradient-checked autodiff path — GaussianTrainer3D (3D->2D projection) + GaussianTrainer2D
 * (alpha-blend backward) + Adam — over a set of posed views.
 *
 * HONEST SCOPE (what this is and is NOT — per the 2026-06-20 /critic review):
 *  - It IS a correct, finite-difference-verified differentiable 3DGS optimizer (the math is real).
 *  - FIXED-CARDINALITY: there is NO densification/pruning. The Gaussian count is exactly `initial.N`
 *    for the whole run. The job's `targetGaussians`/`densifyInterval` are NOT consumed here (they are
 *    the remote-backend / future-densification vocabulary) — so they are deliberately absent from the
 *    consumed `GaussianTrainJobSpec` below rather than declared-but-ignored.
 *  - DIFFUSE COLOR ONLY: flat per-gaussian RGB, no spherical harmonics — cannot fit view-dependent
 *    specular appearance. (A multi-view fit against targets rendered by this same forward pass cannot
 *    reveal this gap; real photometric captures will.)
 *  - CPU COST: O(views * iters * pixels * N) with NO tile binning or frustum culling (every gaussian
 *    is tested at every pixel). Tractable to ~hundreds of gaussians at thumbnail resolution; real
 *    scale (1e5-1e6 gaussians, HD, 30k iters) needs the WGSL kernel (splat-train-backward.wgsl —
 *    drafted, NOT yet dispatched on a GPU) plus tiling. This runner does NOT call that kernel.
 *  - This optimizes a SCENE FROM POSED VIEWS; it is not a full gsplat replacement until capture
 *    ingestion (PLY/point-cloud init + image decode) and the above are built. No real capture has
 *    been trained yet (blocked on source data — see GaussianTrainDataset.ts).
 */
import { type Gaussian3D, type SplatCamera } from './GaussianTrainer3D';
/**
 * Structural subset of @holoscript/core `GaussianTrainJob` that the runner consumes. Kept local
 * (not imported) so the engine package takes no new cross-package coupling on the core barrel —
 * the compiler emits a superset of this shape and the two are pinned by tests on both sides.
 */
export interface GaussianTrainJobSpec {
    hyperparams: {
        iterations: number;
        learningRates: {
            position: number;
            scale: number;
            rotation: number;
            opacity: number;
            color: number;
        };
        /** Renderer-matched 2D low-pass (Mip-Splatting eps2d). NOTE: forward3D applies a fixed 0.3px
         *  internally; a value other than 0.3 here is NOT yet honoured (threading it through forward3D
         *  is a follow-up). Present so the consumed spec records the assumed value. */
        dilation: number;
    };
    /** Adaptive density control (3DGS Algorithm 1). When ABSENT, the runner is fixed-cardinality
     *  (the original behaviour). When present, gaussians clone/split/prune across the warmup window. */
    densification?: {
        /** Densify every `interval` iterations. */
        interval: number;
        /** Start densifying at this iteration (warmup). */
        fromIter: number;
        /** Stop densifying after this iteration. */
        untilIter: number;
        /** Avg 2D-mean gradient (px) above which a gaussian is densified. */
        gradThreshold: number;
        /** Prune gaussians with opacity below this. */
        opacityPrune: number;
        /** Clone if max world scale <= this, else split. */
        scaleThreshold: number;
        /** Split shrink factor (paper φ = 1.6). */
        splitFactor?: number;
        /** Hard cap on gaussian count. */
        maxGaussians: number;
        /** Deterministic RNG seed (default 1). */
        seed?: number;
    };
}
/** A single posed training view: a camera + the ground-truth image it should reproduce. */
export interface TrainView {
    cam: SplatCamera;
    W: number;
    H: number;
    /** Target image, W*H*3 (row-major RGB), values in [0,1]. */
    target: Float64Array;
}
export interface TrainResult {
    gaussians: Gaussian3D;
    initialLoss: number;
    finalLoss: number;
    iterations: number;
    /** L2 loss sampled each iteration (summed over views). */
    lossHistory: number[];
    /** Final gaussian count (differs from initial.N iff densification ran). */
    finalCount: number;
}
/**
 * Execute a sovereign training job. `initial` is the starting gaussian set (from the job's `init`
 * point cloud, or a random scatter); `views` is the resolved posed-view dataset. Optimizes the
 * gaussians in place via Adam over `iterations`, accumulating gradients across all views each step.
 *
 * Note: the 2D low-pass dilation is applied inside forward3D at the renderer-matched 0.3px
 * (Mip-Splatting eps2d). `job.hyperparams.dilation` is the intended value and is expected to be
 * 0.3; a custom dilation would require threading it through forward3D (a follow-up).
 */
export declare function runGaussianTrainJob(job: GaussianTrainJobSpec, initial: Gaussian3D, views: TrainView[]): TrainResult;
//# sourceMappingURL=GaussianTrainRunner.d.ts.map