Merge pull request #498 from espressif/feature/esp_jpeg_prepare

feat(esp_jpeg): Added option to get image size without decoding it

Author: tore-espressif

esp_jpeg/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.3.0
+
+- Added option to get image size without decoding it
+
 ## 1.2.1
 
 - Fixed decoding of non-conforming 0xFFFF marker

esp_jpeg/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.2.1"
+version: "1.3.0"
 description: "JPEG Decoder: TJpgDec"
 url: https://github.com/espressif/idf-extra-components/tree/master/esp_jpeg/
 dependencies:

esp_jpeg/include/jpeg_decoder.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -62,20 +62,20 @@ typedef struct esp_jpeg_image_cfg_s {
 
 /**
  * @brief JPEG output info
- *
  */
 typedef struct esp_jpeg_image_output_s {
     uint16_t width;    /*!< Width of the output image */
     uint16_t height;   /*!< Height of the output image */
+    size_t output_len; /*!< Length of the output image in bytes */
 } esp_jpeg_image_output_t;
 
 /**
  * @brief Decode JPEG image
  *
  * @note This function is blocking.
  *
- * @param cfg: Configuration structure
- * @param img: Output image info
+ * @param[in]  cfg: Configuration structure
+ * @param[out] img: Output image info
  *
  * @return
  *      - ESP_OK            on success
@@ -84,6 +84,23 @@ typedef struct esp_jpeg_image_output_s {
  */
 esp_err_t esp_jpeg_decode(esp_jpeg_image_cfg_t *cfg, esp_jpeg_image_output_t *img);
 
+/**
+ * @brief Get information about the JPEG image
+ *
+ * Use this function to get the size of the JPEG image without decoding it.
+ * Allocate a buffer of size img->output_len to store the decoded image.
+ *
+ * @note cfg->outbuf and cfg->outbuf_size are not used in this function.
+ * @param[in]  cfg: Configuration structure
+ * @param[out] img: Output image info
+ *
+ * @return
+ *      - ESP_OK              on success
+ *      - ESP_ERR_INVALID_ARG if cfg or img is NULL
+ *      - ESP_FAIL            if there is an error in decoding JPEG
+ */
+esp_err_t esp_jpeg_get_image_info(esp_jpeg_image_cfg_t *cfg, esp_jpeg_image_output_t *img);
+
 #ifdef __cplusplus
 }
 #endif

esp_jpeg/jpeg_decoder.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -65,6 +65,7 @@ static uint8_t jpeg_get_color_bytes(esp_jpeg_image_format_t format);
 
 static unsigned int jpeg_decode_in_cb(JDEC *jd, uint8_t *buff, unsigned int nbyte);
 static jpeg_decode_out_t jpeg_decode_out_cb(JDEC *jd, void *bitmap, JRECT *rect);
+static inline uint16_t ldb_word(const void *ptr);
 /*******************************************************************************
 * Public API functions
 *******************************************************************************/
@@ -96,16 +97,17 @@ esp_err_t esp_jpeg_decode(esp_jpeg_image_cfg_t *cfg, esp_jpeg_image_output_t *im
     res = jd_prepare(&JDEC, jpeg_decode_in_cb, workbuf, workbuf_size, cfg);
     ESP_GOTO_ON_FALSE((res == JDR_OK), ESP_FAIL, err, TAG, "Error in preparing JPEG image! %d", res);
 
-    uint8_t scale_div = jpeg_get_div_by_scale(cfg->out_scale);
-    uint8_t out_color_bytes = jpeg_get_color_bytes(cfg->out_format);
+    const uint8_t scale_div       = jpeg_get_div_by_scale(cfg->out_scale);
+    const uint8_t out_color_bytes = jpeg_get_color_bytes(cfg->out_format);
 
     /* Size of output image */
-    uint32_t outsize = (JDEC.height / scale_div) * (JDEC.width / scale_div) * out_color_bytes;
+    const uint32_t outsize = (JDEC.height / scale_div) * (JDEC.width / scale_div) * out_color_bytes;
     ESP_GOTO_ON_FALSE((outsize <= cfg->outbuf_size), ESP_ERR_NO_MEM, err, TAG, "Not enough size in output buffer!");
 
     /* Size of output image */
     img->height = JDEC.height / scale_div;
     img->width = JDEC.width / scale_div;
+    img->output_len = outsize;
 
     /* Decode JPEG */
     res = jd_decomp(&JDEC, jpeg_decode_out_cb, cfg->out_scale);
@@ -119,6 +121,49 @@ esp_err_t esp_jpeg_decode(esp_jpeg_image_cfg_t *cfg, esp_jpeg_image_output_t *im
     return ret;
 }
 
+esp_err_t esp_jpeg_get_image_info(esp_jpeg_image_cfg_t *cfg, esp_jpeg_image_output_t *img)
+{
+    if (cfg == NULL || img == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    } else if (cfg->indata == NULL || cfg->indata_size < 5) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    esp_err_t ret = ESP_FAIL;
+
+    if (ldb_word(cfg->indata) != 0xFFD8) {
+        return ESP_FAIL;    /* Err: SOI is not detected */
+    }
+    unsigned ofs = 2; // Start after SOI marker
+
+    while (true) {
+        /* Get a JPEG marker */
+        uint8_t *seg = cfg->indata + ofs;       /* Segment pointer */
+        unsigned short marker = ldb_word(seg);  /* Marker */
+        unsigned int len = ldb_word(seg + 2);   /* Length field */
+        if (len <= 2 || (marker >> 8) != 0xFF) {
+            return ESP_FAIL;
+        }
+        ofs += 2 + len; /* Number of bytes loaded */
+        if (ofs > cfg->indata_size) {
+            return ESP_FAIL; // No more data
+        }
+
+        if ((marker & 0xFF) == 0xC0) {  /* SOF0 (baseline JPEG) */
+            seg += 4; /* Skip marker and length field */
+
+            /* Size of output image */
+            img->height = ldb_word(seg + 1);
+            img->width = ldb_word(seg + 3);
+            const uint8_t scale_div       = jpeg_get_div_by_scale(cfg->out_scale);
+            const uint8_t out_color_bytes = jpeg_get_color_bytes(cfg->out_format);
+            img->output_len = (img->height / scale_div) * (img->width / scale_div) * out_color_bytes;
+            ret = ESP_OK;
+            break;
+        }
+    }
+    return ret;
+}
+
 /*******************************************************************************
 * Private API functions
 *******************************************************************************/
@@ -234,3 +279,9 @@ static uint8_t jpeg_get_color_bytes(esp_jpeg_image_format_t format)
 
     return 1;
 }
