0
# Watermarks
1

2
Watermarks allow you to add image overlays to your plots for branding, attribution, or decorative purposes. The watermark functionality in plotnine provides flexible positioning and styling options to integrate images seamlessly with your visualizations.
3

4
## Capabilities
5

6
### Watermark Function
7

8
Add image watermarks with customizable positioning, transparency, and styling.
9

10
```python { .api }
11
def watermark(filename, xo=None, yo=None, alpha=0.5, **kwargs):
12
    """
13
    Add image watermark to plot.
14
    
15
    Overlays an image on the plot at specified coordinates with configurable
16
    transparency and positioning options. Useful for adding logos, attribution
17
    marks, or decorative elements.
18
    
19
    Parameters:
20
    - filename: str, path to watermark image file (supports PNG, JPG, etc.)
21
    - xo: float, x-axis offset for watermark positioning (data coordinates)
22
    - yo: float, y-axis offset for watermark positioning (data coordinates)
23
    - alpha: float, transparency level (0=fully transparent, 1=fully opaque)
24
    - **kwargs: additional matplotlib image parameters
25
      - extent: tuple, (left, right, bottom, top) positioning in data coordinates
26
      - aspect: str, aspect ratio handling ('auto', 'equal')
27
      - interpolation: str, image interpolation method
28
      - resample: bool, whether to resample image
29
      - url: str, URL for clickable watermarks
30
      - zorder: float, drawing order (higher values drawn on top)
31
    
32
    Returns:
33
    Watermark layer that can be added to ggplot objects
34
    """
35
```
36

37
## Usage Patterns
38

39
### Basic Watermark Application
40
```python
41
# Add logo watermark to bottom right
42
ggplot(data, aes(x='x', y='y')) + \
43
    geom_point() + \
44
    watermark('logo.png', xo=0.8, yo=0.1, alpha=0.7)
45

46
# Add watermark with custom transparency
47
ggplot(data, aes(x='date', y='value')) + \
48
    geom_line() + \
49
    watermark('company_logo.png', alpha=0.3)
50
```
51

52
### Positioning Control
53
```python
54
# Position watermark using data coordinates
55
max_x = data['x'].max()
56
max_y = data['y'].max()
57

58
ggplot(data, aes(x='x', y='y')) + \
59
    geom_scatter() + \
60
    watermark('watermark.png', xo=max_x * 0.8, yo=max_y * 0.9, alpha=0.5)
61

62
# Use extent for precise positioning
63
ggplot(data, aes(x='year', y='sales')) + \
64
    geom_line() + \
65
    watermark('brand.png', extent=(2015, 2018, 50, 100), alpha=0.4)
66
```
67

68
### Multiple Watermarks
69
```python
70
# Add multiple watermarks for complex branding
71
ggplot(data, aes(x='x', y='y')) + \
72
    geom_point() + \
73
    watermark('logo.png', xo=0.05, yo=0.95, alpha=0.8) + \  # Top left
74
    watermark('attribution.png', xo=0.95, yo=0.05, alpha=0.6)  # Bottom right
75
```
76

77
### Watermark Styling
78
```python
79
# Control drawing order and appearance
80
ggplot(data, aes(x='x', y='y')) + \
81
    geom_point() + \
82
    watermark('background.png', alpha=0.2, zorder=0) + \  # Behind points
83
    watermark('foreground.png', alpha=0.8, zorder=10)     # In front of points
84

85
# Custom interpolation for image quality
86
ggplot(data, aes(x='x', y='y')) + \
87
    geom_point() + \
88
    watermark('high_res_logo.png', alpha=0.7, 
89
              interpolation='bilinear', resample=True)
90
```
91

92
### Professional Applications
93
```python
94
# Corporate report watermark
95
ggplot(sales_data, aes(x='quarter', y='revenue')) + \
96
    geom_col(fill='steelblue') + \
97
    watermark('company_logo.png', xo=0.85, yo=0.9, alpha=0.6) + \
98
    theme_minimal() + \
99
    labs(title='Quarterly Revenue Report',
100
         subtitle='Confidential - Internal Use Only')
101

102
# Academic publication watermark
103
ggplot(research_data, aes(x='treatment', y='response')) + \
104
    geom_boxplot() + \
105
    watermark('university_seal.png', xo=0.02, yo=0.02, alpha=0.3) + \
106
    theme_classic() + \
107
    labs(title='Treatment Effect Analysis')
108
```
109

