# Watermark

A watermark is a faint label drawn behind the data of a chart, typically the ticker symbol, the dataset name, or the chart title. Use one when you want chart context that doesn’t compete with the price action for attention.

There are two ways to add a watermark. The single-line shortcut uses `tvl.chart(watermark=tvl.watermark(text=..., color=..., ...))`. The multi-line form takes a list of [`tvl.watermark_line(...)`](#api-reference) entries via `tvl.watermark(lines=[...])`, one per row of text, each with its own color, font size, line height, and font style.

<!-- coverage-seen-elsewhere:
  watermark_visible -> exercised below
  watermark_image_\* -> not yet exercised; covered by docstring on chart()
-->

## What watermarks are useful for?

- **Branding the chart**: A ticker symbol or dataset name in the background tells the viewer what they’re looking at without occupying a corner.
- **Stating context**: A two-line watermark can show, for example, `AAPL` above and `Daily` below: instrument plus timeframe.
- **Styling for theme**: Adjusting color and font-style lets a watermark blend with light or dark themes.
- **Positioning to taste**: `horz_align` and `vert_align` on `tvl.watermark(...)` cover the nine canonical anchor points on the chart.

## Examples

### Add a simple single-line watermark

The shortest watermark: just `tvl.watermark(text=...)`. Defaults take care of color, font size, and alignment.

```python order=basic_watermark,ohlc
import deephaven.plot.tradingview_lightweight as tvl

ohlc = tvl.data.ohlc()

price = tvl.candlestick(ohlc)
basic_watermark = tvl.chart(price, watermark=tvl.watermark(text="AAPL"))
```

The chart shows `AAPL` faintly centered behind the price.

### Style the single-line watermark

The single-line path bundles the styling options on `tvl.watermark()`: color, font size, font style (italic/normal/etc.), line height, and visibility.

```python order=styled_watermark,ohlc
import deephaven.plot.tradingview_lightweight as tvl

ohlc = tvl.data.ohlc()

price = tvl.candlestick(ohlc)

styled_watermark = tvl.chart(
    price,
    watermark=tvl.watermark(
        text="AAPL",
        color="rgba(25,118,210,0.25)",
        font_size=80,
        font_style="italic",
        line_height=1.0,
        visible=True,
    ),
)
```

The watermark is now a large, semi-transparent, italicized blue label.

### Multi-line watermark

For two or more lines, switch to `tvl.watermark(lines=[...])`. Each entry is built with `tvl.watermark_line(...)` and renders as its own line of text with optional per-line styling: color, font size, line height, and font style.

```python order=multi_watermark,ohlc
import deephaven.plot.tradingview_lightweight as tvl

ohlc = tvl.data.ohlc()

price = tvl.candlestick(ohlc)

lines = [
    tvl.watermark_line(
        "AAPL",
        color="rgba(25,118,210,0.35)",
        font_size=72,
        line_height=80.0,
    ),
    tvl.watermark_line(
        "Daily",
        color="rgba(150, 150, 150, 0.55)",
        font_size=32,
        line_height=40.0,
        font_style="italic",
    ),
]

multi_watermark = tvl.chart(price, watermark=tvl.watermark(lines=lines))
```

Two lines, two styles. The single-line shortcut and `lines` are mutually exclusive, so pick one.

### Position the watermark

`horz_align` accepts `"left"`, `"center"`, `"right"` (the values of `HorzAlign`). `vert_align` accepts `"top"`, `"center"`, `"bottom"` (the values of `VertAlign`). Together they give nine anchor positions; here we cover every value of each enum across three charts.

```python order=top_left,top_center,top_right,middle_left,middle_center,middle_right,bottom_left,bottom_center,bottom_right,ohlc
import deephaven.plot.tradingview_lightweight as tvl

ohlc = tvl.data.ohlc()

def _wm(horz, vert):
    return tvl.chart(
        tvl.candlestick(ohlc),
        watermark=tvl.watermark(
            text=f"{horz}/{vert}",
            color="rgba(25,118,210,0.35)",
            font_size=40,
            horz_align=horz,
            vert_align=vert,
        ),
    )

top_left      = _wm("left",   "top")
top_center    = _wm("center", "top")
top_right     = _wm("right",  "top")
middle_left   = _wm("left",   "center")
middle_center = _wm("center", "center")
middle_right  = _wm("right",  "center")
bottom_left   = _wm("left",   "bottom")
bottom_center = _wm("center", "bottom")
bottom_right  = _wm("right",  "bottom")
```

Nine variants, one for each combination of `HorzAlign` and `VertAlign`.

### Hide the watermark

`visible=False` keeps the configuration but skips drawing. Useful when toggling a watermark on and off without rebuilding the chart configuration.

```python order=hidden_watermark,ohlc
import deephaven.plot.tradingview_lightweight as tvl

ohlc = tvl.data.ohlc()

price = tvl.candlestick(ohlc)
hidden_watermark = tvl.chart(
    price,
    watermark=tvl.watermark(
        text="AAPL",
        color="rgba(25,118,210,0.35)",
        visible=False,
    ),
)
```

The chart shows no watermark even though `text` is set.

### Image watermark

In addition to text, the chart accepts an image watermark (logo or background graphic). Set `tvl.watermark_image(url=...)` and tune `max_width`, `max_height`, `padding`, and `alpha`. The image-watermark path is independent from the text-watermark path; both can coexist.

```python order=image_watermark,ohlc
import deephaven.plot.tradingview_lightweight as tvl

ohlc = tvl.data.ohlc()

price = tvl.candlestick(ohlc)
image_watermark = tvl.chart(
    price,
    watermark_image=tvl.watermark_image(
        url="https://www.deephaven.io/img/dh-community-logo.svg",
        max_width=200,
        max_height=80,
        padding=12,
        alpha=0.2,
        visible=True,
    ),
)
```

The Deephaven logo appears behind the data at 20% opacity.

## API Reference

The text watermark is configured with `tvl.watermark(...)` (returning a
`Watermark`) passed to `watermark=` on `tvl.chart()`; the image watermark uses
`tvl.watermark_image(...)` (returning a `WatermarkImage`) passed to
`watermark_image=`. `tvl.watermark_line(...)` builds each entry of the
multi-line form. See the [Chart container](chart.md) page for the full
`tvl.chart` API.

Create a Watermark config for tvl.chart(watermark=...).

**Returns:** `Watermark` A text-watermark config for tvl.chart(watermark=...).

<ParamTable param={{"module_name": "deephaven.plot.tradingview_lightweight.", "name": "watermark", "parameters": [{"name": "text", "type": "str | None", "description": "Single-line watermark text.", "default": "None"}, {"name": "color", "type": "Literal['gray-50', 'gray-75', 'gray-100', 'gray-200', 'gray-300', 'gray-400', 'gray-500', 'gray-600', 'gray-700', 'gray-800', 'gray-900', 'red-100', 'red-200', 'red-300', 'red-400', 'red-500', 'red-600', 'red-700', 'red-800', 'red-900', 'red-1000', 'red-1100', 'red-1200', 'red-1300', 'red-1400', 'orange-100', 'orange-200', 'orange-300', 'orange-400', 'orange-500', 'orange-600', 'orange-700', 'orange-800', 'orange-900', 'orange-1000', 'orange-1100', 'orange-1200', 'orange-1300', 'orange-1400', 'yellow-100', 'yellow-200', 'yellow-300', 'yellow-400', 'yellow-500', 'yellow-600', 'yellow-700', 'yellow-800', 'yellow-900', 'yellow-1000', 'yellow-1100', 'yellow-1200', 'yellow-1300', 'yellow-1400', 'chartreuse-100', 'chartreuse-200', 'chartreuse-300', 'chartreuse-400', 'chartreuse-500', 'chartreuse-600', 'chartreuse-700', 'chartreuse-800', 'chartreuse-900', 'chartreuse-1000', 'chartreuse-1100', 'chartreuse-1200', 'chartreuse-1300', 'chartreuse-1400', 'celery-100', 'celery-200', 'celery-300', 'celery-400', 'celery-500', 'celery-600', 'celery-700', 'celery-800', 'celery-900', 'celery-1000', 'celery-1100', 'celery-1200', 'celery-1300', 'celery-1400', 'green-100', 'green-200', 'green-300', 'green-400', 'green-500', 'green-600', 'green-700', 'green-800', 'green-900', 'green-1000', 'green-1100', 'green-1200', 'green-1300', 'green-1400', 'seafoam-100', 'seafoam-200', 'seafoam-300', 'seafoam-400', 'seafoam-500', 'seafoam-600', 'seafoam-700', 'seafoam-800', 'seafoam-900', 'seafoam-1000', 'seafoam-1100', 'seafoam-1200', 'seafoam-1300', 'seafoam-1400', 'cyan-100', 'cyan-200', 'cyan-300', 'cyan-400', 'cyan-500', 'cyan-600', 'cyan-700', 'cyan-800', 'cyan-900', 'cyan-1000', 'cyan-1100', 'cyan-1200', 'cyan-1300', 'cyan-1400', 'blue-100', 'blue-200', 'blue-300', 'blue-400', 'blue-500', 'blue-600', 'blue-700', 'blue-800', 'blue-900', 'blue-1000', 'blue-1100', 'blue-1200', 'blue-1300', 'blue-1400', 'indigo-100', 'indigo-200', 'indigo-300', 'indigo-400', 'indigo-500', 'indigo-600', 'indigo-700', 'indigo-800', 'indigo-900', 'indigo-1000', 'indigo-1100', 'indigo-1200', 'indigo-1300', 'indigo-1400', 'purple-100', 'purple-200', 'purple-300', 'purple-400', 'purple-500', 'purple-600', 'purple-700', 'purple-800', 'purple-900', 'purple-1000', 'purple-1100', 'purple-1200', 'purple-1300', 'purple-1400', 'fuchsia-100', 'fuchsia-200', 'fuchsia-300', 'fuchsia-400', 'fuchsia-500', 'fuchsia-600', 'fuchsia-700', 'fuchsia-800', 'fuchsia-900', 'fuchsia-1000', 'fuchsia-1100', 'fuchsia-1200', 'fuchsia-1300', 'fuchsia-1400', 'magenta-100', 'magenta-200', 'magenta-300', 'magenta-400', 'magenta-500', 'magenta-600', 'magenta-700', 'magenta-800', 'magenta-900', 'magenta-1000', 'magenta-1100', 'magenta-1200', 'magenta-1300', 'magenta-1400', 'negative', 'notice', 'positive', 'info', 'accent', 'accent-100', 'accent-200', 'accent-300', 'accent-400', 'accent-500', 'accent-600', 'accent-700', 'accent-800', 'accent-900', 'accent-1000', 'accent-1100', 'accent-1200', 'accent-1300', 'accent-1400', 'bg', 'content-bg', 'subdued-content-bg', 'surface-bg', 'fg'] | str | None", "description": "Text color (single-line only).", "default": "None"}, {"name": "visible", "type": "bool | None", "description": "Show the watermark (defaults to True when text/lines given).", "default": "None"}, {"name": "font_size", "type": "int | None", "description": "Font size in pixels (single-line only).", "default": "None"}, {"name": "font_style", "type": "str | None", "description": "CSS font-style, e.g. \"italic\" (single-line only).", "default": "None"}, {"name": "line_height", "type": "float | None", "description": "Line height in pixels (single-line only).", "default": "None"}, {"name": "horz_align", "type": "Literal['left', 'center', 'right'] | None", "description": "Horizontal alignment; see HorzAlign.", "default": "None"}, {"name": "vert_align", "type": "Literal['top', 'center', 'bottom'] | None", "description": "Vertical alignment; see VertAlign.", "default": "None"}, {"name": "lines", "type": "list[WatermarkLine] | None", "description": "List of WatermarkLine for a multi-line watermark (build each with watermark_line()).", "default": "None"}]}} />
Create a WatermarkImage for tvl.chart(watermark_image=...).

**Returns:** `WatermarkImage` An image-watermark config for tvl.chart(watermark_image=...).

<ParamTable param={{"module_name": "deephaven.plot.tradingview_lightweight.", "name": "watermark_image", "parameters": [{"name": "url", "type": "str | None", "description": "Image URL.", "default": "None"}, {"name": "max_width", "type": "int | None", "description": "Maximum image width in pixels.", "default": "None"}, {"name": "max_height", "type": "int | None", "description": "Maximum image height in pixels.", "default": "None"}, {"name": "padding", "type": "int | None", "description": "Padding around the image in pixels.", "default": "None"}, {"name": "alpha", "type": "float | None", "description": "Image opacity (0-1).", "default": "None"}, {"name": "visible", "type": "bool | None", "description": "Show the image watermark (defaults to True when url given).", "default": "None"}]}} />
Pass a list of watermark_line(...) results to
tvl.chart(..., watermark_lines=[...]) to draw a stacked
multi-line watermark behind the chart.  All fields except text
are optional; omitted fields inherit TVL defaults
(font_size=48, color a theme-derived semi-transparent value,
line_height=1.2 * font_size, font_style='').

**Returns:** `WatermarkLine` A WatermarkLine instance suitable for
passing inside watermark_lines=[...].

<ParamTable param={{"module_name": "deephaven.plot.tradingview_lightweight.", "name": "watermark_line", "parameters": [{"name": "text", "type": "str", "description": "The watermark text.  Required (the line is skipped if empty)."}, {"name": "color", "type": "Optional[Color]", "description": "CSS color string.  Defaults to a theme-derived semi-transparent color.", "default": "None"}, {"name": "font_size", "type": "Optional[int]", "description": "Font size in pixels.  Defaults to 48.", "default": "None"}, {"name": "line_height", "type": "Optional[float]", "description": "Line height in pixels.  Defaults to 1.2 * font_size.", "default": "None"}, {"name": "font_style", "type": "Optional[str]", "description": "CSS font-style string, e.g. \"italic\".  Defaults to \"\".", "default": "None"}]}} />