samples: lib: pixel: show usage of the pixel library

The newly introduced lib/pixel features utilities that help composing
video pipelines together for the purpose of stream processing, as well
as debug utilities.

Signed-off-by: Josuah Demangeon <[email protected]>

Author: josuah

samples/lib/lib.rst

@@ -0,0 +1,6 @@
+.. zephyr:code-sample-category:: lib
+   :name: Libraries
+   :show-listing:
+   :live-search:
+
+   These samples demonstrate how to use the libraries present in Zephyr.

samples/lib/pixel/image/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(pixel_image)
+
+target_sources(app PRIVATE src/main.c)

samples/lib/pixel/image/README.rst

@@ -0,0 +1,51 @@
+.. zephyr:code-sample:: lib_pixel_image
+   :name: Pixel Imaging Library
+
+   Image an image using subsampling.
+
+Overview
+********
+
+A sample showcasing how to perform arbitrary image manipulation using few memory with a
+developer-friendly API.
+
+The input and output are printed as preview images on the console.
+
+Building and Running
+********************
+
+This application can be built and executed on the native simulator as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/lib/pixel/image
+   :host-os: unix
+   :board: native_sim
+   :goals: run
+   :compact:
+
+To build for another board, change "native_sim" above to that board's name.
+
+Sample Output
+=============
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build v4.1.0-3103-g25dca1b19885 ***
+   [00:00:00.000,000] <inf> app: input image, 32x8, 768 bytes:
+   ▄▄▄▄▄▄▄▄▄▄▄ shows-up ▄▄▄▄▄▄▄▄▄▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄ as color ▄▄▄▄▄▄▄▄▄▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄ on the   ▄▄▄▄▄▄▄▄▄▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄ terminal ▄▄▄▄▄▄▄▄▄▄▄|
+   [00:00:00.000,000] <inf> app: output image, 120x40, 14400 bytes:
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄ shows-up ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄ as color ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄ on the   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄ terminal ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄[...]▄▄|
+
+.. image:: preview.png

samples/lib/pixel/image/preview.png

@@ -0,0 +1,6 @@
+CONFIG_PIXEL=y
+CONFIG_ASSERT=y
+CONFIG_LOG=y
+
+# Required to make sure the test harnesses catch the log output
+CONFIG_LOG_MODE_IMMEDIATE=y

samples/lib/pixel/image/prj.conf

@@ -0,0 +1,19 @@
+sample:
+  description: Pixel image sample, image manipulation library
+  name: pixel image
+common:
+  min_ram: 32
+  tags: pixel
+  integration_platforms:
+    - native_sim
+  harness: console
+  harness_config:
+    type: one_line
+    regex:
+      - "input image, 32x8, 768 bytes:"
+      - "output image, 120x40, 14400 bytes:"
+tests:
+  sample.pixel.image:
+    tags: pixel
+    extra_configs:
+      - CONFIG_PIXEL_PRINT_NONE=y

samples/lib/pixel/image/sample.yaml

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025 tinyVision.ai Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdint.h>
+
+#include <zephyr/sys/util.h>
+#include <zephyr/pixel/image.h>
+#include <zephyr/logging/log.h>
+
+LOG_MODULE_REGISTER(app, LOG_LEVEL_INF);
+
+static void gradient(uint8_t *rgb24buf, size_t size, const uint8_t beg[3], const uint8_t end[3])
+{
+	for (int i = 0; i + 3 <= size; i += 3) {
+		rgb24buf[i + 0] = (beg[0] * (size - i) + end[0] * i) / size;
+		rgb24buf[i + 1] = (beg[1] * (size - i) + end[1] * i) / size;
+		rgb24buf[i + 2] = (beg[2] * (size - i) + end[2] * i) / size;
+	}
+}
+
+static uint8_t rgb24frame_in[32 * 8 * 3];
+static uint8_t rgb24frame_out[120 * 40 * 3];
+
+int main(void)
+{
+	const uint8_t beg[] = {0x00, 0x70, 0xc5};
+	const uint8_t end[] = {0x79, 0x29, 0xd2};
+	struct pixel_image img;
+
+	/* Generate a smooth gradient for a small image */
+	gradient(rgb24frame_in, sizeof(rgb24frame_in), beg, end);
+
+	/* Open that buffer as an image type */
+	pixel_image_from_buffer(&img, rgb24frame_in, sizeof(rgb24frame_in), 32, 8,
+				VIDEO_PIX_FMT_RGB24);
+	LOG_INF("input image, %ux%u, %zu bytes:", img.width, img.height, img.size);
+	pixel_image_print_truecolor(&img);
+
+	/* Turn it into a tall vertical image, now displeasant "banding" artifacts appear */
+	pixel_image_resize(&img, 5, 40);
+
+	/* Try to attenuate it with a blur effect (comment this line to see the difference) */
+	pixel_image_kernel(&img, PIXEL_KERNEL_GAUSSIAN_BLUR, 5);
+
+	/* Stretch the gradient horizontally over the entire width of the output buffer */
+	pixel_image_resize(&img, 120, 40);
+
+	/* Save the image into the output buffer and check for errors */
+	pixel_image_to_buffer(&img, rgb24frame_out, sizeof(rgb24frame_out));
+	if (img.err != 0) {
+		LOG_ERR("Image has error %u: %s", img.err, strerror(-img.err));
+		return img.err;
+	}
+
+	/* Now that the imagme is exported, we can print it */
+	LOG_INF("output image, %ux%u, %zu bytes:", img.width, img.height, img.size);
+	pixel_image_print_truecolor(&img);
+
+	return 0;
+}

