简介Weasis是一款免费开源的医学DICOM查看器支持桌面应用、Web访问及便携式媒介集成适用于医院、健康网络、多中心临床试验和患者个人医疗等场景。项目基于Java开发master分支对应Weasis 3.x需Java 8并保留旧版分支供不同环境选型功能上它支持HIS/PHR灵活集成提供DICOM发送storeSCU、STOW-RS、查询/检索C-GET、C-MOVE、WADO-URI及DICOMweb和Dicomizer模块可构建自定义插件并实现多语言部署。压缩包以zip格式发布约2.54MB体积轻量适合快速下载评估包内含源码、配置文件及构建所需基础资料便于本地编译运行。目前已有1091人学习/下载是医学影像软件工程师、系统集成人员及医学信息专业学生研究DICOM协议与查看器架构的实用参考。1. Weasis一个 DICOM 查看器同时覆盖桌面与 Web二选一的时代过去了Weasis 是一款基于 Java 的 DICOM 查看器既能作为桌面应用独立安装使用也能作为 Web 查看器接入到现有影像系统里。一个查看器同时吃下 DICOM 图像浏览、DICOM-RT 结构集加载、DICOM-PR 显示状态解析和 DICOM 文件导出对每天要处理 CT、MR、RT 等多模态影像数据的从业者来说它最直接的价值是结束了“桌面端装一套、网页端再开一套”的割裂局面。下面按部署选型、显示核心、常见坑和进阶用法四个部分拆解给步骤、给参数、给边界照着走基本不会跑偏。2. 双形态部署桌面与 Web 只是入口不同内核是同一套2.1 模块化结构为什么两端能共用一套渲染逻辑Weasis 的工程结构是建立在 OSGi 模块化框架上的。DICOM 文件解析、图像渲染、RT 数据集处理、DICOM-PR 显示状态、导出模块全部被拆成独立的 bundle。桌面版启动时直接把这一组 bundle 加载进同一个 Java 进程Web 版则不是重新写一套浏览器渲染而是通过启动器机制把请求转给本机已经安装好的 Weasis 客户端由同一套渲染核心去完成显示。这一点在选型时非常关键。如果你以为“Web 版等于零安装在浏览器里直接渲染 DICOM”那会误判它的部署形态。Weasis 的 Web 方式本质上是协议唤醒网页携带 DICOM 的路径或远程地址唤醒本地客户端本地端解析并显示。所以先说清楚边界它的 Web 形态适合已经有工作站、能装客户端的环境通过网页把医生直接带到图像跟前省掉手动搜文件的那段路。真正零安装、纯浏览器渲染的场景它并不是为这个设计的。为什么同一个查看器要把两种形态都做了因为医院场景里既有固定阅片工作站又有移动查房和远程会诊入口。固定工作站装机完整用桌面端最稳移动端不方便装完整软件就给一个网页入口点一下把数据从 PACS 或 WADO 服务拉起来。两端共用内核窗宽窗位、标注、序列浏览这些操作习惯完全一致培训成本低很多。2.2 桌面端首启从环境检查到打开第一张 DICOM先确认运行环境。Weasis 是 Java 程序这一步绕不开命令行里直接看版本# 终端检查 Java 环境 java -version输出里能看到类似openjdk version 11.0.22的信息就算过关。如果提示找不到命令需要先装一个 64 位的 JDK 或 JRE。这里有个经验值Weasis 对 Java 8 以上基本都能跑但新版功能在 Java 11 下更稳。很多人卡在“界面起不来但命令行没有任何报错”多半就是 Java 版本太老或者装的是 32 位 JVM。环境没问题后进入解压目录启动。Linux 和 macOS 下入口是bin/weasisWindows 下是bin/weasis.bat也可以在图形界面直接点安装后的程序入口。我习惯在启动脚本里显式指定工作目录避免后续找不到缓存路径# Linux 桌面版启动-w 参数指定工作目录 cd /opt/weasis/bin ./weasis -w /data/weasis-workspace-w参数不是必须的它决定用户配置和缓存放在哪。不指定时会用系统默认用户目录比如 Linux 的~/.weasisWindows 的%USERPROFILE%\.weasis。建议在批量部署时统一指定到固定路径后面做配置备份、缓存清理都好找。提示Windows 下如果遇到配置损坏导致启动异常把用户目录%USERPROFILE%\.weasis连同安装目录里的conf一起删掉恢复到出厂状态是最快的后悔药。启动完成后用文件菜单打开单个 DICOM或者直接把整个文件夹拖进主窗口。拖文件夹时它会扫描目录建立序列列表目录层级会直接影响序列排序。我一般会把数据按“患者—检查—序列”三级目录组织好再拖入否则列表顺序会很乱看着像黑匣子一样不知道哪条对应哪条。2.3 Web 端集成网页把请求转给本地查看器的实际做法集成到现有系统时核心就是生成一段正确的协议链接。安装 Weasis 时它会注册自定义 URL scheme网页收到请求后由浏览器转给本地程序。一个典型的调用地址长这样weasis://command/open?dicomhttp://192.168.1.10/wado/1.2.840.113619.2.55.3.1width1400height900weasis://是安装时注册的协议头command/open是动作命令dicom参数可以是本地文件路径、HTTP 地址或 WADO 地址width和height控制窗口初始尺寸。注意一个细节浏览器能访问的地址不代表 Weasis 客户端一定能访问。客户端不经过浏览器的那套网络策略如果内网有访问限制或网关隔离浏览器测试通过但客户端拉不到数据的情况很常见。页面里的触发方式用最直接的顶层跳转a hrefweasis://command/open?dicomhttp://192.168.1.10/wado/1.2.840.113619.2.55.3.1width1200height800在 Weasis 中打开检查/a不要把这个链接塞进 iframe 里协议跳转需要顶层导航权限被 iframe 拦截后会出现“点了没反应”。集成到系统时地址最好由服务端动态拼接而不是写死在页面里这样检查 UID、患者 ID、来源服务器都可以在服务端统一控制后续换机器只改一处。3. 显示核心DICOM 像素值并不等于屏幕灰度3.1 从像素值到灰度窗宽窗位只是一次线性映射DICOM 文件里真正存图像的大字段是 PixelData它保存的通常不是显示器直接用的灰度值而是原始采集数据。CT 的像素值是从 -1000 到 3000 左右的 HU 值MR 则可能是任意强度范围的整数。要让这张图在屏幕上正常显示必须把原始值压缩到 0 到 255 的灰度范围。这个压缩过程里最重要的参数就是窗宽窗位。窗位Window Center决定显示范围的中间点窗宽Window Width决定涵盖的数值范围。落在范围外的像素被压成纯黑或纯白范围内的像素按线性关系映射。看一段最容易理解的简化实现# 根据窗宽窗位把像素值映射到 0~255 灰度 def apply_voi_lut(value, center, width): low center - width / 2.0 high center width / 2.0 if value low: return 0 # 低于窗范围纯黑 if value high: return 255 # 高于窗范围纯白 return int((value - low) / width * 255)这段代码描述了 DICOM 标准里 VOI LUT 应用的基本逻辑实际实现还要考虑 PhotometricInterpretation 是 MONOCHROME1 还是 MONOCHROME2。MONOCHROME2 是常规灰度高值显示为白色MONOCHROME1 正好相反高值显示为黑色。如果你打开一份乳腺 X 线或某些 DR 图像发现灰度和预期相反先查这个 Tag不要急着怀疑数据传输有问题。知道了这个映射关系就容易理解为什么同一份 DICOM 在不同软件里看起来差别很大。不是谁的解析错了很可能只是默认窗宽窗位预设不同。有的软件默认给腹部预设你拿来看胸部 CT纵隔窗全白肺窗全黑对比度完全不对。这时候手动调一下窗宽窗位就会恢复正常。3.2 窗宽窗位调节与预设交互方式和使用习惯Weasis 里最常用的交互是鼠标左键拖拽调节窗宽窗位滚轮翻序列右键拖拽缩放。如果你换过其他 DICOM 软件肌肉记忆可能不太一样可以在首选项里把快捷键改成自己顺手的方案。这里有一个习惯值得养成对比同一组图像时先把所有序列的窗宽窗位锁定成同一组数值再切换序列对比否则每切一个序列都自动套用各自的预设对比结果就会被显示参数干扰。窗宽窗位的预设一般放在右键菜单或工具栏里常见的腹部、脑部、骨窗、肺窗等都有内置值。手动调到自己满意的状态后可以对当前序列应用并保存为新预设。保存的预设存放在用户配置目录里批量部署时把配置文件分发给所有工作站就能保证全员用同一套显示参数减少因为个人设置不同导致的诊断差异。调窗宽窗位有一条边界要记住它只是显示层面的映射不改变原始像素值。把窗宽调到最大也就是让灰度映射尽可能线性不等于图像被“增强”了。如果要做真实的图像处理比如滤波、增强、分割应该基于原始像素值运算而不是基于屏幕显示值。3.3 DICOM-RT 与 DICOM-PR结构集、剂量和显示状态DICOM-RT 是放疗场景下的一组专用对象。最常见的是 RT Structure Set简称 RTSS里面保存的是轮廓点坐标和对应的解剖结构名称。RTSS 本身不包含图像它必须关联到某一组 CT 或 MR 图像才能显示。Weasis 加载 RTSS 时主要校验两个层面帧参考 UID 是否和图像一致以及坐标体系是否匹配。如果放疗数据是从第三方系统导出的轮廓和图像错位是高频问题。原因一般两种一是帧参考 UID 不一致图像和轮廓不在同一个坐标系里二是重采样后图像的像素间距发生变化但轮廓坐标没有跟着换算。遇到这种情况先看 DICOM 头里的 FrameOfReferenceUID 和 ImagePositionPatient不要直接改轮廓先把数据源对齐再导入。DICOM-PR 则完全不同它保存的是显示状态可以理解为对图像的一套“观看参数”包括窗宽窗位、翻转、缩放、标注位置等。Weasis 加载 PR 后会把图像应用这套参数重新显示。这在对比诊断里很有用但也容易埋坑导出 JPEG 时如果顺手勾选了“应用 PR 显示状态”导出的结果会叠加上 PR 的窗宽窗位和标注和原始像素对应的灰度不一致。这不是 Bug是理解数据对象时容易忽略的边界。4. 避坑排查Weasis 里常见的几类翻车现场4.1 打开中文路径文件时画面空白现象文件在资源管理器里能看到缩略图拖入 Weasis 后序列列表有记录但图像区域黑屏或只显示灰色画布。原因文件路径里的中文或特殊字符在传递到 Java 层时发生了编码转换问题。Windows 环境默认编码不是 UTF-8 时最容易触发路径里再带空格和括号就更容易出问题。解决先把文件复制到纯英文目录试一次。如果英文目录正常确认是路径编码问题那就把工作目录统一改成英文并在启动脚本里强制指定 UTF-8 编码。常见做法是在JAVA_OPTS里加-Dfile.encodingUTF-8然后重启查看器。4.2 Web 端从页面点开查看器没反应现象地址栏直接粘贴链接可以唤出 Weasis但页面里的链接点击后毫无反应。原因页面把链接放在 iframe 或 sandbox 环境中自定义协议跳转被浏览器限制或者链接里的参数被页面框架转义协议头被破坏。解决改用window.location.href直接跳转避免 iframe 嵌套。协议链接手动在地址栏粘贴测试一遍能排除大部分页面侧脚本问题。如果地址栏粘贴可用但页面点击不可用问题基本出在页面容器限制。4.3 导出的 JPEG 灰度偏暗或整体偏黑现象把同一张 CT 导出成 JPG 后在其他看图软件里打开发现整体偏黑或对比度和屏幕上显示的不一致。原因导出时没有先经过窗宽窗位映射直接把 12bit 或 16bit 原始像素值截断成 8bit。比如 CT 原始值 0 到 4096 直接截断绝大多数像素落在低灰度区间看起来就是一片黑。解决导出前先确认当前窗宽窗位状态导出选项里勾选“使用当前显示状态”而不是“原始像素值”。批量导出时这个问题尤其明显几十张图全导完才发现一套都偏了返工成本很高。我现在做批量导出前习惯先导出一帧检查确认灰度正常后再跑全序列。4.4 打开大体积多帧序列时内存溢出现象加载 500 帧以上的 CT 序列时界面越来越卡最后直接报内存溢出错误退出。原因启动参数里的最大堆内存不足多帧数据被一次性读入内存。某些未压缩的 DICOM 多帧文件体积远大于磁盘占用内存翻倍增长。解决在启动脚本里把堆内存调大。Linux 下修改weasis.sh# 调整 Weasis 启动内存限制 export WEASIS_MAX_MEMORY2G export JAVA_OPTS-Xmx2G -Dfile.encodingUTF-8-Xmx2G表示最大堆 2GB处理常规的几百帧序列没问题。注意 32 位 JVM 最大只能分配到 1.5GB 左右如果你确认装的是 64 位 JVM 但仍然受限检查脚本里是否有硬编码的内存参数被覆盖。4.5 两台显示器上灰度看起来不一样现象同一个文件、同一个版本的 Weasis在 A 显示器和 B 显示器上亮度明显不同窗宽窗位已经调到一致还是对不上。原因这个锅一般不归 Weasis 背。显示器没有做 DICOM 灰度校准、显卡驱动做了色温调整、系统开了护眼模式或夜览都会改变实际显示效果。解决先用同一组窗宽窗位、同一张图像在两端对比。如果图像数据完全相同但显示不同先关掉系统护眼模式再看显卡驱动的颜色设置。问题依旧就只能做显示器校准医院阅片屏一般需要专门的 DICOM GSDF 校准流程普通办公屏则不必过分纠结。但作为阅片工具尽量用同一型号显示器减少设备差异带来的干扰。5. 进阶技巧命令行直接拉起文件与批量导出的省力姿势5.1 用命令行直接打开 DICOM 文件大多数人的使用习惯是先打开 Weasis再从菜单里找文件。但命令行直接传参省掉这一步尤其适合接入自动化流程。把安装目录加入 PATH 环境变量后可以这样用# 命令行直接打开单个 DICOM 文件 weasis /data/patient1/CT_1.2.840.113619.2.55.3.dcm # 打开目录并加载该目录下的 DICOM 序列 weasis /data/patient1/第一种方式适合单文件快速查看第二种方式适合把一个序列的所有文件一次载入。实际价值在于可以把 Weasis 挂到自己的处理流程里影像预处理程序跑完后自动拉起查看器让医生做质检不用人工再点一遍菜单。命令行还能配合-o参数执行打开后的动作但具体可用的动作名依版本和模块而定先在自己环境里验证一次再写进脚本。5.2 批量导出 DICOM 为 JPEG 的参考脚本固定阅片工作流里经常要把一批 DICOM 转成 JPEG 发给临床科室做演示。手动一张张导出效率太低参考下面的脚本#!/bin/bash INPUT_DIR/data/dicom_in OUTPUT_DIR/data/jpg_out mkdir -p $OUTPUT_DIR for f in $INPUT_DIR/*.dcm; do base$(basename $f .dcm) weasis -o export.image(\$OUTPUT_DIR/${base}.jpg\, \jpeg\) $f done脚本做了三件事先创建输出目录再遍历输入目录下所有.dcm文件最后逐个调用 Weasis 的导出命令保存为同名 JPG 文件。这里最需要留意的是export.image的引号转义Linux 下用反斜杠转义双引号Windows 的cmd.exe下写法不同最好先拿单文件验证一遍语法再全量跑。批量导出前一定先手动导一张确认灰度和窗宽窗位符合预期别让整套序列在错误参数下跑完再返工。从那以后我每个批量任务都会强制走一遍“先导出单帧、检查灰度、再跑全量”的顺序这个习惯帮我避掉过不止一次整批反色的翻车事故。希望帮到你。本文还有配套的精品资源点击获取