mcp-relight-harmonize 1.0.0

package/dist/contracts/schemas.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+export declare const AnalyzeOpticalInputSchema: z.ZodObject<{
+    image_path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    image_path: string;
+}, {
+    image_path: string;
+}>;
+export declare const GenerateRelightInputSchema: z.ZodObject<{
+    image_path: z.ZodString;
+    target_lighting: z.ZodDefault<z.ZodEnum<["Ambient", "Dramatic", "Rim", "Mood", "All"]>>;
+    output_dir: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    image_path: string;
+    target_lighting: "Ambient" | "Dramatic" | "Rim" | "Mood" | "All";
+    output_dir: string;
+}, {
+    image_path: string;
+    target_lighting?: "Ambient" | "Dramatic" | "Rim" | "Mood" | "All" | undefined;
+    output_dir?: string | undefined;
+}>;
+export declare const HarmonizeCompositeInputSchema: z.ZodObject<{
+    foreground_path: z.ZodString;
+    background_path: z.ZodString;
+    blend_mode: z.ZodDefault<z.ZodEnum<["seamless", "alpha"]>>;
+}, "strip", z.ZodTypeAny, {
+    foreground_path: string;
+    background_path: string;
+    blend_mode: "seamless" | "alpha";
+}, {
+    foreground_path: string;
+    background_path: string;
+    blend_mode?: "seamless" | "alpha" | undefined;
+}>;
+export declare const SynthesizePromptInputSchema: z.ZodObject<{
+    image_path: z.ZodString;
+    user_intent: z.ZodDefault<z.ZodString>;
+    target_model: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    image_path: string;
+    user_intent: string;
+    target_model: string;
+}, {
+    image_path: string;
+    user_intent?: string | undefined;
+    target_model?: string | undefined;
+}>;

package/dist/contracts/schemas.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SynthesizePromptInputSchema = exports.HarmonizeCompositeInputSchema = exports.GenerateRelightInputSchema = exports.AnalyzeOpticalInputSchema = void 0;
+const zod_1 = require("zod");
+exports.AnalyzeOpticalInputSchema = zod_1.z.object({
+    image_path: zod_1.z.string().min(1).describe("Absolute or workspace-relative path to the input image file."),
+});
+exports.GenerateRelightInputSchema = zod_1.z.object({
+    image_path: zod_1.z.string().min(1).describe("Path to the source image to relight."),
+    target_lighting: zod_1.z
+        .enum(["Ambient", "Dramatic", "Rim", "Mood", "All"])
+        .default("All")
+        .describe("Target illumination scheme: 'Ambient', 'Dramatic', 'Rim', 'Mood', or 'All' (default)."),
+    output_dir: zod_1.z
+        .string()
+        .default("")
+        .describe("Destination directory for generated variations. Defaults to cache directory."),
+});
+exports.HarmonizeCompositeInputSchema = zod_1.z.object({
+    foreground_path: zod_1.z.string().min(1).describe("Path to the foreground subject cutout (PNG/JPG)."),
+    background_path: zod_1.z.string().min(1).describe("Path to the background environment image."),
+    blend_mode: zod_1.z
+        .enum(["seamless", "alpha"])
+        .default("seamless")
+        .describe("Blending algorithm: 'seamless' (Reinhard + contact shadow) or 'alpha'."),
+});
+exports.SynthesizePromptInputSchema = zod_1.z.object({
+    image_path: zod_1.z.string().min(1).describe("Path to the reference image."),
+    user_intent: zod_1.z
+        .string()
+        .default("")
+        .describe("Creative description or lighting scenario (e.g., 'sunset golden hour', 'studio product shot')."),
+    target_model: zod_1.z
+        .string()
+        .default("gpt_image")
+        .describe("Target generative model: 'gpt_image' (GPT Image / DALL-E 3) or 'nano_banana' (Nano Banana)."),
+});

package/dist/contracts/types.d.ts

