Utils/QUICKSTART.md

# Utils 模块快速参考指南

## 快速开始

### 1. 提交 Utils 仓库

```bash
cd Utils
git commit -m "初始提交：Utils 工具库模块

包含以下子模块：
- VrCommon: 核心接口和数据结构
- VrUtils: 工具类库（JSON、log4cpp、tinyxml2、INI、MD5、CRC）
- CloudUtils: 点云工具
- DataUtils: 数据处理工具（CloudMathClac、CoordinateTransform）
- CloudView: 点云查看工具
"
```

### 2. 添加远程仓库（可选）

```bash
# 添加远程仓库
git remote add origin <你的远程仓库地址>

# 推送到远程
git push -u origin master
```

### 3. 在主项目中使用 submodule（可选）

如果你想将 Utils 作为 git submodule 使用：

```bash
# 在主项目根目录
cd ..

# 删除当前的 Utils 目录（确保已备份）
# rm -rf Utils

# 添加为 submodule
git submodule add <Utils仓库地址> Utils

# 提交 submodule 配置
git add .gitmodules Utils
git commit -m "将 Utils 添加为 git submodule"
```

## 在其他项目中使用 Utils

### 方法 1: 作为 git submodule

```bash
# 在你的项目根目录
git submodule add <Utils仓库地址> Utils
git submodule update --init --recursive
```

### 方法 2: 直接克隆

```bash
# 在你的项目根目录
git clone <Utils仓库地址> Utils
```

### 方法 3: 复制文件

直接将 Utils 目录复制到你的项目中。

## 在项目中引用 Utils

### 在 .pro 文件中添加

```qmake
# 包含路径
INCLUDEPATH += $$PWD/../Utils/VrCommon/Inc
INCLUDEPATH += $$PWD/../Utils/VrUtils/Inc

# 链接库（Windows）
win32:CONFIG(release, debug|release): {
    LIBS += -L$$PWD/../Utils/VrCommon/release -lVrCommon
    LIBS += -L$$PWD/../Utils/VrUtils/release -lVrUtils
}
else:win32:CONFIG(debug, debug|release): {
    LIBS += -L$$PWD/../Utils/VrCommon/debug -lVrCommon
    LIBS += -L$$PWD/../Utils/VrUtils/debug -lVrUtils
}

# 链接库（Unix/Linux）
else:unix:!macx {
    LIBS += -L$$PWD/../Utils/VrCommon -lVrCommon
    LIBS += -L$$PWD/../Utils/VrUtils -lVrUtils
}
```

### 在主项目中添加 Utils 子项目

```qmake
# 在主项目的 .pro 文件中
TEMPLATE = subdirs

Utils.file = ../Utils/Utils.pro
SUBDIRS += Utils

# 设置依赖关系
YourModule.depends = Utils
```

## 常用命令

### 构建 Utils 模块

```bash
cd Utils
qmake Utils.pro
make
```

### 清理构建产物

```bash
cd Utils
make clean
```

### 更新 Utils 模块（如果使用 submodule）

```bash
# 在主项目根目录
git submodule update --remote Utils
```

## 模块说明

### VrCommon
- **用途**: 核心接口和数据结构定义
- **主要文件**: VrCommon.h, VrConfigCmd.h, VrError.h
- **依赖**: 无

### VrUtils
- **用途**: 通用工具类库
- **主要功能**: 日志、JSON、XML、INI、MD5、CRC、时间、网络、文件、字符串
- **依赖**: VrCommon

### CloudUtils
- **用途**: 点云数据处理工具
- **主要功能**: 激光数据加载、点云图像转换
- **依赖**: VrCommon, VrUtils

### DataUtils
- **用途**: 数据处理工具集
- **子模块**: CloudMathClac（曲线拟合）、CoordinateTransform（坐标转换）
- **依赖**: VrCommon

### CloudView
- **用途**: 点云可视化查看工具（独立应用）
- **依赖**: VrCommon, VrUtils, CloudUtils

## 故障排查

### 问题 1: 找不到头文件

**症状**: 编译时提示找不到 VrCommon.h 或 VrUtils 相关头文件

**解决方案**:
1. 检查 INCLUDEPATH 是否正确设置
2. 确保相对路径正确（根据你的项目结构调整 `../` 的数量）
3. 确保 Utils 目录存在且包含所有必要文件

### 问题 2: 链接错误

**症状**: 编译通过但链接时提示找不到库文件

**解决方案**:
1. 确保先编译 Utils 模块
2. 检查 LIBS 路径是否正确
3. 确认 debug/release 配置匹配

### 问题 3: submodule 未初始化

**症状**: Utils 目录为空

**解决方案**:
```bash
git submodule update --init --recursive
```

## 版本管理建议

### Utils 仓库
- 使用语义化版本号（如 v1.0.0）
- 为重要版本打 tag
- 维护 CHANGELOG.md

### 主项目
- 如果使用 submodule，锁定 Utils 到特定版本
- 定期更新 Utils 到最新稳定版本

## 联系方式

如有问题或建议，请联系项目维护者。