# SimReview SDK

**Repository Path**: cae_platform/simreview_sdk

## Basic Information

- **Project Name**: SimReview SDK
- **Description**: SimReview 3D 显示 SDK
- **Primary Language**: C++
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-08-02
- **Last Updated**: 2023-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SimReview SDK 使用方法

![图片](server/src/ServerWindow/pvIcon512.png "SimReview")

SimReview SDK 是一个帮助 C++ 开发人员快速搭建使用 SimReview 3D/2D 仿真计算或者数据处理程序的 C++/11 工具。你可以在这个SDK的基础上构建一个你自己的带 SimReview 的应用程序，也可以把这个 SDK 嵌入到你现有的项目中，来完成集成 SimReview 的工作，让你的项目快速具备 3D/2D 复杂模型显示或者数据处理的功能。

SDK 示例使用 Qt 编写。可以根据项目需要换成 STD C++ 或者其他。

## 1. 什么是 SimReview 
SimReview 是一个基于 VTK/ParaView 构建的一个用于 2D/3D 数据处理和可视化的程序。项目基于 ParaView 5.11.1，具备 ParaView 的强大数据处理能力和显示效率，拥有广泛的生态。项目目前打包了2个版本，一个mini的版本和一个全功能版本，开发者可以根据需要自行选择。

## 2. SimReview 能干什么
利用 SimReview，开发者可以在自己的桌面应用程序中集成需要3D显示的功能，而不需要自行开发 VTK 或者 OpenGL 显示程序，也不需要开发复杂的后处理程序功能，亦或者进行复杂的第三方接口数据的转换。同时程序还能保障完整高效的数据处理和显示能力，让开发者更多精力集中在自己的项目本身。

