# 图表详细模式功能说明

**日期**: 2026-01-26  
**功能**: 图表可视化改进 - 简洁模式与详细模式

---

## 📋 功能概述

为了满足不同使用场景的需求，我们为收敛三角形图表增加了**简洁模式**和**详细模式**两种显示方式：

- **简洁模式（默认）**: 仅显示收盘价、上沿线、下沿线，图表清爽易读
- **详细模式**: 显示所有枢轴点、拟合点、分段线等调试信息，便于理解算法

---

## 🎯 使用场景

### 简洁模式
- ✅ 日常使用和实盘选股
- ✅ 快速查看三角形形态
- ✅ 对外展示和报告
- ✅ 减少视觉干扰

### 详细模式
- ✅ 算法调试和验证
- ✅ 理解枢轴点识别逻辑
- ✅ 验证分段选择算法
- ✅ 学习和教学用途

---

## 📊 两种模式对比

| 显示元素 | 简洁模式 | 详细模式 | 说明 |
|---------|---------|---------|------|
| **收盘价线** | ✅ | ✅ | 黑色实线 |
| **上沿线** | ✅ | ✅ | 红色虚线 |
| **下沿线** | ✅ | ✅ | 绿色虚线 |
| **所有高点枢轴点** | ❌ | ✅ | 浅红色小实心圆 (6个) |
| **所有低点枢轴点** | ❌ | ✅ | 浅绿色小实心圆 (4个) |
| **上沿拟合点** | ❌ | ✅ | 深红色大空心圆 (3个) |
| **下沿拟合点** | ❌ | ✅ | 深绿色大空心圆 (4个) |
| **高点分段线** | ❌ | ✅ | 红色点划线 + "高1\|2"标签 |
| **低点分段线** | ❌ | ✅ | 绿色点划线 + "低1\|2"标签 |
| **输出文件名** | `YYYYMMDD_代码_名称.png` | `YYYYMMDD_代码_名称_detail.png` |
| **文件大小** | 约 135KB | 约 155KB |

**文件名说明**: 
- 简洁模式文件不带后缀
- 详细模式文件带 `_detail` 后缀
- 两种模式可以同时保留，方便对比查看

---

## 🛠️ 如何启用

### 方法1: 配置文件（默认设置）

编辑 `scripts/triangle_config.py`:

```python
# 图表详细模式（显示枢轴点、分段线等调试信息）
SHOW_CHART_DETAILS = False  # False=简洁模式（默认），True=详细模式
```

### 方法2: 命令行参数（临时启用）

```bash
# 简洁模式（默认）
# 输出: 20260120_SZ002343_慈文传媒.png
python scripts/plot_converging_triangles.py

# 详细模式（临时启用）
# 输出: 20260120_SZ002343_慈文传媒_detail.png
python scripts/plot_converging_triangles.py --show-details

# 对比查看：同时生成两种模式
python scripts/plot_converging_triangles.py              # 生成简洁版
python scripts/plot_converging_triangles.py --show-details # 生成详细版
# 两个文件会同时保留，文件名不同（详细版带_detail后缀）
```

**优先级**: 命令行参数 > 配置文件

**智能清理**: 
- 简洁模式运行时，只清理简洁模式的旧图片
- 详细模式运行时，只清理详细模式的旧图片
- 两种模式互不影响，可以共存

---

## 📈 详细模式显示元素说明

### 1. 所有枢轴点（小实心圆）

**作用**: 显示算法识别的所有局部高点和低点

- **高点枢轴点**: 浅红色，size=50，alpha=0.4
- **低点枢轴点**: 浅绿色，size=50，alpha=0.4

**标签**: `所有高点枢轴点(6)` / `所有低点枢轴点(4)`

### 2. 拟合点（大空心圆）

**作用**: 显示最终用于线性回归拟合趋势线的代表性点

- **上沿拟合点**: 深红色空心圆，size=120，linewidth=2.5
- **下沿拟合点**: 深绿色空心圆，size=120，linewidth=2.5

**标签**: `上沿拟合点(3)` / `下沿拟合点(4)`

**说明**: 
- 如果枢轴点 > 4：分3段，每段选1个（最高/最低）
- 如果枢轴点 ≤ 4：全部使用

### 3. 分段竖线（点划线）

**作用**: 显示算法如何将枢轴点按时间分段

- **高点分段线**: 红色点划线，标签位于顶部
  - `高1|2`: 第1段和第2段分界
  - `高2|3`: 第2段和第3段分界

- **低点分段线**: 绿色点划线，标签位于底部
  - `低1|2`: 第1段和第2段分界
  - `低2|3`: 第2段和第3段分界

**说明**: 只有当枢轴点 > 4 时才显示分段线

---

## 🔍 分段逻辑说明

### 高点和低点独立分段

高点枢轴点和低点枢轴点**分别独立**进行分段，互不影响：

```python
# 高点枢轴点（6个）
n_high = 6 > 4  ✓ 需要分段
segment_size = 6 // 3 = 2

第1段: [0, 2) → 2个点 → 选最高的1个
第2段: [2, 4) → 2个点 → 选最高的1个
第3段: [4, 6) → 2个点 → 选最高的1个

结果: 3个拟合点（红色大空心圆）

# 低点枢轴点（4个）
n_low = 4 ≤ 4  ✗ 不分段

结果: 全部4个都用于拟合（绿色大空心圆）
```

