color_tools.image.watermark

Watermarking functionality for images.

This module provides tools for adding text, image, and SVG watermarks to images with support for positioning, transparency, custom fonts, and text styling.

Functions:

add_text_watermark: Add text watermark with custom fonts and styling add_image_watermark: Add image (PNG) watermark with transparency add_svg_watermark: Add SVG watermark (requires cairosvg)

Example:

>>> from color_tools.image import add_text_watermark
>>> from PIL import Image
>>>
>>> # Add simple text watermark
>>> img = Image.open("photo.jpg")
>>> result = add_text_watermark(
...     img,
...     text="© 2025 My Brand",
...     position="bottom-right",
...     font_size=24,
...     color=(255, 255, 255),
...     opacity=0.8
... )
>>> result.save("watermarked.jpg")
>>>
>>> # Add text with stroke outline
>>> result = add_text_watermark(
...     img,
...     text="SAMPLE",
...     position="center",
...     font_size=72,
...     color=(255, 255, 255),
...     stroke_color=(0, 0, 0),
...     stroke_width=3,
...     opacity=0.5
... )
>>>
>>> # Add logo watermark from SVG
>>> from color_tools.image import add_svg_watermark
>>> result = add_svg_watermark(
...     img,
...     svg_path="logo.svg",
...     position="top-left",
...     scale=0.2,
...     opacity=0.7
... )
color_tools.image.watermark.add_text_watermark(image, text, position='bottom-right', font_name=None, font_file=None, font_size=24, color=(255, 255, 255), opacity=0.8, stroke_color=None, stroke_width=0, margin=10)[source]

Add a text watermark to an image.

Parameters:

  • image (Image) – PIL Image to watermark

  • text (str) – Text to display

  • position (Union[Literal['top-left', 'top-center', 'top-right', 'center-left', 'center', 'center-right', 'bottom-left', 'bottom-center', 'bottom-right'], tuple[int, int]]) – Position preset or (x, y) coordinates

  • font_name (str | None) – System font name (e.g., “Arial”)

  • font_file (str | None) – Custom font file (path or filename in fonts/)

  • font_size (int) – Font size in points

  • color (tuple[int, int, int]) – Text color as (R, G, B)

  • opacity (float) – Opacity from 0.0 (transparent) to 1.0 (opaque)

  • stroke_color (tuple[int, int, int] | None) – Outline color as (R, G, B), or None for no stroke

  • stroke_width (int) – Outline width in pixels (0 for no stroke)

  • margin (int) – Margin from edges for preset positions

Return type:

Image

Returns:

New image with watermark applied

Example

>>> img = Image.open("photo.jpg")
>>> result = add_text_watermark(
...     img,
...     text="© 2025",
...     position="bottom-right",
...     font_file="Roboto-Bold.ttf",
...     font_size=32,
...     color=(255, 255, 255),
...     stroke_color=(0, 0, 0),
...     stroke_width=2,
...     opacity=0.7
... )
color_tools.image.watermark.add_image_watermark(image, watermark_path, position='bottom-right', scale=1.0, opacity=0.8, margin=10)[source]

Add an image watermark (e.g., logo PNG) to an image.

Parameters:

  • image (Image) – PIL Image to watermark

  • watermark_path (str | Path) – Path to watermark image file (PNG recommended)

  • position (Union[Literal['top-left', 'top-center', 'top-right', 'center-left', 'center', 'center-right', 'bottom-left', 'bottom-center', 'bottom-right'], tuple[int, int]]) – Position preset or (x, y) coordinates

  • scale (float) – Scale factor for watermark (1.0 = original size)

  • opacity (float) – Opacity from 0.0 (transparent) to 1.0 (opaque)

  • margin (int) – Margin from edges for preset positions

Return type:

Image

Returns:

New image with watermark applied

Example

>>> img = Image.open("photo.jpg")
>>> result = add_image_watermark(
...     img,
...     watermark_path="logo.png",
...     position="top-left",
...     scale=0.2,
...     opacity=0.7
... )
color_tools.image.watermark.add_svg_watermark(image, svg_path, position='bottom-right', scale=1.0, opacity=0.8, margin=10, width=None, height=None)[source]

Add an SVG watermark (e.g., vector logo) to an image.

Requires cairosvg to be installed:

pip install color-match-tools[image]

Parameters:

  • image (Image) – PIL Image to watermark

  • svg_path (str | Path) – Path to SVG file

  • position (Union[Literal['top-left', 'top-center', 'top-right', 'center-left', 'center', 'center-right', 'bottom-left', 'bottom-center', 'bottom-right'], tuple[int, int]]) – Position preset or (x, y) coordinates

  • scale (float) – Scale factor for watermark (1.0 = original size)

  • opacity (float) – Opacity from 0.0 (transparent) to 1.0 (opaque)

  • margin (int) – Margin from edges for preset positions

  • width (int | None) – Explicit width in pixels (overrides scale)

  • height (int | None) – Explicit height in pixels (overrides scale)

Return type:

Image

Returns:

New image with watermark applied

Raises:

ImportError – If cairosvg is not installed

Example

>>> img = Image.open("photo.jpg")
>>> result = add_svg_watermark(
...     img,
...     svg_path="logo.svg",
...     position="top-right",
...     width=200,
...     opacity=0.6
... )