Merge pull request #439 from espressif/feature/esp_jpeg_default_huffman

esp_jpeg: Add support for default Huffman tables

Author: tore-espressif

.idf_build_apps.toml

@@ -1,5 +1,3 @@
-target = "all"
-paths = "."
 recursive = true
 exclude = [
     ".github",

esp_jpeg/CMakeLists.txt

@@ -7,4 +7,8 @@ if(NOT CONFIG_JD_USE_ROM)
     list(APPEND includes "tjpgd")
 endif()
 
+if(CONFIG_JD_DEFAULT_HUFFMAN)
+    list(APPEND sources "jpeg_default_huffman_table.c")
+endif()
+
 idf_component_register(SRCS ${sources} INCLUDE_DIRS ${includes})

esp_jpeg/Kconfig

@@ -2,7 +2,7 @@ menu "JPEG Decoder"
 
     config JD_USE_ROM
         bool "Use TinyJPG Decoder from ROM"
-        depends on IDF_TARGET_ESP32 || IDF_TARGET_ESP32C3 || IDF_TARGET_ESP32C6 || IDF_TARGET_ESP32S3
+        depends on ESP_ROM_HAS_JPEG_DECODE
         default y
         help
             By default, Espressif SoCs use TJpg decoder implemented in ROM code.
@@ -66,4 +66,15 @@ menu "JPEG Decoder"
         config JD_FASTDECODE_TABLE
             bool "+ Table conversion for huffman decoding (wants 6 << HUFF_BIT bytes of RAM)"
         endchoice
+
+    config JD_DEFAULT_HUFFMAN
+        bool "Support images without Huffman table"
+        depends on !JD_USE_ROM
+        default n
+        help
+            Enable this option to support decoding JPEG images that lack an embedded Huffman table.
+            When enabled, a default Huffman table is used during decoding, allowing the JPEG decoder to handle
+            images without explicitly provided Huffman tables.
+
+            Note: Enabling this option increases ROM usage due to the inclusion of default Huffman tables.
 endmenu

esp_jpeg/README.md

@@ -2,55 +2,62 @@
 
 [![Component Registry](https://components.espressif.com/components/espressif/esp_jpeg/badge.svg)](https://components.espressif.com/components/espressif/esp_jpeg)
 
-TJpgDec is a generic JPEG image decompressor that is highly optimized for small embedded systems. It works with very low memory consumption.
+TJpgDec is a lightweight JPEG image decompressor optimized for embedded systems with minimal memory consumption.
 
-Some microcontrollers have TJpg decoder in ROM, it is used, if there is. [^1] Using ROM code can be disabled in menuconfig.
+On some microcontrollers, TJpgDec is available in ROM and will be used by default, though this can be disabled in menuconfig if desired[^1].
 
 [^1]: **_NOTE:_** When the ROM decoder is used, the configuration can't be changed. The configuration is fixed.
 
 ## Features
 
 **Compilation configuration:**
-- Size of stream input buffer (default 512)
-- Output pixel format (default RGB888): RGB888/RGB565
-- Switches output descaling feature (default enabled)
-- Use table conversion for saturation arithmetic (default enabled)
-- Three optimization levels (default basic): 8/16-bit MCUs, 32-bit MCUs, Table conversion for huffman decoding 
+- Stream input buffer size (default: 512 bytes)
+- Output pixel format (default: RGB888; options: RGB888/RGB565)
+- Enable/disable output descaling (default: enabled)
+- Use table-based saturation for arithmetic operations (default: enabled)
+- Use default Huffman tables: Useful from decoding frames from cameras, that do not provide Huffman tables (default: disabled to save ROM)
+- Three optimization levels (default: 32-bit MCUs) for different CPU types:
+  - 8/16-bit MCUs
+  - 32-bit MCUs
+  - Table-based Huffman decoding
 
 **Runtime configuration:**
-- Pixel Format: RGB888, RGB565
-- Scaling Ratio: 1/1, 1/2, 1/4 or 1/8 Selectable on Decompression
-- Allow swap the first and the last byte of the color
+- Pixel format options: RGB888, RGB565
+- Selectable scaling ratios: 1/1, 1/2, 1/4, or 1/8 (chosen at decompression)
+- Option to swap the first and last bytes of color values
 
 ## TJpgDec in ROM
 
-Some microcontrollers have TJpg decoder in ROM. It is used as default, but it can be disabled in menuconfig. Then there will be used code saved in this component. 
+On certain microcontrollers, TJpgDec is available in ROM and used by default. This can be disabled in menuconfig if you prefer to use the library code provided in this component.
 
 ### List of MCUs, which have TJpgDec in ROM
 - ESP32
 - ESP32-S3
 - ESP32-C3
 - ESP32-C6
+- ESP32-C5
+- ESP32-C61
 
 ### Fixed compilation configuration of the ROM code
-- Stream input buffer: 512
+The ROM version uses the following fixed settings:
+- Stream input buffer: 512 bytes
 - Output pixel format: RGB888
-- Descaling feature for output: Enabled
-- Table for saturation: Enabled
+- Output descaling: enabled
+- Saturation table: enabled
 - Optimization level: Basic (JD_FASTDECODE = 0)
 
 ### Pros and cons using ROM code
 
 **Advantages:**
-- Save 5k of the flash memory (in the same configuration)
+- Saves approximately 5 KB of flash memory with the same configuration
 
 **Disadvantages:**
-- Cannot be changed compilation configuration
-- Some configuration can be faster in some cases
+- Compilation configuration cannot be changed
+- Certain configurations may provide faster performance
 
 ## Speed comparison
 
-In this table are examples of speed decoding JPEG image with this configuration:
+The table below shows example decoding times for a JPEG image using various configurations:
 * Image size: 320 x 180 px
 * Output format: RGB565
 * CPU: ESP32-S3

esp_jpeg/idf_component.yml

@@ -1,5 +1,5 @@
-version: "1.0.5~3"
+version: "1.1.0"
 description: "JPEG Decoder: TJpgDec"
 url: https://github.com/espressif/idf-extra-components/tree/master/esp_jpeg/
 dependencies:
-  idf: ">=4.4"
+  idf: ">=5.0"

esp_jpeg/jpeg_decoder.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -86,7 +86,7 @@ esp_err_t esp_jpeg_decode(esp_jpeg_image_cfg_t *cfg, esp_jpeg_image_output_t *im
 
     /* Prepare image */
     res = jd_prepare(&JDEC, jpeg_decode_in_cb, workbuf, JPEG_WORK_BUF_SIZE, cfg);
-    ESP_GOTO_ON_FALSE((res == JDR_OK), ESP_FAIL, err, TAG, "Error in preparing JPEG image!");
+    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);
@@ -101,7 +101,7 @@ esp_err_t esp_jpeg_decode(esp_jpeg_image_cfg_t *cfg, esp_jpeg_image_output_t *im
 
     /* Decode JPEG */
     res = jd_decomp(&JDEC, jpeg_decode_out_cb, cfg->out_scale);
-    ESP_GOTO_ON_FALSE((res == JDR_OK), ESP_FAIL, err, TAG, "Error in decoding JPEG image!");
+    ESP_GOTO_ON_FALSE((res == JDR_OK), ESP_FAIL, err, TAG, "Error in decoding JPEG image! %d", res);
 
 err:
     if (workbuf) {

esp_jpeg/jpeg_default_huffman_table.c

@@ -0,0 +1,60 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Default Huffman tables for baseline JPEG
+
+// These values are taken directly from CCITT Rec. T.81 (1992 E) Appendix K.3.3
+// The *_num_bits array always contains exactly 16 elements.
+// Each element represents the number of Huffman codes of a specific length:
+// - The first element corresponds to codes of length 1 bit,
+// - The second element to codes of length 2 bits, and so forth up to 16 bits.
+//
+// The *_values array has a length equal to the sum of all elements in the *_num_bits array,
+// representing the actual values associated with each Huffman code in order.
+
+// Luminance DC Table
+const unsigned char esp_jpeg_lum_dc_num_bits[16] = {0, 1, 5, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0};
+const unsigned esp_jpeg_lum_dc_codes_total = 12;
+const unsigned char esp_jpeg_lum_dc_values[12] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
+
+// Chrominance DC Table
+const unsigned char esp_jpeg_chrom_dc_num_bits[16] = {0, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0};
+const unsigned esp_jpeg_chrom_dc_codes_total = 12;
+const unsigned char esp_jpeg_chrom_dc_values[12] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
+
+// Luminance AC Table
+const unsigned char esp_jpeg_lum_ac_num_bits[16] = {0, 2, 1, 3, 3, 2, 4, 3, 5, 5, 4, 4, 0, 0, 1, 125};
+const unsigned esp_jpeg_lum_ac_codes_total = 162;
+const unsigned char esp_jpeg_lum_ac_values[162] = {
+    0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06, 0x13, 0x51, 0x61, 0x07,
+    0x22, 0x71, 0x14, 0x32, 0x81, 0x91, 0xA1, 0x08, 0x23, 0x42, 0xB1, 0xC1, 0x15, 0x52, 0xD1, 0xF0,
+    0x24, 0x33, 0x62, 0x72, 0x82, 0x09, 0x0A, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x25, 0x26, 0x27, 0x28,
+    0x29, 0x2A, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49,
+    0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69,
+    0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89,
+    0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7,
+    0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5,
+    0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE1, 0xE2,
+    0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF1, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8,
+    0xF9, 0xFA
+};
+
+// Chrominance AC Table
+const unsigned char esp_jpeg_chrom_ac_num_bits[16] = {0, 2, 1, 2, 4, 4, 3, 4, 7, 5, 4, 4, 0, 1, 2, 119};
+const unsigned esp_jpeg_chrom_ac_codes_total = 162;
+const unsigned char esp_jpeg_chrom_ac_values[162] = {
+    0x00, 0x01, 0x02, 0x03, 0x11, 0x04, 0x05, 0x21, 0x31, 0x06, 0x12, 0x41, 0x51, 0x07, 0x61, 0x71,
+    0x13, 0x22, 0x32, 0x81, 0x08, 0x14, 0x42, 0x91, 0xA1, 0xB1, 0xC1, 0x09, 0x23, 0x33, 0x52, 0xF0,
+    0x15, 0x62, 0x72, 0xD1, 0x0A, 0x16, 0x24, 0x34, 0xE1, 0x25, 0xF1, 0x17, 0x18, 0x19, 0x1A, 0x26,
+    0x27, 0x28, 0x29, 0x2A, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48,
+    0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68,
+    0x69, 0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87,
+    0x88, 0x89, 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5,
+    0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3,
+    0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA,
+    0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8,
+    0xF9, 0xFA
+};

esp_jpeg/test_apps/main/CMakeLists.txt

@@ -1,4 +1,5 @@
 idf_component_register(SRCS "tjpgd_test.c" "test_tjpgd_main.c"
                        INCLUDE_DIRS "."
                        PRIV_REQUIRES "unity"
-                       WHOLE_ARCHIVE)
+                       WHOLE_ARCHIVE
+                       EMBED_FILES "logo.jpg" "usb_camera.jpg")

esp_jpeg/test_apps/main/jpg_to_rgb888_hex.py

@@ -0,0 +1,64 @@
+from PIL import Image
+
+
+def jpg_to_rgb888_hex_c_array(input_filename: str, output_filename: str) -> str:
+    """
+    Convert a .jpg file to RGB888 hex data and format it as a C-style array.
+
+    Parameters:
+    input_filename (str): The path to the JPEG file.
+
+    Returns:
+    str: A string representing the RGB888 hex data formatted as a C array.
+    """
+    # Open the image file
+    with Image.open(input_filename) as img:
+        # Ensure the image is in RGB mode
+        rgb_img = img.convert("RGB")
+
+        # Get image dimensions
+        width, height = rgb_img.size
+
+        # List to store hex values as C-style entries
+        hex_data = []
+
+        # Iterate over each pixel to get RGB values
+        for y in range(height):
+            for x in range(width):
+                r, g, b = rgb_img.getpixel((x, y))
+                # Format each RGB value as C-style hex (e.g., 0xRRGGBB)
+                hex_data.append(f"0x{r:02X}{g:02X}{b:02X}")
+
+    # Format as a C-style array with line breaks for readability
+    hex_array = ",\n    ".join(hex_data)
+    c_array = f"unsigned int image_data[{width * height}] = {{\n    {hex_array}\n}};"
+
+    # Write the C array to the output file
+    with open(output_filename, "w") as file:
+        file.write(c_array)
+
+    print(f"C-style RGB888 hex array saved to {output_filename}")
+
+    return c_array
+
+
+def main():
+    """
+    Main function to convert a JPEG file to an RGB888 C-style hex array.
+
+    Instructions:
+    1. Replace 'input.jpg' with the path to your JPEG file.
+    2. Run the script to get the C-style array output.
+    """
+    # Input JPEG file path
+    input_filename = "usb_camera.jpg"  # Replace with your JPEG file path
+
+    # Output file path for the C array
+    output_filename = "output_array.c"  # Specify your desired output filename
+
+    # Convert JPEG to C-style RGB888 hex array
+    jpg_to_rgb888_hex_c_array(input_filename, output_filename)
+
+
+if __name__ == "__main__":
+    main()