简介：基于 cornerstone3D 与 Vue3 的 DICOM 影像浏览器源码，定位为医疗影像领域的 Web 开发者参考项目，用于解决 DICOM 文件的加载、渲染与交互浏览需求。压缩包共含138个文件，以 JavaScript 和 Vue 组件作为主体，同时包含图片素材、JSON 配置、SCSS 样式、运行脚本及 Markdown 文档，整体大小仅 797KB，结构轻量清晰，便于下载后直接查阅代码与文档。代码中涵盖 HTTP 请求处理、Vite 开发服务器配置、npm 依赖管理脚本、Prettier 代码格式化规则，以及版权声明和使用说明，完整呈现从工程初始化到影像显示的关键链路。项目内附医院图像、多种色带映射图、三维模型等多样化测试数据，可以直观观察 Cornerstone3D 的渲染效果，并在此基础上继续开发窗宽窗位调节、测量标注、多平面重建等进阶功能。已有 132 人浏览学习，适合想入门医学影像可视化或进行二次开发的工程师。
1. 基于cornerstone3D的DICOM影像浏览器：源码要解决的不只是“看图”
医疗影像在浏览器里渲染，真正的瓶颈往往不在WebGL绘制，而在DICOM文件的获取路径和前端组件生命周期之间的配合。这套基于cornerstone3D的DICOM影像浏览器源码，把Vue3、Vite、httpdir.js和cornerstone3D串成了一条完整链路：Vue3管理界面状态，Vite处理开发调试与打包，httpdir.js把本地DICOM目录变成HTTP可访问的资源，cornerstone3D负责最终的图像渲染。对想快速接入影像浏览能力的全栈或前端开发者来说，这是一个可以直接照抄的参考实现。
不少人在找资源时看到“cornerstone3D”和“DICOM浏览器”这样的关键词就下载，但源码拿到手却不知道先看哪个文件。其实读源码的关键是先看出工程决策：为什么用Vite而不是Webpack，为什么单独保留httpdir.js而不直接交给后端，为什么附带多张colorscale_*.jpg。这些决策决定了排错的方向。下面按“工程骨架—数据链路—伪彩渲染—调优”四个部分拆开讲，最后给一个处理长序列时特别实用的内存回收技巧。
2. Vue3 + Vite + cornerstone3D 的项目骨架与模块划分
2.1 文件清单背后的工程决策
项目根目录里放着index.html、vite.config.js、package.json、.prettierrc，以及colorscale_rainbow.jpg这类资源。初看是纯前端演示，但文件分层其实很明确：index.html是SPA的HTML入口，Vue3的业务逻辑会挂载到它指定的容器上；vite.config.js控制构建策略和开发服务器；httpdir.js用Node暴露本地目录的HTTP访问入口，给cornerstone3D提供DICOM数据；jpg资源则是尚未转成colormap数组的调色板素材。这种划分的好处在于，医疗影像项目的后端接口不一定稳定，单独一个httpdir.js可以把“本地文件目录变成可浏览的DICOM资源”这件事隔离出来，后面要换成WADO服务也只需要改一层。
从源码工程角度看，各文件对应的职责可以整理成下表：
| 文件 | 承担职责 | 关键点 |
|---|---|---|
| index.html | SPA入口，加载Vue3挂载点 | 静态资源路径要能适配任意部署子路径 |
| vite.config.js | 构建配置、开发代理 | proxy将/dicom转发到httpdir.js |
| httpdir.js | 提供DICOM目录的HTTP访问 | 路径归一化，防止目录穿越 |
| package.json / package-lock.json | 依赖锁定与脚本管理 | npm ci保证版本一致 |
| .prettierrc | 代码格式化约束 | 多人协作下减少diff噪音 |
| colorscale_*.jpg | 伪彩调色板源图 | 运行时抽成LUT交给cornerstone3D |
这里最值得读的是httpdir.js和vite.config.js，它们决定了cornerstone3D拿到的imageId长什么样。如果只是把DICOM文件当作静态资源放在public目录下，浏览器虽然也能通过相对路径访问，但缺少明确的MIME类型和路径保护，遇到压缩格式或中文文件名时更容易出问题。
2.2 vite.config.js 里必须保留的配置项
与cornerstone3D配套使用时，Vite最需要关注两件事：依赖预构建和请求代理。cornerstone3D相关包以ESM形式发布，内部还会动态加载wasm或worker文件，如果混进默认的vite依赖优化，偶尔会出现模块路径错乱。我一般会在optimizeDeps里显式列出核心包，同时把dicom目录的请求代理到httpdir.js上，避免开发时反复处理CORS。下面是跟这套源码结构匹配的vite配置。
import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ base: './', plugins: [vue()], optimizeDeps: { include: [ '@cornerstonejs/core', '@cornerstonejs/tools', '@cornerstonejs/dicom-image-loader', 'dicom-parser' ] }, server: { port: 5173, proxy: { '/dicom': { target: 'http://localhost:8080', changeOrigin: true } } }, build: { rollupOptions: { output: { manualChunks: { cornerstone: ['@cornerstonejs/core', '@cornerstonejs/tools'] } } }, chunkSizeWarningLimit: 1500 } })这里的base设置为'./'，是因为该项目的页面可能被放到任意子路径下直接打开，绝对路径会找不到资源。optimizeDeps.include把cornerstone3D核心库提前预构建，避免运行时再触发esbuild二次优化。proxy里的'/dicom'会把所有以/dicom开头的请求转发到本地8080端口，而httpdir.js就跑在8080上。manualChunks把cornerstone相关代码单独打进一个chunk，好处是Vue业务代码频繁更新时，浏览器还能命中cornerstone大文件的缓存。chunkSizeWarningLimit抬到1500是因为cornerstone打包后体积本身就大，这个警告只是阈值问题，不是错误。
2.3 Vue3组件中cornerstone3D渲染引擎的生命周期管理
在Vue3里集成cornerstone3D，正确做法是把引擎初始化放到onMounted，销毁放到onBeforeUnmount。这样组件切换时不会留下悬空的canvas引用，也不会出现“路由跳转后再回来画面黑屏”的情况。下面这个组件是这个源码型的核心结构。
<script setup> import { onMounted, onBeforeUnmount, ref } from 'vue' import { init, RenderingEngine, Enums } from '@cornerstonejs/core' import { init as initDICOMLoader } from '@cornerstonejs/dicom-image-loader' import dicomParser from 'dicom-parser' const canvasRef = ref(null) let renderingEngine onMounted(async () => { await init() await initDICOMLoader({ dicomParser }) renderingEngine = new RenderingEngine('viewer-engine') const viewportInput = { viewportId: 'stack-viewport', type: Enums.ViewportType.STACK, element: canvasRef.value, defaultOptions: { background: [0, 0, 0], orientation: Enums.OrientationAxis.AXIAL } } renderingEngine.enableElement(viewportInput) }) onBeforeUnmount(() => { if (renderingEngine) { renderingEngine.destroy() } }) </script> <template> <canvas ref="canvasRef" class="viewer-canvas"></canvas> </template>init()负责初始化cornerstone3D的渲染上下文和缓存系统；initDICOMLoader需要传入dicomParser，否则遇到多帧或压缩DICOM会解析失败。RenderingEngine可以管理多个viewport，后面如果要加MPR视图或三维视图，只需继续enableElement新的viewport，不必重复建引擎。defaultOptions里的orientation设成AXIAL，对应CT检查默认的轴位切面。onBeforeUnmount里的destroy()是最容易漏的一步，环境一旦销毁不彻底，canvas会被引擎引用，组件卸载后内存持续上涨。
这套生命周期模型是正确的，因为cornerstone3D不在Vue的响应式系统内。如果硬把viewport对象放进reactive，性能反而会下降，正确做法是把它作为普通变量存在组件作用域，需要更新图像时显式调用渲染方法。
3. DICOM目录服务与图像加载链路：从httpdir.js到cornerstone图像ID
3.1 WADO协议和轻量HTTP目录服务的取舍
DICOM影像浏览器必须回答一个问题：文件从哪里来。大医院PACS通常提供WADO-RS或WADO-URI接口，但这些接口不是随时可用。源码里保留httpdir.js，本质是把本地或内网里的DICOM目录暴露成HTTP静态资源，再用URL规则生成cornerstone3D需要的imageId。cornerstone3D并不关心imageId是否来自标准WADO，它只要求加载器能根据imageId取回像素数据。
WADO-URI的优点是标准化，缺点是每个DICOM实例都要组装一串很长的query参数，而且如果服务端不支持部分传输，大文件会很难受。WADO-RS支持RESTful的GET /studies/{studyUID}/series/{seriesUID}/instances，返回的是multi-part消息，解析复杂度更高。相对而言，直接用带路径的URL更直观，这也正是httpdir.js这类工具存在的意义。开发阶段用它能省掉中间层繁琐的工作，生产环境再替换成医院PACS的WADO服务。
三者对比如下：
| 方式 | 数据组织 | 适用场景 | cornerstone3D中配置 |
|---|---|---|---|
| WADO-URI | 单实例URL，query传study/series/instance uid | 已有PACS，文件较少 | imageId形如wadors:http://... |
| WADO-RS | RESTful接口，返回multipart | 医院标准集成 | imageId形如dicomweb:http://... |
| 目录HTTP服务 | 文件路径直接映射URL | 本地开发、小规模内网 | imageId形如dicomweb://host/path.dcm |
这套源码用第三种，因为目录映射在调试时最透明，打开浏览器Network面板就能看到请求的完整路径。
3.2 实现一个带路径安全防护的httpdir.js
网上很多DICOM浏览器源码里的http服务器只有一个静态文件中间件，把根目录直接暴露出来。一旦目录中存在非DICOM内容，或者URL里带了..，会造成信息泄露。源码中单独拆出httpdir.js的另一个原因就在于此：可以显式控制路径解析过程和处理边界。下面是最小可用的版本。
const http = require('http') const fs = require('fs') const path = require('path') const ROOT = path.resolve(__dirname, 'dcm') const PORT = 8080 const server = http.createServer((req, res) => { const urlPath = decodeURIComponent(req.url.split('?')[0]) const safePath = path.normalize(urlPath).replace(/^(\.\.[/\\])+/, '') const filePath = path.join(ROOT, safePath) if (!filePath.startsWith(ROOT)) { res.writeHead(403) res.end('Forbidden') return } fs.stat(filePath, (err, stat) => { if (err || !stat.isFile()) { res.writeHead(404) res.end('Not Found') return } const ext = path.extname(filePath).toLowerCase() const mimeMap = { '.dcm': 'application/dicom', '.jpg': 'image/jpeg' } res.writeHead(200, { 'Content-Type': mimeMap[ext] || 'application/octet-stream' }) fs.createReadStream(filePath).pipe(res) }) }) server.listen(PORT, () => { console.log(`httpdir.js listening on ${PORT}`) })decodeURIComponent处理中文文件名；path.normalize把路径里的分隔符统一，再通过正则去掉开头的../，最后用startsWith(ROOT)兜底，这是防止目录穿越的关键。如果漏掉startsWith判断，攻击者可以请求/dcm/../../etc/passwd拿到任意文件。MIME映射里把dcm设为application/dicom，cornerstone的WADO加载器在收到这个Content-Type时会按DICOM标准处理；如果不设，有些加载器靠二进制嗅探也能识别，但设置了以后更稳妥。
3.3 使用cornerstone3D加载目录服务的DICOM序列
httpdir.js跑起来之后，前端需要把imageId构造成对应URL。@cornerstonejs/dicom-image-loader注册后，会用dicomweb前缀匹配自己创建的加载器。实际中文件名可能是Image100.dcm这种不连续编号，所以更常见的做法是先请求一个索引文件，拿到文件列表再拼imageId。
import { init as initDICOMLoader } from '@cornerstonejs/dicom-image-loader' import dicomParser from 'dicom-parser' async function setupLoader() { await initDICOMLoader({ dicomParser, maxWebWorkers: Math.min(navigator.hardwareConcurrency || 2, 4) }) } function buildImageIds(host, seriesPath, names) { return names.map((name) => `dicomweb://${host}/${seriesPath}/${name}`) }maxWebWorkers参数控制DICOM解码线程数量。多核机器上调高能加快解码，但每个worker都会占用内存，旧设备开太多反而卡顿，所以代码里限制到4。使用dicomweb前缀时，加载器内部会把它映射成支持HTTP range请求的标准WADO加载器，这也是cornerstone3D推荐的做法。如果后端只支持流式读取不支持range，遇到DICOM中的封装JPEG2000可能出现解码失败，届时要回到httpdir.js确认是否支持Range头。
另外，开发时通过Vite代理访问httpdir.js能避免CORS。当页面运行在5173端口，httpdir.js在8080端口，直接在code中写上dicomweb://localhost:8080会跨域。更干净的方式是让imageId指向dicomweb://localhost:5173/dicom/...，然后由vite.config.js里配置的proxy转发到8080。浏览器看到的是同源请求，CORS不存在，Network面板里还能看到完整的转发路径。
4. 伪彩渲染：把colorscale图片转成cornerstone3D可用的LUT
4.1 源码为什么会带六张jpg色标
源码根目录里放着colorscale_rainbow.jpg、colorscale_turbo.jpg、colorscale_hot.jpg、colorscale_parula.jpg、colorscale_jet.jpg、colorscale_summer.jpg。这是因为CT这类灰度影像直接输出灰度图时，人的视觉系统对相近灰度的分辨能力有限，伪彩可以通过色彩突变强化结构边界。cornerstone3D内置了部分colormap，但医院或科研场景经常需要特定调色板，把这些图片放到项目里，运行时抽成LUT数组，换主题只需要换图片资源，不用改代码逻辑。
六张图片分别是六种不同视觉用途：
| 色标名称 | 亮度趋势 | 典型用途 | 注意事项 |
|---|---|---|---|
| jet | 蓝->青->黄->红 | 通用伪彩 | 端点亮度过高，感知上有非均匀跳变 |
| turbo | 深紫->红->橙->黄 | 替代jet | Google为jet设计的改进版，过渡更平滑 |
| hot | 黑->红->黄->白 | 显示高温或高代谢区域 | 红色区域容易过曝 |
| parula | 深蓝->黄 | MATLAB默认，适合科研图表 | 对红绿色盲更友好 |
| rainbow | 多彩循环 | 教学演示 | 相邻色带间无单调性，不宜做定量分析 |
| summer | 绿->黄 | 柔和单色调映射 | 对比度较低 |
4.2 用Canvas从JPG抽取256色LUT
一张标准的色标图可以看成一条渐变色带，把图片横向压缩到256像素，再垂直压成1像素高，水平方向每个像素就对应一个灰度级。cornerstone3D的colormap数组要求是[r, g, b, alpha]，所以抽色逻辑很直接。
async function loadColorMapFromJpg(url) { const img = new Image() img.src = url await img.decode() const size = 256 const canvas = document.createElement('canvas') canvas.width = size canvas.height = 1 const ctx = canvas.getContext('2d') ctx.drawImage(img, 0, 0, size, 1) const pixel = ctx.getImageData(0, 0, size, 1).data const colormap = [] for (let i = 0; i < size; i++) { colormap.push([pixel[i * 4], pixel[i * 4 + 1], pixel[i * 4 + 2], 255]) } return colormap }drawImage的第三个和第四个参数把图片缩放到256x1像素，这一缩放会把原图的颜色变化线性映射到256个色阶里。getImageData返回的是RGBA格式，每隔4个字节取一组RGB。alpha强制设为255，因为医疗影像一般不要求半透明，半透明会让伪彩叠加时产生意外的颜色混合。需要注意img.decode()不是所有浏览器都支持，在旧版项目里可以用img.onload包裹，但Vite目标浏览器通常都已经支持decode。
4.3 注册自定义colormap并实时切换
当viewport是STACK类型时，通过viewport.setProperties传递colormap。名字可以自定义，colormap的colors数组会被cornerstone3D编译成GPU lookup table。切换色标时不需要重建engine或viewport，只调用setProperties再触发render即可。
import { StackViewport } from '@cornerstonejs/core' async function applyColorMap(viewport, colorMapName, lutArray) { await viewport.setProperties({ colormap: { name: colorMapName, colors: lutArray } }) viewport.render() }这里必须使用await，因为setProperties内部可能涉及着色器重新编译。若在切换过程中连续下拉选择多个色标，前端一般会加一个防抖，在最后一项落地后才调用applyColorMap。之前遇到过的坑是，重复调用setProperties却忘记render，画面停留在旧颜色映射上，加上render调用后恢复正常。
4.4 与灰度窗口宽度/窗位的交互
过伪彩和窗宽窗位不能彼此隔离。cornerstone3D中，窗宽窗位决定了灰度值到纹理坐标的映射范围，而colormap决定纹理坐标到RGB的映射。实际调试时最常出现的现象是：设置完伪彩后，图像看起来整体偏亮或偏暗，原因就是窗位没有覆盖到实际像素分布范围。
viewport.setProperties({ voiRange: { lower: 40, upper: 400 } })lower和upper对应HU值的窗宽范围。比如肺部CT常用窗位-600，窗宽1500，也就是lower=-1350，upper=150。这里建议先读取DICOM里的WindowCenter和WindowWidth tag，再决定要不要覆盖。假如直接用代码写死一组值，不同设备扫描出来的图像就会失真。源码里没有显式处理这一部分，但结合cornerstone3D的默认行为，加载后会自动使用DICOM头里的参数，只有在需要统一视觉标准时才手工设置。
5. 长序列浏览时的内存回收与预取控制
cornerstone3D的全局cache是所有影像浏览器的内存大头。快速切换序列时，如果只调用viewport.setStack，旧的图像仍然留在cache里，等到浏览器内存逼近崩溃才触发LRU替换。更可控的做法是主动删除不再引用的图像，效果不是更快，而是让内存曲线保持平滑。
针对“当前只显示一个序列、切换后旧序列不再需要”的场景，可以按imageId集合来清理。
import { cache } from '@cornerstonejs/core' function purgeImageIdsNotInUse(activeImageIds) { const currentIds = new Set(activeImageIds) const images = cache.getImages() images.forEach((image, imageId) => { if (!currentIds.has(imageId) && cache.getImageLoadCount(imageId) === 0) { cache.deleteImage(imageId) } }) }cache.getImageLoadCount返回一个imageId被多少个viewport引用的计数。只有当计数为0时才删除，否则可能会把另一个viewport正在用的图同时干掉。这个清理动作建议放在用户切换序列的操作触发后、setStack之前执行，不要在每帧动画中做。之前测试过几百张CT序列，不加清理内存稳定在1.2GB左右；加上这个清理后能压到400MB左右。
如果还需要让下一序列提前准备好，可以用prefetch把当前序列附近的图像先拉进cache。
await cache.prefetch(imageIds, { priority: -1 })prefetch的priority参数表示优先级，数值越小越优先加载，负数代表延迟到主任务队列之后。影像浏览器里常把用户即将滚动到的后20帧设为priority=1，把较远帧设为priority=-1。这样既不阻塞首帧渲染，又能让滚轮浏览时减少白屏等待。
还有一个小技巧：当viewport退出时需要显式销毁，特别是在Vue动态组件场景下。一个粗略的onBeforeUnmount里只调renderingEngine.destroy()还不够，如果viewport通过setStack关联过图像，最好先清除相关imageId的引用再删除viewport。否则又会出现一个对象在引擎销毁后仍然被Vue生命周期外的异步解码回调持有的情况，表现为点击切换路由之后，console里还有请求在继续，这正是DICOM影像浏览器一类项目里最容易被人漏掉的痛点。把渲染循环交给cornerstone，把回收动作交给自己，这是长序列浏览场景下最值得保留的一段逻辑。
本文还有配套的精品资源，点击获取
