@pilio/gemini-watermark-remover 1.0.26 → 1.0.28

package/src/core/pipelineLayerContracts.js

@@ -0,0 +1,163 @@
+export const PIPELINE_LAYER_ORDER = Object.freeze([
+    'detection',
+    'alpha',
+    'repair',
+    'evaluation'
+]);
+
+export const PIPELINE_LAYER_CONTRACTS = Object.freeze({
+    detection: Object.freeze({
+        layer: 'detection',
+        owns: 'candidate-localization-and-evidence',
+        inputFields: Object.freeze([
+            'originalImageData',
+            'resolvedConfig',
+            'position',
+            'alpha48',
+            'alpha96',
+            'alpha96Variants',
+            'allowAdaptiveSearch',
+            'alphaGainCandidates',
+            'alphaPriorityGains'
+        ]),
+        outputFields: Object.freeze([
+            'selectedTrial',
+            'source',
+            'decisionTier',
+            'adaptiveConfidence',
+            'standardSpatialScore',
+            'standardGradientScore'
+        ]),
+        moduleAnchors: Object.freeze([
+            'pipelineDetectionCandidate',
+            'pipelineInitialContext',
+            'pipelineInitialSelection',
+            'candidateSelector'
+        ]),
+        testAnchors: Object.freeze([
+            'pipelineDetectionCandidate.test',
+            'pipelineInitialContext.test',
+            'pipelineInitialSelection.test',
+            'candidateEvaluation.test'
+        ])
+    }),
+    alpha: Object.freeze({
+        layer: 'alpha',
+        owns: 'alpha-map-selection-and-alpha-fit',
+        inputFields: Object.freeze([
+            'acceptedPipelineState',
+            'runtimeBootstrap',
+            'alpha96',
+            'getAlphaMap',
+            'alpha96Variants',
+            'alphaGain',
+            'alphaMapSource'
+        ]),
+        outputFields: Object.freeze([
+            'alphaTrialEvents',
+            'alphaAdjustmentStages',
+            'alphaGain',
+            'alphaMap',
+            'subpixelShift',
+            'pipelineState'
+        ]),
+        moduleAnchors: Object.freeze([
+            'pipelineAlphaTraceContract',
+            'pipelineAlphaTrial',
+            'pipelineAlphaStageSpecs',
+            'pipelineAcceptedExecutor',
+            'pipelineRuntime'
+        ]),
+        testAnchors: Object.freeze([
+            'pipelineAlphaTraceContract.test',
+            'pipelineAlphaTrial.test',
+            'pipelineAlphaStageSpecs.test',
+            'pipelineAcceptedExecutor.test',
+            'pipelineRuntime.test'
+        ])
+    }),
+    repair: Object.freeze({
+        layer: 'repair',
+        owns: 'texture-repair-and-artifact-gated-cleanup',
+        inputFields: Object.freeze([
+            'pipelineState',
+            'passState',
+            'cleanupFlags',
+            'repairCleanupConfig',
+            'visualPostProcessingEnabled'
+        ]),
+        outputFields: Object.freeze([
+            'repairTrial',
+            'passState',
+            'passes',
+            'source',
+            'finalImageData',
+            'finalProcessedSpatialScore',
+            'finalProcessedGradientScore'
+        ]),
+        moduleAnchors: Object.freeze([
+            'pipelineRepairTrial',
+            'pipelineRepairStageSpecs',
+            'pipelineRepairGates',
+            'pipelineAcceptedExecutor'
+        ]),
+        testAnchors: Object.freeze([
+            'pipelineRepairTrial.test',
+            'pipelineRepairStageSpecs.test',
+            'pipelineRepairGates.test',
+            'pipelineAcceptedExecutor.test'
+        ])
+    }),
+    evaluation: Object.freeze({
+        layer: 'evaluation',
+        owns: 'decision-path-and-risk-gated-arbitration',
+        inputFields: Object.freeze([
+            'detectionCandidate',
+            'alphaTrial',
+            'repairTrial',
+            'selectedTrial',
+            'alphaTrialEvents',
+            'residualVisibility'
+        ]),
+        outputFields: Object.freeze([
+            'decisionPath',
+            'evaluationDecision',
+            'blockedGate',
+            'riskFlags',
+            'selectionDebug',
+            'meta'
+        ]),
+        moduleAnchors: Object.freeze([
+            'pipelineDecisionPath',
+            'candidateEvaluation',
+            'pipelineMeta',
+            'pipelineFinalization',
+            'pipelineResult'
+        ]),
+        testAnchors: Object.freeze([
+            'pipelineDecisionPath.test',
+            'candidateEvaluation.test',
+            'pipelineMeta.test',
+            'pipelineFinalization.test',
+            'pipelineResult.test'
+        ])
+    })
+});
+
+export function getPipelineLayerContract(layer) {
+    return PIPELINE_LAYER_CONTRACTS[layer] ?? null;
+}
+
+export function createPipelineLayerContractSummary() {
+    return PIPELINE_LAYER_ORDER.map((layer) => {
+        const contract = getPipelineLayerContract(layer);
+        return {
+            layer,
+            owns: contract.owns,
+            inputCount: contract.inputFields.length,
+            outputCount: contract.outputFields.length,
+            moduleAnchors: [...contract.moduleAnchors],
+            testAnchors: [...contract.testAnchors]
+        };
+    });
+}

