@hypit/hypit 0.0.1 → 0.1.0

package/packages/provider-image-opencv-local/runtime/raster_execute.py

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""One bounded raster interpreter for @hypit/provider-image-opencv-local."""
+
+import json
+import math
+import sys
+
+import cv2
+import numpy as np
+
+
+def color(value: str):
+    raw = value[1:]
+    red, green, blue = int(raw[0:2], 16), int(raw[2:4], 16), int(raw[4:6], 16)
+    alpha = int(raw[6:8], 16) if len(raw) == 8 else 255
+    return np.array([blue, green, red, alpha], dtype=np.float32)
+
+
+def split(image):
+    if image.ndim == 2:
+        return cv2.cvtColor(image, cv2.COLOR_GRAY2BGR), None
+    if image.shape[2] == 4:
+        return image[:, :, :3], image[:, :, 3]
+    if image.shape[2] == 3:
+        return image, None
+    raise ValueError("unsupported image channel count")
+
+
+def join(bgr, alpha):
+    return bgr if alpha is None else cv2.merge([bgr[:, :, 0], bgr[:, :, 1], bgr[:, :, 2], alpha])
+
+
+def flatten(image, background):
+    bgr, alpha = split(image)
+    if alpha is None:
+        return bgr
+    bg = color(background)[:3]
+    weight = alpha.astype(np.float32)[:, :, None] / 255.0
+    return np.rint(bgr.astype(np.float32) * weight + bg * (1.0 - weight)).clip(0, 255).astype(np.uint8)
+
+
+def crop(image, operation):
+    height, width = image.shape[:2]
+    if operation["unit"] == "fraction":
+        x = int(round(operation["x"] * width))
+        y = int(round(operation["y"] * height))
+        out_width = int(round(operation["width"] * width))
+        out_height = int(round(operation["height"] * height))
+    else:
+        x, y = int(operation["x"]), int(operation["y"])
+        out_width, out_height = int(operation["width"]), int(operation["height"])
+    if out_width < 1 or out_height < 1 or x < 0 or y < 0 or x + out_width > width or y + out_height > height:
+        raise ValueError("crop lies outside the current image")
+    return image[y:y + out_height, x:x + out_width].copy()
+
+
+def interpolation(name):
+    return {
+        "nearest": cv2.INTER_NEAREST,
+        "linear": cv2.INTER_LINEAR,
+        "cubic": cv2.INTER_CUBIC,
+        "area": cv2.INTER_AREA,
+        "lanczos": cv2.INTER_LANCZOS4,
+    }[name]
+
+
+def decode(source):
+    image = cv2.imdecode(np.frombuffer(source, np.uint8), cv2.IMREAD_UNCHANGED)
+    if image is None:
+        raise ValueError("image decode failed")
+    return image
+
+
+def fit_geometry(width, height, target_width, target_height, mode):
+    if mode == "stretch":
+        return target_width, target_height, 0, 0
+    scale = min(target_width / width, target_height / height) if mode == "contain" else max(
+        target_width / width, target_height / height
+    )
+    scaled_width = max(1, round_half_up(width * scale))
+    scaled_height = max(1, round_half_up(height * scale))
+    return scaled_width, scaled_height, (target_width - scaled_width) // 2, (target_height - scaled_height) // 2
+
+
+def resize(image, operation):
+    target_width, target_height = int(operation["width"]), int(operation["height"])
+    mode = operation["fit"]
+    method = interpolation(operation["interpolation"])
+    height, width = image.shape[:2]
+    scaled_width, scaled_height, x, y = fit_geometry(width, height, target_width, target_height, mode)
+    scaled = cv2.resize(image, (scaled_width, scaled_height), interpolation=method)
+    if mode == "cover":
+        return scaled[-y:-y + target_height, -x:-x + target_width].copy()
+    if mode == "stretch":
+        return scaled
+    channels = 4 if scaled.ndim == 3 and scaled.shape[2] == 4 else 3
+    default = "#00000000" if channels == 4 else "#000000"
+    fill = color(operation.get("background", default))
+    canvas = np.empty((target_height, target_width, channels), dtype=np.uint8)
+    canvas[:] = fill[:channels]
+    canvas[y:y + scaled_height, x:x + scaled_width] = scaled
+    return canvas
+
+
+def denoise(image, operation):
+    bgr, alpha = split(image)
+    if bgr.shape[0] < 32 or bgr.shape[1] < 32:
+        return image
+    y, cr, cb = cv2.split(cv2.cvtColor(bgr, cv2.COLOR_BGR2YCrCb))
+    template = int(operation["templateWindow"])
+    search = int(operation["searchWindow"])
+    y = cv2.fastNlMeansDenoising(y, None, float(operation["lumaStrength"]), template, search)
+    cr = cv2.fastNlMeansDenoising(cr, None, float(operation["chromaStrength"]), template, search)
+    cb = cv2.fastNlMeansDenoising(cb, None, float(operation["chromaStrength"]), template, search)
+    out = cv2.cvtColor(cv2.merge([y, cr, cb]), cv2.COLOR_YCrCb2BGR).astype(np.float32)
+    recovery = float(operation["saturationRecovery"])
+    gray = (0.0722 * out[:, :, 0] + 0.7152 * out[:, :, 1] + 0.2126 * out[:, :, 2])[:, :, None]
+    out = np.rint(gray + (out - gray) * recovery).clip(0, 255).astype(np.uint8)
+    return join(out, alpha)
+
+
+def adjust_color(image, operation):
+    bgr, alpha = split(image)
+    out = bgr.astype(np.float32)
+    out *= 2.0 ** float(operation["exposureStops"])
+    out = (out - 127.5) * float(operation["contrast"]) + 127.5
+    gray = (0.0722 * out[:, :, 0] + 0.7152 * out[:, :, 1] + 0.2126 * out[:, :, 2])[:, :, None]
+    out = gray + (out - gray) * float(operation["saturation"])
+    temperature = float(operation["temperature"]) * 32.0
+    tint = float(operation["tint"]) * 32.0
+    out[:, :, 2] += temperature
+    out[:, :, 0] -= temperature
+    out[:, :, 1] += tint
+    gamma = float(operation["gamma"])
+    out = 255.0 * np.power(np.clip(out, 0, 255) / 255.0, 1.0 / gamma)
+    return join(np.rint(out).clip(0, 255).astype(np.uint8), alpha)
+
+
+def sharpen(image, operation):
+    bgr, alpha = split(image)
+    source = bgr.astype(np.float32)
+    blurred = cv2.GaussianBlur(source, (0, 0), sigmaX=float(operation["radius"]))
+    detail = source - blurred
+    threshold = float(operation["threshold"])
+    if threshold > 0:
+        detail[np.max(np.abs(detail), axis=2) < threshold] = 0
+    out = np.rint(source + detail * float(operation["amount"])).clip(0, 255).astype(np.uint8)
+    return join(out, alpha)
+
+
+def blur(image, operation):
+    bgr, alpha = split(image)
+    out = cv2.GaussianBlur(bgr, (0, 0), sigmaX=float(operation["sigma"]))
+    return join(out, alpha)
+
+
+def apply(image, operation):
+    kind = operation["kind"]
+    if kind == "crop":
+        return crop(image, operation)
+    if kind == "resize":
+        return resize(image, operation)
+    if kind == "rotate":
+        return {90: cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE),
+                180: cv2.rotate(image, cv2.ROTATE_180),
+                270: cv2.rotate(image, cv2.ROTATE_90_COUNTERCLOCKWISE)}[int(operation["degrees"])]
+    if kind == "flip":
+        return cv2.flip(image, {"horizontal": 1, "vertical": 0, "both": -1}[operation["axis"]])
+    if kind == "denoise":
+        return denoise(image, operation)
+    if kind == "color":
+        return adjust_color(image, operation)
+    if kind == "sharpen":
+        return sharpen(image, operation)
+    if kind == "blur":
+        return blur(image, operation)
+    if kind == "alpha":
+        return image if operation["mode"] == "preserve" else flatten(image, operation["background"])
+    if kind == "encode":
+        return image
+    raise ValueError(f"unknown image operation {kind}")
+
+
+def encode_image(image, output_format="png", quality=None, background=None):
+    parameters = []
+    if output_format == "jpeg":
+        if image.ndim == 3 and image.shape[2] == 4:
+            if background is None:
+                raise ValueError("JPEG encoding of alpha requires an explicit background")
+            image = flatten(image, background)
+        extension = ".jpg"
+        parameters = [cv2.IMWRITE_JPEG_QUALITY, int(quality or 95)]
+    elif output_format == "webp":
+        extension = ".webp"
+        parameters = [cv2.IMWRITE_WEBP_QUALITY, int(quality or 95)]
+    else:
+        extension = ".png"
+    ok, encoded = cv2.imencode(extension, image, parameters)
+    if not ok:
+        raise ValueError("image encode failed")
+    return encoded.tobytes()
+
+
+def transform(source, operations):
+    image = decode(source)
+    for operation in operations:
+        if operation["kind"] != "encode":
+            image = apply(image, operation)
+    encode = next((item for item in operations if item["kind"] == "encode"), {"format": "png"})
+    output_format = encode["format"]
+    return encode_image(image, output_format, encode.get("quality"), encode.get("background"))
+
+
+def bgra(image):
+    if image is None:
+        raise ValueError("image decode failed")
+    if image.ndim == 2:
+        return cv2.cvtColor(image, cv2.COLOR_GRAY2BGRA)
+    if image.shape[2] == 3:
+        return cv2.cvtColor(image, cv2.COLOR_BGR2BGRA)
+    if image.shape[2] == 4:
+        return image
+    raise ValueError("unsupported image channel count")
+
+
+def round_half_up(value):
+    return math.floor(float(value) + 0.5)
+
+
+def fit_layer(image, frame, mode, method):
+    frame_width = max(1, round_half_up(frame["widthPx"]))
+    frame_height = max(1, round_half_up(frame["heightPx"]))
+    height, width = image.shape[:2]
+    scaled_width, scaled_height, x, y = fit_geometry(width, height, frame_width, frame_height, mode)
+    scaled = cv2.resize(image, (scaled_width, scaled_height), interpolation=method)
+    return scaled, x, y
+
+
+def alpha_over(canvas, image, x, y, opacity):
+    canvas_height, canvas_width = canvas.shape[:2]
+    image_height, image_width = image.shape[:2]
+    left, top = max(0, x), max(0, y)
+    right, bottom = min(canvas_width, x + image_width), min(canvas_height, y + image_height)
+    if left >= right or top >= bottom:
+        return
+    source = image[top - y:bottom - y, left - x:right - x].astype(np.float32) / 255.0
+    target = canvas[top:bottom, left:right].astype(np.float32) / 255.0
+    source_alpha = source[:, :, 3:4] * float(opacity)
+    target_alpha = target[:, :, 3:4]
+    output_alpha = source_alpha + target_alpha * (1.0 - source_alpha)
+    premultiplied = source[:, :, :3] * source_alpha + target[:, :, :3] * target_alpha * (1.0 - source_alpha)
+    rgb = np.divide(premultiplied, output_alpha, out=np.zeros_like(premultiplied), where=output_alpha > 0)
+    canvas[top:bottom, left:right] = np.rint(
+        np.concatenate([rgb, output_alpha], axis=2) * 255.0
+    ).clip(0, 255).astype(np.uint8)
+
+
+def compose(request):
+    width, height = int(request["canvas"]["widthPx"]), int(request["canvas"]["heightPx"])
+    fill = color(request["background"])
+    canvas = np.empty((height, width, 4), dtype=np.uint8)
+    canvas[:] = fill
+    for layer in request["layers"]:
+        with open(layer["source"], "rb") as source_file:
+            image = bgra(decode(source_file.read()))
+        fitted, offset_x, offset_y = fit_layer(
+            image, layer["frame"], layer["fit"], interpolation(layer["interpolation"])
+        )
+        alpha_over(
+            canvas, fitted,
+            round_half_up(layer["frame"]["xPx"]) + offset_x,
+            round_half_up(layer["frame"]["yPx"]) + offset_y,
+            layer["opacity"],
+        )
+    return encode_image(canvas)
+
+
+def main():
+    if sys.argv[1:] == ["--self-test"]:
+        print(json.dumps({"opencv": cv2.__version__, "numpy": np.__version__}))
+        return
+    if len(sys.argv) != 3:
+        raise SystemExit("usage: raster_execute.py <request.json> <output>")
+    request_path, output_path = sys.argv[1:]
+    with open(request_path, "r", encoding="utf-8") as request_file:
+        request = json.load(request_file)
+    if request["kind"] == "transform":
+        with open(request["source"], "rb") as source_file:
+            result = transform(source_file.read(), request["operations"])
+    elif request["kind"] == "compose":
+        result = compose(request)
+    else:
+        raise ValueError("unknown raster request kind")
+    with open(output_path, "wb") as output_file:
+        output_file.write(result)
+
+
+if __name__ == "__main__":
+    main()

package/packages/provider-image-opencv-local/src/activation.ts

@@ -0,0 +1,61 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+import {
+  diagnoseRuntimeExecutable,
+} from "@hypit/runtime-host-node";
+
+import { resolveLocalOpenCvDeployment } from "./deployment.js";
+import { createLocalOpenCvImageProvider } from "./provider.js";
+import { localOpenCvProgram } from "./program.js";
+
+const localOpenCvRuntimeAdapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-image-opencv-local",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("local OpenCV Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "local OpenCV image");
+    runtimeConfigExact(config, [
+      "pythonExecutable", "defaultConcurrency", "processTimeoutMs", "maxInputBytes", "maxOutputBytes",
+    ], "local OpenCV image");
+    const configuredPython = runtimeConfigString(config.pythonExecutable, "OpenCV pythonExecutable");
+    const deployment = resolveLocalOpenCvDeployment({
+      hostStateRoot: context.hostStateRoot,
+      dataRoot: context.dataRoot,
+      instance: context.instance,
+      ...(configuredPython === undefined ? {} : { pythonExecutable: configuredPython }),
+    });
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "OpenCV defaultConcurrency");
+    const processTimeoutMs = runtimeConfigPositiveInteger(config.processTimeoutMs, "OpenCV processTimeoutMs");
+    const maxInputBytes = runtimeConfigPositiveInteger(config.maxInputBytes, "OpenCV maxInputBytes");
+    const maxOutputBytes = runtimeConfigPositiveInteger(config.maxOutputBytes, "OpenCV maxOutputBytes");
+    return {
+      endpoint: createLocalOpenCvImageProvider({
+        instance: context.instance,
+        pool: context.pool,
+        pythonExecutable: deployment.pythonExecutable,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(processTimeoutMs === undefined ? {} : { processTimeoutMs }),
+        ...(maxInputBytes === undefined ? {} : { maxInputBytes }),
+        ...(maxOutputBytes === undefined ? {} : { maxOutputBytes }),
+      }),
+      program: localOpenCvProgram(context.instance, deployment),
+      diagnose: () => diagnoseRuntimeExecutable({
+        root: context.dataRoot,
+        configured: deployment.pythonExecutable,
+        fallback: deployment.pythonExecutable,
+        subject: "OpenCV Python",
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [localOpenCvRuntimeAdapter],
+};
+
+export default hypitPackage;

package/packages/provider-image-opencv-local/src/deployment.ts

@@ -0,0 +1,68 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
+import type { ManagedProgramCommand } from "@hypit/runtime-kit";
+import {
+  pythonEnvironmentExecutable,
+  resolveRuntimeExecutable,
+} from "@hypit/runtime-host-node";
+
+/**
+ * The locked Python project is its own package asset. Repository workspaces and
+ * installed npm distributions therefore resolve the same immutable input.
+ */
+export const localOpenCvManagedProject = join(
+  resolveNodePackageResource("@hypit/image-opencv-runtime", "pyproject.toml", { from: import.meta.url }),
+  "..",
+);
+
+export type LocalOpenCvDeployment = {
+  readonly pythonExecutable: string;
+  readonly stateRoot?: string;
+  readonly installCommands?: readonly ManagedProgramCommand[];
+  readonly ownership: "managed" | "external";
+};
+
+/**
+ * One resolution function is shared by Endpoint construction, doctor and the
+ * service lifecycle. An explicit executable is operator-owned and receives no
+ * unrelated workspace preparation. With no override the bundled frozen uv
+ * project is the complete managed deployment.
+ */
+export function resolveLocalOpenCvDeployment(
+  input: {
+    readonly hostStateRoot: string;
+    readonly dataRoot: string;
+    readonly instance: string;
+    readonly pythonExecutable?: string;
+  },
+): LocalOpenCvDeployment {
+  if (input.pythonExecutable !== undefined) {
+    return {
+      pythonExecutable: resolveRuntimeExecutable(input.dataRoot, input.pythonExecutable),
+      ownership: "external",
+    };
+  }
+  if (!existsSync(localOpenCvManagedProject)) {
+    throw new Error(
+      "local OpenCV has no bundled managed runtime; configure pythonExecutable explicitly",
+    );
+  }
+  const stateRoot = join(
+    input.hostStateRoot,
+    "programs",
+    `image-opencv-${encodeURIComponent(input.instance)}`,
+  );
+  const environment = join(stateRoot, ".venv");
+  return {
+    pythonExecutable: pythonEnvironmentExecutable(environment),
+    stateRoot,
+    installCommands: [{
+      command: "uv",
+      args: ["sync", "--project", localOpenCvManagedProject, "--frozen"],
+      env: { UV_PROJECT_ENVIRONMENT: environment },
+    }],
+    ownership: "managed",
+  };
+}

package/packages/provider-image-opencv-local/src/index.ts

@@ -0,0 +1,2 @@
+export { createLocalOpenCvImageProvider, localOpenCvImageProviderModuleRef } from "./provider.js";
+export type { CreateLocalOpenCvImageProviderOptions } from "./provider.js";

package/packages/provider-image-opencv-local/src/program.ts

@@ -0,0 +1,60 @@
+import { execFile } from "node:child_process";
+
+import type { ManagedProgram, ManagedProgramState } from "@hypit/runtime-kit";
+
+import type { LocalOpenCvDeployment } from "./deployment.js";
+
+/** Kept equal to `services/image-opencv/pyproject.toml` by a test in this package. */
+const REQUIRED_MAJOR = { cv2: 4, numpy: 2 } as const;
+
+const PROBE_PROGRAM =
+  "import cv2, numpy, json; print(json.dumps({'cv2': cv2.__version__, 'numpy': numpy.__version__}))";
+
+function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {
+  return new Promise((resolve) => {
+    execFile(executable, [...args], { timeout: 15_000, shell: false, windowsHide: true }, (error, stdout, stderr) => {
+      resolve(error === null
+        ? { ok: true, output: stdout.trim() }
+        : { ok: false, output: (stderr.trim() || error.message).split("\n").at(-1) ?? "" });
+    });
+  });
+}
+
+/**
+ * OpenCV runs as one bounded process per Need, so there is nothing to keep warm
+ * and this Program declares no `start`. What it does declare is the
+ * interpreter's identity: a Python without `cv2`, or with a `cv2` from before
+ * the APIs this Provider calls, fails in the middle of a Build with a
+ * subprocess error. Probing says so at `doctor` time instead.
+ */
+export function localOpenCvProgram(id: string, deployment: LocalOpenCvDeployment): ManagedProgram {
+  const python = deployment.pythonExecutable;
+  return {
+    id,
+    ...(deployment.stateRoot === undefined ? {} : { stateRoot: deployment.stateRoot }),
+    ...(deployment.installCommands === undefined ? {} : {
+      installation: {
+        commands: deployment.installCommands,
+        probe,
+      },
+    }),
+    probe,
+  };
+
+  async function probe(): Promise<ManagedProgramState> {
+      const result = await run(python, ["-c", PROBE_PROGRAM]);
+      if (!result.ok) return { state: "down", detail: `${python} cannot import cv2 and numpy: ${result.output}` };
+      let found: Record<string, string>;
+      try {
+        found = JSON.parse(result.output) as Record<string, string>;
+      } catch {
+        return { state: "down", detail: `${python} answered something other than a version report` };
+      }
+      const differs = Object.entries(REQUIRED_MAJOR)
+        .filter(([name, major]) => Number.parseInt(found[name] ?? "", 10) !== major)
+        .map(([name, major]) => `${name} is ${found[name] ?? "absent"}, expected ${major}.x`);
+      return differs.length === 0
+        ? { state: "ready" }
+        : { state: "mismatch", detail: `${python} carries ${differs.join("; ")}` };
+  }
+}

package/packages/provider-image-opencv-local/src/provider.ts

@@ -0,0 +1,155 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { artifactTypes } from "@hypit/artifact";
+import { defineEndpointPackage } from "@hypit/endpoint-kit";
+import type { EndpointFulfillment } from "@hypit/endpoint-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { CanonicalValue } from "@hypit/protocol";
+import {
+  assertRasterRequest,
+  rasterCapabilities,
+  rasterOutputMediaType,
+  rasterSources,
+} from "@hypit/raster";
+import type { RasterRequest } from "@hypit/raster";
+
+export const localOpenCvImageProviderModuleRef = {
+  name: "@hypit/provider-image-opencv-local",
+  version: "1",
+} as const;
+
+export type CreateLocalOpenCvImageProviderOptions = {
+  readonly instance?: string;
+  readonly pool?: string;
+  readonly pythonExecutable?: string;
+  readonly processTimeoutMs?: number;
+  readonly maxInputBytes?: number;
+  readonly maxOutputBytes?: number;
+  readonly defaultConcurrency?: number;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function positiveInteger(value: number, subject: string): number {
+  assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive integer`);
+  return value;
+}
+
+function request(value: CanonicalValue): RasterRequest {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value), "Raster request must be an object");
+  const item = value as unknown as RasterRequest;
+  assertRasterRequest(item);
+  return item;
+}
+
+async function runProcess(options: {
+  readonly executable: string;
+  readonly args: readonly string[];
+  readonly timeoutMs: number;
+  readonly maxStderrBytes: number;
+}): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(options.executable, [...options.args], { shell: false, windowsHide: true, stdio: ["ignore", "ignore", "pipe"] });
+    let stderrBytes = 0;
+    const stderr: Buffer[] = [];
+    let failed: Error | undefined;
+    const fail = (error: Error): void => {
+      failed ??= error;
+      child.kill("SIGKILL");
+    };
+    const timer = setTimeout(() => fail(new Error(`OpenCV image transform exceeded ${options.timeoutMs}ms`)),
+      options.timeoutMs);
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderrBytes += chunk.byteLength;
+      if (stderrBytes > options.maxStderrBytes) {
+        fail(new Error("OpenCV image transform stderr exceeded its limit"));
+        return;
+      }
+      stderr.push(chunk);
+    });
+    child.on("error", fail);
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (failed !== undefined) reject(failed);
+      else if (code !== 0) {
+        const detail = Buffer.concat(stderr).toString("utf8").trim();
+        reject(new Error(`OpenCV image transform exited with ${code ?? `signal ${signal ?? "unknown"}`}`
+          + (detail.length === 0 ? "" : `: ${detail}`)));
+      }
+      else resolve();
+    });
+  });
+}
+
+export function createLocalOpenCvImageProvider(config: CreateLocalOpenCvImageProviderOptions) {
+  const pythonExecutable = config.pythonExecutable ?? "python3";
+  const processTimeoutMs = positiveInteger(config.processTimeoutMs ?? 5 * 60_000, "processTimeoutMs");
+  const maxInputBytes = positiveInteger(config.maxInputBytes ?? 128 * 1024 * 1024, "maxInputBytes");
+  const maxOutputBytes = positiveInteger(config.maxOutputBytes ?? 256 * 1024 * 1024, "maxOutputBytes");
+  const script = fileURLToPath(new URL("../runtime/raster_execute.py", import.meta.url));
+  return defineEndpointPackage({
+    module: localOpenCvImageProviderModuleRef,
+    facet: "raster",
+    instance: config.instance ?? "image.opencv.local",
+    pool: config.pool ?? config.instance ?? "image.opencv.local",
+    pricing: { kind: "local" },
+    defaultConcurrency: config.defaultConcurrency ?? 1,
+    capabilities: [{
+      lifecycle: "immediate" as const,
+      capability: rasterCapabilities.execute,
+      returns: artifactTypes.blob,
+      handler: async (context): Promise<EndpointFulfillment> => {
+        const need = request(context.need.constraints);
+        const sources = [...new Map(rasterSources(need).map((source) => [source.resource, source])).values()];
+        const totalInputBytes = sources.reduce((sum, source) => sum + source.size, 0);
+        assert(totalInputBytes <= maxInputBytes, "Raster inputs exceed their configured byte limit");
+        const work = await mkdtemp(join(tmpdir(), "hypit-raster-opencv-"));
+        try {
+          const paths = new Map<string, string>();
+          for (const [index, source] of sources.entries()) {
+            const bytes = await context.resources.get(source.resource);
+            assert(bytes !== undefined, `Raster source Artifact ${source.resource} is unavailable`);
+            assert(bytes.byteLength === source.size, "Raster source size differs from its BlobRef");
+            const path = join(work, `source-${String(index + 1).padStart(4, "0")}.bin`);
+            await writeFile(path, bytes);
+            paths.set(source.resource, path);
+          }
+          const runtimeRequest = need.kind === "transform"
+            ? { kind: "transform", source: paths.get(need.source.resource), operations: need.operations }
+            : {
+                kind: "compose", canvas: need.canvas, background: need.background,
+                layers: need.layers.map((layer) => ({
+                  source: paths.get(layer.source.resource), frame: layer.frame, fit: layer.fit,
+                  interpolation: layer.interpolation, opacity: layer.opacity,
+                })),
+              };
+          const program = join(work, "request.json");
+          const output = join(work, "output.bin");
+          await writeFile(program, JSON.stringify(runtimeRequest), "utf8");
+          await runProcess({
+            executable: pythonExecutable,
+            args: [script, program, output],
+            timeoutMs: processTimeoutMs,
+            maxStderrBytes: 256 * 1024,
+          });
+          const info = await stat(output);
+          assert(info.isFile() && info.size > 0 && info.size <= maxOutputBytes,
+            "OpenCV raster execution produced an invalid output size");
+          const mediaType = rasterOutputMediaType(need);
+          const artifact = await context.resources.put(await readFile(output), mediaType);
+          return {
+            value: artifact,
+          };
+        } finally {
+          await rm(work, { recursive: true, force: true }).catch(() => {});
+        }
+      },
+    }],
+  });
+}