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(...) entries via tvl.watermark(lines=[...]), one per row of text, each with its own color, font size, line height, and font style.

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.

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.

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.

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.

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.

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.

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 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=...).

Parameters	Type	Default	Description
text	str \| None	None	Single-line watermark text.
color	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	None	Text color (single-line only).
visible	bool \| None	None	Show the watermark (defaults to True when text/lines given).
font_size	int \| None	None	Font size in pixels (single-line only).
font_style	str \| None	None	CSS font-style, e.g. "italic" (single-line only).
line_height	float \| None	None	Line height in pixels (single-line only).
horz_align	Literal['left', 'center', 'right'] \| None	None	Horizontal alignment; see HorzAlign.
vert_align	Literal['top', 'center', 'bottom'] \| None	None	Vertical alignment; see VertAlign.
lines	list[WatermarkLine] \| None	None	List of WatermarkLine for a multi-line watermark (build each with watermark_line()).

Create a WatermarkImage for tvl.chart(watermark_image=...).

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

Parameters	Type	Default	Description
url	str \| None	None	Image URL.
max_width	int \| None	None	Maximum image width in pixels.
max_height	int \| None	None	Maximum image height in pixels.
padding	int \| None	None	Padding around the image in pixels.
alpha	float \| None	None	Image opacity (0-1).
visible	bool \| None	None	Show the image watermark (defaults to True when url given).

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=[...].

Parameters	Type	Default	Description
text	str		The watermark text. Required (the line is skipped if empty).
color	Optional[Color]	None	CSS color string. Defaults to a theme-derived semi-transparent color.
font_size	Optional[int]	None	Font size in pixels. Defaults to 48.
line_height	Optional[float]	None	Line height in pixels. Defaults to 1.2 * font_size.
font_style	Optional[str]	None	CSS font-style string, e.g. "italic". Defaults to "".