package/src/core/pipelineMeta.js

@@ -0,0 +1,201 @@
+import {
+    createAcceptedDecisionPath,
+    createRejectedDecisionPath
+} from './candidateEvaluation.js';
+
+function normalizeMetaPosition(position) {
+    if (!position) return null;
+
+    const { x, y, width, height } = position;
+    if (![x, y, width, height].every((value) => Number.isFinite(value))) {
+        return null;
+    }
+
+    return { x, y, width, height };
+}
+
+function normalizeMetaConfig(config) {
+    if (!config) return null;
+
+    const { logoSize, marginRight, marginBottom } = config;
+    if (![logoSize, marginRight, marginBottom].every((value) => Number.isFinite(value))) {
+        return null;
+    }
+
+    return {
+        logoSize,
+        marginRight,
+        marginBottom,
+        ...(typeof config.alphaVariant === 'string' && config.alphaVariant.length > 0
+            ? { alphaVariant: config.alphaVariant }
+            : {})
+    };
+}
+
+export function createWatermarkMeta({
+    position = null,
+    config = null,
+    adaptiveConfidence = null,
+    originalSpatialScore = null,
+    originalGradientScore = null,
+    processedSpatialScore = null,
+    processedGradientScore = null,
+    suppressionGain = null,
+    residualVisibility = null,
+    templateWarp = null,
+    alphaGain = 1,
+    passCount = 0,
+    attemptedPassCount = 0,
+    passStopReason = null,
+    passes = null,
+    source = 'standard',
+    decisionTier = null,
+    applied = true,
+    skipReason = null,
+    subpixelShift = null,
+    selectionDebug = null,
+    alphaAdjustmentStages = null,
+    alphaMapSource = null,
+    decisionPath = null
+} = {}) {
+    const normalizedPosition = normalizeMetaPosition(position);
+
+    return {
+        applied,
+        skipReason: applied ? null : skipReason,
+        size: normalizedPosition ? normalizedPosition.width : null,
+        position: normalizedPosition,
+        config: normalizeMetaConfig(config),
+        detection: {
+            adaptiveConfidence,
+            originalSpatialScore,
+            originalGradientScore,
+            processedSpatialScore,
+            processedGradientScore,
+            suppressionGain,
+            residualVisibility
+        },
+        templateWarp: templateWarp ?? null,
+        alphaGain,
+        passCount,
+        attemptedPassCount,
+        passStopReason,
+        passes: Array.isArray(passes) ? passes : null,
+        // decisionTier is the normalized contract used by UI and attribution.
+        // source remains as a verbose execution trace for debugging/tests.
+        source,
+        decisionTier,
+        subpixelShift: subpixelShift ?? null,
+        selectionDebug,
+        alphaAdjustmentStages: Array.isArray(alphaAdjustmentStages) ? alphaAdjustmentStages : null,
+        alphaMapSource: alphaMapSource ?? null,
+        decisionPath: decisionPath ?? null
+    };
+}
+
+export function createAcceptedWatermarkMeta({
+    selectedTrial = null,
+    selectionSource = null,
+    position = null,
+    config = null,
+    adaptiveConfidence = null,
+    originalSpatialScore = null,
+    originalGradientScore = null,
+    processedSpatialScore = null,
+    processedGradientScore = null,
+    suppressionGain = null,
+    residualVisibility = null,
+    templateWarp = null,
+    alphaGain = 1,
+    passCount = 0,
+    attemptedPassCount = 0,
+    passStopReason = null,
+    passes = null,
+    source = 'standard',
+    decisionTier = null,
+    subpixelShift = null,
+    selectionDebug = null,
+    alphaAdjustmentStages = null,
+    alphaTrialEvents = null,
+    alphaMapSource = null
+} = {}) {
+    const decisionPath = createAcceptedDecisionPath({
+        selectedTrial,
+        selectionSource,
+        source,
+        decisionTier,
+        config,
+        position,
+        adaptiveConfidence,
+        alphaGain,
+        alphaMapSource,
+        templateWarp,
+        alphaAdjustmentStages,
+        alphaTrialEvents,
+        originalSpatialScore,
+        originalGradientScore,
+        processedSpatialScore,
+        processedGradientScore,
+        suppressionGain,
+        residualVisibility
+    });
+
+    return createWatermarkMeta({
+        position,
+        config,
+        adaptiveConfidence,
+        originalSpatialScore,
+        originalGradientScore,
+        processedSpatialScore,
+        processedGradientScore,
+        suppressionGain,
+        residualVisibility,
+        templateWarp,
+        alphaGain,
+        passCount,
+        attemptedPassCount,
+        passStopReason,
+        passes,
+        source,
+        decisionTier,
+        applied: true,
+        subpixelShift,
+        alphaAdjustmentStages,
+        alphaMapSource,
+        selectionDebug,
+        decisionPath
+    });
+}
+
+export function createRejectedWatermarkMeta({
+    reason = 'no-watermark-detected',
+    source = 'skipped',
+    decisionTier = 'insufficient',
+    adaptiveConfidence = null,
+    originalSpatialScore = null,
+    originalGradientScore = null,
+    selectionDebug = null
+} = {}) {
+    return createWatermarkMeta({
+        adaptiveConfidence,
+        originalSpatialScore,
+        originalGradientScore,
+        processedSpatialScore: originalSpatialScore,
+        processedGradientScore: originalGradientScore,
+        suppressionGain: 0,
+        alphaGain: 1,
+        source,
+        decisionTier,
+        applied: false,
+        skipReason: reason,
+        selectionDebug,
+        decisionPath: createRejectedDecisionPath({
+            reason,
+            source,
+            decisionTier,
+            originalSpatialScore,
+            originalGradientScore,
+            adaptiveConfidence
+        })
+    });
+}

