icer_compression API深度参考：核心函数、数据结构与11种错误码详解

icer_compression API深度参考核心函数、数据结构与11种错误码详解【免费下载链接】icer_compressionProgressive, error tolerant, wavelet-based image compression algorithm项目地址: https://gitcode.com/gh_mirrors/ic/icer_compressionicer_compression 是一个用 C 语言实现的NASA ICER 渐进式小波图像压缩算法库专为容错、低内存的嵌入式与深空通信场景设计。本文是面向开发者的 icer_compression API 深度参考一次性讲清核心函数、关键数据结构与全部 11 种错误码的含义与排查方法帮助你在自己的项目中快速集成这套图像压缩算法。全部接口声明位于头文件 lib_icer/inc/icer.h算法背景可参考项目 README.md。快速了解 icer_compression源自 NASA 的容错图像压缩算法ICER 是 NASA 为深空探测任务如火星探测车 MER设计的图像压缩算法核心特点是渐进式传输 小波变换 错误隔离即使传输链路丢包损坏也只影响局部图像而非整张图片。icer_compression 完整实现了这一算法并额外支持 YUV 彩色图像、8/16 位深、7 种小波滤波器且全程只使用整数运算、无动态内存分配非常适合嵌入式环境。下面是官方示例图左图为 512×512 原始灰度图右图为仅分配 70KB 输出配额时的压缩效果肉眼几乎看不出差异。icer_compression 核心函数全解析压缩到解压只需 5 个 API第一步必须调用 icer_init() 完成初始化库内置的熵编码表、Golomb 编码参数等查找表需要先初始化所有程序在使用前都要调用一次int icer_init(); // 返回 ICER_RESULT_OK 表示成功初始化逻辑在 lib_icer/src/icer_init.c 中它依次完成编码方案、解码方案、flush 位与 Golomb 编码器的初始化。图像压缩核心函数灰度与 YUV 彩色双版本压缩入口同时提供 8 位与 16 位版本函数签名如下uint16 版本同理见 lib_icer/inc/icer.h// 灰度/单通道压缩 int icer_compress_image_uint8(uint8_t *image, size_t image_w, size_t image_h, uint8_t stages, enum icer_filter_types filt, uint8_t segments, icer_output_data_buf_typedef *output_data); // 彩色压缩Y、U、V 三个通道分别传入 int icer_compress_image_yuv_uint8(uint8_t *y, uint8_t *u, uint8_t *v, size_t image_w, size_t image_h, uint8_t stages, enum icer_filter_types filt, uint8_t segments, icer_output_data_buf_typedef *output_data);参数中stages是小波分解级数上限 6filt从ICER_FILTER_A到ICER_FILTER_Q共 7 种滤波器可选segments是错误隔离分段数上限 32分段越多容错越好、压缩率略降。完整调用示例见 example/src/example_encode.c。图像解压核心函数还原像素与宽高解压同样区分灰度与彩色、8 位与 16 位需要注意image_w/image_h是指针解压时会回填真实尺寸int icer_decompress_image_uint8(uint8_t *image, size_t *image_w, size_t *image_h, size_t image_bufsize, const uint8_t *datastream, size_t data_length, uint8_t stages, enum icer_filter_types filt, uint8_t segments);如果不知道压缩数据的尺寸可先用工具函数icer_get_image_dimensions()读取宽高再分配缓冲区避免缓冲区分配错误。实用工具函数输出缓冲区与配额控制icer_init_output_struct()绑定输出缓冲区并设置字节配额byte quota配额用尽时压缩会提前停止实现目标大小压缩icer_compress_partition_*/icer_compress_bitplane_*底层分段与位平面压缩接口进阶用户可自行控制压缩流程icer_wavelet_transform_*小波正/逆变换接口可单独使用做频域处理。深入理解 icer_compression 关键数据结构icer_output_data_buf_typedef压缩输出的统一出口压缩结果统一写入该结构定义见 lib_icer/inc/icer.h压缩完成后从rearrange_start开始读取size_used字节即为最终码流typedef struct { size_t size_used; // 实际使用的字节数 size_t size_allocated; // 分配的字节配额 uint8_t *data_start; // 缓冲区起始地址 uint8_t *rearrange_start; // 压缩数据起始地址 } icer_output_data_buf_typedef;icer_image_segment_typedef错误隔离的最小传输单元ICER 将图像切成多个 segment每个 segment 自带前导码、CRC32 校验与尺寸信息解码端可独立校验、跳过损坏段typedef struct { uint16_t preamble; // ICER_PACKET_PREAMBLE 0x605B uint16_t ll_mean_val; uint8_t decomp_level; uint8_t subband_type; uint8_t segment_number; uint8_t lsb_chan; uint32_t image_w, image_h; uint32_t data_length; // 数据长度按位计 uint32_t data_crc32; // 数据区 CRC32 uint32_t crc32; // 头部 CRC32 } icer_image_segment_typedef;编码/解码上下文与上下文模型icer_encoder_context_typedef熵编码器状态包含环形缓冲区、各 bin 的计数等lib_icer/src/icer_encoding.cicer_decoder_context_typedef熵解码器状态负责码字解析与 bin 缓冲lib_icer/src/icer_decoding.cicer_context_model_typedef每个子带LL/HL/LH/HH的概率上下文模型维护 zero_count 与 total_count用于自适应算术编码icer_packet_context描述每个数据包的分解级数、子带类型、通道与优先级是渐进式传输的调度依据。编译期常量与功能开关速查宏默认值说明ICER_MAX_SEGMENTS32最大错误隔离分段数ICER_MAX_DECOMP_STAGES6最大小波分解级数ICER_MAX_PACKETS / _16300 / 8008 位 / 16 位最大数据包数ICER_CIRC_BUF_SIZE2048编码环形缓冲区大小USE_UINT8/16_FUNCTIONS自动选择编译 8/16 位函数USE_ENCODE/DECODE_FUNCTIONS自动选择编译编码/解码函数USER_PROVIDED_BUFFERS关闭开启后由用户自备全局缓冲区这些配置集中在 lib_icer/inc/icer.h 与 lib_icer/src/icer_config.c 中按需裁剪可显著降低嵌入式内存占用。icer_compression 11种错误码详解与排查指南所有 API 均返回enum icer_status中的值完整定义见 lib_icer/inc/icer.h。其中ICER_RESULT_OK 0表示成功其余 11 种均为负数错误码一张表看懂错误码名称含义与常见触发场景-1ICER_INTEGER_OVERFLOW整数溢出多见于小波变换或尺寸计算如 lib_icer/src/icer_wavelet.c-2ICER_OUTPUT_BUF_TOO_SMALL输出缓冲区太小配额×2 超过缓冲长度见 lib_icer/src/icer_util.c-3ICER_TOO_MANY_SEGMENTS分段数超过 ICER_MAX_SEGMENTS 或超过像素数见 lib_icer/src/icer_partition.c-4ICER_TOO_MANY_STAGES小波分解级数超过上限见 lib_icer/src/icer_wavelet.c-5ICER_BYTE_QUOTA_EXCEEDED已超出字节配额压缩按预期提前停止属正常终止信号-6ICER_BITPLANE_OUT_OF_RANGE位平面序号越界见 lib_icer/src/icer_context_modeller.c-7ICER_DECODER_OUT_OF_DATA解码数据不足码流被截断或长度参数错误见 lib_icer/src/icer_decoding.c-8ICER_DECODED_INVALID_DATA解码出非法数据通常意味着 CRC 校验失败、码流损坏-9ICER_PACKET_COUNT_EXCEEDED数据包数量超限见 lib_icer/src/icer_compress.c-10ICER_FATAL_ERROR致命错误内部状态异常需检查参数与缓冲区-11ICER_INVALID_INPUT输入参数无效如图像尺寸异常见 lib_icer/src/icer_compress.c编码端常见错误码配额、分段与溢出 ICER_BYTE_QUOTA_EXCEEDED在编码中其实不是失败——它表示压缩已按目标大小完成属于可预期的正常终止参考 lib_icer/src/icer_encoding.c 的配额检查逻辑。若出现ICER_OUTPUT_BUF_TOO_SMALL请把缓冲区加大到配额的 2 倍以上因为 ICER 需要额外空间做数据重排若出现ICER_TOO_MANY_SEGMENTS请检查分段数是否超过 32 或图像像素总数。解码端常见错误码数据不足与数据损坏 ICER_DECODER_OUT_OF_DATA与ICER_DECODED_INVALID_DATA是解码端最常见的两类错误。前者多由data_length传错或码流被截断引起建议先用icer_get_image_dimensions()校验码流头部后者多因解压参数stages / filt / segments与压缩时不匹配——用非默认参数压缩时解压必须传入完全相同的参数这是 ICER 数据格式的设计要求详见 README.md 的 icer_util 示例。错误排查实用建议 永远先调icer_init()否则查找表未初始化会引发不可预期行为压缩/解压使用相同 stages、filt、segments可先用默认参数跑通流程解码前先校验 CRCICER 每个 segment 自带data_crc32与头部crc32可用于判断码流是否在传输中损坏对嵌入式部署按需裁剪USE_UINT8/UINT16与USE_ENCODE/DECODE宏可减少固件体积。彩图压缩效果参考与总结彩色压缩走 YUV 色彩空间下方左图为 140KB 配额的高保真压缩图右图为 70KB 配额的压缩图可以看到在低配额下整体结构依然完整这正是 ICER 渐进式 错误隔离设计的价值所在。总结来说icer_compression 的 API 设计非常克制5 个核心压缩/解压函数 少量工具函数 明确的错误码体系配合 lib_icer/inc/icer.h 的完整声明和 example/ 下的示例代码任何 C 项目都能在一小时内跑通压缩→传输→解压全流程。希望这份 icer_compression API 参考能帮你快速定位问题、顺利集成这套来自 NASA 的容错图像压缩算法。【免费下载链接】icer_compressionProgressive, error tolerant, wavelet-based image compression algorithm项目地址: https://gitcode.com/gh_mirrors/ic/icer_compression创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考