# QtDataVisualization

**Repository Path**: qt-adventure-works/qt-data-visualization

## Basic Information

- **Project Name**: QtDataVisualization
- **Description**: **Qt Data Visualization 3D** 是一个基于 **Qt Data Visualization 模块**构建的 **MVC 架构三维数据可视化演示平台**。该项目展示了如何使用 Qt 的 3D 数据可视化能力来呈现复杂的多维数据，支持 **3D柱状图、3D散点图、3D曲面图** 三种核心图表类型。

本项目采用 **Model-View-Controller (MVC)** 
- **Primary Language**: C/C++
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qt Data Visualization 3D - 三维数据可视化平台

[![Qt](https://img.shields.io/badge/Qt-5/6-green.svg)](https://www.qt.io/)
[![C++](https://img.shields.io/badge/C++-11/17-blue.svg)](https://isocpp.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 📋 项目概述

**Qt Data Visualization 3D** 是一个基于 **Qt Data Visualization 模块**构建的 **MVC 架构三维数据可视化演示平台**。该项目展示了如何使用 Qt 的 3D 数据可视化能力来呈现复杂的多维数据，支持 **3D柱状图、3D散点图、3D曲面图** 三种核心图表类型。

本项目采用 **Model-View-Controller (MVC)** 设计模式，实现了数据层、视图层和控制层的完全解耦，便于扩展和维护。

---

## 🏗️ 技术架构

### 整体架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                        主窗口 (MainWindow)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ 3D 柱状图     │  │ 3D 散点图     │  │ 3D 曲面图     │      │
│  │ (Bars3DView) │  │(Scatter3DView)│  │(Surface3DView)│      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌───────────────────────────────────────────────────┐      │
│  │              控制面板 (ControlPanel)                │      │
│  └───────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              ↕ 信号/槽机制
┌─────────────────────────────────────────────────────────────┐
│                   控制器 (ViewController)                     │
│         • 协调 Model 和 View 之间的交互                       │
│         • 处理用户操作和数据刷新请求                           │
└─────────────────────────────────────────────────────────────┘
                              ↕ 直接调用
┌─────────────────────────────────────────────────────────────┐
│                      数据模型 (DataModel)                     │
│  ┌──────────┐  ┌───────────┐  ┌───────────┐                 │
│  │ 柱状图数据 │  │ 散点图数据  │  │ 曲面图数据  │                 │
│  │ BarData   │  │ScatterData│  │SurfaceData│                 │
│  └──────────┘  └───────────┘  └───────────┘                 │
└─────────────────────────────────────────────────────────────┘
```

### MVC 三层职责

| 层级 | 类名 | 职责描述 |
|------|------|----------|
| **Model (模型层)** | `DataModel` | 管理所有3D图表的原始数据生成、存储和信号通知 |
| **View (视图层)** | `MainWindow` + 3个View子类 | 负责UI展示、用户交互、图形渲染 |
| **Controller (控制层)** | `ViewController` | 协调Model与View，处理业务逻辑和数据刷新 |

---

## ✨ 核心功能特性

### 📊 三种3D可视化图表

#### 1️⃣ 3D 柱状图 (Q3DBars)
- **用途**: 展示分类数据的对比关系
- **特点**:
  - 支持多行多列数据矩阵展示
  - 自定义行列标签（如：季度、产品名称）
  - 柱体高度直观反映数值大小
  - 支持3D旋转和缩放查看

#### 2️⃣ 3D 散点图 (Q3DScatter)
- **用途**: 展示数据点的空间分布和聚类特征
- **特点**:
  - 支持多系列数据（本项目展示3个集群）
  - 不同颜色区分不同数据系列
  - 可视化数据的空间分布规律
  - 支持球体、螺旋、环形等多种分布模式

#### 3️⃣ 3D 曲面图 (Q3DSurface)
- **用途**: 展示连续函数或地形地貌等连续变化的数据
- **特点**:
  - 高分辨率网格渲染（40×40采样点）
  - 支持复杂数学函数可视化（鞍面+波动）
  - 平滑曲面插值
  - 直观展示数据的高低起伏

### 🎛️ 实时控制面板

| 控制项 | 功能说明 |
|--------|----------|
| **正交投影切换** | 在透视投影和正交投影之间切换，消除透视变形 |
| **阴影质量调节** | 5档可调：无阴影 → 低质量 → 中等 → 高 → 高质量软阴影 |
| **反射效果开关** | 启用/禁用曲面的反射效果 |
| **反射率滑块** | 动态调整反射强度（0-100%） |

### 🎨 视觉设计
- 现代化绿色主题UI设计
- 渐变色按钮和标签页
- 响应式布局（左侧图表区:右侧控制面板 = 4:1）
- 工具栏快捷导航

---

## 📈 应用场景与行业数据展示

### 💼 商业智能与销售分析

#### 场景：季度产品销售对比
```
数据维度：
• X轴：时间维度（Q1, Q2, Q3, Q4 季度）
• Z轴：产品维度（产品A/B/C/D/E）
• Y轴：销售额（万元）

适用行业：零售、电商、制造业、快消品
```
**可视化价值**:
- 一眼看出哪个季度哪款产品表现最佳
- 发现季节性销售趋势
- 对比不同产品的市场表现
- 辅助制定生产计划和库存策略

**扩展建议**:
- 添加年份维度对比历史同期数据
- 颜色编码表示同比增长率
- 悬停显示详细数值和占比

---

### 🔬 科学研究与数据分析

#### 场景：实验数据聚类分析
```
数据维度：
• X/Y/Z轴：三个独立变量的观测值
• 颜色：样本类别或分组

适用行业：生物医药、材料科学、气象预测、地质勘探
```

**具体应用实例**:

| 领域 | X轴 | Y轴 | Z轴 | 分析目标 |
|------|-----|-----|-----|----------|
| **基因表达** | 基因A表达量 | 基因B表达量 | 基因C表达量 | 识别癌症亚型 |
| **材料性能** | 温度 | 压力 | 强度 | 寻找最优工艺参数 |
| **气象数据** | 经度 | 纬度 | 海拔温度 | 分析气候模式 |
| **金融风控** | 收入 | 负债 | 信用评分 | 客户分群 |

**可视化价值**:
- 发现数据中的自然集群结构
- 识别异常点和离群值
- 验证假设的数据分布模式
- 为机器学习提供特征工程依据

---

### 🗺️ 地理信息与地形建模

#### 场景：地形高程与热力场分析
```
数据维度：
• X轴：经度或水平位置
• Z轴：纬度或深度
• Y轴：高程/温度/浓度等标量场

适用行业：GIS、城市规划、环境监测、石油天然气
```

**具体应用实例**:

| 应用场景 | Y轴含义 | 数据来源 | 决策支持 |
|----------|---------|----------|----------|
| **数字地形** | 海拔高程 | 卫星遥感/LiDAR | 工程选址、洪水模拟 |
| **地下水污染** | 污染物浓度 | 监测井采样 | 治理方案制定 |
| **油田储层** | 孔隙度/渗透率 | 地震测井数据 | 钻井位置优化 |
| **城市热岛** | 地表温度 | 热红外遥感 | 绿地规划 |

**数学函数可视化**:
- 本项目默认展示 **鞍面函数 + 正弦波叠加**
- 公式：`y = 0.3(x² - z²) + 0.5·sin(1.5x)·cos(1.5z)`
- 可扩展为任意二维标量场的可视化引擎

---

### 📊 制造业质量控制

#### 场景：多参数产品质量分布
```
数据维度：
• X轴：参数A（如：尺寸公差）
• Y轴：参数B（如：重量偏差）  
• Z轴：参数C（如：表面粗糙度）
• 颜色：批次或生产线

适用行业：汽车制造、半导体、航空航天
```

**可视化价值**:
- 识别超出规格的产品批次
- 发现参数之间的相关性
- 追踪工艺漂移趋势
- 优化六西格玛控制限

---

### 🎯 金融科技与风险管理

#### 场景：投资组合风险收益分析
```
数据维度：
• X轴：预期收益率
• Y轴：波动率（风险）
• Z轴：流动性指标
• 大小：资产规模

适用行业：证券、基金、保险、银行
```

**可视化价值**:
- 构建有效前沿曲线
- 识别风险分散化机会
- 压力测试情景可视化
- 客户风险偏好匹配

---

## 🔧 技术栈

| 技术 | 版本要求 | 说明 |
|------|----------|------|
| **Qt Framework** | Qt 5.x / Qt 6.x | 跨平台GUI框架 |
| **Qt Data Visualization** | 包含在Qt中 | 核心3D图表模块 |
| **C++ Standard** | C++11 (Qt5) / C++17 (Qt6) | 现代C++特性 |
| **OpenGL** | 2.0+ | 底层图形渲染 |
| **OpenMP** | 可选 | 并行计算加速 |
| **MSVC Compiler** | 2017+ (Windows) | Windows平台编译器 |

---

## 📁 项目目录结构

```
Qt Data Visualization/
├── main.cpp                          # 应用入口，MVC初始化
├── mainwindow.h / .cpp               # 主窗口(View层)
├── QtDataVisualization3D.pro         # Qt项目配置文件
├── Makefile / Makefile.Debug/Release # 构建文件
│
├── common/                           # 🔧 公共组件(MVC核心)
│   ├── DataModel.h / .cpp            #    数据模型 - 数据生成与管理
│   ├── ViewController.h / .cpp       #    控制器 - 业务逻辑协调
│   ├── ControlPanel.h / .cpp         #    控制面板 - 图表属性调节UI
│   └── CustomInputHandler.h / .cpp   #    自定义输入处理 - 交互增强
│
├── modules/                          # 📊 3D图表模块(View层)
│   ├── bars/                         #    3D柱状图模块
│   │   ├── Bars3DView.h / .cpp       #    Bars3DView类实现
│   │   └── bars.pri                  #    模块编译配置
│   ├── scatter/                      #    3D散点图模块
│   │   ├── Scatter3DView.h / .cpp    #    Scatter3DView类实现
│   │   └── scatter.pri               #    模块编译配置
│   └── surface/                      #    3D曲面图模块
│       ├── Surface3DView.h / .cpp    #    Surface3DView类实现
│       └── surface.pri              #     模块编译配置
│
├── x64/                              # 📦 编译输出目录
│   ├── debug/                        #    Debug版本
│   └── release/                      #    Release版本(PDB调试符号)
│
├── debug/                            # 调试中间文件
└── release/                          # 发布中间文件
```

---

## 🚀 快速开始

### 环境准备

#### 必需软件
1. **Qt SDK** (推荐 Qt 5.15 LTS 或 Qt 6.5+)
   - 下载地址：https://www.qt.io/download
   - 安装时确保勾选 **"Qt Data Visualization"** 组件
   
2. **C++ 编译器**
   - Windows: MSVC 2017+ 或 MinGW 64-bit
   - Linux: GCC 7+
   - macOS: Clang 10+

3. **Qt Creator IDE** (可选但推荐)
   - 用于项目管理和调试

#### 验证安装
```bash
# 检查 Qt Data Visualization 模块是否可用
qmake --version
# 确保 qmake 能找到 datavisualization 模块
```

### 编译与运行

#### 方式一：使用 Qt Creator (推荐)

1. 打开 Qt Creator
2. 选择 **"文件 → 打开文件或项目"**
3. 导航到 `QtDataVisualization3D.pro` 文件并打开
4. 选择合适的编译套件 (Kit):
   - Desktop Qt 5.15.2 MSVC 2019 64bit (推荐)
   - Desktop Qt 6.5.x MSVC 2022 64bit
5. 点击左下角 **▶ 运行** 按钮

#### 方式二：命令行构建

```bash
# 进入项目目录
cd "e:/Jay_Pro_Test/Qt3D/Qt Data Visualization"

# 生成Makefile (Release版本)
qmake CONFIG+=release "DEFINES+=WIN64"

# 或者 Debug版本
# qmake CONFIG+=debug "DEFINES+=WIN64"

# 编译
mingw32-make -j8        # MinGW
# 或
nmake                    # MSVC
# 或
jom -j8                  # MSVC并行编译

# 运行
./x64/release/QtDataVisualization3D.exe
```

#### 构建配置选项

| 配置项 | 说明 |
|--------|------|
| `CONFIG += release` | 发布版本，启用优化 |
| `CONFIG += debug` | 调试版本，包含完整调试信息 |
| `DEFINES += WIN64` | 目标平台为64位Windows |
| `CONFIG += force_debug_info` | Release模式下生成PDB符号文件 |
| `/MP` | MSVC并行编译加速 |
| `/openmp` | 启用OpenMP并行计算支持 |

---

## 📖 使用指南

### 界面概览

启动程序后，您将看到以下界面：

```
╔═══════════════════════════════════════════════════════════════╗
║  🛠️ 工具栏: [刷新数据] | [柱状图] [散点图] [曲面图]           ║
╠═══════════════════════════════════════════════════════════════╣
║          Qt Data Visualization 3D 数据可视化平台              ║
╠══════════════════════════════════════════╦═══════════════════╣
║                                           ║                   ║
║   ┌─────────────────────────────────┐    ║  🎛️ 控制面板      ║
║   │                                 │    ║                   ║
║   │                                 │    ║  □ 正交投影       ║
║   │         3D 图表区域             │    ║                   ║
║   │      (支持鼠标拖拽旋转)         │    ║  ▼ 阴影质量:      ║
║   │                                 │    ║    [中等    ▼]   ║
║   │                                 │    ║                   ║
║   │                                 │    ║  ☑ 反射效果      ║
║   └─────────────────────────────────┘    ║                   ║
║                                           ║  反射率: ━━━●━━━ ║
║ [3D柱状图] [3D散点图] [3D曲面图]          ║      (65%)       ║
╠═══════════════════════════════════════════════════════════════╣
║  💡 就绪 - 请选择标签页查看不同3D图表                          ║
╚═══════════════════════════════════════════════════════════════╝
```

### 操作说明

#### 3D图表交互
| 操作 | 功能 |
|------|------|
| **鼠标左键拖拽** | 旋转3D视角 |
| **鼠标滚轮** | 缩放图表 |
| **鼠标右键拖拽** | 平移视图 |
| **点击工具栏按钮** | 快速切换图表类型 |

#### 控制面板操作
1. **正交投影**: 
   - ✅ 勾选：消除透视变形，适合精确尺寸比较
   - ❌ 取消：保留透视效果，更具立体感

2. **阴影质量**: 
   - 从下拉框选择：无 / 低 / 中等 / 高 / 软阴影
   - 质量越高越逼真，但性能消耗越大

3. **反射效果**: 
   - 仅对曲面图有效
   - 模拟镜面反射效果

4. **反射率调节**: 
   - 拖动滑块调整反射强度 0% ~ 100%

---

## 🔌 扩展开发指南

### 添加新的数据源

修改 `common/DataModel.cpp` 中的数据生成方法：

```cpp
// 示例：从数据库加载真实数据
QVector<DataModel::BarDataItem> DataModel::generateBarData()
{
    QVector<BarDataItem> data;
    
    // 方式1：连接数据库
    /*
    QSqlQuery query("SELECT quarter, product, sales FROM sales_data");
    while (query.next()) {
        BarDataItem item;
        item.row = query.value(0).toInt();    // 季度索引
        item.col = query.value(1).toInt();    // 产品索引
        item.value = query.value(2).toFloat(); // 销售额
        data.append(item);
    }
    */
    
    // 方式2：读取CSV/Excel文件
    // 方式3：调用REST API获取实时数据
    // 方式4：对接MQTT物联网数据流
    
    return data;
}
```

### 添加新的图表类型

参考现有模块创建新的3D视图：

1. 在 `modules/` 下新建文件夹（如 `modules/pie/`）
2. 创建 `.pri` 文件定义源文件
3. 继承 QWidget 封装 Qt Data Visualization 组件
4. 在 `MainWindow` 中注册新标签页

### 自定义主题样式

编辑 `mainwindow.cpp` 中的 `applyStyle()` 方法：

```cpp
// 修改配色方案为深色主题
void MainWindow::applyStyle()
{
    setStyleSheet(R"(
        QMainWindow { background-color: #1e1e1e; }
        QLabel#titleLabel { color: #00ff00; }
        // ... 其他样式定制
    )");
}
```

---

## 🎓 学习资源

### 官方文档
- [Qt Data Visualization 官方文档](http://doc.qt.io/qt/qtdatavisualization-index.html)
- [Qt Data Visualization Examples](http://doc.qt.io/qt/qtdatavisualization-qtdatavisualization-bars-example.html)
- [Q3DBars API 参考](http://doc.qt.io/qt/q3dbars.html)
- [Q3DScatter API 参考](http://doc.qt.io/qt/q3dscatter.html)
- [Q3DSurface API 参考](http://doc.qt.io/qt/q3dsurface.html)

### 相关技术
- [OpenGL 教程](https://learnopengl.com/) - 底层图形编程
- [Qt Quick 3D](https://doc.qt.io/qt/qtquick3d-index.html) - 新一代3D框架
- [VTK](https://vtk.org/) - 专业科学可视化库

---

## ⚙️ 性能优化建议

| 优化项 | 方法 | 预期效果 |
|--------|------|----------|
| **大数据集** | 使用代理模式批量更新数据 | 减少50%+刷新时间 |
| **高帧率** | 降低阴影质量和采样密度 | GPU负载降低30% |
| **内存占用** | 分页加载数据，按需渲染 | 内存减少60%+ |
| **并行计算** | 启用OpenMP (`/openmp`) | 多核CPU利用率提升 |

---

## 🐛 已知问题与解决方案

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 中文乱码 | 编码设置不正确 | `.pro` 文件中已添加 UTF-8 设置 |
| 编译错误堆空间不足 | 大量静态数据初始化 | 已添加 `CONFIG += resources_big` |
| 3D图表黑屏 | OpenGL驱动问题 | 更新显卡驱动或使用软件OpenGL |
| Release无法调试 | 缺少调试符号 | 已配置 `force_debug_info` |

---

## 📄 许可证

本项目采用 MIT 许可证开源。详见 [LICENSE](LICENSE) 文件。

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

---

## 📮 联系方式

如有问题或建议，欢迎通过以下方式联系：

- 📧 提交 GitHub Issue
- 💬 讨论区留言

---

## 🗓️ 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| **v1.0.0** | 2025-06-11 | 初始版本发布<br>- MVC架构实现<br>- 3种3D图表类型<br>- 控制面板功能<br>- 现代化UI设计 |

---

<div align="center">

**⭐ 如果这个项目对您有帮助，请给一个 Star！⭐**

Made with ❤️ using Qt & C++

</div>