package/src/core/pipelineMetrics.js

@@ -0,0 +1,88 @@
+import {
+    computeRegionGradientCorrelation,
+    computeRegionSpatialCorrelation
+} from './adaptiveDetector.js';
+import { calculateNearBlackRatio } from './candidateSelector.js';
+
+const FIRST_PASS_SIGN_FLIP_GRADIENT_THRESHOLD = 0.08;
+const FIRST_PASS_SIGN_FLIP_MIN_GRADIENT_DROP = 0.2;
+
+export function shouldStopAfterFirstPass({
+    originalSpatialScore,
+    originalGradientScore,
+    firstPassSpatialScore,
+    firstPassGradientScore
+}) {
+    if (Math.abs(firstPassSpatialScore) <= 0.25) {
+        return true;
+    }
+
+    return originalSpatialScore >= 0 &&
+        firstPassSpatialScore < 0 &&
+        firstPassGradientScore <= FIRST_PASS_SIGN_FLIP_GRADIENT_THRESHOLD &&
+        (originalGradientScore - firstPassGradientScore) >= FIRST_PASS_SIGN_FLIP_MIN_GRADIENT_DROP;
+}
+
+export function createRegionCorrelationMetrics({
+    imageData,
+    alphaMap,
+    position,
+    includeNearBlackRatio = false
+} = {}) {
+    const region = { x: position.x, y: position.y, size: position.width };
+    const metrics = {
+        spatialScore: computeRegionSpatialCorrelation({
+            imageData,
+            alphaMap,
+            region
+        }),
+        gradientScore: computeRegionGradientCorrelation({
+            imageData,
+            alphaMap,
+            region
+        })
+    };
+    if (includeNearBlackRatio) {
+        metrics.nearBlackRatio = calculateNearBlackRatio(imageData, position);
+    }
+    return metrics;
+}
+
+export function createFirstPassMetrics({
+    imageData,
+    alphaMap,
+    position,
+    originalSpatialScore,
+    originalGradientScore
+} = {}) {
+    const firstPassMetrics = createRegionCorrelationMetrics({
+        imageData,
+        alphaMap,
+        position,
+        includeNearBlackRatio: true
+    });
+    const clearedResidual = shouldStopAfterFirstPass({
+        originalSpatialScore,
+        originalGradientScore,
+        firstPassSpatialScore: firstPassMetrics.spatialScore,
+        firstPassGradientScore: firstPassMetrics.gradientScore
+    });
+
+    return {
+        spatialScore: firstPassMetrics.spatialScore,
+        gradientScore: firstPassMetrics.gradientScore,
+        nearBlackRatio: firstPassMetrics.nearBlackRatio,
+        clearedResidual,
+        passStopReason: clearedResidual ? 'residual-low' : 'single-pass',
+        passRecord: {
+            index: 1,
+            beforeSpatialScore: originalSpatialScore,
+            beforeGradientScore: originalGradientScore,
+            afterSpatialScore: firstPassMetrics.spatialScore,
+            afterGradientScore: firstPassMetrics.gradientScore,
+            improvement: Math.abs(originalSpatialScore) - Math.abs(firstPassMetrics.spatialScore),
+            gradientDelta: firstPassMetrics.gradientScore - originalGradientScore,
+            nearBlackRatio: firstPassMetrics.nearBlackRatio
+        }
+    };
+}

