# Watermark

A watermark is faint text or an image drawn behind a chart’s data, such as a brand, a disclaimer, or an environment name like “staging”. It is drawn faintly so it doesn’t compete with the series.

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**: an organisation or product name behind the data, marking where the chart came from.
- **Disclaiming**: a standing notice such as “internal use only”, “not investment advice”, or “sample data”.
- **Flagging the environment**: “staging”, “dev”, or “replay”, so a screenshot cannot be mistaken for production.
- **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="ACME CAPITAL"))
```

The chart shows `ACME CAPITAL` 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="ACME CAPITAL",
        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 mark.

### 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(
        "ACME CAPITAL",
        color="rgba(25,118,210,0.35)",
        font_size=72,
        line_height=80.0,
    ),
    tvl.watermark_line(
        "Internal use only",
        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="ACME CAPITAL",
        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, returning a `WatermarkLine`. 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"}]}} />