Umi-OCR HTTP 二維碼接口實(shí)戰(zhàn)Base64 識(shí)別與文本生成圖片的完整調(diào)用指南【免費(fèi)下載鏈接】Umi-OCROCR software, free and offline. 開(kāi)源、免費(fèi)的離線OCR軟件。支持截屏/批量導(dǎo)入圖片PDF文檔識(shí)別排除水印/頁(yè)眉頁(yè)腳掃描/生成二維碼。內(nèi)置多國(guó)語(yǔ)言庫(kù)。項(xiàng)目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR本文基于 Umi-OCR 倉(cāng)庫(kù)中 docs/http/api_qrcode.md 的官方接口說(shuō)明系統(tǒng)講解 Umi-OCR 二維碼 HTTP 接口的兩類(lèi)能力將 Base64 圖片解析為二維碼/條形碼文本以及從文本反向生成二維碼圖片。讀完后你可以直接在自己的項(xiàng)目前端腳本、后端服務(wù)或自動(dòng)化流水線中集成離線二維碼識(shí)別與生成能力并從源碼層面理解接口背后的 zxingcpp 解析鏈、圖像預(yù)處理參數(shù)和錯(cuò)誤碼設(shè)計(jì)。一、前置準(zhǔn)備啟動(dòng) HTTP 服務(wù)Umi-OCR 的二維碼接口屬于其 HTTP 接口體系的一部分。調(diào)用接口前需要滿足以下條件開(kāi)啟 HTTP 服務(wù)在 Umi-OCR 的全局設(shè)置頁(yè)中勾選“高級(jí)”選項(xiàng)后可以看到 HTTP 服務(wù)設(shè)置默認(rèn)處于開(kāi)啟狀態(tài)。接口手冊(cè)見(jiàn) docs/http/README.md。確認(rèn)監(jiān)聽(tīng)端口默認(rèn)端口為1224可從 UmiOCR-data/py_src/utils/pre_configs.py 中確認(rèn)默認(rèn)配置server_port: 1224。若端口被占用UmiOCR-data/py_src/server/web_server.py 中的服務(wù)邏輯會(huì)自動(dòng)遞增端口并記錄實(shí)際端口以啟動(dòng)日志中的Listening on http://...為準(zhǔn)。訪問(wèn)地址本機(jī)調(diào)用使用http://127.0.0.1:1224如需被局域網(wǎng)訪問(wèn)需將主機(jī)切換為“任何可用地址”。從源碼結(jié)構(gòu)看HTTP 服務(wù)基于 Bottle 框架構(gòu)建并在 UmiOCR-data/py_src/server/web_server.py 中為所有響應(yīng)添加了Access-Control-Allow-Origin: *等跨域頭因此瀏覽器前端可以直接fetch調(diào)用同時(shí)單次請(qǐng)求體上限被設(shè)置為 100 MBBaseRequest.MEMFILE_MAX大尺寸圖片的 Base64 請(qǐng)求無(wú)需擔(dān)心被截?cái)?。官方手?cè)還給出了三條運(yùn)行注意事項(xiàng)見(jiàn) docs/http/README.md關(guān)閉 Umi-OCR 時(shí)若仍有未斷開(kāi)的 HTTP 連接可能導(dǎo)致進(jìn)程關(guān)閉不完全需等待連接釋放或強(qiáng)制結(jié)束進(jìn)程后端組件對(duì)并發(fā)支持較差盡量不要并發(fā)調(diào)用長(zhǎng)時(shí)間、大批量、連續(xù)調(diào)用時(shí)小概率出現(xiàn)ECONNREFUSED之類(lèi)報(bào)錯(cuò)重新發(fā)起請(qǐng)求即可。二、接口總覽一個(gè) URL兩種模式二維碼識(shí)別與二維碼生成共用同一個(gè) URL/api/qrcode例http://127.0.0.1:1224/api/qrcode均為POST方法、JSON 字典參數(shù)。區(qū)分兩種模式的關(guān)鍵在于請(qǐng)求體中攜帶的鍵請(qǐng)求體含base64鍵 → 走圖片識(shí)別二維碼分支請(qǐng)求體含text鍵 → 走文本生成二維碼圖片分支。這一路由分派邏輯可以直接在 UmiOCR-data/py_src/server/qrcode_server.py 中確認(rèn)# 路由函數(shù) def init(UmiWeb): UmiWeb.route(/api/qrcode, methodPOST) def _qrcode(): try: data request.json except Exception as e: return json.dumps({code: 800, data: f請(qǐng)求無(wú)法解析為json。}) if not data: return json.dumps({code: 801, data: f請(qǐng)求為空。}) if base64 in data: return json.dumps(base2text(data)) elif text in data: return json.dumps(text2base(data)) return json.dumps({code: 802, data: 指令中不存在 base64 或 text})由此得到一組“請(qǐng)求級(jí)”錯(cuò)誤碼在任何分支之前就會(huì)返回code含義800請(qǐng)求體無(wú)法解析為 JSON801請(qǐng)求體為空802指令中既沒(méi)有base64也沒(méi)有text以下分兩節(jié)詳細(xì)講解兩種模式的請(qǐng)求/響應(yīng)格式與調(diào)用示例。三、模式一Base64 識(shí)別二維碼/api/qrcode傳入圖片的 Base64 編碼字符串返回圖中所有二維碼/條形碼的文本、格式、位置和方向。一張圖片中可能包含多個(gè)碼接口會(huì)逐一返回。3.1 請(qǐng)求格式方法POST參數(shù)為 JSON 字典base64必填。待識(shí)別圖像的 Base64 編碼字符串無(wú)需data:image/png;base64,等前綴。options可選。參數(shù)字典支持以下圖像預(yù)處理選項(xiàng)參數(shù)取值范圍默認(rèn)行為說(shuō)明preprocessing.median_filter_size1~9 的奇數(shù)不濾波中值濾波器大小用于去噪preprocessing.sharpness_factor0.1~10.0不調(diào)整銳度增強(qiáng)因子preprocessing.contrast_factor0.1~10.0不調(diào)整對(duì)比度增強(qiáng)因子1 增強(qiáng)0~1 減弱1 保持原樣preprocessing.grayscaletrue/falsefalse是否轉(zhuǎn)換為灰度圖preprocessing.threshold0~255 整數(shù)不生效二值化閾值僅當(dāng)grayscaletrue時(shí)生效參數(shù)示例{ base64: iVBORw0KGgoAAAAN……, options: { preprocessing.sharpness_factor: 1.0, preprocessing.contrast_factor: 1.0, preprocessing.grayscale: false, preprocessing.threshold: false } }3.2 響應(yīng)格式返回 JSON頂層結(jié)構(gòu)與 OCR 結(jié)果非常相似字段類(lèi)型描述codeint任務(wù)狀態(tài)碼。100為成功101為圖中無(wú)碼無(wú)文本其余為失敗datalist/string識(shí)別結(jié)果。成功時(shí)為列表101或失敗時(shí)為錯(cuò)誤原因字符串timedouble識(shí)別耗時(shí)秒timestampdouble任務(wù)開(kāi)始時(shí)間戳秒code100時(shí)data為列表記錄圖片中每個(gè)碼的結(jié)果每項(xiàng)包含參數(shù)名類(lèi)型描述textstring碼的文本內(nèi)容formatstring碼的格式如QRCode可選值見(jiàn)下boxlist文本框順時(shí)針?biāo)膫€(gè)角的 xy 坐標(biāo)[左上,右上,右下,左下]orientationint碼的方向0 為正上scoreint為與 OCR 格式兼容而設(shè)永遠(yuǎn)為 1無(wú)實(shí)際含義支持的碼格式format取值A(chǔ)ztec、Codabar、Code128、Code39、Code93、DataBar、DataBarExpanded、DataMatrix、EAN13、EAN8、ITF、LinearCodes、MatrixCodes、MaxiCode、MicroQRCode、PDF417、QRCode、UPCA、UPCE識(shí)別成功的結(jié)果示例{ code: 100, data: [ { orientation: 0, box: [[4,4],[25,4],[25,25],[4,25]], score: 1, format: QRCode, text: abc } ], time: 0, timestamp: 1711521012.625574 }識(shí)別失敗含code101無(wú)碼、其他錯(cuò)誤碼時(shí)data為字符串錯(cuò)誤原因例如{code: 204, data: 【Error】zxingcpp 二維碼解析失敗。\n[Error] zxingcpp read_barcodes failed?！瓆3.3 調(diào)用示例JavaScript以下示例摘自官方文檔可直接用于瀏覽器或 Node 環(huán)境const url http://127.0.0.1:1224/api/qrcode; const base64 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/...此處為完整 Base64原文見(jiàn) docs/http/api_qrcode.md; const data { base64: base64 }; fetch(url, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify(data) }) .then(response response.json()) .then(data { if(data.code 100) { console.log(QRCode count:, data.data.length); for (let d of data.data) { console.log( text: , d.text); console.log( format: , d.format); console.log( orientation: , d.orientation); console.log( ); } } else { console.log(Error! Code, data.code, Msg: , data.data); } }) .catch(error console.error(error));3.4 源碼解析識(shí)別鏈路與錯(cuò)誤碼識(shí)別二維碼的實(shí)際執(zhí)行邏輯位于 UmiOCR-data/py_src/mission/mission_qrcode.py。HTTP 層base2text取出base64與options后通過(guò)MissionQRCode.addMissionWait(opt, [{base64: base64}])提交任務(wù)并同步等待結(jié)果核心處理在msnTask方法中鏈路為讀圖 → 預(yù)處理 → zxingcpp 解析 → 結(jié)果轉(zhuǎn)字典各環(huán)節(jié)都有獨(dú)立錯(cuò)誤碼code階段說(shuō)明901依賴檢查無(wú)法導(dǎo)入二維碼解析器 zxingcpp202讀圖圖片讀取失敗Base64 解碼或Image.open失敗203預(yù)處理圖像預(yù)處理失敗204解析zxingcpp.read_barcodes拋異常205結(jié)果轉(zhuǎn)換解析結(jié)果轉(zhuǎn)字典失敗101無(wú)碼圖中未找到任何碼data為QR code not found in the image.102解碼失敗檢測(cè)到碼但全部解碼無(wú)效幾個(gè)值得注意的實(shí)現(xiàn)細(xì)節(jié)均見(jiàn) UmiOCR-data/py_src/mission/mission_qrcode.pybox 坐標(biāo)順序_zxingcpp2dict按top_left → top_right → bottom_right → bottom_left組裝四個(gè)角與文檔“順時(shí)針?biāo)慕恰钡拿枋鲆恢?。非文本?nèi)容的處理當(dāng)碼的content_type不是Text時(shí)如 GS1、二進(jìn)制內(nèi)容源碼會(huì)先嘗試按 UTF-8 解碼bytes解碼失敗則在文本前加[Base64]標(biāo)記并以 Base64 字符串輸出。也就是說(shuō)text字段在極少數(shù)情況下可能是“type: Binary Base64”的混合內(nèi)容調(diào)用方需留意。預(yù)處理參數(shù)與文檔的對(duì)應(yīng)關(guān)系_preprocessing方法mission_qrcode.py中中值濾波使用 PIL 的MedianFilter(sizes)且要求奇數(shù)銳度、對(duì)比度使用ImageEnhance二值化邏輯為灰度值 threshold → 255否則 → 0且僅在grayscaletrue時(shí)執(zhí)行——這解釋了為什么文檔強(qiáng)調(diào)threshold只在灰度模式下生效。score 恒為 1源碼中d[score] 1有注釋“置信度兼容OCR格式無(wú)意義”與文檔描述吻合。四、模式二從文本生成二維碼圖片/api/qrcode傳入文本根據(jù)文本生成二維碼圖片返回圖片的 Base64 字符串JPEG 編碼。URL 與識(shí)別接口一致僅請(qǐng)求參數(shù)不同。4.1 請(qǐng)求格式方法POST參數(shù)為 JSON 字典text必填。要寫(xiě)入二維碼的文本。options可選。參數(shù)字典參數(shù)類(lèi)型默認(rèn)值說(shuō)明formatstringQRCode碼格式可選值同識(shí)別接口的 format 列表wint0生成圖像寬度0表示自動(dòng)設(shè)為最小寬度hint0生成圖像高度0表示自動(dòng)設(shè)為最小高度quiet_zoneint-1碼四周空白邊緣寬度-1表示自動(dòng)調(diào)節(jié)ec_levelint-1糾錯(cuò)等級(jí)。-1:自動(dòng)1:7%0:15%3:25%2:30%。僅對(duì)Aztec、PDF417、QRCode生效參數(shù)示例{ text: 要寫(xiě)入二維碼的文本, options: { format: QRCode, w: 0, h: 0, quiet_zone: -1, ec_level: -1 } }4.2 響應(yīng)格式字段類(lèi)型描述codeint100成功其余為失敗datastring成功時(shí)為圖片的 Base64 字符串JPEG 編碼失敗時(shí)為錯(cuò)誤信息字符串4.3 調(diào)用示例JavaScriptconst url http://127.0.0.1:1224/api/qrcode; const data { text: test abc 123 !!!, // options: { // format: QRCode, // w: 0, // h: 0, // quiet_zone: -1, // ec_level: -1, // } }; fetch(url, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify(data) }) .then(response response.json()) .then(data { if(data.code 100) { console.log(Image base64: \n, data.data); } else { console.log(Error! Code, data.code, Msg: , data.data); } }) .catch(error console.error(error));拿到 Base64 后前端可直接拼成img srcdata:image/jpeg;base64,...展示后端則可解碼寫(xiě)盤(pán)。4.4 源碼解析生成鏈路生成分支的服務(wù)端實(shí)現(xiàn)為 UmiOCR-data/py_src/server/qrcode_server.py 中的text2base它從options中取出format默認(rèn)QRCode、w/h默認(rèn)0、quiet_zone默認(rèn)-1、ec_level默認(rèn)-1調(diào)用MissionQRCode.createImage得到 PIL 圖像再以JPEG格式寫(xiě)入BytesIO并 Base64 編碼返回——這與文檔“返回圖片編碼為 jpeg”的描述一致異常時(shí)返回{code: 200, data: [Error] ...}。真正的編碼動(dòng)作在 UmiOCR-data/py_src/mission/mission_qrcode.py 的createImage中先通過(guò)getattr(zxingcpp.BarcodeFormat, format, None)校驗(yàn)格式名是否合法非法格式直接返回[Error] format {format} not in zxingcpp.BarcodeFormat!調(diào)用zxingcpp.write_barcode(bFormat, text, w, h, quiet_zone, ec_level)生成位圖再經(jīng)Image.fromarray(bit, L)轉(zhuǎn)為灰度 PIL 圖像源碼注釋明確了糾錯(cuò)等級(jí)映射-1自動(dòng)、1對(duì)應(yīng) L(7%)、0對(duì)應(yīng) M(15%)、3對(duì)應(yīng) Q(25%)、2對(duì)應(yīng) H(30%)且糾錯(cuò)等級(jí)僅用于Aztec、PDF417和QRCode——與文檔表格一致。五、錯(cuò)誤碼速查與常見(jiàn)問(wèn)題把請(qǐng)求級(jí)與分支級(jí)錯(cuò)誤碼匯總?cè)缦路奖闩耪蟘ode所屬分支含義800路由層請(qǐng)求無(wú)法解析為 JSON801路由層請(qǐng)求為空802路由層指令中不存在base64或text901識(shí)別zxingcpp 解析器導(dǎo)入失敗100識(shí)別/生成成功101識(shí)別圖中無(wú)碼102識(shí)別碼全部解碼失敗200生成生成過(guò)程拋異常data為錯(cuò)誤信息202識(shí)別圖片讀取失敗203識(shí)別圖像預(yù)處理失敗204識(shí)別zxingcpp 解析異常205識(shí)別結(jié)果轉(zhuǎn)字典失敗實(shí)踐建議先驗(yàn)連通性瀏覽器訪問(wèn)http://127.0.0.1:1224/應(yīng)返回 Umi-OCR 的名稱標(biāo)識(shí)見(jiàn) web_server.py 的根路由可用于確認(rèn)服務(wù)已啟動(dòng)。小圖失敗時(shí)加預(yù)處理對(duì)模糊、有噪點(diǎn)的截圖可組合median_filter_size奇數(shù)contrast_factor1 灰度/二值化重試參數(shù)含義見(jiàn) 3.1 節(jié)表格。避免并發(fā)官方手冊(cè)明確后端并發(fā)支持較差批量業(yè)務(wù)請(qǐng)串行調(diào)用偶發(fā)ECONNREFUSED時(shí)重試即可。注意score字段該字段僅用于格式兼容不要將其當(dāng)作置信度使用。六、相關(guān)文檔與延伸閱讀二維碼接口并非孤立存在Umi-OCR 的 HTTP 接口手冊(cè)中還包含可組合使用的其他能力HTTP接口手冊(cè)總覽服務(wù)開(kāi)啟、局域網(wǎng)訪問(wèn)與注意事項(xiàng)圖片OCR接口Base64 圖片文字識(shí)別其響應(yīng)格式box/score/end與二維碼接口刻意保持兼容文檔識(shí)別PDF流程上傳 → 輪詢 → 下載 → 清理的完整任務(wù)流配套 Python 示例 與 Web 示例命令行接口/argv接口等價(jià)于命令行傳參僅允許127.0.0.1調(diào)用可參考 README_CLI.md 了解全部命令行參數(shù)CHANGE_LOG.md 記錄了二維碼功能演進(jìn)二維碼解析庫(kù)改用 zxingcpp、新增二維碼識(shí)別頁(yè)與生成功能、HTTP 二維碼接口支持圖像預(yù)處理參數(shù)等可作為版本能力確認(rèn)依據(jù)。【免費(fèi)下載鏈接】Umi-OCROCR software, free and offline. 開(kāi)源、免費(fèi)的離線OCR軟件。支持截屏/批量導(dǎo)入圖片PDF文檔識(shí)別排除水印/頁(yè)眉頁(yè)腳掃描/生成二維碼。內(nèi)置多國(guó)語(yǔ)言庫(kù)。項(xiàng)目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考