0
# Main Rendering Interface
1
2
The Pilmoji class provides the core emoji rendering functionality for Pillow images. It manages emoji placement, text layout, resource lifecycle, and offers comprehensive control over rendering parameters through a context manager interface.
3
4
## Capabilities
5
6
### Pilmoji Class
7
8
Main emoji rendering interface that handles text rendering with emoji substitution, supporting both Unicode emojis and Discord custom emojis with configurable positioning, scaling, and source providers.
9
10
```python { .api }
11
class Pilmoji:
12
"""
13
The main emoji rendering interface.
14
15
Parameters:
16
- image: PIL.Image.Image - The Pillow image to render on
17
- source: Union[BaseSource, Type[BaseSource]] - Emoji source (defaults to Twemoji)
18
- cache: bool - Whether to cache emojis (default: True)
19
- draw: Optional[ImageDraw.ImageDraw] - Drawing instance (auto-created if None)
20
- render_discord_emoji: bool - Enable Discord emoji rendering (default: True)
21
- emoji_scale_factor: float - Default emoji scaling factor (default: 1.0)
22
- emoji_position_offset: Tuple[int, int] - Default emoji position offset (default: (0, 0))
23
"""
24
25
def __init__(
26
self,
27
image: Image.Image,
28
*,
29
source: Union[BaseSource, Type[BaseSource]] = Twemoji,
30
cache: bool = True,
31
draw: Optional[ImageDraw.ImageDraw] = None,
32
render_discord_emoji: bool = True,
33
emoji_scale_factor: float = 1.0,
34
emoji_position_offset: Tuple[int, int] = (0, 0)
35
) -> None: ...
36
```
37
38
#### Usage Example
39
40
```python
41
from pilmoji import Pilmoji
42
from pilmoji.source import MicrosoftEmojiSource
43
from PIL import Image, ImageFont
44
45
# Create image and font
46
image = Image.new('RGB', (400, 100), (255, 255, 255))
47
font = ImageFont.load_default()
48
49
# Use Microsoft emoji source with custom scaling
50
with Pilmoji(
51
image,
52
source=MicrosoftEmojiSource,
53
emoji_scale_factor=1.2,
54
emoji_position_offset=(0, -2)
55
) as pilmoji:
56
pilmoji.text((10, 10), "Hello! π How are you? π", (0, 0, 0), font)
57
```
58
59
### Text Rendering
60
61
Renders text with emoji support, handling multi-line text, custom positioning, and extensive formatting options compatible with Pillow's ImageDraw.text interface.
62
63
```python { .api }
64
def text(
65
self,
66
xy: Tuple[int, int],
67
text: str,
68
fill: ColorT = None,
69
font: FontT = None,
70
anchor: str = None,
71
spacing: int = 4,
72
node_spacing: int = 0,
73
align: str = "left",
74
direction: str = None,
75
features: str = None,
76
language: str = None,
77
stroke_width: int = 0,
78
stroke_fill: ColorT = None,
79
embedded_color: bool = False,
80
*args,
81
emoji_scale_factor: float = None,
82
emoji_position_offset: Tuple[int, int] = None,
83
**kwargs
84
) -> None:
85
"""
86
Draws text with emoji rendering support, including multi-line text.
87
88
Parameters:
89
- xy: Tuple[int, int] - Position to render text
90
- text: str - Text to render (supports Unicode and Discord emojis)
91
- fill: ColorT - Text color
92
- font: FontT - Font to use
93
- spacing: int - Line spacing in pixels (default: 4)
94
- node_spacing: int - Spacing between text/emoji nodes (default: 0)
95
- emoji_scale_factor: float - Emoji scaling override
96
- emoji_position_offset: Tuple[int, int] - Emoji position offset override
97
- Additional parameters inherited from Pillow's ImageDraw.text
98
"""
99
```
100
101
#### Usage Example
102
103
```python
104
# Multi-line text with custom emoji positioning
105
multiline_text = """
106
Welcome to our app! π
107
Features include:
108
β’ Fast processing β‘
109
β’ Beautiful UI π¨
110
β’ Discord support <:custom:123456789>
111
"""
112
113
with Pilmoji(image) as pilmoji:
114
pilmoji.text(
115
(20, 20),
116
multiline_text.strip(),
117
fill=(50, 50, 50),
118
font=font,
119
spacing=6,
120
node_spacing=2,
121
emoji_scale_factor=1.1,
122
emoji_position_offset=(1, -1)
123
)
124
```
125
126
### Text Size Calculation
127
128
Calculates text dimensions including emoji substitutions, supporting multi-line text and custom emoji scaling for accurate layout planning.
129
130
```python { .api }
131
def getsize(
132
self,
133
text: str,
134
font: FontT = None,
135
*,
136
spacing: int = 4,
137
emoji_scale_factor: float = None
138
) -> Tuple[int, int]:
139
"""
140
Calculate width and height of text when rendered with emojis.
141
142
Parameters:
143
- text: str - Text to measure
144
- font: FontT - Font to use for measurement
145
- spacing: int - Line spacing (default: 4)
146
- emoji_scale_factor: float - Emoji scaling factor
147
148
Returns:
149
- Tuple[int, int] - (width, height) of rendered text
150
"""
151
```
152
153
#### Usage Example
154
155
```python
156
text = "Hello! π This is a test π§ͺ"
157
158
with Pilmoji(image) as pilmoji:
159
width, height = pilmoji.getsize(text, font, emoji_scale_factor=1.2)
160
print(f"Text dimensions: {width}x{height}")
161
162
# Use dimensions for centering
163
image_width, image_height = image.size
164
x = (image_width - width) // 2
165
y = (image_height - height) // 2
166
167
pilmoji.text((x, y), text, (0, 0, 0), font)
168
```
169
170
### Context Manager Support
171
172
Automatic resource management through context manager protocol, ensuring proper cleanup of HTTP sessions, cached emoji streams, and drawing resources.
173
174
```python { .api }
175
def __enter__(self) -> Pilmoji: ...
176
177
def __exit__(self, *_) -> None: ...
178
179
def open(self) -> None:
180
"""
181
Re-opens closed renderer.
182
183
Raises:
184
- ValueError: If renderer is already open
185
"""
186
187
def close(self) -> None:
188
"""
189
Safely closes renderer and cleans up resources.
190
191
Raises:
192
- ValueError: If renderer is already closed
193
"""
194
```
195
196
#### Usage Example
197
198
```python
199
# Automatic resource management
200
with Pilmoji(image) as pilmoji:
201
pilmoji.text((10, 10), "Emoji text π", (0, 0, 0), font)
202
# Resources automatically cleaned up
203
204
# Manual resource management
205
pilmoji = Pilmoji(image)
206
try:
207
pilmoji.text((10, 10), "Emoji text π", (0, 0, 0), font)
208
finally:
209
pilmoji.close()
210
```