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(...) 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: 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.

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.

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.

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.

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

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 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 "".