簡(jiǎn)介這份源碼資源面向具備一定 Vue3 與前端工程基礎(chǔ)的開(kāi)發(fā)者聚焦醫(yī)療影像 Web 可視化場(chǎng)景提供一套基于 cornerstone3D 的 DICOM 影像瀏覽器完整實(shí)現(xiàn)。項(xiàng)目以 Vue3 單頁(yè)應(yīng)用為骨架結(jié)合 cornerstone3D 完成醫(yī)學(xué)影像的渲染與交互并配套 HTTP 請(qǐng)求封裝、Vite 構(gòu)建配置、npm 依賴鎖定、Prettier 代碼格式化規(guī)則及版權(quán)聲明等工程化文件便于讀者理解從依賴管理到界面渲染的完整鏈路。壓縮包共 137 個(gè)文件以 56 個(gè) js 邏輯腳本、28 個(gè) vue 組件、27 個(gè) png 與 13 個(gè) jpg 圖像資源為主另含 svg、json、scss、html 等配置與樣式文件整體約 800KB目錄結(jié)構(gòu)清晰方便按模塊查閱。目前已有 812 人學(xué)習(xí)關(guān)注。通過(guò)研讀源碼讀者可掌握 DICOM 影像加載、窗寬窗位與色彩映射等關(guān)鍵實(shí)現(xiàn)思路并借鑒其工程組織方式快速搭建自己的醫(yī)療影像瀏覽環(huán)境。1. 從零讀懂 cornerstone3DDICOM 影像瀏覽器到底在瀏覽器里跑什么如果你在醫(yī)療影像或前端可視化方向待過(guò)大概率聽(tīng)過(guò) cornerstone3D 這個(gè)名字。它是一套完全跑在瀏覽器里的醫(yī)學(xué)影像渲染引擎核心能力是把 DICOM 格式的 CT、MR、超聲等序列通過(guò) WebGL 在 Canvas 上重建出可交互的斷層圖像。和傳統(tǒng)做法——后端渲染成圖片再傳給前端——相比cornerstone3D 把渲染壓力放到了客戶端換來(lái)的是實(shí)時(shí)窗寬窗位調(diào)節(jié)、任意層厚重建、MPR 多平面重建這些以前只有桌面工作站才敢想的功能。這套源碼值得啃的原因很直接它是目前開(kāi)源生態(tài)里少數(shù)把 DICOM 解析、GPU 紋理管理、工具交互三層都做完整的項(xiàng)目。你拿到源碼后能做的事包括搭一個(gè)私有化閱片器、在自有 PACS 數(shù)據(jù)上做 AI 標(biāo)注前端、給科研團(tuán)隊(duì)做影像組學(xué)預(yù)處理界面。適合有 JavaScript/TypeScript 基礎(chǔ)、了解一點(diǎn) WebGL 概念、手頭有 DICOM 數(shù)據(jù)或能拿到測(cè)試數(shù)據(jù)的開(kāi)發(fā)者。完全沒(méi)碰過(guò)醫(yī)學(xué)影像格式的人也能跟但需要先補(bǔ) DICOM 的坐標(biāo)系和像素編碼這兩塊常識(shí)。2. 環(huán)境搭建與最小可運(yùn)行 Demo把第一張 CT 圖渲染出來(lái)2.1 依賴選型為什么是 cornerstone3D 而不是老版 cornerstone老版 cornerstonecornerstone-core基于 Canvas 2D 做像素級(jí)繪制處理單幀圖像夠用但遇到體數(shù)據(jù)volume就力不從心——它沒(méi)有真正的 3D 紋理概念MPR 重建要靠 CPU 逐層拼幀率掉得厲害。cornerstone3D 換成了 WebGL 自定義渲染管線把整個(gè)序列當(dāng)作一個(gè) 3D 紋理上傳到 GPU切片切換只是改一下采樣平面性能差距在 512×512×300 的 CT 序列上能到十倍以上。選型時(shí)還要注意生態(tài)配套。cornerstone3D 把功能拆成了多個(gè)包c(diǎn)ornerstonejs/core負(fù)責(zé)渲染引擎和體積管理cornerstonejs/tools提供窗寬窗位、縮放、平移、測(cè)量等交互工具cornerstonejs/dicom-image-loader處理 DICOM 文件的解析和傳輸。這種拆分的好處是按需引入壞處是版本對(duì)齊容易翻車(chē)——core 和 tools 的 minor 版本不匹配時(shí)工具注冊(cè)會(huì)靜默失敗控制臺(tái)不報(bào)錯(cuò)但鼠標(biāo)拖拽沒(méi)反應(yīng)。我一般會(huì)鎖死三個(gè)包的版本號(hào)一致升級(jí)時(shí)一起升。2.2 最小渲染流程從 DICOM 文件到 Canvas 上的圖像下面這段代碼是一個(gè)最小可運(yùn)行示例假設(shè)你已經(jīng)用 Vite 或 Webpack 起了一個(gè)前端工程并且本地有一個(gè) DICOM 文件目錄可以通過(guò) HTTP 訪問(wèn)。// 引入核心包 import * as cornerstone from cornerstonejs/core; import * as cornerstoneTools from cornerstonejs/tools; import dicomImageLoader from cornerstonejs/dicom-image-loader; // 初始化渲染引擎指定渲染后端為 WebGL await cornerstone.init(); // 注冊(cè) DICOM 圖像加載器告訴引擎怎么解析 .dcm 文件 dicomImageLoader.external.cornerstone cornerstone; dicomImageLoader.external.dicomParser dicomParser; // 需要額外安裝 dicom-parser // 配置圖像加載器的工作路徑指向 dicom-image-loader 的 web worker dicomImageLoader.configure({ useWebWorkers: true, decodeConfig: { convertFloatPixelDataToInt: false, // CT 的 HU 值可能是負(fù)數(shù)不要強(qiáng)制轉(zhuǎn) int }, }); // 創(chuàng)建一個(gè)渲染引擎實(shí)例綁定到頁(yè)面上的 div 容器 const element document.getElementById(viewport); const renderingEngine new cornerstone.RenderingEngine(myEngine); renderingEngine.enableElement({ viewportId: ctViewport, type: cornerstone.Enums.ViewportType.STACK, // 先用 STACK 模式看單幀 element, defaultOptions: { background: [0, 0, 0], // 黑色背景符合閱片習(xí)慣 }, }); // 構(gòu)造圖像 ID 列表cornerstone 用 URL scheme 定位圖像 const imageIds [ dicomweb:http://localhost:3000/data/ct/slice001.dcm, dicomweb:http://localhost:3000/data/ct/slice002.dcm, // ... 更多切片 ]; // 獲取 viewport 并設(shè)置圖像 const viewport renderingEngine.getViewport(ctViewport); await viewport.setStack(imageIds, 0); // 第二個(gè)參數(shù)是初始幀索引 viewport.render();這段代碼的邏輯鏈條是初始化引擎 → 注冊(cè)加載器 → 創(chuàng)建渲染引擎實(shí)例 → 綁定 DOM 容器 → 構(gòu)造圖像 ID → 設(shè)置數(shù)據(jù) → 渲染。每一步都有坑。cornerstone.init()必須在所有其他操作之前調(diào)用否則后續(xù)的RenderingEngine構(gòu)造函數(shù)會(huì)拋錯(cuò)。dicomImageLoader.external.cornerstone這行賦值不能漏加載器內(nèi)部會(huì)通過(guò)這個(gè)引用回調(diào)核心包的 API。useWebWorkers: true在開(kāi)發(fā)環(huán)境可能因?yàn)榭缬騿?wèn)題加載不了 worker 腳本可以先設(shè)成false排查確認(rèn)流程通了再開(kāi)。2.3 關(guān)鍵參數(shù)窗寬窗位與像素值映射DICOM 圖像里存的不是直接的灰度值而是原始像素值加上一組映射參數(shù)。CT 的像素值經(jīng)過(guò) Rescale Slope 和 Rescale Intercept 變換后得到 HU 值Hounsfield Unit再通過(guò)窗寬窗位映射到 0-255 的顯示灰度。cornerstone3D 默認(rèn)會(huì)自動(dòng)讀取 DICOM 標(biāo)簽里的這些參數(shù)但你可以手動(dòng)覆蓋。// 手動(dòng)設(shè)置窗寬窗位適用于自動(dòng)映射效果不理想的場(chǎng)景 const viewport renderingEngine.getViewport(ctViewport); viewport.setProperties({ voiRange: { lower: -1000, // 窗下限對(duì)應(yīng)空氣 upper: 1000, // 窗上限對(duì)應(yīng)骨骼 }, }); viewport.render();voiRange的 lower 和 upper 直接決定對(duì)比度。看肺窗時(shí)設(shè)[-1350, 150]看縱隔窗設(shè)[-150, 250]看骨窗設(shè)[200, 3000]。這些數(shù)值不是玄學(xué)是放射科多年積累的共識(shí)。如果你發(fā)現(xiàn)圖像全黑或全白先檢查voiRange是不是設(shè)反了或者范圍太窄。3. 從 STACK 到 VOLUME多序列加載與 MPR 重建的實(shí)操路徑3.1 為什么必須切到 VOLUME 模式STACK 模式一次只加載一幀適合快速預(yù)覽但做不了 MPR。VOLUME 模式會(huì)把整個(gè)序列當(dāng)作一個(gè) 3D 體數(shù)據(jù)上傳到 GPU之后你可以從任意角度切面。代價(jià)是內(nèi)存占用——一個(gè) 512×512×500 的 16 位 CT 序列大約占 256MB 顯存集成顯卡上可能直接崩。我一般會(huì)在加載前先估算體積大小超過(guò) 400MB 的序列做降采樣或者分塊加載。// 切換到 VOLUME 模式 renderingEngine.enableElement({ viewportId: volumeViewport, type: cornerstone.Enums.ViewportType.ORTHOGRAPHIC, // 正交投影適合 MPR element: document.getElementById(volumeViewport), defaultOptions: { orientation: cornerstone.Enums.OrientationAxis.AXIAL, // 初始為軸位 }, }); // 構(gòu)造 volume 對(duì)象 const volume await cornerstone.volumeLoader.createAndCacheVolume(myVolume, { imageIds, }); // 加載 volume 數(shù)據(jù)到 GPU await volume.load(); // 將 volume 設(shè)置到 viewport const viewport renderingEngine.getViewport(volumeViewport); await viewport.setVolumes([{ volumeId: myVolume }]); viewport.render();createAndCacheVolume是異步的必須等volume.load()完成后再調(diào)setVolumes否則渲染出來(lái)是空白。OrientationAxis有三個(gè)值A(chǔ)XIAL軸位、SAGITTAL矢狀位、CORONAL冠狀位。實(shí)際閱片界面通常同時(shí)開(kāi)三個(gè) viewport每個(gè)設(shè)不同 orientation共享同一個(gè) volume。3.2 MPR 重建的坐標(biāo)系與切片定位MPR 的核心是定義一個(gè)切割平面然后從 3D 紋理里采樣出這個(gè)平面上的像素。cornerstone3D 用camera對(duì)象描述這個(gè)平面位置focalPoint、方向viewPlaneNormal、上方向viewUp。改這三個(gè)參數(shù)就能實(shí)現(xiàn)任意斜切。// 獲取當(dāng)前 camera 并修改實(shí)現(xiàn)斜位重建 const camera viewport.getCamera(); viewport.setCamera({ ...camera, focalPoint: [100, 200, 50], // 切割平面經(jīng)過(guò)的世界坐標(biāo)點(diǎn) viewPlaneNormal: [0.707, 0.707, 0], // 45 度斜切 viewUp: [0, 0, 1], }); viewport.render();世界坐標(biāo)系的單位是毫米原點(diǎn)在序列的第一幀左上角。focalPoint決定切面位置viewPlaneNormal決定切面朝向。這兩個(gè)參數(shù)配合不好會(huì)出現(xiàn)切面在體積外面渲染結(jié)果全黑。調(diào)試時(shí)可以先打印 volume 的dimensions和spacing確認(rèn)坐標(biāo)范圍。3.3 多序列融合顯示CT 與 PET 的配準(zhǔn)疊加臨床場(chǎng)景經(jīng)常需要把 PET 的功能代謝信息疊加到 CT 的解剖結(jié)構(gòu)上。cornerstone3D 支持在同一個(gè) viewport 里加載多個(gè) volume通過(guò)blendMode控制混合方式。// 加載第二個(gè) volumePET const petVolume await cornerstone.volumeLoader.createAndCacheVolume(petVolume, { imageIds: petImageIds, }); await petVolume.load(); // 同時(shí)設(shè)置兩個(gè) volumeCT 作為底圖PET 作為疊加層 await viewport.setVolumes([ { volumeId: myVolume, blendMode: cornerstone.Enums.BlendModes.COMPOSITE }, { volumeId: petVolume, blendMode: cornerstone.Enums.BlendModes.COMPOSITE }, ]); // 調(diào)整疊加層的透明度和顏色映射 viewport.setProperties({ colormap: { name: hot, // PET 常用熱力圖配色 opacity: 0.4, }, }); viewport.render();BlendModes.COMPOSITE是標(biāo)準(zhǔn)的 alpha 混合適合 PET/CT。如果做的是同模態(tài)的對(duì)比比如兩次 CT 掃描可以用BlendModes.AVERAGE或者BlendModes.DIFFERENCE。注意兩個(gè) volume 的坐標(biāo)系必須對(duì)齊否則疊加出來(lái)是錯(cuò)位的。實(shí)際項(xiàng)目中配準(zhǔn)這一步通常在服務(wù)端做完前端拿到的已經(jīng)是同一坐標(biāo)系下的數(shù)據(jù)。4. 工具鏈集成測(cè)量、標(biāo)注與交互的避坑指南4.1 工具注冊(cè)的正確順序cornerstone3D 的工具系統(tǒng)是插件式的每個(gè)工具長(zhǎng)度測(cè)量、角度測(cè)量、ROI 勾畫(huà)都需要先注冊(cè)再激活。順序錯(cuò)了工具不生效而且不報(bào)錯(cuò)。// 先添加工具到全局工具組 cornerstoneTools.addTool(cornerstoneTools.LengthTool); cornerstoneTools.addTool(cornerstoneTools.AngleTool); cornerstoneTools.addTool(cornerstoneTools.RectangleROITool); // 再創(chuàng)建工具組并激活 const toolGroup cornerstoneTools.ToolGroupManager.createToolGroup(myToolGroup); toolGroup.addTool(cornerstoneTools.LengthTool.toolName); toolGroup.addTool(cornerstoneTools.AngleTool.toolName); toolGroup.addTool(cornerstoneTools.RectangleROITool.toolName); // 設(shè)置工具的鼠標(biāo)綁定 toolGroup.setToolActive(cornerstoneTools.LengthTool.toolName, { bindings: [{ mouseButton: cornerstoneTools.Enums.MouseBindings.Primary }], }); toolGroup.setToolActive(cornerstoneTools.AngleTool.toolName, { bindings: [{ mouseButton: cornerstoneTools.Enums.MouseBindings.Secondary }], }); // 最后把工具組綁定到 viewport toolGroup.addViewport(volumeViewport, myEngine);addTool是全局注冊(cè)addTool到 toolGroup 是局部啟用。兩步都做完才能用。setToolActive的 bindings 里Primary 是左鍵Secondary 是右鍵Auxiliary 是中鍵。如果工具沒(méi)反應(yīng)先檢查addViewport的第二個(gè)參數(shù)是不是渲染引擎的 id這個(gè) id 在new RenderingEngine(myEngine)時(shí)指定寫(xiě)錯(cuò)了工具組找不到 viewport。4.2 標(biāo)注數(shù)據(jù)的持久化工具畫(huà)出來(lái)的標(biāo)注默認(rèn)存在內(nèi)存里刷新頁(yè)面就沒(méi)了。要持久化需要監(jiān)聽(tīng)標(biāo)注的添加和修改事件把數(shù)據(jù)序列化后存到后端。// 監(jiān)聽(tīng)標(biāo)注添加事件 element.addEventListener(cornerstoneTools.Enums.Events.ANNOTATION_ADDED, (event) { const annotation event.detail.annotation; const serialized { toolName: annotation.metadata.toolName, data: annotation.data, // 包含坐標(biāo)、測(cè)量值等 frameIndex: annotation.metadata.frameIndex, }; // 發(fā)送到后端保存 fetch(/api/annotations, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(serialized), }); });annotation.data的結(jié)構(gòu)因工具而異。長(zhǎng)度測(cè)量存的是兩個(gè)端點(diǎn)坐標(biāo)ROI 存的是多邊形頂點(diǎn)數(shù)組。恢復(fù)時(shí)用cornerstoneTools.annotation.state.addAnnotation把數(shù)據(jù)塞回去。注意坐標(biāo)系是圖像坐標(biāo)還是世界坐標(biāo)跨序列恢復(fù)時(shí)要做轉(zhuǎn)換。4.3 性能優(yōu)化大序列下的幀率保持當(dāng)序列超過(guò) 500 幀或者同時(shí)開(kāi)多個(gè) viewport 時(shí)幀率會(huì)明顯下降。幾個(gè)有效的優(yōu)化手段一是開(kāi)useWebWorkers把 DICOM 解析放到 worker 線程二是對(duì)不需要實(shí)時(shí)交互的 viewport 降低渲染頻率用requestAnimationFrame做節(jié)流三是用cornerstone.setUseCPURendering(false)確保走 GPU 路徑。// 節(jié)流渲染非活動(dòng) viewport 每 100ms 渲染一次 let lastRenderTime 0; function throttledRender(viewport, interval 100) { const now performance.now(); if (now - lastRenderTime interval) { viewport.render(); lastRenderTime now; } }如果顯存不夠可以在加載 volume 時(shí)指定targetBuffer為Uint8Array而不是默認(rèn)的Float32Array精度損失在肉眼可接受范圍內(nèi)內(nèi)存占用減半。5. 常見(jiàn)問(wèn)題排查從黑屏到工具失效的 5 個(gè)血淚坑現(xiàn)象一Canvas 全黑控制臺(tái)無(wú)報(bào)錯(cuò)。原因通常是voiRange設(shè)反了或者 DICOM 的 Rescale 參數(shù)沒(méi)讀到。解決方法是先打印viewport.getProperties()看voiRange的實(shí)際值再檢查 DICOM 文件的RescaleSlope和RescaleIntercept標(biāo)簽是否存在。有些設(shè)備導(dǎo)出的文件這兩個(gè)標(biāo)簽是空的需要手動(dòng)設(shè)默認(rèn)值?，F(xiàn)象二工具畫(huà)不出標(biāo)注鼠標(biāo)拖拽沒(méi)反應(yīng)。九成是工具組沒(méi)綁定到 viewport。檢查toolGroup.addViewport的第二個(gè)參數(shù)和new RenderingEngine的參數(shù)是否一致。另一個(gè)可能是setToolActive的 bindings 被其他工具覆蓋了用toolGroup.getActiveTools()看當(dāng)前激活了哪些?，F(xiàn)象三MPR 切面全黑或顯示錯(cuò)位。先確認(rèn) volume 的spacing是否正確。如果 DICOM 里PixelSpacing和SliceThickness缺失cornerstone 會(huì)用默認(rèn)值 1mm導(dǎo)致切面位置算錯(cuò)。手動(dòng)構(gòu)造 volume 時(shí)傳入正確的 spacing 可以解決。現(xiàn)象四多序列疊加時(shí)顏色異常。PET 的像素值范圍通常遠(yuǎn)大于 CT直接疊加會(huì)被 CT 的窗寬窗位壓制。需要單獨(dú)給 PET 設(shè)voiRange或者用colormap做偽彩色映射。另外檢查兩個(gè) volume 的direction矩陣是否一致不一致說(shuō)明坐標(biāo)系沒(méi)對(duì)齊?，F(xiàn)象五內(nèi)存泄漏長(zhǎng)時(shí)間使用后瀏覽器崩潰。cornerstone3D 的 volume 緩存不會(huì)自動(dòng)釋放。切換序列時(shí)要手動(dòng)調(diào)cornerstone.cache.removeVolumeLoadObject(volumeId)清理舊數(shù)據(jù)。工具組的標(biāo)注數(shù)據(jù)也要在序列切換時(shí)清空否則會(huì)越積越多。6. 進(jìn)階技巧用自定義 Shader 實(shí)現(xiàn)偽彩與邊緣增強(qiáng)cornerstone3D 的渲染管線允許替換片元著色器這意味著你可以在 GPU 上做像素級(jí)的后處理。一個(gè)實(shí)用場(chǎng)景是給灰度 CT 疊加偽彩色讓不同密度組織區(qū)分更明顯。下面是一個(gè)簡(jiǎn)化的自定義 shader 示例實(shí)現(xiàn)基于 HU 值的三色映射。// 片元著色器根據(jù)像素強(qiáng)度映射到偽彩色 precision highp float; uniform sampler2D u_texture; uniform float u_windowCenter; uniform float u_windowWidth; varying vec2 v_texCoord; void main() { vec4 pixel texture2D(u_texture, v_texCoord); float hu pixel.r * 65535.0 - 1024.0; // 還原 HU 值 float lower u_windowCenter - u_windowWidth / 2.0; float upper u_windowCenter u_windowWidth / 2.0; float normalized clamp((hu - lower) / (upper - lower), 0.0, 1.0); // 三色映射低密度偏藍(lán)中等密度偏綠高密度偏紅 vec3 color; if (normalized 0.33) { color mix(vec3(0.0, 0.0, 1.0), vec3(0.0, 1.0, 0.0), normalized * 3.0); } else if (normalized 0.66) { color mix(vec3(0.0, 1.0, 0.0), vec3(1.0, 1.0, 0.0), (normalized - 0.33) * 3.0); } else { color mix(vec3(1.0, 1.0, 0.0), vec3(1.0, 0.0, 0.0), (normalized - 0.66) * 3.0); } gl_FragColor vec4(color, 1.0); }這個(gè) shader 的核心邏輯是把窗寬窗位歸一化后的值映射到一條藍(lán)-綠-黃-紅的漸變帶上。實(shí)際使用時(shí)需要把 shader 編譯成 WebGL program替換 cornerstone 默認(rèn)的渲染 pass。cornerstone3D 提供了registerShader接口但文檔不多我當(dāng)初是直接讀源碼里Shader類的實(shí)現(xiàn)才搞明白怎么掛上去的。另一個(gè)進(jìn)階方向是邊緣增強(qiáng)用 Sobel 算子對(duì)切片做卷積突出骨骼和血管的邊界。這個(gè)在 GPU 上做比 CPU 快得多但要注意卷積核大小和紋理采樣次數(shù)的平衡3×3 的核已經(jīng)夠用5×5 以上幀率會(huì)明顯下降。驗(yàn)證自定義 shader 是否生效最直接的方法是改一個(gè)極端參數(shù)看畫(huà)面有沒(méi)有變化。比如把u_windowWidth設(shè)成 1正常情況畫(huà)面應(yīng)該變成黑白二值圖。如果沒(méi)變化說(shuō)明 shader 沒(méi)編譯成功或者 uniform 沒(méi)傳進(jìn)去。檢查 WebGL 的getShaderInfoLog輸出編譯錯(cuò)誤都在那里。我自己的習(xí)慣是每接一個(gè)新序列先用默認(rèn)參數(shù)跑一遍截圖存底然后逐步調(diào)窗寬窗位和 shader 參數(shù)對(duì)比著看。醫(yī)學(xué)影像這東西肉眼判斷比任何指標(biāo)都可靠。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取