# Text2Animation

**Repository Path**: xander23333/Text2Animation

## Basic Information

- **Project Name**: Text2Animation
- **Description**: 项目：文本动画生成
版权所有：北航虚拟现实国家重点实验室
- **Primary Language**: C#
- **License**: Zlib
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2021-01-19
- **Last Updated**: 2022-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开发者文档

## 项目架构

项目主要代码分为两部分，LDS2SGA和SGA2NSM，通过接口文件SGA.result连接。LDS代码在Assets/Script/LDS，NSM部分代码主要在Assets/Demo/Demo.

optimize0630是最新版本的代码（截止2020.8.18）

Text2Animation是之前开发时的版本，请忽略（因为文档有些价值，因此留下了该文件夹）。

SceneGen_release 是原 LDS 项目修改过的代码，直接覆盖使用，Debug时需要同步一下

## LDS



- 组件TextDialog，设定按钮和组件界面，即用户直接交互部分
- ScriptProcessor，整个剧本处理模块的接口。输入格式剧本string，输出接口文件SGA.result。里面规定了语句的接口，对格式的处理等。处理流程是：先判断语句是否是命令，如果不是则分为环境和动作语句分别进行处理。

LDS核心检索部分，主要重写自LDS原项目，有一定程度修改：

- Scene为SSG接口，输入out-scene.txt，输出ssg。`runOneEvolutionStep()`是检索的主函数。
- SceneGenerator和Scene一样是接口类，主要包装核心操作。`generateTSScenes`是主函数。
- SemanticGraph是场景语义图基类，包含基本的匹配、删除、读取等功能。`alignObjectNodesToGraph`和`alignRelationNodesToGraph`是子图匹配函数。SelSentence定义了一些基本类，如语句、结点等。
- TextSemGraph是检索语句生成的场景语义图，SemanticGraph的子类。生成TextSSG的过程为：从buildGraphFromSEL进入，mapNodeNameToFixedNameSet进行结点Name的预处理（对于relation结点调用RelationModel进行查找并映射，对于各类结点均有名称的修改），addImplicitAttributes和addImplicitRelations处理特殊语句（demo)。TextSemGraphManager为TSG的管理类。
- SeneSemGraph是包含了模型信息(meta开头的成员)的场景语义图，SemanticGraph的子类。SeneSemGraphManager为管理类
- RelationModel读取标注的Pairwise_release.model等文件，里面包含了一些标注的关系等信息。该类用于在生成TextSSG时进行结点的生成，以及生成SubSSG之后进行enrich。RelationModelManager为管理员。
- SemGraphMatcher是匹配生成SSG的功能类，retrieveDatabaseSSGs是主函数，从这里生成检索结果。

碰撞检测和位置摆放：

- LayoutPlanner。因为原项目的这一步处理使用了Qt的接口，因此我们自己写了这一部分功能。主要分为：1.读取生成的模型边界信息  2.根据关系对模型位置进行修正 3.对碰撞进行调整。



## NSM

SGA2NSM中，TextLoader负责读取接口文件，SIG负责监听修改和生成动画。需要将预处理好的模型放入Resources/Prefabs/models中并生成Prefab文件，在TextLoader的model_tags中保存了对应的类型，才能从result中导入并交互。

## 其他





# 操作指南

## 一 环境配置

### 0 环境需求

- Python2.7
- JDK 8
- 能运行java项目的IDE（推荐IntelliJ IDEA）
- Unity2020: 2020.3.12f1 or later version

### 1 启动NLP server

1) Setup JDK 8 path in IntelliJ IDEA
2) Run ``Text2Animation\NLP_release\JavaScene\src\nlp\Main.java`` with IntelliJ to start NLP server at the background

这一步完成IntelliJ的终端上应该显示``The NLP server is running.``

### 2 启动Unity

1) 用Unity Hub打开 ``Text2Animation\Unity`` 
2) 点击Play Mode

### 3 输入文本试一试吧~

1) 在文本框中输入语句，格式见第2节
2) 点击Process按钮 或者按回车键，程序会处理输入的语句，生成对应的场景或者动画

## 二 语句格式

语句分为两类，场景和动作，用'$'标识符区分。处理时以句子为单位，因此所有的场景描述语句都要在句号前加标识符'$'。

### 1 动作

**<角色名称> <漫游动作> (<漫游动作交互物体>)  +  (<模板动作>)(<模板动作交互物体>)**

漫游动作(locomotion)需要是第三人称单数现在时或进行时。目前支持的漫游动作为NSM中的基本动作: Stand, Walk, turn,Run, Sit。模板动作(template action)支持使用 副词 或者 连接词+句子 两种方式描述。

输入空白时等价于输入"A man stands."

例句

```
Eve sits angrily on the sofa.
Eve sits on the sofa while Eve plays the piano.
Eve sits on the sofa and Eve plays the piano.
Eve sits on the sofa when Eve plays the piano.
sit on the chair and play the piano
sit angrily on the chair
```

### 2 场景

描述物体以及物体之间关系，建议用There be句型。

例句

```
$There is a desk and a chair.
$There are two chairs.
$There is a bottle on a desk.
$There is a bed near the sofa.
$A chair and a bed.
$A desk with a chair.
```

### 3 功能性语句

- 设置相机，一共有8个机位："front", "left", "right", "back", "front-left", "front-right", "back-right", "back-left"

  ```
  camera front
  ```

- 改变天气: "sunset", "night", "bluesky", "rain", "dusk", "sunrise", "haze"
  和降雨/雪: "rain", "snow"

  ```
  sky sunset
  
  wea rain
  ```
- 清除当前场景

  ```
  clear
  ```
  
- 读取场景

  ```
  ls scene00122
  ```
  
- 存储当前场景

  ```
  ss test0721
  ```

## 三 例子

```
$There is a desk with two monitors, a keyboard, and a mouse.
$There is a round dining table.
$There is a vase and a teapot on the table.
$There is a chair in front of the desk$.
Eve sits on the chair and Eve plays.
```

![image-20210721055828594](C:/Users/user/Desktop/image-20210721055828594.png)



```
$There is a couch and two sofa chairs in the room.
$In front of the couch is a messy coffee table. 
$In front of the couch, there is a tv with two speakers.
$There is a bottle on the table.
Alice sits on the chair.
```

![542af9b3e69c9e4a6c2db53479fffb0](C:/Users/user/Desktop/542af9b3e69c9e4a6c2db53479fffb0.png)

## 四 优化

<img src="C:/Users/user/Desktop/113fa7a5c3d788229d59cf8d6f8b4cd.png" alt="113fa7a5c3d788229d59cf8d6f8b4cd" style="zoom: 70%;" /><img src="C:/Users/user/Desktop/304d91e7bf273dbc1e340933075d955.png" alt="304d91e7bf273dbc1e340933075d955" style="zoom:67%;" />



点击Optimize On开关将会开启优化功能，算法会根据动作迭代找到最佳的场景布局，但是需要较长时间（0.5h左右）停止迭代

## 五 配置文件

params.xml里写了软件所需的各种文件路径，这些都是已经修改好的相对路径，一般情况不需修改。