technical-patterns-lab/docs/2026-01-26_图表详细模式功能.md

图表详细模式功能说明

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

---

📋 功能概述

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

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

---

🎯 使用场景

简洁模式

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

详细模式

• ✅ 算法调试和验证
• ✅ 理解枢轴点识别逻辑
• ✅ 验证分段选择算法
• ✅ 学习和教学用途

---

📊 两种模式对比

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

文件名说明:

• 简洁模式文件不带后缀
• 详细模式文件带 _detail 后缀
• 两种模式可以同时保留，方便对比查看

---

🛠️ 如何启用

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

编辑 scripts/triangle_config.py:

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

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

# 简洁模式（默认）
# 输出: 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 时才显示分段线

---

🔍 分段逻辑说明

高点和低点独立分段

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

# 高点枢轴点（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. 配置参数

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

2. 函数签名

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

3. 条件渲染

# 详细模式：显示所有枢轴点、拟合点、分段线
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. 命令行参数

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

---

🔧 维护建议

未来可能的改进

1. 更多可视化选项

   • 支持只显示枢轴点（不显示分段线）
   • 支持自定义颜色方案
   • 支持调整标记大小

2. 交互式图表

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

3. 配置模板

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

---

✅ 测试验证

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

python scripts/plot_converging_triangles.py

预期结果:

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

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

python scripts/plot_converging_triangles.py --show-details

预期结果:

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

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

修改 triangle_config.py:

SHOW_CHART_DETAILS = True

运行:

python scripts/plot_converging_triangles.py

预期结果:

• ✅ 详细模式生效（即使不加 --show-details）

---

📚 相关文档

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

---

🎉 总结

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

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

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