# 结构动力特性识别脚本 (Free-Vibration Identification)

## 项目简介
本目录用于完成建筑结构动力特性识别任务。脚本基于专门的自由衰减数据文件，提取顶部响应传感器 `WSMS00007` 的 Z 向信号，识别结构一阶自振频率与阻尼比，并输出可视化诊断结果。

## 技术路线
本目录的分析流程围绕自由衰减信号展开，包含信号读取、主频识别、滤波降噪与阻尼估计四个步骤：

1. **顶部响应读取**
   从 `free_vib` 目录下的 CSV 文件中读取 `WSMS00007` 的 `value3` 列，作为结构顶部响应信号。
2. **频域主频识别**
   对原始自由衰减信号执行 FFT，在 `0.1Hz ~ 5.0Hz` 范围内寻找主峰，识别一阶自振频率。
3. **带通滤波**
   以识别出的主频为中心，构造巴特沃斯带通滤波器，对原始信号进行滤波，得到平滑的衰减振动波形。
4. **阻尼比计算**
   从滤波信号中提取波峰，自动选择包络线质量较高的一段，通过对数衰减率计算平均衰减量与阻尼比。

## 核心模块说明

- **`signal_utils.py`**
  共享信号处理工具。负责传感器常量定义、采样率估计、稳态段截取、FFT 主频识别、抛物线插值、带通滤波与波峰筛选。
- **`task3_identify.py`**
  任务主入口。负责校验自由衰减数据来源、执行一阶频率与阻尼比识别，并生成包含原始波形、滤波波形和包络线的诊断图。

## 使用指南

**1. 运行任务脚本**
对单个自由衰减 CSV 文件执行结构动力特性识别：
```bash
python scripts_2\task3_identify.py --file downloads\Non_TMD\free_vib\free_decay.csv
```

**2. 指定输出目录**
将图像与诊断结果输出到自定义目录：
```bash
python scripts_2\task3_identify.py --file downloads\Non_TMD\free_vib\free_decay.csv --output-dir evaluation_outputs\task3_custom
```

**3. 调整滤波带宽**
通过命令行参数修改主频两侧的带宽范围：
```bash
python scripts_2\task3_identify.py --file downloads\Non_TMD\free_vib\free_decay.csv --bandwidth 0.25
```