Prism Candle Forge

Prism Candle Forge — MT4 蜡烛形态识别引擎

Prism Candle Forge 是一个原生的 MQL4 库，利用基于 ATR 加权的几何分析来检测并验证 20 多种日本蜡烛图形态。它提供形态识别、方向置信度评分、蜡烛形态分类以及趋势上下文验证 — 全部通过 8 个导出函数实现，可供任何 Expert Advisor、指标或脚本调用。无需 DLL，无外部依赖，纯 MQL4 高性能计算。

以编译二进制文件 (Prism_Candle_Forge.ex4) 形式分发。本说明文档是您的完整 API 参考手册。

安装说明

1. 从 MQL5 Market 下载 Prism_Candle_Forge.ex4。
2. 将其放置在：MQL4/Libraries/
3. 将下面的 #import 代码块添加到您的 .mq4 源文件中。
4. 编译您的 EA 或指标。全部 8 个函数现已可用。

导入声明（即拷即用）

#import "Prism_Candle_Forge.ex4"
   int    PCF_DetectPattern(const double &open[], const double &high[], const double &low[], const double &close[],
                             int bar_index, double atr_value, string &pattern_name, double &confidence, int &direction);
   int    PCF_ScanMultiPattern(const double &open[], const double &high[], const double &low[], const double &close[],
                                int bar_index, double atr_value, string &pattern_names[], double &confidences[],
                                int &directions[], int max_patterns);
   double PCF_PatternStrength(const double &open[], const double &high[], const double &low[], const double &close[],
                               int bar_index, double atr_value);
   int    PCF_CandleType(double open_price, double high_price, double low_price, double close_price, double atr_value);
   double PCF_BodyRatio(double open_price, double high_price, double low_price, double close_price);
   double PCF_WickBalance(double open_price, double high_price, double low_price, double close_price);
   int    PCF_IsTrendConfirmed(const double &close[], int bar_index, int lookback_period, double min_slope_pips);
   int    PCF_GetVersion();
#import

API 参考

PCF_DetectPattern

检测指定 K 线上的最强蜡烛形态。可识别 20 多种形态，包括 Hammer、Engulfing、Morning/Evening Star、Doji 变体、Piercing Line、Dark Cloud Cover、Three White Soldiers、Three Black Crows、Harami、Tweezer、Marubozu、Hanging Man 以及 Shooting Star。

参数:

• open[], high[], low[], close[]: 来自图表的 OHLC 价格数组。
• bar_index: 要分析的 K 线索引。必须在数组有效索引范围内。
• atr_value: 用于自适应阈值缩放的当前 ATR 值。必须为正数。
• pattern_name (by ref): 接收检测到的最强形态名称（例如 "Bullish Engulfing"）。
• confidence (by ref): 形态置信度评分，范围从 0.0（较弱）到 1.0（标准教科书形态）。
• direction (by ref): +1 表示看涨信号，-1 表示看跌信号。

返回值: 该 K 线上检测到的形态数量（若无则为 0）。将输出参数设置为置信度最高的形态。

PCF_ScanMultiPattern

扫描单个 K 线上的所有蜡烛形态，并按置信度降序返回多个结果。

参数:

• open[], high[], low[], close[]: OHLC 价格数组。
• bar_index: 要分析的 K 线。
• atr_value: 用于自适应阈值的 ATR。
• pattern_names[] (by ref): 接收形态名称的数组。内部自动调整大小，最大为 max_patterns。
• confidences[] (by ref): 接收置信度评分的数组。
• directions[] (by ref): 接收方向的数组 (+1/-1)。
• max_patterns: 返回的最大结果数（例如 5）。

返回值: 实际检测到的形态数量（0 到 max_patterns）。

PCF_PatternStrength

返回一个综合方向动能评分，汇聚该 K 线上检测到的所有形态。

参数:

• open[], high[], low[], close[]: OHLC 数组。
• bar_index: 目标 K 线索引。
• atr_value: 用于缩放的 ATR。

返回值: 评分范围从 -100.0（极度看跌）到 +100.0（极度看涨）。0 表示中性。

