3D DVC Dataset Generator

用于3D数字体积相关(DVC)的独立数据集生成库。生成带有真实变形场(流场)的体积图像对，用于训练光流/DVC模型。

An independent dataset generation library for 3D Digital Volume Correlation (DVC). It generates paired volume images with ground-truth deformation fields (flow fields) for training optical flow and DVC models.

原始信息汇总

3D DVC 数据集生成器 数据集概述

数据集简介

这是一个用于**三维数字体相关（3D DVC）**的独立数据集生成库。它生成带有真实变形场（流场）的体图像对，用于训练光流/DVC模型。该库从RAFT-DVC项目中提取，无PyTorch依赖。

核心功能

• 生成数据对：生成参考帧（vol0）与变形帧（vol1）的体图像对，并提供真实的光流场（flow）。
• 两种生成流程：
  1. 流程A（合成生成）：从零开始程序化生成粒子图像体对。完全可控且可复现。
  2. 流程B（从实验图像裁剪）：从真实的显微镜图像（TIF或NumPy格式）中随机裁剪子体积，并应用合成变形场，构建半合成数据集。
• 统一的配置与入口：通过YAML配置文件中的source_type字段选择流程，使用单一入口点运行。

生成流程详情

流程A：合成生成 (source_type: synthetic)

1. 根据配置生成随机粒子（位置、半径、强度）。
2. 生成变形场（仿射/B样条/局部化/组合类型）。
3. 前向扭曲粒子坐标。
4. 渲染未变形体（vol0）和变形体（vol1）。
5. 应用成像效果（泊松噪声与高斯模糊）。
6. 质量检查并保存为.npy文件。

流程B：从实验图像裁剪 (source_type: crop_from_image)

1. 从TIF或.npy文件加载并筛选有效文件。
2. 随机裁剪子体积（带有质量过滤）。
3. 进行强度归一化/去噪。
4. 应用合成变形场。
5. 通过backward_swap或forward扭曲方法生成图像对。
6. 保存.npy文件及元数据。

输出数据格式

数据集按train/、val/、test/划分。每个划分目录结构如下：

<dataset_name>/ ├── train/ │ ├── vol0/ sample_0000.npy # (D,H,W) float32 -- 参考帧 │ ├── vol1/ sample_0000.npy # (D,H,W) float32 -- 变形帧 │ ├── flow/ sample_0000.npy # (3,D,H,W) float32 -- 真实流场 [dz,dy,dx] │ ├── metadata/ sample_0000.json # 生成参数与统计信息 │ └── visualizations/ sample_0000.png # 可选的切片可视化图像

• 流场约定：flow[c, z, y, x] 表示从vol0到vol1的以体素为单位的位移。c=0对应z方向，c=1对应y方向，c=2对应x方向。
• 根目录同时包含用于复现的完整配置快照 (generation_config.yaml) 和生成摘要 (generation_summary.yaml)。

关键特性与配置

变形类型

• affine：全局仿射变形（旋转、平移、剪切），用于刚体全局运动。
• bspline：B样条平滑随机场，用于连续软组织变形。
• localized：在随机中心处局部集中的变形，用于应力集中模拟。
• combined：仿射与B样条的随机加权混合，用于最大多样性。

扭曲策略（流程B）

• backward_swap（默认推荐）：生成反向流场，扭曲后交换vol0/vol1的角色，将取反后的流场保存为前向方向。精确无孔洞，速度快。
• forward：前向扭曲，使用三线性溅射法。近似方法，可能有孔洞，速度慢。

预置配置示例

流程A配置（合成）：

• synthetic_128_v2：体积128^3，粒子半径0.8-3.0体素，数量200-2000，使用全部4种变形类型，为推荐配置。

流程B配置（基于Franck实验室数据）：

• exp_Franck_128：体积126x128x128，完整尺寸，用于生产。

依赖环境

核心依赖由pyproject.toml管理：

• 必需：numpy, scipy, pyyaml, tqdm, tifffile
• 可选（可视化）：matplotlib, pyvista
• 无需PyTorch。原始的RAFT-DVC grid_sample反向扭曲已被scipy.ndimage.map_coordinates替代。

