feat(jupyter): Add Deno.jupyter.image API (#26284)

This commit adds `Deno.jupyter.image` API to display PNG and JPG images: ``` const data = Deno.readFileSync("./my-image.jpg"); Deno.jupyter.image(data); Deno.jupyter.image("./my-image.jpg"); ```
denoland · Nov 16, 2024 · a1bcdf1 · a1bcdf1
1 parent 8d2960d
commit a1bcdf1
Show file tree

Hide file tree

Showing 4 changed files with 108 additions and 1 deletion.
diff --git a/cli/js/40_jupyter.js b/cli/js/40_jupyter.js
@@ -177,6 +177,52 @@ function isCanvasLike(obj) {
   return obj !== null && typeof obj === "object" && "toDataURL" in obj;
 }
 
+function isJpg(obj) {
+  // Check if obj is a Uint8Array
+  if (!(obj instanceof Uint8Array)) {
+    return false;
+  }
+
+  // JPG files start with the magic bytes FF D8
+  if (obj.length < 2 || obj[0] !== 0xFF || obj[1] !== 0xD8) {
+    return false;
+  }
+
+  // JPG files end with the magic bytes FF D9
+  if (
+    obj.length < 2 || obj[obj.length - 2] !== 0xFF ||
+    obj[obj.length - 1] !== 0xD9
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+function isPng(obj) {
+  // Check if obj is a Uint8Array
+  if (!(obj instanceof Uint8Array)) {
+    return false;
+  }
+
+  // PNG files start with a specific 8-byte signature
+  const pngSignature = [137, 80, 78, 71, 13, 10, 26, 10];
+
+  // Check if the array is at least as long as the signature
+  if (obj.length < pngSignature.length) {
+    return false;
+  }
+
+  // Check each byte of the signature
+  for (let i = 0; i < pngSignature.length; i++) {
+    if (obj[i] !== pngSignature[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 /** Possible HTML and SVG Elements */
 function isSVGElementLike(obj) {
   return obj !== null && typeof obj === "object" && "outerHTML" in obj &&
@@ -233,6 +279,16 @@ async function format(obj) {
   if (isDataFrameLike(obj)) {
     return extractDataFrame(obj);
   }
+  if (isJpg(obj)) {
+    return {
+      "image/jpeg": core.ops.op_base64_encode(obj),
+    };
+  }
+  if (isPng(obj)) {
+    return {
+      "image/png": core.ops.op_base64_encode(obj),
+    };
+  }
   if (isSVGElementLike(obj)) {
     return {
       "image/svg+xml": obj.outerHTML,
@@ -314,6 +370,28 @@ const html = createTaggedTemplateDisplayable("text/html");
  */
 const svg = createTaggedTemplateDisplayable("image/svg+xml");
 
+function image(obj) {
+  if (typeof obj === "string") {
+    try {
+      obj = Deno.readFileSync(obj);
+    } catch {
+      // pass
+    }
+  }
+
+  if (isJpg(obj)) {
+    return makeDisplayable({ "image/jpeg": core.ops.op_base64_encode(obj) });
+  }
+
+  if (isPng(obj)) {
+    return makeDisplayable({ "image/png": core.ops.op_base64_encode(obj) });
+  }
+
+  throw new TypeError(
+    "Object is not a valid image or a path to an image. `Deno.jupyter.image` supports displaying JPG or PNG images.",
+  );
+}
+
 function isMediaBundle(obj) {
   if (obj == null || typeof obj !== "object" || Array.isArray(obj)) {
     return false;
@@ -465,6 +543,7 @@ function enableJupyter() {
     md,
     html,
     svg,
+    image,
     $display,
   };
 }

diff --git a/cli/tsc/dts/lib.deno.unstable.d.ts b/cli/tsc/dts/lib.deno.unstable.d.ts
@@ -1180,6 +1180,32 @@ declare namespace Deno {
       ...values: unknown[]
     ): Displayable;
 
+    /**
+     * Display a JPG or PNG image.
+     *
+     * ```
+     * Deno.jupyter.image("./cat.jpg");
+     * Deno.jupyter.image("./dog.png");
+     * ```
+     *
+     * @category Jupyter
+     * @experimental
+     */
+    export function image(path: string): Displayable;
+
+    /**
+     * Display a JPG or PNG image.
+     *
+     * ```
+     * const img = Deno.readFileSync("./cat.jpg");
+     * Deno.jupyter.image(img);
+     * ```
+     *
+     * @category Jupyter
+     * @experimental
+     */
+    export function image(data: Uint8Array): Displayable;
+
     /**
      * Format an object for displaying in Deno
      *

diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
@@ -471,6 +471,8 @@ const NOT_IMPORTED_OPS = [
   // Related to `Deno.jupyter` API
   "op_jupyter_broadcast",
   "op_jupyter_input",
+  // Used in jupyter API
+  "op_base64_encode",
 
   // Related to `Deno.test()` API
   "op_test_event_step_result_failed",

diff --git a/tests/unit/ops_test.ts b/tests/unit/ops_test.ts
@@ -1,6 +1,6 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
-const EXPECTED_OP_COUNT = 11;
+const EXPECTED_OP_COUNT = 12;
 
 Deno.test(function checkExposedOps() {
   // @ts-ignore TS doesn't allow to index with symbol