本程序可以根据启动参数，选择隐藏或显示菜单、进度条、工具栏等界面。开发者只需在启动时添加相应的 [flag](#41-启动) 即可。

开发者只需要先准备好（预先录制：）几行 Python 脚本，让 SimReview 根据脚本自行完成复杂的后处理任务，可以大幅提高项目开发周期。

### 2.1. 支持的文件格式
支持的文件取决于插件，在插件支持的情况下，可以支持更多。目前支持的有：

| 文件格式   | 软件    | 说明  |
|-----------|---------|-------|
| .k        | LS-DYNA | 前处理网格文件 |
| d3plot    | LS-DYNA | 后处理结果文件 |
| .inp      |         |      |
| .cas; .cash5 |       |  Fluent 前处理模型文件  |
| .dat      |  Fluent | Fluent 后处理结果 |
|           |         |    |

## 3. SDK 简单用法
将 example 里面的示例 Demo 程序直接拷贝到你的项目中，直接让示例代码成为你项目的一部分，让你的项目支持3D显示功能。当然，这时你的项目应该是 Qt 环境的，非 Qt 环境的示例待补充。示例项目使用的是 CMake。如果需要其它示例，联系作者。

### 3.1. Example 示例：

![图片](example/image/client_example2.png "Example")

* LS-DYNA 前后处理模型显示(.k; d3plot)
（已完成）
 
* ANSYS inp 前处理显示模型显示(.inp)

* Fluent cas 前处理模型显示(.cas)
（未完成）
##### 1.导出fluent数据，用Export --> Ensight Case Gold
##### 2.删除.encas文件中所有"标志
##### 3.删除.encas文件中最后两行（从script开始的两行）
##### 4.将.encas文件后缀改为.case
##### 5.在paraview中load该case文件即可

也可以直接保存成 CGNS 格式直接打开。

* CAD stl 模型显示(.stl)

* VTK 后处理模型显示(.vtk; ...)

### 3.2. 脚本录制方法：
> 无参数环境启动 SimReview，也就是直接双击 SimReview.exe。然后在菜单栏 Tools -> Start Trace 打开脚本录制功能。同样单击 Tools -> Stop Trace 结束录制。
>
> 录制结束后，需要根据实际项目情况，微调 Python 代码。

一些高级的功能，可以通过阅读本文中的高级用法小节([跳转](#4-高级用法))来掌握。更高级的仿真数据处理功能，可能需要仿真工程师或数据工程师的支持。

## 4. SDK 高级用法
通过深入理解示例代码，开发者可以在自己的项目中开发更高级的功能。首先 git clone 下载 SimReview SDK 项目代码，将 SimReview 的发布文件放到你的项目可执行目录中，然后将 client 工程的代码集成到你的项目中的主界面或者某一个按钮的动作。

接下来，让 SimReview 作为服务端（server），你的程序作为客户端（client），通过 TCP 协议开始通讯。

你的主程序和 SimReview 是两个运行时独立的应用程序，互不阻塞，当然可以根据你的项目需要修改。

具体用法参看项目 client 代码。

### 4.1. 启动
设置好定制界面参数，直接启动即可：
~~~
quint64 embedFlag = svEmbed_Null
    | svEmbed_Embeded                 // 隐藏标题栏
    | svEmbed_HideMenuAll             // 隐藏所有菜单
    | svEmbed_HideMenuExtern          // 隐藏拓展菜单
    | svEmbed_HideStatusBarAll        // 隐藏所有状态栏
    | svEmbed_HideStatusBarMem        // 隐藏状态栏磁盘显示
    | svEmbed_HideSelectIcon;         // 隐藏控制栏选择按钮
    | svEmbed_CleanMode;              // 隐藏所有非3D/2D显示区域内容
QString embedEnv = QString::number(embedFlag);
qputenv(_PreDefine_Embed_flag, embedEnv.toStdString().c_str());
QProcessEnvironment processEnv = QProcessEnvironment::systemEnvironment();
_process->setProcessEnvironment(processEnv);

// 启动 SimReview
_process->startDetached(cmd, QStringList(), workDir, &processId);
~~~

其中，svEmbed_Flag、svEmbed_Null 等变量的定义，位于 \svTcpServerObserver.h 头文件中。

### 4.2. 发送命令
和 SimReview 的通讯方式为，使用一个经过包装的文本格式 svTcpMsgData，通过 TCP 协议发送该文本：
~~~
svTcpMsgData data;
data.dataType = type;                 // 自定义发送命令的类型
svTcpMsgDataBlock dataBlock;
dataBlock.data.append(cmd.toUtf8());  // 命令文本
data.blocks.append(dataBlock);
svTcpMsgPhaser phase(data);
QVariant qvData(phase.raw());
if (!qvData.canConvert<QByteArray>()) {
    msg = QString(tr("Error byte array format."));
    return;
}
QSharedPointer<svNetWriting> writing(new svNetWriting(qvData.value<QByteArray>()), &QObject::deleteLater);
connect(writing.data(), &svNetWriting::fulfil, this, &ClientWorker::fulfil_slot);
if (_session->write(writing))
{
    msg = QString(tr("Data in deque."));
    st = svTcpSessionCli::Status_Sent;
    sj = svTcpSessionCli::Response_Unknown;
}
else {
    msg = QString(tr("Data add deque failed."));
}
~~~

注意：当在一次 svTcpMsgData 命令中提交多个 svTcpMsgDataBlock，仅第一个的内容会被执行。

### 4.2.1. 命令调试
如果你不想在你的项目中测试你的命令，那么你可以使用 client 工具进行测试：

在启动 SimReview 后，你可以使用 client 跟 SimReview 沟通。在发送命令行输入你要发送的内容。
注意第三个参数，是你的命令长度。如果没有及时就该它，可能导致 SimReview 以为到达命令的结尾，而忽略你的输入，如下图示例中的长度设置为1000。

服务端的端口，默认是43615。运行过程中可能动态调整，最新的端口配置文件路径可以在一下位置获取：（请注意替换 UserName）
C:\Users\UserName\AppData\Roaming\ParaView\SimReview_tcp.ini
> [TCP]
>
> address=127.0.0.1
> 
> port=43615

![图片](example/image/client_example.png "Debug example")

### 4.2.2. Python命令格式
其中，命令的类型分为如下几种：

| 类型   | ID  | 说明  |
|--------|-----|------|
|    Type_PythonCode   |      = 0 |   // default command type |
|    Type_Command      |      = 1 |   // commands you can defined. now supported show/hide menubar/pipeline/property. |
|    Type_Command_Raw  |      = 2 |   // command with QByteArray text free format |
|    Type_Command_JSON |      = 3 |   // command with JSON format |
|    Type_Msg          |      = 100 | // message text |
|    Type_Msg_JSON     |      = 101 | // message text with JSON format |

常用的命令类型为 Type_PythonCode（默认）和 Type_Command。绝大部分的功能 SimReview 都支持 Python 脚本，例如读取某一格式文件，定义 Filter，自定义计算结果等。但是，仍然有部分功能默认 Python 脚本无法完成，这个时候就需要一些额外的命令，如 Type_Command。

### 4.2.3. Command命令格式
目前支持的 Type_Command 有：
| 命令       | 说明  |
|------------|------|
| pipeline show | 显示隐藏 pipeline 对话框，命令：pipeline hide |
| property show | 显示隐藏 property 对话框，命令：property hide |
| menubar show file | 显示隐藏菜单栏，命令：menubar hide file。全部支持的菜单包括 file，sources，filters，edit，view，tools，macros，catalyst，extractors 和 help |
| server disconnect | 清空已经打开的历史文件或 Filter。  |

使用 Command 模式很简单，只需要在前面的代码([跳转](#42-发送命令))中，令 type = Type_Command，然后把对应的文本命令放入 svTcpMsgDataBlock 的 data 即可。

### 4.3. 状态更新
正常情况下，发送完数据之后，待 SimReview 完成执行操作后，会返回一个标记为 "Done" 的状态。根据这个状态，你的程序（客户端）可以判断一些耗时的操作是否成功完成。

### 4.4. 功能定制
开发者遇到以下这些情况的时候可能需要对 SimReview 进行不同程度的定制：

#### 4.4.1. 示例不包含的文件格式
当需要打开并显示一个 VTK/ParaView 支持格式的文件，但是本项目提供的示例没有包含相关代码的时候。这种情况比较容易实现。开发者只需要找一个懂仿真的工程师，使用 ParaView 的脚本录制功能，录制一段对应格式文件的 Python 脚本即可。

当开发者发现结果文件中的直接结果不能满足使用要求时，这时候需要对读取的结果数据进行计算。在 ParaView 中计算结果非常方便，只需要添加相应的 Filter 即可完成。计算过程的 Python 实现代码可能需要仿真工程师的协助。

#### 4.4.2. 不支持的格式
如果遇到 VTK/ParaView 本身不支持的数据格式，开发者只能查找相关资源来解决。

通常，网络上有一些人开源了一些插件（Plugin）来解决这一问题。如果遇到没有开源的插件，那么你可以尝试自己写一个或者向本项目作者寻求帮助。

但更常见的情况是，你的文件的格式不是公开的，属于一些公司自有，通常这会涉及到一些版权问题。这种情况只能向版权方寻求许可。

#### 4.4.3. 其他

* 关于软件体积瘦身

多数场景是，你开发的项目可能只需要一个非常非常简单的2D/3D显示功能，格式文件也只有一种，结果数据也非常单一。那么这种情况下，你使用一个完整版的 SimReview 会导致你本身的项目过于庞大。一个完整的发布版超过了 1GB 大小。因此，为了节省资源和你的时间，项目发布了一个 mini 版本，约 200MB 左右。后续会根据某些更具体的使用场景，发布一些体积更小的版本。

* 关于故障恢复

有时候由于一些默认设置问题，可能会让 SimReview 在嵌入你的项目之后，不能达到你的预期功能，甚至出现一些不方便的问题，比如影响到操作或者显示的问题。这时候简单的 Python 脚本可能无法实现你的功能。那么，你这个时候可以单独启动 SimReview，直接双击 Post 目录下的 exe，或者，通过([flag](#41-启动)) 参数，从菜单栏进入详细的 SimReview 控制功能进行设置并保存。默认情况下，调整好的设置将自动保存为软件的配置参数保存在 C:\Users\UserName\AppData\Roaming\ParaView\ 目录下。如果遇到崩溃问题，那么大多数情况下是 SimReview 的 Python 脚本中指定读取文件的 Reader 或者 Plugin 选择错误或者不支持当前的格式导致。可以通过修改 Reader 和 Plugin 来解决。

## 5. SimReview 定制
本软件在开发时预留了一些定制界面的方式，比如可以通过 ([flag](#41-启动)) 参数自定义软件运行界面显示的窗口、工具栏、进度条等，或者使用 Command 模式开关一些窗口。再比如可以通过添加环境变量 WYATT_DEBUG=Any 的方式让程序进入调试状态。

关于更多的个性化 SimReview 功能，请联系项目作者。

## 6. 未来功能
由于时间仓促，很多脚本都没有录制完成。但是，SimReview 的原身 ParaView 可以通过曲线救国的方式支持绝大多数文件格式的数据。后续可以在本项目中提需求，或者用户自行编写脚本和 Plugin。

此外，未来考虑添加浏览器端浏览功能。

## 7. Example 视频
![图片](example/image/client_example.gif "Example Video")

License @ BSD-3