MuPDF mutool barcode 命令完全指南基于 ZXing 的条码生成与识别实战【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdfmutool barcode是 MuPDF 工具集SumatraPDF 内置的文档渲染引擎中专门用于条码解码与生成的命令行子命令既能从图片或任意受支持的文档PDF、XPS、EPUB 等页面中批量识别条码内容也能将文本编码为 QR Code、EAN-13、DataMatrix 等 20 种条码格式并输出为 PNG 或 PDF。阅读本文后你将掌握mutool barcode的完整参数体系、两种工作模式-d解码 /-c编码、全部 20 种条码格式的适用场景并理解其底层如何借助 ZXing 库在 MuPDF 的像素图pixmap与页面渲染管线中完成条码读写。命令概览与可用性说明barcode命令的入口由 mutool.c 中的工具注册表声明#if FZ_ENABLE_BARCODE { mubar_main, barcode, encode/decode barcodes }, #endif这意味着该命令并非在所有构建中都存在。只有 MuPDF 在编译时启用了FZ_ENABLE_BARCODE宏且链接了 ZXing 条码库时才会注册否则mutool barcode会输出barcode support disabled并直接退出见 mubar.c 中#else分支。这正是 mutool-barcode.rst 开头特别标注This command may not be available!的原因。从构建层面看HAVE_ZXINGCPP决定是否启用该功能Unix 构建在 Makethird 中探测系统 ZXing C 库HAVE_SYS_ZXINGCPP并通过-DHAVE_ZXINGCPP与-DFZ_ENABLE_BARCODE1传入编译参数Windows 构建则由独立的 libmubarcode.vcxproj 项目承载其预处理器定义中同时包含ZXING_EXPERIMENTAL_API启用实验性 ZXing API与FZ_ENABLE_BARCODE1。命令本身支持两个子模式通过首个参数区分模式语法用途解码mutool barcode -d [options] file1.pdf [pages1] [file2.pdf [pages2] ...]从文档/图片页面中识别条码编码mutool barcode -c [options] text将文本生成条码图片mubar_main的分发逻辑见 mubar.c仅当argc 2且第二个参数为-c或-d时才进入对应实现否则打印用法并返回失败。解码模式从文档与图片中识别条码命令语法与参数详解mutool barcode -d [options] file1.pdf [pages1] [file2.pdf [pages2] ...]解码模式各选项含义如下对应 mubar.c 中mubar_decode的参数解析-ppassword当输入文件被加密典型如加密 PDF时使用。实现中先调用fz_needs_password检测若需要密码则调用fz_authenticate_password校验密码错误会抛出cannot authenticate password错误。-ooutput解码结果输出文件名例如output.txt。不指定时识别出的条码文本打印到标准输出stdout。-rrotation解码前对输入页面执行的旋转角度单位度范围 0–360。该值通过fz_atof解析后传入底层 ZXing 的rotated(rotate)调用用于处理页面上条码方向不正的场景。输入文件与页码范围位置参数中file1、file2等为输入文件名支持所有 MuPDF 可识别的文档格式紧随每个文件之后可以跟一个可选的页码范围参数。页码规则第一页编号为1最后一页为N默认范围是1-N即全部页面支持逗号分隔的多个范围如1,3,5支持逆序范围。源码中的处理逻辑在 mubar.c用fz_is_page_range判断下一个参数是否为页码范围再用fz_parse_page_range循环解析start end时正序遍历、否则逆序遍历。例如# 解码 a.pdf 的第 1、3、5 页以及 b.pdf 的默认全部页面 mutool barcode -d a.pdf 1,3,5 b.pdf解码输出格式对于每个被处理的页面输出一行结果识别成功条码类型: 条码内容例如qrcode: https://example.com未识别到输出none。输出格式由 mubar.c 中的mubar_decode_page决定类型名来自fz_string_from_barcode_type内容来自fz_decode_barcode_from_page的返回值。多个文件/页面会依序逐行输出。解码的底层实现原理mubar_decode_page的调用链可以完整还原解码过程加载页面fz_load_page按页码page_no-1内部从 0 起加载页面渲染为灰度像素图fz_decode_barcode_from_page见 barcode.c先取页面边界fz_bound_page与子区域求交创建一个以0xFF白色清空的灰度 pixmap再用fz_new_draw_device加fz_run_page把页面光栅化到该 pixmap 上调用 ZXing 识别灰度 pixmap 交给fz_decode_barcode_from_pixmap最终进入 zxingbarcode.cpp 的barcode_decode_from_samples构造 ZXing 的ImageView并调用ReadBarcode(image.rotated(rotate))完成识别。一个值得注意的约束底层识别只接受灰度1 通道或 RGB3 通道像素图其他通道数会直接抛出Barcodes can be greyscale or RGB only错误见 barcode.c。解码路径中对识别结果统一使用TextMode::Escaped提取文本保证特殊字符可安全输出。编码模式将文本生成条码命令语法与参数详解mutool barcode -c [options] text其中text是要编码进条码的原始文本。各选项见 mubar.c 的mubar_create-ooutput输出文件名扩展名决定输出格式——.png生成 PNG 图片.pdf生成 PDF 文件不指定时默认为out.png。若扩展名既不是.png也不是.pdf会报错invalid output format (must be PNG or PDF)。-Fformat目标条码格式支持 20 种详见下文格式清单大小写不敏感fz_barcode_type_from_string使用fz_strcasecmp匹配默认值为qrcode传入无法识别的字符串会打印用法并退出。-ssize输出条码的像素尺寸。注意当前仓库中命令行层的默认值是256 像素mubar.c第 94 行int size 256而底层barcode_create在 size 为 0 时才会退化为能解码的最小尺寸scale(2)这与文档中未指定则选择最小可解码尺寸的描述存在版本差异以实际构建行为为准。-q为条码添加静区quiet zone即在条码四周留出空白边距。底层通过setMargin(quiet ? 10 : 0)实现。-t在可用时为条码附加人类可读文本。例如 EAN-13 这类自带数字语义的条码会把内容以明文形式印在条码旁边。该选项仅在启用ZXING_EXPERIMENTAL_API的构建如 Windows 的 libmubarcode.vcxproj中实际生效非实验性 API 路径在 zxingbarcode.cpp 中标注了TODO: human readable text (not available with non-experimental API)。-elevel纠错等级。文档声明范围为 0–8而当前源码fz_new_barcode_pixmap的校验为ec_level 0 || ec_level 8即抛错见 barcode.c实际可用值为0–7。QR Code 等支持多级纠错的条码可通过该参数权衡容量与抗损能力。编码的底层实现原理mubar_create首先调用fz_new_barcode_pixmap生成条码像素图然后按扩展名写入文件PNG 输出直接调用fz_save_pixmap_as_pngPDF 输出走fz_save_pixmap_as_pclmPCLm 编码路径设置压缩与整页条带高度见 mubar.c。fz_new_barcode_pixmapbarcode.c先做合法性校验类型必须在FZ_BARCODE_NONE与FZ_BARCODE__LIMIT之间、纠错等级 0–7然后调用 ZXing 的barcode_create生成原始位图数据拷贝进一个灰度fz_pixmap后返回。生成的 pixmap 分辨率在实验性 API 下为 72 DPI非实验性 API 下为 36 DPI。ZXing 侧的生成流程zxingbarcode.cpp为构造MultiFormatWriter→ 设置 UTF-8 编码 → 设置边距静区与纠错等级 →encode(value, size, size ? size : 50)得到BitMatrix→ 转换为字节位图。整条链路刻意用 Ctry/catch包住确保 C 异常不会跨越到 MuPDF 的 C 错误处理机制异常信息通过exception缓冲区回传。支持的 20 种条码格式编码模式通过-F指定格式完整清单如下与 barcode.h 中的fz_barcode_type枚举及 barcode.c 的字符串表一一对应-F参数条码类型典型用途aztecAztec Code高密度 2D 码适合车票、证件codabarCodabar图书馆、血库等老式 1D 码code39Code 39工业、国防领域常用字母数字 1D 码code93Code 93Code 39 的高密度变体code128Code 128最通用的高密度 1D 码物流、零售databarGS1 DataBar零售小件商品databarexpandedGS1 DataBar Expanded可变长度 GS1 数据datamatrixData Matrix电子元件、医疗小面积打标ean8EAN-8短版国际商品条码ean13EAN-13国际商品零售条码itfITF (Interleaved 2 of 5)仓储、纸箱外包装maxicodeMaxiCode快递包裹UPS 等pdf417PDF417证件、登机牌等堆叠式 2D 码qrcodeQR Code通用 2D 码默认格式upcaUPC-A北美商品条码upceUPC-EUPC-A 的压缩形式microqrcodeMicro QR Code极小面积 QR 变体rmqrcoderMQR Code矩形 QR 变体dxfilmedgeDX Film Edge胶片冲洗行业条码databarlimitedGS1 DataBar Limited小型零售单品其中rmqrcode、dxfilmedge、databarlimited三种格式在 ZXing 的映射表中仅于ZXING_EXPERIMENTAL_API构建下启用见 zxingbarcode.cpp非实验性 API 构建会将其映射为无效格式。面向开发者的底层 C APImutool barcode的命令行能力全部建立在 MuPDF 的公开 C API 之上声明见 barcode.h这些 API 同样可被其他 MuPDF 集成方直接调用fz_new_barcode_pixmap(ctx, type, value, size, ec_level, quiet, hrt)按类型、文本、尺寸、纠错等级、静区、可读文本参数生成条码像素图fz_new_barcode_image(...)基于 pixmap 进一步封装为fz_image便于直接嵌入页面绘制fz_decode_barcode_from_page(ctx, type, page, subarea, rotate)从文档页面的指定子区域fz_rect解码rotate支持 0/90/180/270fz_decode_barcode_from_pixmap(...)/fz_decode_barcode_from_display_list(...)分别从现有像素图或 display list 中解码fz_barcode_type_from_string/fz_string_from_barcode_type条码类型字符串与枚举的双向转换大小写不敏感。因此即便是复杂应用也可以跳过命令行直接在 MuPDF 渲染管线中嵌入条码的生成与识别能力。实战示例汇总# 1) 从 PDF 全部页面解码结果输出到标准输出 mutool barcode -d invoice.pdf # 2) 只解码第 2 到 4 页写入文本文件 mutool barcode -d -o codes.txt invoice.pdf 2-4 # 3) 解码前将页面旋转 90 度并处理加密文档 mutool barcode -d -p secret -r 90 encrypted.pdf # 4) 生成一个默认尺寸的 QR Code默认格式 qrcode mutool barcode -c https://example.com -o qr.png # 5) 生成带静区、人类可读文本、高纠错等级的 EAN-13 mutool barcode -c -F ean13 -q -t -e 4 5901234123457 -o ean.pdf # 6) 生成 512 像素的 Data Matrix 并输出为 PDF mutool barcode -c -F datamatrix -s 512 -o dm.pdf S/N: 2026-001小结mutool barcode将 ZXing 的条码读写能力无缝接入 MuPDF 的文档渲染管线解码侧复用页面的光栅化流程把任意受支持文档的页面转成灰度图后交给 ZXing 识别编码侧则从文本生成位图并输出为 PNG 或 PDF。理解其参数体系-d/-c模式、-p/-o/-r/-F/-s/-q/-t/-e与底层 APIbarcode.h、barcode.c、zxingbarcode.cpp后即可在 SumatraPDF 所依赖的这一渲染引擎生态中独立完成从条码识别到条码生成的完整工作流。【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MuPDF mutool barcode 命令完全指南基于 ZXing 的条码生成与识别实战【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdfmutool barcode是 MuPDF 工具集SumatraPDF 内置的文档渲染引擎中专门用于条码解码与生成的命令行子命令既能从图片或任意受支持的文档PDF、XPS、EPUB 等页面中批量识别条码内容也能将文本编码为 QR Code、EAN-13、DataMatrix 等 20 种条码格式并输出为 PNG 或 PDF。阅读本文后你将掌握mutool barcode的完整参数体系、两种工作模式-d解码 /-c编码、全部 20 种条码格式的适用场景并理解其底层如何借助 ZXing 库在 MuPDF 的像素图pixmap与页面渲染管线中完成条码读写。命令概览与可用性说明barcode命令的入口由 mutool.c 中的工具注册表声明#if FZ_ENABLE_BARCODE { mubar_main, barcode, encode/decode barcodes }, #endif这意味着该命令并非在所有构建中都存在。只有 MuPDF 在编译时启用了FZ_ENABLE_BARCODE宏且链接了 ZXing 条码库时才会注册否则mutool barcode会输出barcode support disabled并直接退出见 mubar.c 中#else分支。这正是 mutool-barcode.rst 开头特别标注This command may not be available!的原因。从构建层面看HAVE_ZXINGCPP决定是否启用该功能Unix 构建在 Makethird 中探测系统 ZXing C 库HAVE_SYS_ZXINGCPP并通过-DHAVE_ZXINGCPP与-DFZ_ENABLE_BARCODE1传入编译参数Windows 构建则由独立的 libmubarcode.vcxproj 项目承载其预处理器定义中同时包含ZXING_EXPERIMENTAL_API启用实验性 ZXing API与FZ_ENABLE_BARCODE1。命令本身支持两个子模式通过首个参数区分模式语法用途解码mutool barcode -d [options] file1.pdf [pages1] [file2.pdf [pages2] ...]从文档/图片页面中识别条码编码mutool barcode -c [options] text将文本生成条码图片mubar_main的分发逻辑见 mubar.c仅当argc 2且第二个参数为-c或-d时才进入对应实现否则打印用法并返回失败。解码模式从文档与图片中识别条码命令语法与参数详解mutool barcode -d [options] file1.pdf [pages1] [file2.pdf [pages2] ...]解码模式各选项含义如下对应 mubar.c 中mubar_decode的参数解析-ppassword当输入文件被加密典型如加密 PDF时使用。实现中先调用fz_needs_password检测若需要密码则调用fz_authenticate_password校验密码错误会抛出cannot authenticate password错误。-ooutput解码结果输出文件名例如output.txt。不指定时识别出的条码文本打印到标准输出stdout。-rrotation解码前对输入页面执行的旋转角度单位度范围 0–360。该值通过fz_atof解析后传入底层 ZXing 的rotated(rotate)调用用于处理页面上条码方向不正的场景。输入文件与页码范围位置参数中file1、file2等为输入文件名支持所有 MuPDF 可识别的文档格式紧随每个文件之后可以跟一个可选的页码范围参数。页码规则第一页编号为1最后一页为N默认范围是1-N即全部页面支持逗号分隔的多个范围如1,3,5支持逆序范围。源码中的处理逻辑在 mubar.c用fz_is_page_range判断下一个参数是否为页码范围再用fz_parse_page_range循环解析start end时正序遍历、否则逆序遍历。例如# 解码 a.pdf 的第 1、3、5 页以及 b.pdf 的默认全部页面 mutool barcode -d a.pdf 1,3,5 b.pdf解码输出格式对于每个被处理的页面输出一行结果识别成功条码类型: 条码内容例如qrcode: https://example.com未识别到输出none。输出格式由 mubar.c 中的mubar_decode_page决定类型名来自fz_string_from_barcode_type内容来自fz_decode_barcode_from_page的返回值。多个文件/页面会依序逐行输出。解码的底层实现原理mubar_decode_page的调用链可以完整还原解码过程加载页面fz_load_page按页码page_no-1内部从 0 起加载页面渲染为灰度像素图fz_decode_barcode_from_page见 barcode.c先取页面边界fz_bound_page与子区域求交创建一个以0xFF白色清空的灰度 pixmap再用fz_new_draw_device加fz_run_page把页面光栅化到该 pixmap 上调用 ZXing 识别灰度 pixmap 交给fz_decode_barcode_from_pixmap最终进入 zxingbarcode.cpp 的barcode_decode_from_samples构造 ZXing 的ImageView并调用ReadBarcode(image.rotated(rotate))完成识别。一个值得注意的约束底层识别只接受灰度1 通道或 RGB3 通道像素图其他通道数会直接抛出Barcodes can be greyscale or RGB only错误见 barcode.c。解码路径中对识别结果统一使用TextMode::Escaped提取文本保证特殊字符可安全输出。编码模式将文本生成条码命令语法与参数详解mutool barcode -c [options] text其中text是要编码进条码的原始文本。各选项见 mubar.c 的mubar_create-ooutput输出文件名扩展名决定输出格式——.png生成 PNG 图片.pdf生成 PDF 文件不指定时默认为out.png。若扩展名既不是.png也不是.pdf会报错invalid output format (must be PNG or PDF)。-Fformat目标条码格式支持 20 种详见下文格式清单大小写不敏感fz_barcode_type_from_string使用fz_strcasecmp匹配默认值为qrcode传入无法识别的字符串会打印用法并退出。-ssize输出条码的像素尺寸。注意当前仓库中命令行层的默认值是256 像素mubar.c第 94 行int size 256而底层barcode_create在 size 为 0 时才会退化为能解码的最小尺寸scale(2)这与文档中未指定则选择最小可解码尺寸的描述存在版本差异以实际构建行为为准。-q为条码添加静区quiet zone即在条码四周留出空白边距。底层通过setMargin(quiet ? 10 : 0)实现。-t在可用时为条码附加人类可读文本。例如 EAN-13 这类自带数字语义的条码会把内容以明文形式印在条码旁边。该选项仅在启用ZXING_EXPERIMENTAL_API的构建如 Windows 的 libmubarcode.vcxproj中实际生效非实验性 API 路径在 zxingbarcode.cpp 中标注了TODO: human readable text (not available with non-experimental API)。-elevel纠错等级。文档声明范围为 0–8而当前源码fz_new_barcode_pixmap的校验为ec_level 0 || ec_level 8即抛错见 barcode.c实际可用值为0–7。QR Code 等支持多级纠错的条码可通过该参数权衡容量与抗损能力。编码的底层实现原理mubar_create首先调用fz_new_barcode_pixmap生成条码像素图然后按扩展名写入文件PNG 输出直接调用fz_save_pixmap_as_pngPDF 输出走fz_save_pixmap_as_pclmPCLm 编码路径设置压缩与整页条带高度见 mubar.c。fz_new_barcode_pixmapbarcode.c先做合法性校验类型必须在FZ_BARCODE_NONE与FZ_BARCODE__LIMIT之间、纠错等级 0–7然后调用 ZXing 的barcode_create生成原始位图数据拷贝进一个灰度fz_pixmap后返回。生成的 pixmap 分辨率在实验性 API 下为 72 DPI非实验性 API 下为 36 DPI。ZXing 侧的生成流程zxingbarcode.cpp为构造MultiFormatWriter→ 设置 UTF-8 编码 → 设置边距静区与纠错等级 →encode(value, size, size ? size : 50)得到BitMatrix→ 转换为字节位图。整条链路刻意用 Ctry/catch包住确保 C 异常不会跨越到 MuPDF 的 C 错误处理机制异常信息通过exception缓冲区回传。支持的 20 种条码格式编码模式通过-F指定格式完整清单如下与 barcode.h 中的fz_barcode_type枚举及 barcode.c 的字符串表一一对应-F参数条码类型典型用途aztecAztec Code高密度 2D 码适合车票、证件codabarCodabar图书馆、血库等老式 1D 码code39Code 39工业、国防领域常用字母数字 1D 码code93Code 93Code 39 的高密度变体code128Code 128最通用的高密度 1D 码物流、零售databarGS1 DataBar零售小件商品databarexpandedGS1 DataBar Expanded可变长度 GS1 数据datamatrixData Matrix电子元件、医疗小面积打标ean8EAN-8短版国际商品条码ean13EAN-13国际商品零售条码itfITF (Interleaved 2 of 5)仓储、纸箱外包装maxicodeMaxiCode快递包裹UPS 等pdf417PDF417证件、登机牌等堆叠式 2D 码qrcodeQR Code通用 2D 码默认格式upcaUPC-A北美商品条码upceUPC-EUPC-A 的压缩形式microqrcodeMicro QR Code极小面积 QR 变体rmqrcoderMQR Code矩形 QR 变体dxfilmedgeDX Film Edge胶片冲洗行业条码databarlimitedGS1 DataBar Limited小型零售单品其中rmqrcode、dxfilmedge、databarlimited三种格式在 ZXing 的映射表中仅于ZXING_EXPERIMENTAL_API构建下启用见 zxingbarcode.cpp非实验性 API 构建会将其映射为无效格式。面向开发者的底层 C APImutool barcode的命令行能力全部建立在 MuPDF 的公开 C API 之上声明见 barcode.h这些 API 同样可被其他 MuPDF 集成方直接调用fz_new_barcode_pixmap(ctx, type, value, size, ec_level, quiet, hrt)按类型、文本、尺寸、纠错等级、静区、可读文本参数生成条码像素图fz_new_barcode_image(...)基于 pixmap 进一步封装为fz_image便于直接嵌入页面绘制fz_decode_barcode_from_page(ctx, type, page, subarea, rotate)从文档页面的指定子区域fz_rect解码rotate支持 0/90/180/270fz_decode_barcode_from_pixmap(...)/fz_decode_barcode_from_display_list(...)分别从现有像素图或 display list 中解码fz_barcode_type_from_string/fz_string_from_barcode_type条码类型字符串与枚举的双向转换大小写不敏感。因此即便是复杂应用也可以跳过命令行直接在 MuPDF 渲染管线中嵌入条码的生成与识别能力。实战示例汇总# 1) 从 PDF 全部页面解码结果输出到标准输出 mutool barcode -d invoice.pdf # 2) 只解码第 2 到 4 页写入文本文件 mutool barcode -d -o codes.txt invoice.pdf 2-4 # 3) 解码前将页面旋转 90 度并处理加密文档 mutool barcode -d -p secret -r 90 encrypted.pdf # 4) 生成一个默认尺寸的 QR Code默认格式 qrcode mutool barcode -c https://example.com -o qr.png # 5) 生成带静区、人类可读文本、高纠错等级的 EAN-13 mutool barcode -c -F ean13 -q -t -e 4 5901234123457 -o ean.pdf # 6) 生成 512 像素的 Data Matrix 并输出为 PDF mutool barcode -c -F datamatrix -s 512 -o dm.pdf S/N: 2026-001小结mutool barcode将 ZXing 的条码读写能力无缝接入 MuPDF 的文档渲染管线解码侧复用页面的光栅化流程把任意受支持文档的页面转成灰度图后交给 ZXing 识别编码侧则从文本生成位图并输出为 PNG 或 PDF。理解其参数体系-d/-c模式、-p/-o/-r/-F/-s/-q/-t/-e与底层 APIbarcode.h、barcode.c、zxingbarcode.cpp后即可在 SumatraPDF 所依赖的这一渲染引擎生态中独立完成从条码识别到条码生成的完整工作流。【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