samples/lib/pixel/image/src/main.c

@@ -0,0 +1,15 @@
+.. zephyr:code-sample-category:: lib_pixel
+   :name: Pixel Library
+   :show-listing:
+   :live-search:
+
+   These samples demonstrate how to use the Pixel processing library of Zephyr.
+
+These samples can be used as starting point for test benches that print an input image,
+perform some custom processing, and print the color image back along with the logs directly
+on the terminal.
+
+This helps debugging when other methods are not available.
+
+The ``truecolor`` printing functions give accurate 24-bit RGB colors but slower than the
+``256color`` variants.

samples/lib/pixel/pixel.rst

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(pixel)
+
+target_sources(app PRIVATE src/main.c)

samples/lib/pixel/print/CMakeLists.txt

@@ -0,0 +1,57 @@
+.. zephyr:code-sample:: lib_pixel_print
+   :name: Pixel Printiing Library
+
+   Print images on the console.
+
+Overview
+********
+
+A sample showcasing how to make use of the pixel library to visualize an image or histogram data
+by printing it out on the console using `ANSI escape codes`_.
+
+This way debug logs can be interleaved with small preview images for debug purposes.
+
+.. _ANSI escape codes: https://en.wikipedia.org/wiki/ANSI_escape_code
+
+Building and Running
+********************
+
+This application can be built and executed on QEMU as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/lib/pixel/print
+   :host-os: unix
+   :board: native_sim
+   :goals: run
+   :compact:
+
+To build for another board, change "native_sim" above to that board's name.
+
+Sample Output
+=============
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build v4.1.0-2611-gfaa7b74cfda7 ***
+   [00:00:00.000,000] <inf> app: Printing the gradient #0070c5 -> #7929d2
+   [00:00:00.000,000] <inf> app: hexdump:
+    col0      col1      col2      col3      col4      [...]  col14     col15
+    R  G  B   R  G  B   R  G  B   R  G  B   R  G  B   [...]  R  G  B   R  G  B
+    00 70 c5  00 6f c5  00 6f c5  00 6f c5  00 6f c5  [...]  00 6f c5  03 6d c5  row0
+    03 6d c5  04 6d c5  04 6d c5  04 6d c5  04 6d c5  [...]  04 6d c5  07 6b c5  row1
+    07 6b c5  07 6b c5  08 6b c5  08 6b c5  08 6b c5  [...]  07 6b c5  0b 69 c6  row2
+    0b 69 c6  0b 69 c6  0b 69 c6  0c 68 c6  0c 68 c6  [...]  0b 69 c6  0e 67 c6  row3
+    0f 67 c6  0f 66 c6  0f 66 c6  0f 66 c6  10 66 c6  [...]  0f 66 c6  12 65 c7  row4
+    12 64 c7  13 64 c7  13 64 c7  13 64 c7  13 64 c7  [...]  13 64 c7  16 62 c7  row5
+    16 62 c7  16 62 c7  17 62 c7  17 62 c7  17 62 c7  [...]  16 62 c7  1a 60 c7  row6
+   [...]
+   [00:00:00.000,000] <inf> app: truecolor:
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄|
+   ▄▄▄ shows-up ▄▄▄|
+   ▄▄▄ as color ▄▄▄|
+   ▄▄▄ on the   ▄▄▄|
+   ▄▄▄ terminal ▄▄▄|
+   ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄|
+   [...]
+
+.. image:: preview.png