+
+static inline uint16_t ldb_word(const void *ptr)
+{
+    const uint8_t *p = (const uint8_t *)ptr;
+    return ((uint16_t)p[0] << 8) | p[1];
+}

esp_jpeg/test_apps/main/tjpgd_test.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Unlicense OR CC0-1.0
  */
@@ -84,6 +84,64 @@ TEST_CASE("Test JPEG decompression library", "[esp_jpeg]")
     free(decoded);
 }
 
+/**
+ * @brief JPEG unknown size test
+ *
+ * This test case verifies the functionality of the JPEG decompression library
+ * when decoding an image with unknown size. The image is decoded from a
+ * JPEG file, and the output size is determined dynamically. The test checks
+ * that the decoded image dimensions match the expected values and that the
+ * pixel data is within an acceptable tolerance range.
+ */
+TEST_CASE("Test JPEG unknown size", "[esp_jpeg]")
+{
+    unsigned char *decoded, *p;
+    const unsigned char *o;
+
+    /* JPEG decode */
+    esp_jpeg_image_cfg_t jpeg_cfg = {
+        .indata = (uint8_t *)logo_jpg,
+        .indata_size = logo_jpg_len,
+        .out_format = JPEG_IMAGE_FORMAT_RGB888,
+    };
+
+    // 1. Get required output size
+    esp_jpeg_image_output_t outimg;
+    esp_err_t err = esp_jpeg_get_image_info(&jpeg_cfg, &outimg);
+    TEST_ASSERT_EQUAL(err, ESP_OK);
+    TEST_ASSERT_EQUAL(TESTW * TESTH * 3, outimg.output_len);
+    TEST_ASSERT_EQUAL(outimg.width, TESTW);
+    TEST_ASSERT_EQUAL(outimg.height, TESTH);
+
+    // 2. Allocate output buffer and assign it to the config
+    decoded = malloc(outimg.output_len);
+    TEST_ASSERT_NOT_NULL(decoded);
+    jpeg_cfg.outbuf = decoded;
+    jpeg_cfg.outbuf_size = outimg.output_len;
+
+    // 3. Decode the image
+    err = esp_jpeg_decode(&jpeg_cfg, &outimg);
+    TEST_ASSERT_EQUAL(err, ESP_OK);
+
+    /* Decoded image size */
+    TEST_ASSERT_EQUAL(TESTW * TESTH * 3, outimg.output_len);
+    TEST_ASSERT_EQUAL(outimg.width, TESTW);
+    TEST_ASSERT_EQUAL(outimg.height, TESTH);
+
+    p = decoded;
+    o = logo_rgb888;
+    for (int x = 0; x < outimg.width * outimg.height; x++) {
+        /* The color can be +- 2 */
+        TEST_ASSERT_UINT8_WITHIN(2, o[0], p[0]);
+        TEST_ASSERT_UINT8_WITHIN(2, o[1], p[1]);
+        TEST_ASSERT_UINT8_WITHIN(2, o[2], p[2]);
+
+        p += 3;
+        o += 3;
+    }
+    free(decoded);
+}
+
 #define WORKING_BUFFER_SIZE 4096
 TEST_CASE("Test JPEG decompression library: User defined working buffer", "[esp_jpeg]")
 {
@@ -224,6 +282,15 @@ TEST_CASE("Test JPEG decompression library: No Huffman tables", "[esp_jpeg]")
 
 #endif
 
+/**
+ * @brief Invalid JPEG marker test
+ *
+ * This test case verifies the behavior of the JPEG decompression library
+ * when encountering an invalid marker (0xFFFF) in the JPEG data stream.
+ * The test uses a known JPEG image (camera_2_jpg) that contains this invalid
+ * marker. The test checks whether the library can handle the invalid marker
+ * gracefully and still decode the image correctly.
+ */
 TEST_CASE("Test JPEG invalid marker 0xFFFF", "[esp_jpeg]")
 {
     unsigned char *decoded;