PCF_CandleType

使用相对于 ATR 的实体和影线比例，将单根蜡烛分类为 8 种形态类型之一。

参数:

• open_price, high_price, low_price, close_price: 单根蜡烛的 OHLC 数值。
• atr_value: 用于相对尺寸计算的 ATR。若为零或负数，则使用绝对阈值。

返回值: 1=Bull Marubozu, 2=Bear Marubozu, 3=Hammer, 4=Inverted Hammer, 5=Doji, 6=Spinning Top, 7=Standard Bull, 8=Standard Bear.

PCF_BodyRatio

计算蜡烛实体与总高低振幅的比率。可用于过滤蜡烛有效性。

参数:

• open_price, high_price, low_price, close_price: 单根蜡烛 OHLC。

返回值: 比率范围从 0.0（无实体 / doji）到 1.0（全实体 / marubozu）。振幅为零时返回 0.0。

PCF_WickBalance

衡量蜡烛的影线方向不对称性。

参数:

• open_price, high_price, low_price, close_price: 单根蜡烛 OHLC。

返回值: -1.0（全下影线，看涨拒绝）至 +1.0（全上影线，看跌拒绝）。0.0 表示影线对称。影线总长度为零时返回 0.0。

PCF_IsTrendConfirmed

在回溯窗口内使用线性回归斜率验证趋势上下文。用于过滤符合主流趋势的形态。

参数:

• close[]: 收盘价数组。
• bar_index: 回溯窗口的起始 K 线。
• lookback_period: 评估的 K 线数量。最小为 5。受限于数组边界。
• min_slope_pips: 确认为趋势所需的最小绝对斜率（以点为单位）。

返回值: +1（确认上升趋势），-1（确认下降趋势），0（震荡/盘整或数据不足）。

PCF_GetVersion

以整数形式返回库版本，用于运行时兼容性检查。

返回值: 100（代表版本 1.00）。

完整集成示例

#property strict
#import "Prism_Candle_Forge.ex4"
   int    PCF_DetectPattern(const double &open[], const double &high[], const double &low[], const double &close[],
                             int bar_index, double atr_value, string &pattern_name, double &confidence, int &direction);
   double PCF_PatternStrength(const double &open[], const double &high[], const double &low[], const double &close[],
                               int bar_index, double atr_value);
   int    PCF_CandleType(double open_price, double high_price, double low_price, double close_price, double atr_value);
   int    PCF_GetVersion();
#import

void OnTick()
{
   double o[], h[], l[], c[];
   ArrayCopyRates(o, Symbol(), 0);
   int copied = CopyOpen(Symbol(), 0, 0, 100, o);
   CopyHigh(Symbol(), 0, 0, 100, h);
   CopyLow(Symbol(), 0, 0, 100, l);
   CopyClose(Symbol(), 0, 0, 100, c);

   double atr = iATR(Symbol(), 0, 14, 1);

   string pat_name;
   double conf;
   int dir;
   int count = PCF_DetectPattern(o, h, l, c, 1, atr, pat_name, conf, dir);

   if(count > 0)
      Print("Pattern: ", pat_name, " Confidence: ", conf, " Direction: ", dir);

   double strength = PCF_PatternStrength(o, h, l, c, 1, atr);
   Print("Aggregate Strength: ", strength);

   int candle = PCF_CandleType(o[1], h[1], l[1], c[1], atr);
   Print("Candle Type: ", candle);
}

架构设计

全部 8 个函数均为无状态（stateless）且相互独立。每次调用都会对提供的 OHLC 数组执行纯几何与统计分析，无持久状态、无图表对象、无计时器、无网络访问。基于 ATR 的相对阈值确保在所有金融品种（外汇、贵金属、指数、加密货币）和所有时间周期上均能准确识别形态，无需手动调整参数。

兼容性

• 平台：仅限 MetaTrader 4
• 策略测试器：完全兼容（支持回测与参数优化）
• 外部依赖：无（无需 DLL）
• 无图表对象，无计时器，无界面开销 — 纯计算引擎
• 线程安全：所有函数均为无状态设计；支持多图表并发调用