簡介DicomPrint-master 是一套面向醫(yī)療影像開發(fā)者的 DICOM 打印工具源碼聚焦醫(yī)學(xué)影像的膠片打印、格式定制與尺寸調(diào)整適合具備一定 C# 與 DICOM 協(xié)議基礎(chǔ)的技術(shù)人員研究或二次開發(fā)。資源包共 57 個(gè)文件約 15.21MB以 cs 源碼、dcm 樣例影像、txt 說明、jpg 截圖、csproj 工程文件為主另含 docx/doc 文檔、uml 圖、dll 庫、sln 解決方案及 pdf 一致性聲明覆蓋 PrintSCU、PrintSCP 服務(wù)、公共庫與示例 Demo 等模塊。已有 598 人學(xué)習(xí)下載。讀者可從中獲取圖像解析、膠片布局設(shè)置、尺寸調(diào)整、質(zhì)量控制、元數(shù)據(jù)處理、預(yù)覽與批處理等完整實(shí)現(xiàn)思路并借助樣例 DICOM 文件與說明文檔快速理解打印工作流為定制化開發(fā)或排錯(cuò)提供參考。1. 從一臺(tái)老式激光相機(jī)說起DicomPrint-master 到底能干什么如果你在醫(yī)院 PACS 運(yùn)維或者影像設(shè)備對接的崗位上待過大概率遇到過這種場景一臺(tái)服役十年的老式激光相機(jī)只認(rèn) DICOM Print SCU 協(xié)議而新上的 PACS 系統(tǒng)只提供 DICOM Storage 和 Worklist 服務(wù)兩邊就是握不上手。找廠商升級(jí)報(bào)價(jià)夠買半臺(tái)新設(shè)備自己寫一個(gè)打印服務(wù)端又卡在 DIMSE 消息構(gòu)造和 N-CREATE/N-SET 的狀態(tài)機(jī)里出不來。DicomPrint-master 這個(gè)源碼包就是沖著這個(gè)場景來的——它用一套相對完整的 DICOM Print 服務(wù)端實(shí)現(xiàn)把 Film Session、Film Box、Image Box 三層管理模型跑通讓 PACS 或任意 SCU 端能把影像頁發(fā)過來再由它轉(zhuǎn)成可打印的位圖或 PDF 落到本地。這個(gè)包適合三類人一是做 PACS 集成、需要快速驗(yàn)證打印鏈路的工程師二是維護(hù)老舊影像設(shè)備、想用軟件方案替代專用打印機(jī)的運(yùn)維三是學(xué) DICOM 協(xié)議、想找一個(gè)能跑起來的 Print SCU/SCP 對照代碼的開發(fā)者。它不解決圖像后處理也不做排版美化核心價(jià)值就是把 DICOM Print 那套 SOP Class 的交互流程用可讀的代碼攤開給你看。下面我按“先跑通、再拆解、后避坑”的順序把這份源碼包從部署到調(diào)參到排錯(cuò)完整走一遍。2. 把 DicomPrint-master 跑起來環(huán)境、依賴與最小驗(yàn)證鏈路2.1 先看清目錄結(jié)構(gòu)和入口在哪拿到源碼包后別急著敲命令先花兩分鐘把目錄掃一遍。DicomPrint-master 的典型結(jié)構(gòu)是根目錄下分src、config、lib、scripts幾塊src里按 DIMSE 服務(wù)、SOP 類處理、打印渲染三層分包。入口通常是一個(gè)繼承自BasicServiceClassProvider或類似基類的 Print SCP 類它注冊了BasicFilmSessionSOPClass、BasicFilmBoxSOPClass、BasicGrayscaleImageBoxSOPClass這幾個(gè) UID。你要找的就是那個(gè)在main里啟動(dòng)DicomServer并綁定端口的文件常見命名是PrintSCP.java或DicomPrintServer.py取決于原始實(shí)現(xiàn)語言。確認(rèn)入口后再看config下的application.properties或dicom.properties里面會(huì)有 AE Title、端口、打印輸出目錄、默認(rèn)膠片尺寸這幾個(gè)關(guān)鍵項(xiàng)。這一步不做后面報(bào)錯(cuò)你連改哪個(gè)文件都不知道。2.2 依賴安裝與編譯JDK、DCM4CHE 與構(gòu)建工具這類 DICOM 打印服務(wù)端底層多半依賴 dcm4che 或 fo-dicom 這類庫來處理 PDU 和 DIMSE。以 Java 版為例你需要 JDK 8 或 11Maven 3.6 以上。先確認(rèn)pom.xml里 dcm4che 的版本常見是 5.x 系列它對應(yīng) DICOM 標(biāo)準(zhǔn) 2020 版左右。如果包內(nèi)自帶lib目錄放了 jar那就省去聯(lián)網(wǎng)拉依賴的麻煩直接把lib下所有 jar 加入 classpath 即可。編譯命令我一般這樣走# 進(jìn)入項(xiàng)目根目錄 cd DicomPrint-master # 如果有 Maven 包裝器優(yōu)先用它避免本機(jī) Maven 版本差異 ./mvnw clean package -DskipTests # 如果沒有包裝器用本機(jī) Maven mvn clean package -DskipTests # 編譯完成后target 目錄下會(huì)生成可執(zhí)行 jar 或 classes ls target/這里-DskipTests不是偷懶而是這類源碼包里的單元測試經(jīng)常依賴真實(shí) DICOM 節(jié)點(diǎn)沒配好測試環(huán)境會(huì)直接卡住編譯流程。編譯成功后target下應(yīng)該有一個(gè)dicomprint-*.jar或者classes目錄。如果報(bào)package org.dcm4che3 does not exist說明依賴沒拉全檢查pom.xml里的倉庫地址是否可達(dá)或者手動(dòng)把lib下的 jar 通過mvn install:install-file裝進(jìn)本地倉庫。2.3 配置 AE Title、端口與輸出目錄配置文件是跑通鏈路的關(guān)鍵。打開config/application.properties你會(huì)看到類似下面的條目# DICOM 服務(wù)端 AE TitleSCU 端必須與此一致才能關(guān)聯(lián) dicom.scp.aetitleDICOMPRINT # 監(jiān)聽端口1024 以下需要 root 權(quán)限建議用 11112 dicom.scp.port11112 # 打印輸出目錄Film Box 完成后生成的位圖或 PDF 落在這里 print.output.dir./output # 默認(rèn)膠片尺寸常見 8x10 或 14x17單位英寸 print.film.size14x17 # 每個(gè) Film Box 最大 Image Box 數(shù)量 print.max.imagebox20dicom.scp.aetitle必須和 SCU 端配置的 Called AE Title 完全一致大小寫敏感這是最常見的關(guān)聯(lián)失敗原因。print.output.dir建議用絕對路徑相對路徑在不同啟動(dòng)方式下解析結(jié)果不一樣容易找不到輸出文件。print.film.size要和實(shí)際打印機(jī)或后續(xù)排版邏輯匹配設(shè)錯(cuò)了會(huì)導(dǎo)致圖像被裁切或留白異常。改完配置后啟動(dòng)命令通常是java -jar target/dicomprint-*.jar --spring.config.locationconfig/application.properties如果包不是 Spring Boot 結(jié)構(gòu)那就用java -cp target/classes:lib/* com.xxx.PrintSCP這種形式具體主類名從入口文件里找。2.4 用 DCM4CHE 工具或 dcmtk 發(fā)一頁測試圖像服務(wù)端起來后別急著接 PACS先用命令行工具發(fā)一頁圖驗(yàn)證鏈路。dcmtk 的dcmsend或storescu可以模擬 SCU但打印 SOP Class 需要專門的printscu工具dcmtk 里對應(yīng)的是dcmpssnd或自己用echoscu先測關(guān)聯(lián)。更直接的辦法是用 dcm4che 的dcm4che-tool-printscu命令大致如下# 先測關(guān)聯(lián)確認(rèn) AE Title 和端口通 echoscu -v -aet TESTSCU -aec DICOMPRINT 127.0.0.1 11112 # 關(guān)聯(lián)成功后用 printscu 發(fā)送打印請求 printscu -v -aet TESTSCU -aec DICOMPRINT 127.0.0.1 11112 \ -f 14x17 -i ./test.dcmechoscu返回Association Accepted說明網(wǎng)絡(luò)層和 AE Title 沒問題。printscu執(zhí)行后會(huì)依次觸發(fā) N-CREATE Film Session、N-CREATE Film Box、N-SET Image Box、N-ACTION Print 這一串操作。如果服務(wù)端日志里能看到Film Session created、Image Box set、Print action received并且output目錄下出現(xiàn)了文件那最小鏈路就算通了。這一步跑不通后面所有調(diào)參都是空談。3. 拆開 DICOM Print 狀態(tài)機(jī)Film Session、Film Box 與 Image Box 怎么串3.1 三層管理模型與 SOP Class UID 對照DICOM Print 管理模型是三層嵌套一個(gè) Film Session 下掛多個(gè) Film Box一個(gè) Film Box 下掛多個(gè) Image Box。每個(gè)層級(jí)對應(yīng)一個(gè) SOP ClassSCU 通過 N-CREATE 創(chuàng)建上層實(shí)例拿到 UID 后再創(chuàng)建下層。源碼里處理這套邏輯的地方通常在PrintService或FilmSessionHandler類中。關(guān)鍵 UID 如下表層級(jí)SOP Class 名稱UID 后綴Film SessionBasic Film Session1.2.840.10008.5.1.1.1Film BoxBasic Film Box1.2.840.10008.5.1.1.2Image BoxBasic Grayscale Image Box1.2.840.10008.5.1.1.4Image BoxBasic Color Image Box1.2.840.10008.5.1.1.4.1源碼里如果只實(shí)現(xiàn)了 Grayscale Image Box那彩色圖像發(fā)過來會(huì)直接被拒。檢查supportedSOPClasses列表里有沒有注冊 Color Image Box沒有的話要么補(bǔ)上要么在 SCU 端強(qiáng)制轉(zhuǎn)灰度。Film Box 創(chuàng)建時(shí)會(huì)帶一批屬性Film Size ID、Magnification Type、Smoothing Type、Border Density、Trim、Configuration Information。這些屬性決定了后續(xù) Image Box 怎么排布源碼里一般有個(gè)FilmBoxAttributeHandler來解析它們。3.2 N-CREATE 與 N-SET 的消息構(gòu)造細(xì)節(jié)N-CREATE 請求里SCU 會(huì)帶一個(gè) Attribute List服務(wù)端解析后返回一個(gè)帶新 UID 的響應(yīng)。源碼里構(gòu)造響應(yīng)的代碼通常長這樣// 創(chuàng)建 Film Session 響應(yīng)分配 UID 并回填屬性 Attributes filmSession new Attributes(); filmSession.setString(Tag.SOPInstanceUID, VR.UI, UIDUtils.createUID()); filmSession.setString(Tag.SOPClassUID, VR.UI, UID.BasicFilmSessionSOPClass); filmSession.setInt(Tag.NumberOfCopies, VR.IS, 1); filmSession.setString(Tag.PrintPriority, VR.CS, MED); // 構(gòu)造 N-CREATE 響應(yīng) DimseRSP rsp new DimseRSP(CommandStatus.Success, filmSession);UIDUtils.createUID()生成的是根為1.2.840.10008的實(shí)例 UID必須全局唯一否則 SCU 端可能拒絕后續(xù) N-SET。NumberOfCopies控制打印份數(shù)PrintPriority影響隊(duì)列調(diào)度這些屬性在源碼里如果寫死實(shí)際使用時(shí)會(huì)不夠靈活建議改成從配置讀。N-SET 用于往 Image Box 里塞像素?cái)?shù)據(jù)請求里帶PixelData和PhotometricInterpretation服務(wù)端收到后要按 Film Box 的排版參數(shù)把圖像縮放、旋轉(zhuǎn)、拼接到膠片畫布上。這一步的渲染邏輯是源碼里最值得細(xì)看的部分通常涉及BufferedImage的Graphics2D操作。3.3 打印觸發(fā)與輸出文件生成所有 Image Box 都 N-SET 完成后SCU 發(fā) N-ACTION 請求Action Type ID 為 1表示 Print。服務(wù)端收到后要把當(dāng)前 Film Box 對應(yīng)的畫布落盤。源碼里一般有個(gè)PrintActionHandler核心邏輯是// 收到 N-ACTION Print 后把 Film Box 畫布輸出為 PNG 或 PDF public void onPrintAction(String filmBoxUID) { FilmBox box filmBoxMap.get(filmBoxUID); BufferedImage canvas box.getCanvas(); File output new File(outputDir, filmBoxUID .png); ImageIO.write(canvas, png, output); // 如果配置了 PDF 輸出再走一遍 PDF 渲染 if (pdfEnabled) { PDFRenderer.render(canvas, new File(outputDir, filmBoxUID .pdf)); } }filmBoxUID作為文件名可以避免并發(fā)打印時(shí)互相覆蓋。如果源碼里用的是時(shí)間戳高并發(fā)下同一秒內(nèi)多個(gè) Film Box 會(huì)撞名這是實(shí)際部署中容易翻車的地方。輸出格式支持 PNG 還是 PDF取決于源碼里引了哪些庫常見的是ImageIO加pdfbox。落盤后你可以用ls -lh output/確認(rèn)文件大小是否合理一張 14x17 的灰度膠片PNG 大概在 2 到 5 MB太小說明畫布沒畫上東西。4. 避坑與排查關(guān)聯(lián)失敗、圖像錯(cuò)位、內(nèi)存泄漏這三類問題最要命4.1 關(guān)聯(lián)被拒AE Title 大小寫與 PDU 長度協(xié)商現(xiàn)象是echoscu返回Association Rejected日志里寫Called AE Title not recognized。原因通常是 SCU 端配的 Called AE Title 和服務(wù)端dicom.scp.aetitle不一致或者服務(wù)端啟動(dòng)時(shí)讀的配置文件不是你以為的那個(gè)。解決方法是先用netstat -tlnp | grep 11112確認(rèn)端口在聽再用echoscu -aec逐個(gè)試大小寫組合。另一個(gè)隱蔽原因是 PDU 長度協(xié)商老設(shè)備可能只支持 16KB而服務(wù)端默認(rèn) 64KB需要在配置里把dicom.max.pdu.length調(diào)到 16384。4.2 圖像錯(cuò)位或裁切Film Size 與 Magnification Type 不匹配現(xiàn)象是輸出的膠片上圖像偏到一角或者邊緣被切掉。原因是 Film Box 創(chuàng)建時(shí) SCU 傳的 Film Size ID 是14x17而服務(wù)端配置的默認(rèn)畫布是8x10渲染時(shí)按小畫布裁剪導(dǎo)致。解決方法是讓服務(wù)端以 SCU 傳入的 Film Size ID 為準(zhǔn)動(dòng)態(tài)創(chuàng)建畫布而不是用固定配置。源碼里如果寫死了畫布尺寸找到createCanvas方法把尺寸參數(shù)改成從 Film Box 屬性讀取。Magnification Type 設(shè)為REPLICATE時(shí)圖像不縮放直接平鋪設(shè)為BILINEAR才做插值縮放設(shè)錯(cuò)了也會(huì)導(dǎo)致視覺上的錯(cuò)位。4.3 內(nèi)存泄漏Film Box 對象沒釋放導(dǎo)致 OOM現(xiàn)象是服務(wù)跑幾天后OutOfMemoryError堆轉(zhuǎn)儲(chǔ)里全是FilmBox和BufferedImage對象。原因是 N-ACTION Print 完成后filmBoxMap里的條目沒移除畫布 BufferedImage 一直占著內(nèi)存。解決方法是打印完成后立即filmBoxMap.remove(filmBoxUID)并把畫布引用置空。如果源碼里用靜態(tài) Map 存 Film Box那泄漏是必然的改成ConcurrentHashMap并在 finally 塊里清理。另外Image Box 的像素?cái)?shù)據(jù)在 N-SET 后如果沒及時(shí)釋放也會(huì)累積檢查imageBoxMap的清理邏輯。4.4 并發(fā)打印時(shí)文件覆蓋與 UID 沖突現(xiàn)象是兩臺(tái) SCU 同時(shí)打印輸出目錄里只有一個(gè)文件另一個(gè)被覆蓋。原因是文件名用了固定前綴加序號(hào)序號(hào)在并發(fā)下重復(fù)。解決方法是文件名直接用 Film Box 的 SOP Instance UID這個(gè) UID 全局唯一不會(huì)撞。如果源碼里用System.currentTimeMillis()做文件名同一毫秒內(nèi)兩個(gè)請求就會(huì)覆蓋改成 UID 或加隨機(jī)后綴。UID 沖突還可能導(dǎo)致 SCU 端 N-SET 找不到對應(yīng)的 Image Box日志里會(huì)出現(xiàn)Unknown SOP Instance UID這時(shí)候要檢查 UID 生成邏輯是否線程安全。4.5 中文路徑與編碼問題導(dǎo)致輸出失敗現(xiàn)象是print.output.dir設(shè)成含中文的路徑后文件寫不出來日志報(bào)FileNotFoundException。原因是 JVM 默認(rèn)編碼和文件系統(tǒng)編碼不一致尤其在 Windows 上。解決方法是在啟動(dòng)命令里加-Dfile.encodingUTF-8并且路徑盡量用英文。如果必須用中文路徑用Paths.get(dir, filename)代替字符串拼接讓 NIO 處理編碼。這個(gè)坑在測試環(huán)境用英文路徑時(shí)不會(huì)暴露一上生產(chǎn)就翻車血淚經(jīng)驗(yàn)是部署前先用中文路徑跑一遍。5. 進(jìn)階把打印輸出接到實(shí)際工作流與自動(dòng)化驗(yàn)證5.1 用 DCM4CHE 的 printscu 做回歸測試每次改完源碼別手動(dòng)發(fā)圖驗(yàn)證寫一個(gè) shell 腳本把printscu調(diào)用包起來跑完檢查輸出目錄文件數(shù)和大小。腳本大概這樣#!/bin/bash # 回歸測試發(fā)一頁圖檢查輸出文件是否生成且大小合理 OUTPUT_DIR./output rm -f $OUTPUT_DIR/*.png printscu -v -aet TESTSCU -aec DICOMPRINT 127.0.0.1 11112 \ -f 14x17 -i ./test.dcm # 檢查是否生成了文件 FILE_COUNT$(ls $OUTPUT_DIR/*.png 2/dev/null | wc -l) if [ $FILE_COUNT -ne 1 ]; then echo FAIL: expected 1 output file, got $FILE_COUNT exit 1 fi # 檢查文件大小是否在合理范圍2MB 到 10MB FILE_SIZE$(stat -c%s $OUTPUT_DIR/*.png) if [ $FILE_SIZE -lt 2000000 ] || [ $FILE_SIZE -gt 10000000 ]; then echo FAIL: output file size $FILE_SIZE out of range exit 1 fi echo PASS這個(gè)腳本能擋住大部分低級(jí)錯(cuò)誤沒輸出、輸出為空、輸出被裁切導(dǎo)致文件過小。把它掛到 CI 里每次提交自動(dòng)跑一遍比人工點(diǎn)強(qiáng)得多。5.2 把輸出 PDF 接入 PACS 歸檔或本地打印隊(duì)列生成的 PDF 如果只是躺在output目錄里價(jià)值有限。常見做法是寫一個(gè)監(jiān)聽器用WatchService監(jiān)控目錄新文件一出現(xiàn)就調(diào)lp或lpr送到本地打印隊(duì)列或者用storescu把 PDF 轉(zhuǎn)成 Secondary Capture 存回 PACS。下面是一個(gè)簡單的文件監(jiān)聽片段// 監(jiān)控輸出目錄新 PDF 出現(xiàn)后送到打印隊(duì)列 WatchService watchService FileSystems.getDefault().newWatchService(); Paths.get(outputDir).register(watchService, StandardWatchEventKinds.ENTRY_CREATE); while (true) { WatchKey key watchService.take(); for (WatchEvent? event : key.pollEvents()) { Path newFile outputDir.resolve((Path) event.context()); if (newFile.toString().endsWith(.pdf)) { // 調(diào)用系統(tǒng)打印命令注意路徑空格轉(zhuǎn)義 Runtime.getRuntime().exec(new String[]{lp, -d, printer1, newFile.toString()}); } } key.reset(); }lp -d printer1里的printer1要換成實(shí)際隊(duì)列名用lpstat -p查。如果打印隊(duì)列在遠(yuǎn)程把lp換成lpr -H remotehost。這個(gè)監(jiān)聽器要處理文件寫入未完成的情況PDF 可能還在寫就被監(jiān)聽到了加一個(gè)Thread.sleep(500)或者檢查文件鎖。5.3 參數(shù)調(diào)優(yōu)并發(fā)數(shù)、超時(shí)與日志級(jí)別生產(chǎn)環(huán)境要把dicom.scp.max.associations調(diào)到 10 以上否則多個(gè) SCU 同時(shí)連會(huì)被拒。dicom.scp.idle.timeout設(shè) 300 秒避免空閑關(guān)聯(lián)一直占著。日志級(jí)別從 DEBUG 調(diào)到 INFO不然高頻打印時(shí)日志文件一天能漲幾個(gè) GB。如果源碼里用的是 log4j 或 logback改配置文件里的root level即可。調(diào)完這些參數(shù)后用ab或jmeter模擬 5 個(gè)并發(fā) SCU 同時(shí)發(fā)打印請求觀察內(nèi)存和輸出文件是否正常。我自己的習(xí)慣是每次改完配置先用echoscu測關(guān)聯(lián)再用printscu發(fā)一頁最后看輸出目錄和日志三步都過了才認(rèn)為這次改動(dòng)是安全的。從那以后我每次部署 DicomPrint 到新環(huán)境都強(qiáng)制走一遍這個(gè)三步驗(yàn)證沒再出現(xiàn)過上線才發(fā)現(xiàn)關(guān)聯(lián)不上的情況。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取