搜集汇总

数据集介绍

构建方式

在三维数字体积相关（DVC）研究领域，高质量数据集的构建对于模型训练至关重要。该数据集通过两种主要管道生成：合成生成管道从零开始程序化创建粒子图像体积对，涉及随机粒子生成、变形场模拟以及成像效果应用；实验图像裁剪管道则从真实显微图像中随机裁剪子体积，并施加合成变形场以构建半合成数据。两种管道均采用统一的YAML配置架构，确保了生成过程的可控性与可重复性。

特点

该数据集的核心特点在于其提供了带有地面真实变形场的三维体积图像对，专门用于光学流或DVC模型的训练。数据集支持多种变形类型，包括仿射、B样条、局部化及组合变形，以模拟从刚体运动到软组织变形的多样场景。输出格式规范，包含训练、验证和测试分割，每样本均提供参考帧、变形帧、流场及元数据，便于直接用于深度学习框架。

使用方法

用户可通过交互式菜单或命令行快速启动数据集生成过程。安装后，运行`generate-dataset`命令并指定配置文件即可触发相应管道。配置文件允许自定义体积形状、变形参数、分割比例及质量控制阈值。生成的数据集以NumPy格式保存，流场遵循从参考帧到变形帧的位移约定，可直接集成到模型训练流程中，支持后续的可视化与分析工具。

背景与挑战

背景概述

三维数字体积相关（3D Digital Volume Correlation, DVC）是一种用于量化三维材料内部变形场的先进计算力学方法，广泛应用于生物力学、材料科学与工程领域。3D DVC Dataset Generator 作为独立的数据集生成库，由相关研究团队基于RAFT-DVC框架提取并优化，旨在为光学流与DVC模型的训练提供具有真实变形场标注的体图像对。该工具通过合成生成与实验图像裁剪两种管道，系统性地构建大规模、高质量的体数据，推动了数据驱动型DVC算法的发展，并为复杂变形场的精确测量奠定了数据基础。

当前挑战

在三维数字体积相关领域，获取具有精确地面真实变形场的大规模体图像数据一直面临严峻挑战。实验采集的成本高昂且受限于成像设备的空间分辨率与噪声干扰，而合成数据则需在物理真实性与计算效率之间取得平衡。该数据集的构建过程需克服多重困难：模拟真实材料微观结构的粒子生成与渲染必须保持几何与强度分布的合理性；变形场的合成需涵盖从全局仿射到局部非线性等多种力学行为，以确保模型的泛化能力；同时，在从实验图像中裁剪子体积时，需处理图像噪声、强度不均匀性以及边界效应，以维持数据的一致性与可用性。

常用场景

经典使用场景

在三维数字体积相关（DVC）领域，该数据集生成器主要用于创建具有地面真实变形场的体图像对，为光学流或DVC模型的训练提供标准化数据。通过模拟真实物理变形过程，如仿射变换、B样条平滑场或局部集中变形，它能够生成多样化的合成数据，支持从零开始的程序化生成或基于实验图像的半合成裁剪，从而为三维变形分析研究奠定数据基础。

衍生相关工作

该数据集生成器衍生了多项经典研究工作，特别是在RAFT-DVC框架的扩展中，它为三维光学流网络提供了训练数据支持。基于其生成的数据，研究者开发了多种变形估计算法，如基于B样条的变形模型和局部化应变分析方法，这些工作进一步推动了DVC在动态成像和计算力学中的应用深度与广度。

数据集最近研究

最新研究方向

在三维数字体积相关（DVC）领域，数据集生成技术正朝着高保真与高效率融合的方向演进。该数据集生成器通过合成与半合成双管道策略，为光学流与DVC模型训练提供了精准的地面真实变形场，有效应对了实验数据稀缺与标注困难的挑战。前沿研究聚焦于利用物理模拟增强数据真实性，结合B样条与局部化变形场生成技术，以模拟生物软组织等复杂材料的力学行为。热点事件体现在与RAFT-DVC等先进模型的深度集成，推动了无监督与弱监督学习在三维体积分析中的应用，显著提升了计算力学与生物医学成像领域的模型泛化能力与测量精度。