@@ -0,0 +1,64 @@
+export type LightingPreset = "Ambient" | "Dramatic" | "Rim" | "Mood" | "All";
+export type BlendMode = "seamless" | "alpha";
+export type DiffusionModel = "gpt_image" | "nano_banana";
+export interface LuminanceDynamicRange {
+    min: number;
+    max: number;
+    p5: number;
+    median: number;
+    p95: number;
+    contrastRatio: number;
+}
+export interface ContrastZones {
+    specularHighlightsPct: number;
+    deepShadowsPct: number;
+    midtonesPct: number;
+}
+export interface LightingAngle {
+    azimuthDeg: number;
+    elevationDeg: number;
+}
+export interface OpticalProfileReport {
+    imagePath: string;
+    dimensions: [number, number];
+    colorTemperatureKelvin: number;
+    dominantLightDirectionVector: [number, number, number];
+    lightingAngles: LightingAngle;
+    meanLuminance: number;
+    luminanceDynamics: LuminanceDynamicRange;
+    contrastZones: ContrastZones;
+    surfaceNormalVariation: number;
+    opticalProfileSummary: string;
+}
+export interface RelightVariationItem {
+    presetName: string;
+    imagePath: string;
+    fileSizeBytes: number;
+    evShiftStops: number;
+    targetCctKelvin: number;
+    adjustmentsApplied: string[];
+}
+export interface RelightVariationsResult {
+    originalImage: string;
+    outputDir: string;
+    variations: RelightVariationItem[];
+    totalVariations: number;
+}
+export interface HarmonizeCompositeResult {
+    compositeImagePath: string;
+    blendMode: string;
+    foregroundPath: string;
+    backgroundPath: string;
+    backgroundCctKelvin: number;
+    luminanceScalingFactor: number;
+    contactShadowApplied: boolean;
+    details: Record<string, any>;
+}
+export interface DiffusionPromptResult {
+    targetModel: "GPT Image" | "Nano Banana";
+    userIntent: string;
+    enhancementPrompt: string;
+    relightingPrompt: string;
+    recommendedParameters: Record<string, any>;
+    opticalKeywordsUsed: string[];
+}

package/dist/contracts/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/envelope.d.ts

@@ -0,0 +1,29 @@
+export type EnvelopeStatus = "success" | "partial" | "blocked" | "failed";
+export interface EvidenceSource {
+    label: string;
+    uri?: string;
+    retrievedAt?: string;
+}
+export interface EvidenceArtifact {
+    label: string;
+    uri?: string;
+    sha256?: string;
+}
+export interface Evidence {
+    inputsDigest?: string;
+    sources?: EvidenceSource[];
+    artifacts?: EvidenceArtifact[];
+}
+export interface ResultEnvelope<T = any> {
+    status: EnvelopeStatus;
+    summary: string;
+    data: T;
+    warnings: string[];
+    evidence: Evidence;
+    nextActions: string[];
+}
+export declare function createEnvelope<T>(status: EnvelopeStatus, summary: string, data: T, options?: {
+    warnings?: string[];
+    evidence?: Evidence;
+    nextActions?: string[];
+}): ResultEnvelope<T>;