package/src/core/pipelinePassState.js

@@ -0,0 +1,36 @@
+function finiteOrFallback(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+export function createEmptyPipelinePassState() {
+    return {
+        passCount: 0,
+        attemptedPassCount: 0,
+        passStopReason: null,
+        passes: null
+    };
+}
+
+export function createFirstPassPipelinePassState({
+    firstPassMetrics = null
+} = {}) {
+    return {
+        passCount: 1,
+        attemptedPassCount: 1,
+        passStopReason: firstPassMetrics?.passStopReason ?? null,
+        passes: [firstPassMetrics?.passRecord]
+    };
+}
+
+export function applyPipelinePassOutcome({
+    current,
+    outcome
+} = {}) {
+    const passIncrement = Math.max(0, finiteOrFallback(outcome?.passIncrement, 0));
+    return {
+        passCount: finiteOrFallback(current?.passCount, 0) + passIncrement,
+        attemptedPassCount: finiteOrFallback(current?.attemptedPassCount, 0) + passIncrement,
+        passStopReason: outcome?.passStopReason ?? current?.passStopReason ?? null,
+        passes: current?.passes ?? null
+    };
+}

package/src/core/pipelineRepairGates.js

@@ -0,0 +1,124 @@
+const DEFAULT_PREVIEW_EDGE_CLEANUP_MAX_SIZE = 40;
+const DEFAULT_KNOWN_48_EDGE_CLEANUP_MIN_SIZE = 40;
+const DEFAULT_KNOWN_48_EDGE_CLEANUP_MAX_SIZE = 56;
+const DEFAULT_V2_SMALL_EDGE_CLEANUP_SIZE = 36;
+const DEFAULT_V2_SMALL_EDGE_CLEANUP_SIZE_TOLERANCE = 2;
+
+export function shouldUsePreviewAnchorFastCleanup(
+    selectedTrial,
+    position,
+    { previewEdgeCleanupMaxSize = DEFAULT_PREVIEW_EDGE_CLEANUP_MAX_SIZE } = {}
+) {
+    return selectedTrial?.provenance?.previewAnchor === true &&
+        position?.width >= 24 &&
+        position?.width <= previewEdgeCleanupMaxSize;
+}
+
+export function isKnown48AnchorConfig(
+    config,
+    {
+        known48EdgeCleanupMinSize = DEFAULT_KNOWN_48_EDGE_CLEANUP_MIN_SIZE,
+        known48EdgeCleanupMaxSize = DEFAULT_KNOWN_48_EDGE_CLEANUP_MAX_SIZE
+    } = {}
+) {
+    if (!config || config.logoSize < known48EdgeCleanupMinSize || config.logoSize > known48EdgeCleanupMaxSize) {
+        return false;
+    }
+
+    const marginRight = Number(config.marginRight);
+    const marginBottom = Number(config.marginBottom);
+    if (!Number.isFinite(marginRight) || !Number.isFinite(marginBottom)) return false;
+
+    const isCurrentLargeMargin = Math.abs(marginRight - 96) <= 2 && Math.abs(marginBottom - 96) <= 2;
+    const isCurrentStandardMargin = marginRight >= 28 && marginRight <= 36 && marginBottom >= 28 && marginBottom <= 36;
+    return isCurrentLargeMargin || isCurrentStandardMargin;
+}
+
+export function shouldUseKnown48EdgeCleanup({
+    selectedTrial,
+    position,
+    source,
+    known48EdgeCleanupMinSize = DEFAULT_KNOWN_48_EDGE_CLEANUP_MIN_SIZE,
+    known48EdgeCleanupMaxSize = DEFAULT_KNOWN_48_EDGE_CLEANUP_MAX_SIZE
+} = {}) {
+    if (selectedTrial?.provenance?.previewAnchor === true) return false;
+    if (position?.width < known48EdgeCleanupMinSize || position?.width > known48EdgeCleanupMaxSize) return false;
+    if (!isKnown48AnchorConfig(selectedTrial?.config, {
+        known48EdgeCleanupMinSize,
+        known48EdgeCleanupMaxSize
+    })) return false;
+
+    const sourceText = String(source || '');
+    return sourceText === 'standard' ||
+        sourceText.startsWith('standard+gain') ||
+        sourceText.includes('catalog') ||
+        sourceText.includes('fixed-local');
+}
+
+export function isV2SmallAnchorConfig(
+    config,
+    { v2SmallEdgeCleanupSize = DEFAULT_V2_SMALL_EDGE_CLEANUP_SIZE } = {}
+) {
+    if (!config || config.logoSize !== v2SmallEdgeCleanupSize || config.alphaVariant !== 'v2') {
+        return false;
+    }
+
+    const marginRight = Number(config.marginRight);
+    const marginBottom = Number(config.marginBottom);
+    return Number.isFinite(marginRight) &&
+        Number.isFinite(marginBottom) &&
+        marginRight >= 48 &&
+        marginBottom >= 48;
+}
+
+export function shouldUseV2SmallEdgeCleanup({
+    selectedTrial,
+    position,
+    source,
+    v2SmallEdgeCleanupSize = DEFAULT_V2_SMALL_EDGE_CLEANUP_SIZE,
+    v2SmallEdgeCleanupSizeTolerance = DEFAULT_V2_SMALL_EDGE_CLEANUP_SIZE_TOLERANCE
+} = {}) {
+    if (selectedTrial?.provenance?.previewAnchor === true) return false;
+    if (
+        position?.width < v2SmallEdgeCleanupSize - v2SmallEdgeCleanupSizeTolerance ||
+        position?.width > v2SmallEdgeCleanupSize + v2SmallEdgeCleanupSizeTolerance
+    ) {
+        return false;
+    }
+    if (!isV2SmallAnchorConfig(selectedTrial?.config, { v2SmallEdgeCleanupSize })) return false;
+    if (selectedTrial?.provenance?.catalogFamily !== 'gemini-v2-small') return false;
+
+    const sourceText = String(source || '');
+    return sourceText.includes('catalog');
+}
+
+export function createRepairCleanupFlags({
+    selectedTrial,
+    position,
+    source,
+    previewEdgeCleanupMaxSize = DEFAULT_PREVIEW_EDGE_CLEANUP_MAX_SIZE,
+    known48EdgeCleanupMinSize = DEFAULT_KNOWN_48_EDGE_CLEANUP_MIN_SIZE,
+    known48EdgeCleanupMaxSize = DEFAULT_KNOWN_48_EDGE_CLEANUP_MAX_SIZE,
+    v2SmallEdgeCleanupSize = DEFAULT_V2_SMALL_EDGE_CLEANUP_SIZE,
+    v2SmallEdgeCleanupSizeTolerance = DEFAULT_V2_SMALL_EDGE_CLEANUP_SIZE_TOLERANCE
+} = {}) {
+    return {
+        usePreviewAnchorFastCleanup: shouldUsePreviewAnchorFastCleanup(selectedTrial, position, {
+            previewEdgeCleanupMaxSize
+        }),
+        useKnown48EdgeCleanup: shouldUseKnown48EdgeCleanup({
+            selectedTrial,
+            position,
+            source,
+            known48EdgeCleanupMinSize,
+            known48EdgeCleanupMaxSize
+        }),
+        useV2SmallEdgeCleanup: shouldUseV2SmallEdgeCleanup({
+            selectedTrial,
+            position,
+            source,
+            v2SmallEdgeCleanupSize,
+            v2SmallEdgeCleanupSizeTolerance
+        })
+    };
+}