滑动参数调节面板-双模式处理流程.md 27 KB
滑动参数调节面板 - 双模式处理流程
SliderAdjustmentPanel 组件的完整处理流程文档
📖 概述
本文档描述了滑动参数调节面板（SliderAdjustmentPanel）的完整处理流程，包括传统模式和WASM模式的双模式支持。
🎯 组件职责
滑动参数调节面板是三级面板，用于调整图像处理参数，支持：
- 实时参数调节与预览
- 参数持久化保存
- 风格预设切换
- 双处理模式（传统模式 / WASM模式）
🔄 完整处理流程
1. 组件初始化阶段
graph TD
A[组件挂载] --> B[读取系统配置]
B --> C{处理模式?}
C -->|传统模式| D[传统模式初始化]
C -->|WASM模式| E[WASM模式初始化]
E --> F[初始化SDK]
F --> G[注册enhanced loader]
D --> H[获取图像ID]
G --> H
H --> I[加载图像参数]
I --> J[渲染UI]
1.1 读取处理模式配置
// 从系统设置Redux store读取
const processingMode = useAppSelector(selectProcessingMode);
const isWASMMode = processingMode === 'wasm';
1.2 获取当前图像ID
useEffect(() => {
// 从 viewer 容器获取当前选中的图像
const dcmUrls = store.getState().viewerContainer.selectedViewers;
// 验证：必须且仅有一个选中的图像
if (dcmUrls.length !== 1) {
console.error('异常：选中图像数量不为1');
return;
}
// 提取 SOP Instance UID
const sopInstanceUid = getSopInstanceUidFromUrl(dcmUrls[0]);
if (sopInstanceUid) {
// 加载该图像的处理参数
dispatch(loadImageProcessingParams(sopInstanceUid));
}
}, [dispatch]);
1.3 加载图像处理参数
// Redux Thunk 异步操作
loadImageProcessingParams(sopInstanceUid)
├─> 调用 API: getImageProcessingParams(sopInstanceUid)
├─> 返回参数: { contrast, detail, latitude, noise }
└─> 更新 Redux state
├─> parameters (合并前端参数 brightness, sharpness)
├─> currentImageId
└─> isInitialLoad = true (防止触发自动预览)
2. 传统模式处理流程
2.1 参数调节流程
graph LR
A[用户拖动滑块] --> B[handleParameterChange]
B --> C[更新Redux state]
C --> D{是后端参数?}
D -->|是| E[触发防抖预览]
D -->|否| F[仅更新UI]
E --> G[500ms后执行]
G --> H[buildProcessedDcmUrl]
H --> I[添加URL参数]
I --> J[updateViewerUrl]
J --> K[Cornerstone重新渲染]
2.2 URL参数构建
// 传统模式：构建带参数的DCM URL
const processedUrl = buildProcessedDcmUrl(currentImageId, {
contrast: params.contrast.toString(),
detail: params.detail.toString(),
latitude: params.latitude.toString(),
noise: params.noise.toString(),
});
// 示例URL
// /dr/api/v1/pub/dcm/1.2.3.4.5?contrast=5&detail=3&latitude=7&noise=2
2.3 后端参数 vs 前端参数
| 参数名称 | 参数类型 | 处理方式 |
|---|---|---|
| contrast (增益) | 后端参数 | URL传递，后端处理 |
| detail (细节) | 后端参数 | URL传递，后端处理 |
| latitude (动态范围) | 后端参数 | URL传递，后端处理 |
| noise (噪声模式) | 后端参数 | URL传递，后端处理 |
| brightness (对比度) | 前端参数 | 仅UI更新，不触发预览 |
| sharpness (亮度) | 前端参数 | 仅UI更新，不触发预览 |
3. WASM模式处理流程
3.1 SDK初始化
// 使用自定义Hook初始化SDK
const { sdk, isSDKReady, isInitializing, error: sdkError } = useImageEnhancementSDK({
sopInstanceUid: currentImageId,
enabled: isWASMMode, // 仅在WASM模式下启用
});
// Hook内部流程
useImageEnhancementSDK
├─> 初始化Cornerstone3D
├─> 创建SDK实例 (createImageEnhancementSDK)
│ ├─> 配置WASM URL: /static/DRENHANCE.js
│ ├─> 配置TIF URL: /dr/api/v1/pub/tif/{sopInstanceUid}-0001.tif
│ └─> 配置DCM URL: /dr/api/v1/pub/dcm/{sopInstanceUid}.dcm
├─> 注册 'enhanced' schema loader
└─> 返回SDK实例
3.2 WASM参数调节流程
graph LR
A[用户拖动滑块] --> B[handleParameterChange]
B --> C[更新Redux state]
C --> D[更新SDK ParameterManager]
D --> E[触发WASM防抖预览]
E --> F[300ms后执行]
F --> G[生成新imageId+时间戳]
G --> H[enhanced:sopInstanceUid_timestamp]
H --> I[updateViewerUrl]
I --> J[触发enhanced loader]
J --> K[SDK WASM处理]
K --> L[返回增强图像]
L --> M[Cornerstone渲染]
3.3 WASM预览实现
const debouncedWASMPreview = useCallback(
(params: FullProcessingParams) => {
if (isInitialLoad || !sdk || !currentImageId) return;
clearTimeout(saveTimerRef.current);
saveTimerRef.current = setTimeout(async () => {
// 1. 更新SDK参数管理器
sdk.parameterManager.updateParameters(params);
// 2. 生成唯一imageId（带时间戳强制重新加载）
const timestamp = Date.now();
const enhancedImageId = `enhanced:${currentImageId}_${timestamp}`;
// 3. 更新viewer URL
dispatch(updateViewerUrl({
originalUrl: dcmUrls[0],
newUrl: enhancedImageId,
}));
// 4. Cornerstone调用enhanced loader
// 5. SDK处理TIF数据并应用WASM增强
// 6. 返回增强后的图像
}, 300); // WASM模式使用更短的防抖时间
},
[currentImageId, isInitialLoad, sdk, dispatch]
);
🎯 滑块调整后的完整执行流程
概览：从滑块到屏幕显示
用户滑动滑块
↓
handleParameterChange() 被触发
↓
1️⃣ 立即更新Redux State（UI响应）
↓
2️⃣ 检查参数类型（后端 vs 前端）
↓
3️⃣ 判断处理模式（WASM / 传统）
↓
4️⃣ 执行对应的防抖预览函数
↓
5️⃣ 更新Viewer URL
↓
6️⃣ Cornerstone重新渲染图像
📊 完整时间轴对比
WASM模式时间轴（默认）
时间点 0ms
├─ 用户滑动滑块（例如：增益从5调到7）
└─ onChange事件触发
时间点 0ms（立即）
├─ handleParameterChange('contrast', 7) 执行
├─ dispatch(updateParameter({ name: 'contrast', value: 7 }))
├─ Redux state更新：parameters.contrast = 7
└─ UI立即显示新值：滑块位置 = 7
时间点 0ms（立即）
├─ 构建新参数对象：newParams = { ...parameters, contrast: 7 }
├─ 判断：'contrast' 属于后端参数 ✅
├─ 判断：当前模式 = 'wasm' ✅
└─ 调用：debouncedWASMPreview(newParams)
时间点 0-300ms
└─ 防抖等待中...（用户可能继续调参）
时间点 300ms（防抖结束）
├─ 清除之前的定时器
├─ 开始执行WASM预览逻辑
├─ Step 1: sdk.parameterManager.updateParameters(newParams)
│ └─ SDK内部参数存储更新
├─ Step 2: 生成唯一imageId
│ └─ enhancedImageId = `enhanced:1.2.3.4.5_1701364800000`
└─ Step 3: dispatch(updateViewerUrl({ newUrl: enhancedImageId }))
时间点 300ms+（网络请求开始）
├─ Cornerstone检测到URL变化
├─ 调用注册的Enhanced Loader
└─ EnhancedImageLoader.loadImage(enhancedImageId) 执行
├─ Step 1: prefetchMetadata()
│ ├─ URL: /dr/api/v1/pub/dcm/1.2.3.4.5.dcm
│ ├─ 网络请求1：获取DCM元数据（几KB）
│ └─ DicomMetaDataManager缓存元数据
│
├─ Step 2: DicomMetaDataManager.get()
│ └─ 从缓存读取元数据（窗宽窗位等）
│
├─ Step 3: tifService.fetchImageData() 🎯 关键！
│ ├─ URL: /dr/api/v1/pub/tif/1.2.3.4.5-0001.tif
│ ├─ 网络请求2：下载TIF文件（2-4MB，16-bit原始数据）
│ ├─ 解析TIFF格式
│ └─ 返回: TIFImageData {
│ width: 512,
│ height: 512,
│ bitsPerSample: 16,
│ pixelData: Uint16Array(262144) // 512×512像素
│ }
│
└─ Step 4: imageCreator.createEnhancedImage()
├─ 调用WASM增强算法
├─ Module.enhancePixelData(pixelData, params)
│ └─ 使用新参数处理16-bit像素数据
├─ 创建Cornerstone图像对象
└─ 返回：CornerstoneImage
时间点 300ms++ (渲染)
├─ Cornerstone接收增强后的图像
├─ 应用窗宽窗位
├─ GPU渲染到Canvas
└─ 屏幕显示更新后的图像 ✨
总耗时：约 300ms（防抖）+ 100-300ms（网络+WASM处理）
传统模式时间轴
时间点 0ms
└─ 用户滑动滑块
时间点 0ms（立即）
├─ handleParameterChange('contrast', 7)
├─ Redux state更新
└─ UI显示新值
时间点 0ms（立即）
├─ 判断：当前模式 = 'traditional'
└─ 调用：debouncedPreview(newParams)
时间点 0-500ms
└─ 防抖等待中...
时间点 500ms（防抖结束）
├─ 构建处理URL
│ └─ /dr/api/v1/pub/dcm/xxx.dcm?contrast=7&detail=5&latitude=5&noise=5
├─ dispatch(updateViewerUrl({ newUrl: `dicomweb:${url}` }))
└─ Cornerstone检测到URL变化
时间点 500ms+
├─ 网络请求：带参数的DCM文件
├─ 后端服务器处理图像（应用参数）
├─ 返回处理后的DCM
└─ Cornerstone渲染
总耗时：约 500ms（防抖）+ 200-500ms（后端处理）
🔗 WASM模式TIF获取完整调用链
// 📍 Level 1: 用户交互层
<ParameterSlider onChange={(value) => handleParameterChange('contrast', value)} />
↓
// 📍 Level 2: 参数处理层 (SliderAdjustmentPanel.tsx)
handleParameterChange(name: 'contrast', value: 7) {
// 1. 立即更新UI
dispatch(updateParameter({ name: 'contrast', value: 7 }))
// 2. 准备新参数
const newParams = { ...parameters, contrast: 7 }
// 3. 检查并调用WASM预览
if (['contrast', 'detail', 'latitude', 'noise'].includes(name)) {
if (isWASMMode) {
debouncedWASMPreview(newParams) // ← 这里
}
}
}
↓
// 📍 Level 3: 防抖预览层 (SliderAdjustmentPanel.tsx)
debouncedWASMPreview(params) {
setTimeout(async () => {
// 1. 更新SDK参数管理器
sdk.parameterManager.updateParameters(params)
// 2. 生成唯一ID（带时间戳）
const timestamp = Date.now()
const enhancedImageId = `enhanced:${currentImageId}_${timestamp}`
// 3. 触发URL更新
dispatch(updateViewerUrl({
originalUrl: dcmUrls[0],
newUrl: enhancedImageId // ← 关键：新URL触发重新加载
}))
}, 300)
}
↓
// 📍 Level 4: Cornerstone层
// Cornerstone检测到imageId变化，调用注册的loader
cornerstone.imageLoader.loadImage(enhancedImageId)
→ 查找 'enhanced:' schema的loader
→ 调用 EnhancedImageLoader.loadImage()
↓
// 📍 Level 5: 图像加载器层 (EnhancedImageLoader.ts)
async loadImage(imageId: string): Promise<CornerstoneImage> {
console.log(`🔄 Loader被调用 - imageId: ${imageId}`)
// 清理imageId（移除前缀和时间戳）
const cleanId = imageId.replace(/^enhanced:/, "").split('_')[0]
// cleanId = "1.2.3.4.5"
try {
// 🔑 Step 1: 预加载DCM元数据
await prefetchMetadata(imageId)
// 🔍 Step 2: 从缓存获取元数据
const metadataUrl = this.getMetadataUrl(cleanId)
const dcmMetadata = DicomMetaDataManager.get(metadataUrl)
// 🎯 Step 3: 获取TIF原始数据 ← 关键步骤！
const tifData = await this.tifService.fetchImageData(cleanId)
console.log('📦 TIF数据获取成功:', {
width: tifData.width, // 512
height: tifData.height, // 512
bits: tifData.bitsPerSample // 16
})
// 🏗️ Step 4: WASM增强 + 创建图像
const enhancedImage = await this.imageCreator
.createEnhancedImage(tifData, dcmMetadata)
return enhancedImage
} catch (error) {
console.error('❌ 增强图像加载失败:', error)
throw error
}
}
↓
// 📍 Level 6: TIF服务层 (TIFImageService.ts)
async fetchImageData(sopInstanceUID: string): Promise<TIFImageData> {
// 1. 构建TIF URL
const tifUrl = `${this.baseUrl}/tif/${sopInstanceUID}-0001.tif`
// tifUrl = "/dr/api/v1/pub/tif/1.2.3.4.5-0001.tif"
console.log('🌐 开始下载TIF文件:', tifUrl)
// 2. 网络请求获取TIF文件
const response = await fetch(tifUrl, {
headers: {
'Authorization': this.authorization,
'Accept': 'image/tiff',
...this.headers
}
})
if (!response.ok) {
throw new Error(`TIF下载失败: ${response.status}`)
}
// 3. 获取二进制数据
const arrayBuffer = await response.arrayBuffer()
console.log('📦 TIF文件下载完成:', {
size: `${(arrayBuffer.byteLength / 1024 / 1024).toFixed(2)} MB`
})
// 4. 解析TIFF格式
const tiffData = await this.parseTIFF(arrayBuffer)
// 5. 提取16-bit像素数据
return {
width: tiffData.width,
height: tiffData.height,
bitsPerSample: 16,
pixelData: new Uint16Array(tiffData.data),
photometricInterpretation: 'MONOCHROME2'
}
}
↓
// 📍 Level 7: WASM增强层 (EnhancedImageCreator.ts)
async createEnhancedImage(
tifData: TIFImageData,
dcmMetadata?: DicomMetadata
): Promise<CornerstoneImage> {
// 1. 获取当前参数
const params = this.parameterManager.getCurrentParameters()
console.log('🎛️ 应用增强参数:', params)
// 2. WASM算法处理像素数据
const enhancedPixels = await this.wasmEnhancer.enhancePixelData(
tifData.pixelData, // Uint16Array(262144) - 16bit原始数据
params // { contrast: 7, detail: 5, ... }
)
// 3. 创建Cornerstone图像对象
const image: CornerstoneImage = {
imageId: this.generateImageId(),
width: tifData.width,
height: tifData.height,
color: false,
// 使用增强后的像素数据
getPixelData: () => enhancedPixels,
// 从DCM元数据获取
minPixelValue: dcmMetadata?.image?.smallestPixelValue || 0,
maxPixelValue: dcmMetadata?.image?.largestPixelValue || 65535,
slope: dcmMetadata?.modalityLut?.rescaleSlope || 1,
intercept: dcmMetadata?.modalityLut?.rescaleIntercept || 0,
windowCenter: dcmMetadata?.voiLut?.windowCenter?.[0] || 32768,
windowWidth: dcmMetadata?.voiLut?.windowWidth?.[0] || 65536,
// 其他属性...
}
return image
}
↓
// 📍 Level 8: WASM模块层 (WASMEnhancer.ts)
async enhancePixelData(
pixelData: Uint16Array,
params: EnhancementParams
): Promise<Uint16Array> {
console.log('⚙️ WASM模块开始处理...')
// 调用编译好的WASM函数
const result = this.wasmModule._enhance_image(
pixelData,
params.contrast, // 7 (新值)
params.detail, // 5
params.latitude, // 5
params.noise // 5
)
console.log('✅ WASM处理完成')
return new Uint16Array(result)
}
↓
// 📍 Level 9: 渲染层
// Cornerstone接收增强后的图像对象
// → 应用窗宽窗位
// → GPU渲染到Canvas
// → 屏幕显示更新 ✨
📡 网络请求详解
WASM模式的两次网络请求
// 请求1: DCM元数据（首次加载时，后续从缓存读取）
GET /dr/api/v1/pub/dcm/1.2.3.4.5.dcm
Headers: {
Authorization: "Bearer xxx",
Accept: "application/dicom"
}
Response:
- Size: 几KB到几十KB
- Content: DICOM元数据（患者信息、窗宽窗位等）
- 用途: 提供图像显示参数
- 缓存: DicomMetaDataManager（整个会话期间）
// 请求2: TIF原始数据（每次参数调整都会请求）
GET /dr/api/v1/pub/tif/1.2.3.4.5-0001.tif
Headers: {
Authorization: "Bearer xxx",
Accept: "image/tiff"
}
Response:
- Size: 2-4MB (512×512×2字节)
- Content: 16-bit TIFF图像
- 用途: 提供原始像素数据用于WASM增强
- 缓存: 无（每次重新获取以应用新参数）
传统模式的一次网络请求
// 请求: 带参数的DCM文件
GET /dr/api/v1/pub/dcm/1.2.3.4.5.dcm?contrast=7&detail=5&latitude=5&noise=5
Headers: {
Authorization: "Bearer xxx"
}
Response:
- Size: 完整DCM文件
- Content: 后端处理后的DICOM图像
- 用途: 直接用于显示
- 缓存: Cornerstone缓存机制
🔄 数据流转详解
16-bit像素数据的转换流程
1️⃣ 服务器TIF文件
└─ TIFF格式，16-bit灰度图像
└─ 文件大小：约2-4MB（512×512×2）
↓ fetch网络请求
2️⃣ ArrayBuffer（二进制数据）
└─ JavaScript二进制缓冲区
└─ 包含完整TIFF文件内容
↓ parseTIFF解析
3️⃣ TIFImageData对象
{
width: 512,
height: 512,
bitsPerSample: 16,
pixelData: Uint16Array(262144), // 512×512个16位整数
photometricInterpretation: 'MONOCHROME2'
}
↓ WASM增强算法
4️⃣ 增强后的像素数据
└─ Uint16Array(262144)
└─ 应用了新参数的增强结果
└─ 例如：对比度增强、细节提升、噪声抑制
↓ 创建Cornerstone图像
5️⃣ CornerstoneImage对象
{
imageId: "enhanced:1.2.3.4.5_timestamp",
width: 512,
height: 512,
getPixelData: () => enhancedPixels,
windowCenter: 32768,
windowWidth: 65536,
// ... 其他属性
}
↓ Cornerstone渲染管线
6️⃣ GPU渲染
└─ 应用窗宽窗位映射
└─ 转换为8-bit RGB显示
└─ WebGL渲染到Canvas
↓
7️⃣ 屏幕显示
└─ 用户看到增强后的图像 ✨
⚡ 性能优化分析
防抖机制的作用
// 场景：用户快速拖动滑块
时间 0ms: 滑块值 5 → 触发，设置300ms定时器A
时间 50ms: 滑块值 6 → 取消A，设置300ms定时器B
时间 100ms: 滑块值 7 → 取消B，设置300ms定时器C
时间 150ms: 滑块值 8 → 取消C，设置300ms定时器D
时间 200ms: 用户停止拖动
时间 500ms: 定时器D触发，仅执行一次WASM处理（参数=8）
优势：
✅ 避免频繁网络请求（TIF下载）
✅ 避免频繁WASM处理（CPU密集）
✅ 最终状态一致（参数=8）
✅ 用户体验流畅（UI立即响应）
WASM vs 传统模式性能对比
场景：用户调节参数10次
传统模式：
├─ 防抖: 500ms × 10次 = 不一定（可能合并）
├─ 网络请求: 10次后端DCM处理请求
├─ 后端处理: 10次图像处理（服务器负载）
└─ 总耗时: 较长（网络往返+后端处理）
WASM模式：
├─ 防抖: 300ms × 10次 = 不一定（可能合并）
├─ 网络请求: 10次TIF下载（可优化为缓存）
├─ 本地处理: 10次WASM增强（浏览器本地）
└─ 总耗时: 较短（本地处理更快）
优化建议：
💡 WASM模式可增加TIF缓存（首次下载后复用）
💡 调参时仅更新SDK参数，不重新下载TIF
💡 进一步缩短防抖时间（如200ms）
🐛 常见问题排查
问题1：滑块移动但图像不更新
可能原因：
// 检查1：是否为初始加载状态
if (isInitialLoad) {
// 初始加载时不会触发预览
console.log('初始加载中，跳过预览')
}
// 检查2：是否为前端参数
if (['brightness', 'sharpness'].includes(paramName)) {
// 前端参数不触发预览
console.log('前端参数，不触发预览')
}
// 检查3：WASM模式SDK是否就绪
if (isWASMMode && !isSDKReady) {
console.error('SDK未就绪，无法预览')
}
// 检查4：是否有网络错误
// 查看浏览器Network标签
问题2：TIF下载失败
// 检查URL是否正确
const expectedUrl = `/dr/api/v1/pub/tif/${sopInstanceUid}-0001.tif`
// 检查认证令牌
headers: {
'Authorization': `Bearer ${token}`
}
// 检查CORS配置
// 服务器需允许跨域请求
// 检查文件是否存在
// 后端日志查看TIF文件路径
问题3：WASM处理很慢
// 可能原因：
1. WASM模块未正确加载
→ 检查 /static/DRENHANCE.js 是否可访问
2. 参数范围过大导致计算密集
→ 优化WASM算法或限制参数范围
3. 图像尺寸过大
→ 大图像（如1024×1024）处理时间更长
4. 风格切换流程
graph TD
A[用户选择风格] --> B[handleStyleChange]
B --> C[applyPreset - 应用预设参数]
C --> D[更新Redux state]
D --> E{处理模式?}
E -->|传统模式| F[触发URL预览]
E -->|WASM模式| G[触发WASM预览]
F --> H[延迟100ms保存参数]
G --> H
H --> I[saveProcessingParams]
I --> J[后端持久化]
风格预设映射：
const PROCESSING_PRESETS = {
'均衡': {
contrast: 5,
detail: 5,
latitude: 5,
noise: 5,
brightness: 0,
sharpness: 0,
},
'高对比': {
contrast: 8,
detail: 3,
latitude: 7,
noise: 2,
brightness: 0,
sharpness: 0,
},
'锐组织': {
contrast: 6,
detail: 8,
latitude: 4,
noise: 3,
brightness: 0,
sharpness: 0,
},
'骨骼': {
contrast: 7,
detail: 2,
latitude: 8,
noise: 1,
brightness: 0,
sharpness: 0,
},
};
5. 参数保存流程
5.1 手动保存
handleSave()
├─> 提取后端参数 (contrast, detail, latitude, noise)
├─> dispatch(saveProcessingParams)
├─> API调用: POST /api/image-processing-params/{sopInstanceUid}
├─> 后端持久化到数据库
└─> 显示成功消息
5.2 自动保存时机
- ✅ 风格切换后
- ✅ 参数重置后
- ❌ 参数调节中（不自动保存，避免频繁请求）
6. 重置参数流程
handleReset()
├─> dispatch(resetToPreset)
│ └─> 恢复当前风格的默认参数
├─> 显示成功消息
├─> 延迟100ms保存参数
└─> 持久化到后端
7. 双模式对比总结
| 特性 | 传统模式 | WASM模式 |
|---|---|---|
| 数据源 | DCM文件 | TIF原始数据 (16-bit) |
| 处理位置 | 后端服务器 | 浏览器本地 (WASM) |
| URL Schema | dicomweb:/dr/api/v1/pub/dcm/xxx?params |
enhanced:sopInstanceUid_timestamp |
| 参数传递 | URL查询参数 | SDK ParameterManager |
| 防抖延迟 | 500ms | 300ms (更快) |
| 处理参数 | 4个后端参数 | 4个后端参数 + 2个前端参数 |
| 图像质量 | 标准 | 高质量 (16-bit增强) |
| 网络依赖 | 每次调参需请求 | 仅初始加载TIF |
| 适用场景 | 标准工作流 | 高质量增强需求 |
8. 参数类型说明
8.1 FullProcessingParams 接口
interface FullProcessingParams {
// 后端参数（会发送到服务器）
contrast: number; // 增益 (0-10)
detail: number; // 细节 (0-10)
latitude: number; // 动态范围 (0-10)
noise: number; // 噪声模式 (0-10)
// 前端参数（仅本地维护）
brightness: number; // 对比度 (-5 to 5)
sharpness: number; // 亮度 (-5 to 5)
}
8.2 参数范围定义
const PARAMETER_RANGES = {
gain: { min: 0, max: 10, step: 0.1 }, // 增益
detail: { min: 0, max: 10, step: 0.1 }, // 细节
latitude: { min: 0, max: 10, step: 0.1 }, // 动态范围
noise: { min: 0, max: 10, step: 0.1 }, // 噪声模式
brightness: { min: -5, max: 5, step: 0.1 }, // 对比度
sharpness: { min: -5, max: 5, step: 0.1 }, // 亮度
};
9. 错误处理
9.1 初始化错误
// 图像选择异常
if (dcmUrls.length !== 1) {
console.error('没有选中的图像或数量大于1，无法加载参数');
return; // 阻止后续执行
}
// SDK初始化失败（WASM模式）
if (isWASMMode && sdkError) {
// UI显示: SDK错误指示器
// 降级: 可考虑自动切换到传统模式
}
9.2 参数加载错误
// Redux error state监听
useEffect(() => {
if (error) {
message.error(error); // 显示错误消息
// 使用默认参数继续工作
}
}, [error]);
9.3 预览更新错误
try {
// 更新预览逻辑
} catch (error) {
console.error('更新预览图像失败:', error);
message.error('更新预览图像失败');
// 不阻止用户继续操作
}
10. 性能优化要点
10.1 防抖机制
- 传统模式: 500ms 防抖，减少后端请求
- WASM模式: 300ms 防抖，本地处理更快响应
10.2 初始加载优化
const isInitialLoad = useAppSelector(selectIsInitialLoad);
// 初始加载时不触发预览，避免不必要的渲染
if (isInitialLoad) {
return; // 跳过预览
}
10.3 定时器清理
useEffect(() => {
return () => {
// 组件卸载时清理定时器
if (saveTimerRef.current) {
clearTimeout(saveTimerRef.current);
}
};
}, []);
11. 模式切换时机
用户在系统设置 > 首选项 > 高级处理模式中配置处理模式后：
- 配置保存到后端数据库
- Redux state更新
- 需要重新进入SliderAdjustmentPanel才生效
- 面板根据新配置初始化对应模式
12. 未来扩展点
12.1 模式自动降级
// WASM模式初始化失败时自动降级到传统模式
if (isWASMMode && sdkError) {
console.warn('WASM模式初始化失败，降级到传统模式');
dispatch(updateProcessingMode('traditional'));
}
12.2 参数预设模板
支持用户自定义参数预设，保存常用的参数组合。
12.3 实时性能监控
- WASM处理耗时
- 网络请求耗时
- 渲染性能指标
📊 状态流转图
stateDiagram-v2
[*] --> Initializing: 组件挂载
Initializing --> LoadingConfig: 读取处理模式
LoadingConfig --> InitTraditional: 传统模式
LoadingConfig --> InitWASM: WASM模式
InitTraditional --> LoadingParams: 初始化完成
InitWASM --> LoadingParams: SDK就绪
LoadingParams --> Ready: 参数加载完成
Ready --> Adjusting: 用户调参
Adjusting --> Previewing: 防抖触发
Previewing --> Ready: 预览完成
Ready --> Saving: 保存参数
Saving --> Ready: 保存完成
Ready --> [*]: 返回上级
🔧 关键代码片段
防抖预览核心逻辑
const debouncedPreview = useCallback(
(params: FullProcessingParams) => {
if (isInitialLoad) return;
clearTimeout(saveTimerRef.current);
saveTimerRef.current = setTimeout(() => {
if (!currentImageId) return;
try {
const dcmUrls = store.getState().viewerContainer.selectedViewers;
if (dcmUrls.length !== 1) return;
const processedUrl = buildProcessedDcmUrl(currentImageId, {
contrast: params.contrast.toString(),
detail: params.detail.toString(),
latitude: params.latitude.toString(),
noise: params.noise.toString(),
});
dispatch(updateViewerUrl({
originalUrl: dcmUrls[0],
newUrl: `dicomweb:${processedUrl}`,
}));
} catch (error) {
message.error('更新预览图像失败');
}
}, 500);
},
[currentImageId, isInitialLoad, dispatch]
);
📝 总结
SliderAdjustmentPanel通过配置驱动的方式支持双处理模式：
- 传统模式：稳定可靠，适合标准工作流
- WASM模式：高质量增强，适合专业场景
两种模式在用户体验上保持一致，底层处理逻辑根据配置自动切换，实现了灵活性和可维护性的平衡。
文档版本: 1.0
创建日期: 2025-11-30
最后更新: 2025-11-30