feat(noise-removal): SOTA noise removal with 4 quality tiers (#57)

* feat(noise-removal): register tool in shared constants and i18n * feat(noise-removal): add SCUNet and NAFNet model architectures * feat(noise-removal): add Python denoising engine with 4 quality tiers * feat(noise-removal): add TypeScript bridge for Python sidecar * feat(noise-removal): add frontend settings with 4-tier selector * feat(noise-removal): register in tool registry and pipeline * feat(noise-removal): add Fastify API route with Zod validation * feat(noise-removal): add SCUNet and NAFNet model downloads to Docker build * test(noise-removal): add to e2e tool page rendering tests * test(noise-removal): add integration tests for API endpoint * style: fix biome formatting and import ordering * fix(noise-removal): use correct model download URLs NAFNet model is hosted on HuggingFace, not GitHub releases. Also align SCUNet URL to use the KAIR releases (same as Docker build). * fix(noise-removal): remove emojis from tier selector, simplify labels Drop emoji icons from Quick/Balanced/Quality/Maximum buttons. Replace technical algorithm names with plain descriptions users can understand. --------- Co-authored-by: stirling-image <stirling-image@users.noreply.github.com>
2026-08-03 07:46:42 +02:00 · 2026-04-13 19:50:23 +08:00
parent 61794dca2d
commit dfffc0a8cc
16 changed files with 1804 additions and 0 deletions
@@ -24,6 +24,7 @@ import { registerGifTools } from "./gif-tools.js";
 import { registerImageEnhancement } from "./image-enhancement.js";
 import { registerImageToPdf } from "./image-to-pdf.js";
 import { registerInfo } from "./info.js";
+import { registerNoiseRemoval } from "./noise-removal.js";
 import { registerOcr } from "./ocr.js";
 import { registerPdfToImage } from "./pdf-to-image.js";
 import { registerQrGenerate } from "./qr-generate.js";
@@ -132,6 +133,7 @@ export async function registerToolRoutes(app: FastifyInstance): Promise<void> {
    { id: "image-enhancement", register: registerImageEnhancement },
    { id: "content-aware-resize", register: registerContentAwareResize },
    { id: "colorize", register: registerColorize },
+    { id: "noise-removal", register: registerNoiseRemoval },
  ];

  let skipped = 0;
@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { noiseRemoval } from "@stirling-image/ai";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import { autoOrient } from "../../lib/auto-orient.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
+import { decodeHeic } from "../../lib/heic-converter.js";
+import { createWorkspace } from "../../lib/workspace.js";
+import { updateSingleFileProgress } from "../progress.js";
+import { registerToolProcessFn } from "../tool-factory.js";
+
+const settingsSchema = z.object({
+  tier: z.enum(["quick", "balanced", "quality", "maximum"]).default("balanced"),
+  strength: z.union([z.number(), z.string()]).transform(Number).default(50),
+  detailPreservation: z.union([z.number(), z.string()]).transform(Number).default(50),
+  colorNoise: z.union([z.number(), z.string()]).transform(Number).default(30),
+  format: z.enum(["original", "png", "jpeg", "webp"]).default("original"),
+  quality: z.union([z.number(), z.string()]).transform(Number).default(90),
+});
+
+/**
+ * AI noise removal route.
+ * Uses the Python sidecar for multi-tier denoising.
+ */
+export function registerNoiseRemoval(app: FastifyInstance) {
+  app.post("/api/v1/tools/noise-removal", async (request: FastifyRequest, reply: FastifyReply) => {
+    let fileBuffer: Buffer | null = null;
+    let filename = "image";
+    let settingsRaw: string | null = null;
+    let clientJobId: string | null = null;
+
+    try {
+      const parts = request.parts();
+      for await (const part of parts) {
+        if (part.type === "file") {
+          const chunks: Buffer[] = [];
+          for await (const chunk of part.file) {
+            chunks.push(chunk);
+          }
+          fileBuffer = Buffer.concat(chunks);
+          filename = part.filename ?? "image";
+        } else if (part.fieldname === "settings") {
+          settingsRaw = part.value as string;
+        } else if (part.fieldname === "clientJobId") {
+          clientJobId = part.value as string;
+        }
+      }
+    } catch (err) {
+      return reply.status(400).send({
+        error: "Failed to parse multipart request",
+        details: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    if (!fileBuffer || fileBuffer.length === 0) {
+      return reply.status(400).send({ error: "No image file provided" });
+    }
+
+    const validation = await validateImageBuffer(fileBuffer);
+    if (!validation.valid) {
+      return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+    }
+
+    try {
+      const parsed = settingsSchema.parse(settingsRaw ? JSON.parse(settingsRaw) : {});
+      request.log.info(
+        { toolId: "noise-removal", imageSize: fileBuffer.length, tier: parsed.tier },
+        "Starting noise removal",
+      );
+
+      // Decode HEIC/HEIF input via system decoder
+      if (validation.format === "heif") {
+        fileBuffer = await decodeHeic(fileBuffer);
+      }
+
+      // Auto-orient to fix EXIF rotation before processing
+      fileBuffer = await autoOrient(fileBuffer);
+
+      const jobId = randomUUID();
+      const workspacePath = await createWorkspace(jobId);
+
+      // Progress callback
+      const jobIdForProgress = clientJobId;
+      const onProgress = jobIdForProgress
+        ? (percent: number, stage: string) => {
+            updateSingleFileProgress({
+              jobId: jobIdForProgress,
+              phase: "processing",
+              stage,
+              percent,
+            });
+          }
+        : undefined;
+
+      const result = await noiseRemoval(
+        fileBuffer,
+        join(workspacePath, "output"),
+        {
+          tier: parsed.tier,
+          strength: parsed.strength,
+          detailPreservation: parsed.detailPreservation,
+          colorNoise: parsed.colorNoise,
+          format: parsed.format,
+          quality: parsed.quality,
+        },
+        onProgress,
+      );
+
+      if (clientJobId) {
+        updateSingleFileProgress({
+          jobId: clientJobId,
+          phase: "complete",
+          percent: 100,
+        });
+      }
+
+      const CONTENT_TYPES: Record<string, string> = {
+        png: "image/png",
+        jpeg: "image/jpeg",
+        jpg: "image/jpeg",
+        webp: "image/webp",
+      };
+      const contentType = CONTENT_TYPES[result.format] || "image/png";
+      const ext = result.format === "jpeg" ? "jpg" : result.format;
+      const outputFilename = `${filename.replace(/\.[^.]+$/, "")}_denoised.${ext}`;
+
+      return reply
+        .header("Content-Type", contentType)
+        .header("Content-Disposition", `attachment; filename="${outputFilename}"`)
+        .header("X-Image-Width", String(result.width))
+        .header("X-Image-Height", String(result.height))
+        .send(result.buffer);
+    } catch (err) {
+      request.log.error({ err, toolId: "noise-removal" }, "Noise removal failed");
+      return reply.status(422).send({
+        error: "Noise removal failed",
+        details: err instanceof Error ? err.message : "Unknown error",
+      });
+    }
+  });
+
+  // Register in the pipeline/batch registry so this tool can be used
+  // as a step in automation pipelines (without progress callbacks).
+  registerToolProcessFn({
+    toolId: "noise-removal",
+    settingsSchema: z.object({
+      tier: z.enum(["quick", "balanced", "quality", "maximum"]).default("balanced"),
+      strength: z.union([z.number(), z.string()]).transform(Number).default(50),
+      detailPreservation: z.union([z.number(), z.string()]).transform(Number).default(50),
+      colorNoise: z.union([z.number(), z.string()]).transform(Number).default(30),
+      format: z.enum(["original", "png", "jpeg", "webp"]).default("original"),
+      quality: z.union([z.number(), z.string()]).transform(Number).default(90),
+    }),
+    process: async (inputBuffer, settings, filename) => {
+      const s = settings as z.infer<typeof settingsSchema>;
+      const orientedBuffer = await autoOrient(inputBuffer);
+      const jobId = randomUUID();
+      const workspacePath = await createWorkspace(jobId);
+      const result = await noiseRemoval(orientedBuffer, join(workspacePath, "output"), {
+        tier: s.tier,
+        strength: s.strength,
+        detailPreservation: s.detailPreservation,
+        colorNoise: s.colorNoise,
+        format: s.format,
+        quality: s.quality,
+      });
+      const ext = result.format === "jpeg" ? "jpg" : result.format;
+      const outputFilename = `${filename.replace(/\.[^.]+$/, "")}_denoised.${ext}`;
+      const CONTENT_TYPES: Record<string, string> = {
+        png: "image/png",
+        jpeg: "image/jpeg",
+        jpg: "image/jpeg",
+        webp: "image/webp",
+      };
+      return {
+        buffer: result.buffer,
+        filename: outputFilename,
+        contentType: CONTENT_TYPES[result.format] || "image/png",
+      };
+    },
+  });
+}