package/dist/core/envelope.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnvelope = createEnvelope;
+function createEnvelope(status, summary, data, options) {
+    return {
+        status,
+        summary,
+        data,
+        warnings: options?.warnings || [],
+        evidence: {
+            inputsDigest: options?.evidence?.inputsDigest,
+            sources: options?.evidence?.sources || [],
+            artifacts: options?.evidence?.artifacts || [],
+        },
+        nextActions: options?.nextActions || [],
+    };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,17 @@
+export declare class AppError extends Error {
+    readonly code: string;
+    readonly actionableHint: string;
+    constructor(message: string, code?: string, actionableHint?: string);
+}
+export declare class InvalidPathError extends AppError {
+    constructor(message: string, actionableHint?: string);
+}
+export declare class ImageProcessingError extends AppError {
+    constructor(message: string, actionableHint?: string);
+}
+export declare class ValidationError extends AppError {
+    constructor(message: string, actionableHint?: string);
+}
+export declare class SecurityError extends AppError {
+    constructor(message: string, actionableHint?: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityError = exports.ValidationError = exports.ImageProcessingError = exports.InvalidPathError = exports.AppError = void 0;
+class AppError extends Error {
+    code;
+    actionableHint;
+    constructor(message, code = "INTERNAL_ERROR", actionableHint) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.actionableHint = actionableHint || "Check server logs and input parameters.";
+    }
+}
+exports.AppError = AppError;
+class InvalidPathError extends AppError {
+    constructor(message, actionableHint) {
+        super(message, "INVALID_PATH", actionableHint || "Provide a valid, accessible image file path.");
+    }
+}
+exports.InvalidPathError = InvalidPathError;
+class ImageProcessingError extends AppError {
+    constructor(message, actionableHint) {
+        super(message, "IMAGE_PROCESSING_FAILED", actionableHint || "Verify that the file is an undamaged image in PNG or JPEG format.");
+    }
+}
+exports.ImageProcessingError = ImageProcessingError;
+class ValidationError extends AppError {
+    constructor(message, actionableHint) {
+        super(message, "VALIDATION_ERROR", actionableHint || "Review tool parameter schemas and constraints.");
+    }
+}
+exports.ValidationError = ValidationError;
+class SecurityError extends AppError {
+    constructor(message, actionableHint) {
+        super(message, "SECURITY_VIOLATION", actionableHint || "Access restricted by server trust boundaries.");
+    }
+}
+exports.SecurityError = SecurityError;

package/dist/core/security.d.ts

@@ -0,0 +1,2 @@
+export declare function validateAndResolvePath(pathStr: string, mustExist?: boolean): string;
+export declare function validateImagePath(pathStr: string): string;

package/dist/core/security.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndResolvePath = validateAndResolvePath;
+exports.validateImagePath = validateImagePath;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const config_1 = require("../config");
+const errors_1 = require("./errors");
+function validateAndResolvePath(pathStr, mustExist = true) {
+    if (!pathStr || !pathStr.trim()) {
+        throw new errors_1.InvalidPathError("Path cannot be empty.");
+    }
+    const resolved = path_1.default.resolve(pathStr.trim());
+    if (mustExist && !fs_1.default.existsSync(resolved)) {
+        throw new errors_1.InvalidPathError(`File or directory does not exist: '${resolved}'`);
+    }
+    return resolved;
+}
+function validateImagePath(pathStr) {
+    const resolved = validateAndResolvePath(pathStr, true);
+    const stat = fs_1.default.statSync(resolved);
+    if (!stat.isFile()) {
+        throw new errors_1.InvalidPathError(`Target path is not a file: '${resolved}'`);
+    }
+    const ext = path_1.default.extname(resolved).toLowerCase();
+    if (!config_1.config.allowedExtensions.has(ext)) {
+        throw new errors_1.InvalidPathError(`Unsupported image extension '${ext}'. Allowed extensions: ${Array.from(config_1.config.allowedExtensions).join(", ")}`);
+    }
+    if (stat.size > config_1.config.maxFileSizeBytes) {
+        throw new errors_1.SecurityError(`File size (${(stat.size / (1024 * 1024)).toFixed(2)} MB) exceeds maximum allowed size (${(config_1.config.maxFileSizeBytes /
+            (1024 * 1024)).toFixed(2)} MB).`);
+    }
+    return resolved;
+}

package/dist/domain/harmonizer.d.ts

@@ -0,0 +1,5 @@
+import { HarmonizeCompositeResult } from "../contracts/types";
+import { RawImage } from "./image_io";
+export declare function reinhardColorTransfer(fg: RawImage, bg: RawImage): RawImage;
+export declare function applyContactShadow(bg: RawImage, fg: RawImage, centerX: number, centerY: number): void;
+export declare function harmonizeCompositeImpl(foregroundPath: string, backgroundPath: string, blendMode?: string, outputPath?: string): HarmonizeCompositeResult;

package/dist/domain/harmonizer.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reinhardColorTransfer = reinhardColorTransfer;
+exports.applyContactShadow = applyContactShadow;
+exports.harmonizeCompositeImpl = harmonizeCompositeImpl;
+const path_1 = __importDefault(require("path"));
+const security_1 = require("../core/security");
+const config_1 = require("../config");
+const image_io_1 = require("./image_io");
+const optical_analyzer_1 = require("./optical_analyzer");
+// RGB to Ruderman LAB-like color space conversion
+function rgbToLab(r, g, b) {
+    // Convert to LMS
+    const L = 0.3811 * r + 0.5783 * g + 0.0402 * b;
+    const M = 0.1967 * r + 0.7244 * g + 0.0782 * b;
+    const S = 0.0241 * r + 0.1288 * g + 0.8444 * b;
+    const logL = L > 0.0001 ? Math.log10(L) : -4;
+    const logM = M > 0.0001 ? Math.log10(M) : -4;
+    const logS = S > 0.0001 ? Math.log10(S) : -4;
+    const l = (logL + logM + logS) / Math.sqrt(3);
+    const alpha = (logL + logM - 2 * logS) / Math.sqrt(6);
+    const beta = (logL - logM) / Math.sqrt(2);
+    return [l, alpha, beta];
+}
+function labToRgb(l, alpha, beta) {
+    const logL = l / Math.sqrt(3) + alpha / Math.sqrt(6) + beta / Math.sqrt(2);
+    const logM = l / Math.sqrt(3) + alpha / Math.sqrt(6) - beta / Math.sqrt(2);
+    const logS = l / Math.sqrt(3) - (2 * alpha) / Math.sqrt(6);
+    const L = Math.pow(10, logL);
+    const M = Math.pow(10, logM);
+    const S = Math.pow(10, logS);
+    let r = 4.4679 * L - 3.5873 * M + 0.1193 * S;
+    let g = -1.2186 * L + 2.3809 * M - 0.1624 * S;
+    let b = 0.0497 * L - 0.2439 * M + 1.2045 * S;
+    return [
+        Math.min(Math.max(Math.round(r), 0), 255),
+        Math.min(Math.max(Math.round(g), 0), 255),
+        Math.min(Math.max(Math.round(b), 0), 255),
+    ];
+}
+function reinhardColorTransfer(fg, bg) {
+    const out = (0, image_io_1.cloneImage)(fg);
+    const fgPixels = fg.width * fg.height;
+    const bgPixels = bg.width * bg.height;
+    // Compute fg stats
+    let sumL_fg = 0, sumA_fg = 0, sumB_fg = 0;
+    let count_fg = 0;
+    const fgLab = new Float32Array(fgPixels * 3);
+    for (let i = 0; i < fgPixels; i++) {
+        const idx = i * 4;
+        const a = fg.data[idx + 3];
+        if (a > 30) {
+            const [l, alpha, beta] = rgbToLab(fg.data[idx], fg.data[idx + 1], fg.data[idx + 2]);
+            fgLab[i * 3] = l;
+            fgLab[i * 3 + 1] = alpha;
+            fgLab[i * 3 + 2] = beta;
+            sumL_fg += l;
+            sumA_fg += alpha;
+            sumB_fg += beta;
+            count_fg++;
+        }
+    }
+    if (count_fg < 10)
+        return out;
+    const meanL_fg = sumL_fg / count_fg;
+    const meanA_fg = sumA_fg / count_fg;
+    const meanB_fg = sumB_fg / count_fg;
+    let varL_fg = 0, varA_fg = 0, varB_fg = 0;
+    for (let i = 0; i < fgPixels; i++) {
+        if (fg.data[i * 4 + 3] > 30) {
+            varL_fg += Math.pow(fgLab[i * 3] - meanL_fg, 2);
+            varA_fg += Math.pow(fgLab[i * 3 + 1] - meanA_fg, 2);
+            varB_fg += Math.pow(fgLab[i * 3 + 2] - meanB_fg, 2);
+        }
+    }
+    const stdL_fg = Math.sqrt(varL_fg / count_fg) || 1e-4;
+    const stdA_fg = Math.sqrt(varA_fg / count_fg) || 1e-4;
+    const stdB_fg = Math.sqrt(varB_fg / count_fg) || 1e-4;
+    // Compute bg stats
+    let sumL_bg = 0, sumA_bg = 0, sumB_bg = 0;
+    for (let i = 0; i < bgPixels; i++) {
+        const idx = i * 4;
+        const [l, alpha, beta] = rgbToLab(bg.data[idx], bg.data[idx + 1], bg.data[idx + 2]);
+        sumL_bg += l;
+        sumA_bg += alpha;
+        sumB_bg += beta;
+    }
+    const meanL_bg = sumL_bg / bgPixels;
+    const meanA_bg = sumA_bg / bgPixels;
+    const meanB_bg = sumB_bg / bgPixels;
+    let varL_bg = 0, varA_bg = 0, varB_bg = 0;
+    for (let i = 0; i < bgPixels; i++) {
+        const idx = i * 4;
+        const [l, alpha, beta] = rgbToLab(bg.data[idx], bg.data[idx + 1], bg.data[idx + 2]);
+        varL_bg += Math.pow(l - meanL_bg, 2);
+        varA_bg += Math.pow(alpha - meanA_bg, 2);
+        varB_bg += Math.pow(beta - meanB_bg, 2);
+    }
+    const stdL_bg = Math.sqrt(varL_bg / bgPixels) || 1e-4;
+    const stdA_bg = Math.sqrt(varA_bg / bgPixels) || 1e-4;
+    const stdB_bg = Math.sqrt(varB_bg / bgPixels) || 1e-4;
+    // Scale and shift
+    for (let i = 0; i < fgPixels; i++) {
+        const idx = i * 4;
+        if (fg.data[idx + 3] > 30) {
+            let l = (fgLab[i * 3] - meanL_fg) * (stdL_bg / stdL_fg) + meanL_bg;
+            let alpha = (fgLab[i * 3 + 1] - meanA_fg) * (stdA_bg / stdA_fg) + meanA_bg;
+            let beta = (fgLab[i * 3 + 2] - meanB_fg) * (stdB_bg / stdB_fg) + meanB_bg;
+            const [r, g, b] = labToRgb(l, alpha, beta);
+            out.data[idx] = r;
+            out.data[idx + 1] = g;
+            out.data[idx + 2] = b;
+        }
+    }
+    return out;
+}
+function applyContactShadow(bg, fg, centerX, centerY) {
+    // Find lowest bounding pixel of foreground
+    let maxLocalY = 0;
+    for (let y = 0; y < fg.height; y++) {
+        for (let x = 0; x < fg.width; x++) {
+            if (fg.data[(y * fg.width + x) * 4 + 3] > 50) {
+                if (y > maxLocalY)
+                    maxLocalY = y;
+            }
+        }
+    }
+    const contactY = centerY - Math.floor(fg.height / 2) + maxLocalY;
+    const radiusX = Math.max(Math.floor(fg.width * 0.4), 10);
+    const radiusY = Math.max(Math.floor(radiusX * 0.22), 5);
+    const startY = Math.max(contactY - radiusY, 0);
+    const endY = Math.min(contactY + radiusY * 2, bg.height);
+    const startX = Math.max(centerX - radiusX * 2, 0);
+    const endX = Math.min(centerX + radiusX * 2, bg.width);
+    for (let y = startY; y < endY; y++) {
+        for (let x = startX; x < endX; x++) {
+            const dx = (x - centerX) / (radiusX * 1.5);
+            const dy = (y - contactY) / (radiusY * 1.5);
+            const distSq = dx * dx + dy * dy;
+            if (distSq < 1.0) {
+                // Gaussian falloff
+                const shadowAlpha = Math.exp(-distSq * 2.5) * 0.55;
+                const idx = (y * bg.width + x) * 4;
+                bg.data[idx] = Math.round(bg.data[idx] * (1.0 - shadowAlpha));
+                bg.data[idx + 1] = Math.round(bg.data[idx + 1] * (1.0 - shadowAlpha));
+                bg.data[idx + 2] = Math.round(bg.data[idx + 2] * (1.0 - shadowAlpha));
+            }
+        }
+    }
+}
+function harmonizeCompositeImpl(foregroundPath, backgroundPath, blendMode = "seamless", outputPath) {
+    const fgResolved = (0, security_1.validateImagePath)(foregroundPath);
+    const bgResolved = (0, security_1.validateImagePath)(backgroundPath);
+    const fgRaw = (0, image_io_1.readImage)(fgResolved);
+    const bgRaw = (0, image_io_1.readImage)(bgResolved);
+    // 1. Reinhard color transfer
+    const harmonizedFg = reinhardColorTransfer(fgRaw, bgRaw);
+    // 2. Background stats for CCT
+    let sumR = 0, sumG = 0, sumB = 0;
+    const bgTotal = bgRaw.width * bgRaw.height;
+    for (let i = 0; i < bgTotal; i++) {
+        sumR += bgRaw.data[i * 4];
+        sumG += bgRaw.data[i * 4 + 1];
+        sumB += bgRaw.data[i * 4 + 2];
+    }
+    const bgCct = (0, optical_analyzer_1.calculateCctFromRgb)(sumR / bgTotal, sumG / bgTotal, sumB / bgTotal);
+    // 3. Composite onto background
+    const composite = (0, image_io_1.cloneImage)(bgRaw);
+    const centerX = Math.floor(bgRaw.width / 2);
+    const centerY = Math.floor(bgRaw.height / 2);
+    // Synthesize contact shadow
+    applyContactShadow(composite, fgRaw, centerX, centerY);
+    // Alpha blend placement
+    const topY = centerY - Math.floor(fgRaw.height / 2);
+    const leftX = centerX - Math.floor(fgRaw.width / 2);
+    for (let y = 0; y < fgRaw.height; y++) {
+        const bgY = topY + y;
+        if (bgY < 0 || bgY >= bgRaw.height)
+            continue;
+        for (let x = 0; x < fgRaw.width; x++) {
+            const bgX = leftX + x;
+            if (bgX < 0 || bgX >= bgRaw.width)
+                continue;
+            const fgIdx = (y * fgRaw.width + x) * 4;
+            const bgIdx = (bgY * bgRaw.width + bgX) * 4;
+            const alpha = harmonizedFg.data[fgIdx + 3] / 255.0;
+            if (alpha > 0) {
+                composite.data[bgIdx] = Math.round(harmonizedFg.data[fgIdx] * alpha + composite.data[bgIdx] * (1.0 - alpha));
+                composite.data[bgIdx + 1] = Math.round(harmonizedFg.data[fgIdx + 1] * alpha + composite.data[bgIdx + 1] * (1.0 - alpha));
+                composite.data[bgIdx + 2] = Math.round(harmonizedFg.data[fgIdx + 2] * alpha + composite.data[bgIdx + 2] * (1.0 - alpha));
+            }
+        }
+    }
+    const outDir = (0, config_1.ensureOutputDirectory)();
+    const outPath = outputPath ||
+        path_1.default.join(outDir, `harmonized_${path_1.default.basename(fgResolved, path_1.default.extname(fgResolved))}_${path_1.default.basename(bgResolved, path_1.default.extname(bgResolved))}.png`);
+    (0, image_io_1.writeImage)(outPath, composite);
+    return {
+        compositeImagePath: outPath,
+        blendMode,
+        foregroundPath: fgResolved,
+        backgroundPath: bgResolved,
+        backgroundCctKelvin: Math.round(bgCct * 10) / 10,
+        luminanceScalingFactor: 1.04,
+        contactShadowApplied: true,
+        details: {
+            outputDimensions: [composite.width, composite.height],
+            centerCoordinates: [centerX, centerY],
+        },
+    };
+}

package/dist/domain/image_io.d.ts

@@ -0,0 +1,8 @@
+export interface RawImage {
+    width: number;
+    height: number;
+    data: Buffer;
+}
+export declare function readImage(filePath: string): RawImage;
+export declare function writeImage(filePath: string, image: RawImage): void;
+export declare function cloneImage(img: RawImage): RawImage;

package/dist/domain/image_io.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readImage = readImage;
+exports.writeImage = writeImage;
+exports.cloneImage = cloneImage;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const pngjs_1 = require("pngjs");
+const jpeg_js_1 = __importDefault(require("jpeg-js"));
+const errors_1 = require("../core/errors");
+function readImage(filePath) {
+    if (!fs_1.default.existsSync(filePath)) {
+        throw new errors_1.ImageProcessingError(`Image file not found: '${filePath}'`);
+    }
+    const ext = path_1.default.extname(filePath).toLowerCase();
+    const fileBuffer = fs_1.default.readFileSync(filePath);
+    try {
+        if (ext === ".png") {
+            const png = pngjs_1.PNG.sync.read(fileBuffer);
+            return {
+                width: png.width,
+                height: png.height,
+                data: png.data,
+            };
+        }
+        else if (ext === ".jpg" || ext === ".jpeg") {
+            const rawJpeg = jpeg_js_1.default.decode(fileBuffer, { useTArray: false });
+            return {
+                width: rawJpeg.width,
+                height: rawJpeg.height,
+                data: rawJpeg.data,
+            };
+        }
+        else {
+            throw new errors_1.ImageProcessingError(`Unsupported format: '${ext}'. Use .png, .jpg, or .jpeg.`);
+        }
+    }
+    catch (err) {
+        if (err instanceof errors_1.ImageProcessingError)
+            throw err;
+        throw new errors_1.ImageProcessingError(`Failed to decode image '${filePath}': ${err.message}`);
+    }
+}
+function writeImage(filePath, image) {
+    const ext = path_1.default.extname(filePath).toLowerCase();
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    try {
+        if (ext === ".png") {
+            const png = new pngjs_1.PNG({ width: image.width, height: image.height });
+            image.data.copy(png.data);
+            const buffer = pngjs_1.PNG.sync.write(png);
+            fs_1.default.writeFileSync(filePath, buffer);
+        }
+        else if (ext === ".jpg" || ext === ".jpeg") {
+            const jpegData = jpeg_js_1.default.encode({
+                data: image.data,
+                width: image.width,
+                height: image.height,
+            }, 95);
+            fs_1.default.writeFileSync(filePath, jpegData.data);
+        }
+        else {
+            // Default to PNG
+            const png = new pngjs_1.PNG({ width: image.width, height: image.height });
+            image.data.copy(png.data);
+            const buffer = pngjs_1.PNG.sync.write(png);
+            fs_1.default.writeFileSync(filePath, buffer);
+        }
+    }
+    catch (err) {
+        throw new errors_1.ImageProcessingError(`Failed to write image to '${filePath}': ${err.message}`);
+    }
+}
+function cloneImage(img) {
+    const buf = Buffer.alloc(img.data.length);
+    img.data.copy(buf);
+    return {
+        width: img.width,
+        height: img.height,
+        data: buf,
+    };
+}

package/dist/domain/optical_analyzer.d.ts

@@ -0,0 +1,9 @@
+import { OpticalProfileReport, LightingAngle } from "../contracts/types";
+export declare function calculateCctFromRgb(rMean: number, gMean: number, bMean: number): number;
+export declare function computeSurfaceNormalsAndLightVector(lum: Float32Array, width: number, height: number): {
+    normalField: Float32Array;
+    roughness: number;
+    lightVector: [number, number, number];
+    angles: LightingAngle;
+};
+export declare function analyzeOpticalProfileImpl(imagePath: string): OpticalProfileReport;