UTT SPEEDOMETER CONFLUENCE GAUGE (SPD) - MT5
=============================================
UltimateTrading.tools  |  https://ultimatetrading.tools
Version 1.00  |  Licence: MPL 2.0 (see LICENCE section)

WHAT IT IS
----------
A semicircular speedometer in its own indicator window. The needle is driven
by a six-factor confluence score from 0 (fully bearish) to 100 (fully bullish)
and sweeps across five equal sectors:

    0-19   STRONG SELL
   20-39   SELL
   40-59   NEUTRAL
   60-79   BUY
   80-100  STRONG BUY

The gauge geometry is a faithful MT5 port of the "Speedometer Toolbox"
Pine Script by rumpypumpydumpy. The original drives its needle with an RSI
"for illustration only"; this edition replaces that with the confluence
engine below and retunes itself per instrument.

THE SIX FACTORS
---------------
Each factor is scored 0-100 and blended by weight (inputs 03):

  Trend       EMA stack (fast/slow) and separation measured in ATR   25
  Momentum    Wilder RSI                                             20
  MACD        Histogram normalised by ATR                            15
  Stochastic  Position in the recent range                           10
  Location    Position inside the Bollinger envelope                 15
  Direction   DMI balance scaled by ADX strength                     15

The blended score is smoothed (EMA) and a gain is applied around 50 so the
needle actually reaches the extremes on quiet instruments.

Every series is computed in-house (Wilder RMA for ATR/RSI/DMI, EMA signal
for MACD) rather than through iATR/iMACD/iADX, so the factors behave the
way the Pine originals do.

AUTO SWITCHING
--------------
On attach the symbol code, description and market path are classified into
one of nine profiles. Each profile supplies its own lengths, smoothing and
gain. Leave "Instrument profile" on Auto, or pick one manually to override.

  Profile           Matches                          EMA     RSI  Smooth Gain
  Volatility fast   Vol 10, Vol 25, every 1s index   13/34   9    5      1.20
  Volatility slow   Vol 50/75/100 (non-1s)           21/55   14   3      1.35
  Boom              Boom 300/500/1000                34/89   21   8      0.95
  Crash             Crash 300/500/1000               34/89   21   8      0.95
  Step Index        Step                             10/30   10   2      1.80
  Jump              Jump 10-100                      21/55   14   5      1.15
  Range Break       Range Break 100/200              13/34   10   3      1.60
  Gold              XAUUSD / spot gold               21/50   14   3      1.30
  Generic           anything else                    21/55   14   3      1.35

Boom/Crash use long windows and a low gain so a single spike cannot throw
the needle to an extreme it cannot justify. Step uses short windows and a
high gain, otherwise the needle never leaves NEUTRAL.

To use your own lengths on any symbol, set "Ignore the profile and use the
values below" = true in inputs 04.

NON-REPAINTING
--------------
The score is taken on closed bars. The needle reads the LAST CLOSED bar
unless "Live needle" is switched on (inputs 03), in which case it follows
the forming bar and will move within the bar.

Alerts fire on a sector change of the last closed bar only, never on the
forming bar, and never for a bar that closed before the indicator was
attached.

INSTALLATION
------------
1. Copy UTT_SpeedometerGauge.mq5 to
       <MT5 data folder>\MQL5\Indicators\UTT\
   (create the UTT folder if it does not exist)
2. Open MetaEditor, open the file, press F7 to compile.
3. Restart MetaTrader 5 or refresh the Navigator, then drag the indicator
   onto any chart. It opens in a separate window below the price chart.

Single self-contained file. No includes, no DLLs.

Give the indicator window enough height for the arc. If the pane is too
short the gauge waits until it fits rather than drawing an ellipse; the
score line and all buffers keep updating regardless.

INPUTS
------
01 GAUGE GEOMETRY   Offset from right edge, auto-fit radius, arc segments,
                    band/edge/needle widths.
02 AUTO SWITCHING   Instrument profile (Auto/manual), show profile name.
03 SCORE ENGINE     Live needle, six factor weights.
04 MANUAL OVERRIDES Ignore profile; EMA/RSI/MACD/Stoch/BB/DMI/ADX/ATR
                    lengths, smoothing, gain.
05 COLOURS          Five sector colours, edge, needle, text, score line.
06 LABELS           Sector labels, ticks, font, font size.
07 ALERTS           Master switch, extremes-only, popup/push/email/sound.
08 PERFORMANCE      Max bars to analyse, instance id (change for a 2nd
                    copy on the same chart).

iCUSTOM BUFFERS (for Expert Advisors)
-------------------------------------
Buffer  Label     Contents
  0     Score     Confluence score 0..100
  1     Sector    1 = STRONG SELL ... 5 = STRONG BUY
  2     F.Trend   Trend factor 0..100
  3     F.RSI     Momentum factor 0..100
  4     F.MACD    MACD factor 0..100
  5     F.Stoch   Stochastic factor 0..100
  6     F.Loc     Location factor 0..100
  7     F.DMI     Direction factor 0..100
  8     Profile   Active profile id (0 Auto, 1 VFast, 2 VSlow, 3 Boom,
                  4 Crash, 5 Step, 6 Jump, 7 Range, 8 Gold, 9 Generic)
  9     Cross     +1 sector stepped up, -1 stepped down, 0 no change

Contract: outside Live needle mode, shift 0 (the forming bar) is
EMPTY_VALUE on every buffer. Read shift 1. Bars inside the warm-up window
are also EMPTY_VALUE rather than flat.

Example:
  int h = iCustom(_Symbol, _Period, "UTT\\UTT_SpeedometerGauge");
  double sec[1]; CopyBuffer(h, 1, 1, 1, sec);   // sector of last closed bar
  if(sec[0] == 5) { /* STRONG BUY */ }

QUICK TUNING
------------
Needle too jumpy       raise Score smoothing, lower Score gain
Needle stuck in NEUTRAL  raise Score gain, shorten lengths
Too many alerts        keep "Only alert on STRONG BUY / STRONG SELL" = true
Two gauges on one chart  set a different Instance id on the second copy

LICENCE
-------
MetaTrader 5 port of "Speedometer Toolbox" (Pine v4) by rumpypumpydumpy,
licensed under the Mozilla Public License 2.0 (https://mozilla.org/MPL/2.0/).
This port is a derivative work and remains under MPL 2.0. The attribution
in the source header must be kept and the source of MPL-covered files must
stay available to recipients. Commercial use and distribution are permitted
under those terms.

The Speedometer Confluence Gauge is a market-reading tool, not a trading
system. Use it alongside your own structure, risk and session rules.