### 为什么这样设计？

1. **时间均衡**: 确保前、中、后三个时间段都有代表点
2. **代表性强**: 每段选最极值点，确保线是真正的边界
3. **稳定性好**: 多点回归比两点连线更稳健
4. **覆盖性好**: 确保趋势线能包络所有枢轴点

---

## 💡 图表解读示例

### 简洁模式（默认）

```
图表内容：
├─ 黑色实线：收盘价
├─ 红色虚线：上沿线（向下）
└─ 绿色虚线：下沿线（向上）

图例：
- 收盘价
- 上沿
- 下沿
```

**优点**: 
- 清晰直观
- 无视觉干扰
- 适合日常使用

---

### 详细模式（`--show-details`）

```
图表内容：
├─ 黑色实线：收盘价
├─ 红色虚线：上沿线
├─ 绿色虚线：下沿线
├─ 浅红小圆：所有6个高点枢轴点
├─ 浅绿小圆：所有4个低点枢轴点
├─ 深红大圆：上沿拟合点3个（从6个中选出）
├─ 深绿大圆：下沿拟合点4个（全部使用）
├─ 红色竖线：高点分段线（"高1|2"、"高2|3"）
└─ （低点因≤4，无分段线）

图例：
- 收盘价
- 上沿
- 下沿
- 所有高点枢轴点(6)
- 所有低点枢轴点(4)
- 上沿拟合点(3)
- 下沿拟合点(4)
```

**优点**:
- 完整展示算法逻辑
- 便于验证和调试
- 有助于理解原理

---

## 🎨 视觉层次设计

图表元素的 Z-order（从后到前）：

```
1. 网格线（alpha=0.3）
2. 价格曲线（黑色，zorder=默认）
3. 分段竖线（红/绿，alpha=0.4，zorder=3）
4. 所有枢轴点（浅色小圆，alpha=0.4，zorder=4）
5. 拟合点（深色大圆，zorder=5）
6. 趋势线（红/绿虚线，zorder=默认）
```

**设计原则**:
- 详细信息放在后层（不遮挡主要信息）
- 关键信息（拟合点）突出显示（zorder高）
- 使用透明度（alpha）区分重要性

---

## 📝 代码实现要点

### 1. 配置参数

```python
# triangle_config.py
SHOW_CHART_DETAILS = False  # 默认简洁模式
```

### 2. 函数签名

```python
def plot_triangle(
    # ... 其他参数
    show_details: bool = False,  # 是否显示详细信息
) -> None:
```

### 3. 条件渲染

```python
# 详细模式：显示所有枢轴点、拟合点、分段线
if show_details:
    # 绘制所有枢轴点
    ax1.scatter(ph_display_idx, high_win[ph_idx], ...)
    
    # 绘制拟合点
    ax1.scatter(selected_ph_display, high_win[selected_ph_pos], ...)
    
    # 绘制分段线
    if len(ph_idx) > 4:
        ax1.axvline(boundary_1, ...)
```

### 4. 命令行参数

```python
parser.add_argument(
    "--show-details",
    action="store_true",
    help="显示详细调试信息（枢轴点、拟合点、分段线等）",
)
```

---

## 🔧 维护建议

### 未来可能的改进

1. **更多可视化选项**
   - 支持只显示枢轴点（不显示分段线）
   - 支持自定义颜色方案
   - 支持调整标记大小

2. **交互式图表**
   - 使用 plotly 实现交互式图表
   - 鼠标悬停显示详细信息
   - 可点击切换详细模式

3. **配置模板**
   - 预设多种显示模板（极简、标准、详细）
   - 支持保存自定义配置

---

## ✅ 测试验证

### 测试用例1: 默认简洁模式

```bash
python scripts/plot_converging_triangles.py
```

**预期结果**:
- ✅ 控制台显示："详细模式: 关闭 (简洁模式)"
- ✅ 图表只显示收盘价、上沿、下沿
- ✅ 图例简洁（3项）

### 测试用例2: 命令行启用详细模式

```bash
python scripts/plot_converging_triangles.py --show-details
```

**预期结果**:
- ✅ 控制台显示："详细模式: 开启 (--show-details)"
- ✅ 图表显示所有枢轴点、拟合点、分段线
- ✅ 图例详细（7项）

### 测试用例3: 配置文件启用详细模式

修改 `triangle_config.py`:
```python
SHOW_CHART_DETAILS = True
```

运行:
```bash
python scripts/plot_converging_triangles.py
```

**预期结果**:
- ✅ 详细模式生效（即使不加 `--show-details`）

---

## 📚 相关文档

- [README.md](../README.md) - 项目概述
- [USAGE.md](../USAGE.md) - 使用指南
- [枢轴点分段选择算法详解.md](./枢轴点分段选择算法详解.md) - 分段算法完整说明 ⭐
- [枢轴点检测原理.md](./枢轴点检测原理.md) - 枢轴点算法说明
- [2026-01-26_枢轴点拟合改进.md](./2026-01-26_枢轴点拟合改进.md) - 拟合算法改进

---

## 🎉 总结

通过添加**简洁模式**和**详细模式**，图表功能更加灵活：

- **对于日常用户**: 简洁清爽的图表，快速查看形态
- **对于研究者**: 完整的算法细节，深入理解逻辑
- **对于开发者**: 便于调试和验证算法正确性

这个功能提升了项目的易用性和专业性！🎯