0
# Pilmoji
1

2
Pilmoji is an emoji renderer for Pillow (Python Imaging Library) that enables rendering both Unicode emojis and Discord custom emojis within images. It offers comprehensive multi-line text rendering capabilities with fine-grained control over emoji positioning, scaling, and supports multiple emoji sources including Twemoji, Microsoft, Apple, and custom sources through subclassing.
3

4
## Package Information
5

6
- **Package Name**: pilmoji
7
- **Language**: Python
8
- **Installation**: `pip install pilmoji` or `pip install pilmoji[requests]` for enhanced HTTP performance
9

10
## Core Imports
11

12
```python
13
from pilmoji import Pilmoji
14
```
15

16
For emoji sources:
17

18
```python
19
from pilmoji.source import MicrosoftEmojiSource, AppleEmojiSource, Twemoji
20
```
21

22
For helpers and utilities:
23

24
```python
25
from pilmoji import Node, NodeType, getsize, to_nodes
26
```
27

28
## Basic Usage
29

30
```python
31
from pilmoji import Pilmoji
32
from PIL import Image, ImageFont
33

34
# Create an image
35
image = Image.new('RGB', (550, 80), (255, 255, 255))
36
font = ImageFont.truetype('arial.ttf', 24)
37

38
# Text with emojis
39
text = '''
40
Hello, world! 👋 Here are some emojis: 🎨 🌊 😎
41
I also support Discord emoji: <:rooThink:596576798351949847>
42
'''
43

44
# Render text with emoji support
45
with Pilmoji(image) as pilmoji:
46
    pilmoji.text((10, 10), text.strip(), (0, 0, 0), font)
47

48
image.show()
49
```
50

51
## Architecture
52

53
Pilmoji uses a modular architecture built around three core components:
54

55
- **Pilmoji Class**: Main rendering interface that manages emoji placement, text layout, and resource lifecycle through context manager pattern
56
- **Source System**: Pluggable emoji providers (BaseSource hierarchy) that fetch emoji images from various sources like Twitter, Apple, Microsoft, or custom CDNs
57
- **Node Parser**: Text analysis system that breaks strings into structured nodes (text, unicode emoji, Discord emoji) for precise rendering control
58

59
This design enables flexible emoji rendering pipelines that can be easily customized with different emoji styles, caching strategies, and rendering parameters while maintaining compatibility with existing Pillow workflows.
60

61
## Capabilities
62

63
### Main Rendering Interface
64

65
Core emoji rendering functionality through the Pilmoji class, providing context manager support, resource management, and comprehensive text rendering with emoji substitution capabilities.
66

67
```python { .api }
68
class Pilmoji:
69
    def __init__(
70
        self,
71
        image: Image.Image,
72
        *,
73
        source: Union[BaseSource, Type[BaseSource]] = Twemoji,
74
        cache: bool = True,
75
        draw: Optional[ImageDraw.ImageDraw] = None,
76
        render_discord_emoji: bool = True,
77
        emoji_scale_factor: float = 1.0,
78
        emoji_position_offset: Tuple[int, int] = (0, 0)
79
    ) -> None: ...
80
    
81
    def text(
82
        self,
83
        xy: Tuple[int, int],
84
        text: str,
85
        fill: ColorT = None,
86
        font: FontT = None,
87
        anchor: str = None,
88
        spacing: int = 4,
89
        node_spacing: int = 0,
90
        align: str = "left",
91
        direction: str = None,
92
        features: str = None,
93
        language: str = None,
94
        stroke_width: int = 0,
95
        stroke_fill: ColorT = None,
96
        embedded_color: bool = False,
97
        *args,
98
        emoji_scale_factor: float = None,
99
        emoji_position_offset: Tuple[int, int] = None,
100
        **kwargs
101
    ) -> None: ...
102
    
103
    def getsize(
104
        self,
105
        text: str,
106
        font: FontT = None,
107
        *,
108
        spacing: int = 4,
109
        emoji_scale_factor: float = None
110
    ) -> Tuple[int, int]: ...
111
```
112

113
[Main Rendering Interface](./core-rendering.md)
114

115
### Emoji Sources
116

117
Comprehensive system for fetching emoji images from various providers including Twitter, Apple, Microsoft, Google, and custom sources, with built-in Discord emoji support and HTTP optimization.
118

119
```python { .api }
120
class BaseSource(ABC):
121
    def get_emoji(self, emoji: str, /) -> Optional[BytesIO]: ...
122
    def get_discord_emoji(self, id: int, /) -> Optional[BytesIO]: ...
123

124
class Twemoji(EmojiCDNSource): ...
125
class AppleEmojiSource(EmojiCDNSource): ...
126
class MicrosoftEmojiSource(EmojiCDNSource): ...
127
class GoogleEmojiSource(EmojiCDNSource): ...
128
class SamsungEmojiSource(EmojiCDNSource): ...
129
class WhatsAppEmojiSource(EmojiCDNSource): ...
130
class FacebookEmojiSource(EmojiCDNSource): ...
131
class MessengerEmojiSource(EmojiCDNSource): ...
132
class JoyPixelsEmojiSource(EmojiCDNSource): ...
133
class OpenmojiEmojiSource(EmojiCDNSource): ...
134
class EmojidexEmojiSource(EmojiCDNSource): ...
135
class MozillaEmojiSource(EmojiCDNSource): ...
136
```
137

138
[Emoji Sources](./emoji-sources.md)
139

140
### Text Processing and Utilities
141

142
Helper functions for text analysis, emoji detection, node parsing, and text measurement with emoji support, enabling advanced text layout and processing workflows.
143

144
```python { .api }
145
def to_nodes(text: str, /) -> List[List[Node]]: ...
146
def getsize(
147
    text: str,
148
    font: FontT = None,
149
    *,
150
    spacing: int = 4,
151
    emoji_scale_factor: float = 1
152
) -> Tuple[int, int]: ...
153

154
class Node(NamedTuple):
155
    type: NodeType
156
    content: str
157

158
class NodeType(Enum):
159
    text = 0
160
    emoji = 1
161
    discord_emoji = 2
162

163
EMOJI_REGEX: re.Pattern[str]  # Pre-compiled regex for emoji detection
164
```
165

166
[Text Processing and Utilities](./text-processing.md)
167

168
## Type Definitions
169

170
```python { .api }
171
# Type aliases for font and color parameters
172
FontT = Union[ImageFont.ImageFont, ImageFont.FreeTypeFont, ImageFont.TransposedFont]
173
ColorT = Union[int, Tuple[int, int, int], Tuple[int, int, int, int], str]
174
SupportsInt = Union[int, Any]  # For Discord emoji IDs
175

176
# Standard library imports for complete type definitions
177
from typing import Union, Tuple, Optional, Type, List, Any
178
from enum import Enum
179
from collections.abc import SupportsInt
180
import re
181
from io import BytesIO
182
from abc import ABC
183
```