110
### Integration with Themes and Layouts
111
```python
112
# Watermark that adapts to theme
113
ggplot(data, aes(x='x', y='y', color='group')) + \
114
    geom_point() + \
115
    facet_wrap('category') + \
116
    watermark('logo.png', alpha=0.4) + \
117
    theme_dark()  # Watermark works with dark theme
118

119
# Conditional watermarks based on data
120
if data['confidential'].any():
121
    plot += watermark('confidential.png', xo=0.5, yo=0.5, alpha=0.8)
122
```
123

124
### File Format Support
125
```python
126
# Different image formats
127
ggplot(data, aes(x='x', y='y')) + \
128
    geom_point() + \
129
    watermark('logo.png', alpha=0.7)      # PNG with transparency
130

131
ggplot(data, aes(x='x', y='y')) + \
132
    geom_point() + \
133
    watermark('photo.jpg', alpha=0.5)     # JPEG format
134

135
ggplot(data, aes(x='x', y='y')) + \
136
    geom_point() + \
137
    watermark('vector.svg', alpha=0.6)    # SVG format (if supported)
138
```
139

140
### Dynamic Watermark Positioning
141
```python
142
# Position based on plot data range
143
x_range = data['x'].max() - data['x'].min()
144
y_range = data['y'].max() - data['y'].min()
145

146
ggplot(data, aes(x='x', y='y')) + \
147
    geom_point() + \
148
    watermark('logo.png', 
149
              xo=data['x'].min() + x_range * 0.1,
150
              yo=data['y'].max() - y_range * 0.1,
151
              alpha=0.6)
152
```
153

154
### Error Handling and Best Practices
155
```python
156
# Handle missing watermark files gracefully
157
import os
158

159
watermark_file = 'logo.png'
160
plot = ggplot(data, aes(x='x', y='y')) + geom_point()
161

162
if os.path.exists(watermark_file):
163
    plot += watermark(watermark_file, alpha=0.6)
164
else:
165
    print(f"Watermark file {watermark_file} not found")
166

167
# Optimize watermark size for performance
168
# Use appropriately sized images to avoid memory issues with large plots
169
```
170

171
## Technical Notes
172

173
### Coordinate System Interaction
174
- Watermark positioning uses the plot's data coordinate system
175
- Position values correspond to the actual x and y axis values
176
- Watermarks are affected by coordinate transformations (log scales, etc.)
177

178
### Performance Considerations
179
- Large watermark images can impact plot rendering performance
180
- Consider resizing watermark images to appropriate dimensions before use
181
- Use appropriate alpha values to balance visibility and subtlety
182

183
### Layer Ordering
184
- Watermarks can be positioned above or below other plot elements using zorder
185
- Default zorder places watermarks above most plot elements
186
- Adjust zorder for proper layering with annotations and other elements
187

188
### File Path Handling
189
- Supports both absolute and relative file paths
190
- Relative paths are resolved from the current working directory
191
- Consider using absolute paths for production applications
192

193
## Common Use Cases
194

195
### Branding and Attribution
196
```python
197
# Company branding
198
ggplot(data, aes(x='metric', y='value')) + \
199
    geom_col() + \
200
    watermark('company_logo.png', xo=0.9, yo=0.1, alpha=0.5) + \
201
    theme_minimal()
202
```
203

204
### Confidentiality Marking
205
```python
206
# Confidential data marking
207
ggplot(sensitive_data, aes(x='x', y='y')) + \
208
    geom_point() + \
209
    watermark('confidential_stamp.png', xo=0.5, yo=0.5, alpha=0.7)
210
```
211

212
### Decorative Elements
213
```python
214
# Subtle background decoration
215
ggplot(data, aes(x='x', y='y')) + \
216
    watermark('subtle_pattern.png', alpha=0.1, zorder=0) + \
217
    geom_point() + \
218
    theme_void()
219
```