Small Wavelet Thumbnail & Preview Codec - WTPC

// In ONE .c file, define the implementation macro before including:
#define WTPC_IMAGE_IMPLEMENTATION
#include "wtpc_image.h"

// Everywhere else, just include the header to get the API declarations:
#include "wtpc_image.h"

   === API ===

   typedef enum {
       WTPC_ENC_AUTO    = 0,
       WTPC_ENC_HUFFMAN = 1,
       WTPC_ENC_EBCOT   = 2
   } wtpc_enc_mode;

   typedef struct {
       int encoded_bytes;   - output number of bytes
       int result_q;        - resulting quantization factor if target_bytes provided, or same as 'quality' if target_bytes=0
       int search_steps;    - number of iterations to search target bytes quantization 
       int ebcot;           - 1 = ebcot or 0 = huffman mode for best pick if auto encode_mode used
       int huffman_y_size;  - in bits if not picked static table
       int huffman_u_size;
       int huffman_v_size;
       int huffman_y_table; - 0..NUM_DEF_TABLES-1 - static, NUM_DEF_TABLES - custom written in bitstream
       int huffman_u_table;
       int huffman_v_table;
   } wtpc_enc_info;

   unsigned char *wtpc_encode_mem(const unsigned char *rgb, wtpc_enc_info *info,
       int w, int h, int target_bytes, int quality, int chroma_420,
       int encode_mode, int huf_extra_ctx, int has_alpha, int stride, int block_size);
     Encode an RGB/RGBA image in memory. Returns malloc'd WTPC bitstream,
     or NULL on error. Caller must free().
       rgb           : input pixels, h rows of stride bytes each.
                        Each row has w pixels, 3 bytes/pixel (RGB) or 4 (RGBA).
       info          : output struct, filled with encoding details (may be NULL).
       w, h          : image dimensions (>= 1).
       target_bytes  : desired output size in bytes. 0 = use 'quality' instead.
                       When > 0, the encoder does a binary search over the
                       quality range [1..MAX_QUALITY] to hit the target.
       quality       : quantization level 1..MAX_QUALITY (1024). Lower = better
                       quality / larger file. Used only when target_bytes == 0.
       chroma_420    : 0 = 4:4:4 (full chroma), 1 = 4:2:0 (half chroma).
                       4:2:0 saves ~15-30% bytes with minor visual loss.
       encode_mode   : WTPC_ENC_AUTO (auto-pick ebcot/huffman),
                       WTPC_ENC_HUFFMAN, WTPC_ENC_EBCOT.
       huf_extra_ctx : 0 = single Huffman table (faster),
                       1 = two context-switched tables (slightly better).
       has_alpha     : 0 = RGB (3 channels), 1 = RGBA (4 channels).
       stride        : bytes per row (0 = tightly packed = w * pixel_bytes).
                        Allows BMP-like padded data without repacking.
       block_size    : 0 = normal encode, or precinct size for EBCOT block mode
                       (32, 64, 128, 256, 512, 1024, 2048). Full-image wavelet,
                       entropy coding split into NxN blocks for speed. 3-4x faster
                       on large images; only valid with EBCOT (not Huffman).

   unsigned char *wtpc_decode_mem(const unsigned char *data, int data_len,
       int *w, int *h, int *out_quality, int *out_comp);
     Decode a WTPC bitstream from memory. Returns malloc'd pixel buffer
     (w*h*3 for RGB, w*h*4 for RGBA). Caller must free().
       data          : input WTPC bitstream bytes.
       data_len      : number of bytes in 'data'.
       w, h          : output image dimensions.
       out_quality   : quality level used for encoding (may be NULL).
       out_comp      : number of color components: 3 = RGB, 4 = RGBA (may be NULL).

   int wtpc_encode_file(const char *out_path, const unsigned char *rgb,
       wtpc_enc_info *info, int w, int h, int target_bytes, int quality,
       int chroma_420, int encode_mode, int huf_extra_ctx, int has_alpha, int stride, int block_size);
     Same as wtpc_encode_mem but writes directly to a file.
     Returns 0 on success, -1 on error.

   unsigned char *wtpc_decode_file(const char *in_path,
       int *w, int *h, int *out_quality, int *out_comp);
     Same as wtpc_decode_mem but reads from a file.

   === Wavelet Hash API (ultra-compact, ThumbHash-like) ===

   uint8_t *wtpc_hash_encode_mem(const uint8_t *rgb, int w, int h, int *out_len);
     Encode an RGB image (w,h <= 256) to a compact wavelet hash.
     Uses CDF 9/7 wavelet + YUV color space, auto-budget from image size.
     Returns malloc'd hash buffer, or NULL on error. Caller must free().
       rgb     : input pixels, tightly packed RGB (w*h*3 bytes).
       w, h    : image dimensions (1..256).
       out_len : filled with hash size in bytes.

   uint8_t *wtpc_hash_decode_mem(const uint8_t *hash, int hash_len, int *w, int *h);
     Decode a wavelet hash back to w x h RGB image.
     Returns malloc'd pixel buffer (w*h*3 bytes), or NULL on error. Caller must free().
       hash     : input hash bytes (from wtpc_hash_encode_mem).
       hash_len : number of bytes in hash.
       w, h     : filled with decoded image dimensions.

   === Build-time options ===
     #define WTPC_NO_STDIO        : exclude file I/O functions.
     #define DEBUG_WAVELET        : dump wavelet coefficient images (needs stb).
     #define STANDARD_CDF97       : enable standard CDF 9/7 K-scaling.
     #define BAC_USE_TABLE        : use 64 KB reciprocal lookup table for
                                    BAC division (~+1-3% speed, 64 KB memory).
                                    Default: 64-bit integer division.
     #define WTPC_TUNE_PARAMS     : mutable quantization tables for grid-search tuning.
     #define WTPC_TUNE_CTX        : tune ebcot contexts
     #define WTPC_NO_SIMD         : do not use sse/avx/neon intrinsics.
     #define WTPC_RC_ONLY_LESS_THAN_TARGET : rate control never overshoots
                                    target_bytes (picks the largest size <= target
                                    instead of the closest). Implied by
                                    WTPC_TUNE_PARAMS.