158 lines
3.6 KiB
Markdown
158 lines
3.6 KiB
Markdown
# 🎨 Advanced Text Rendering Engine (CLI)
|
|
|
|
A production-ready, Photoshop-like text rendering engine built with
|
|
**Python + Pillow**.
|
|
|
|
This tool allows you to render fully styled text onto images using a
|
|
validated JSON configuration file. Designed for automation, batch
|
|
processing, and CI/CD usage.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## ✨ Features
|
|
|
|
- CLI-based interface
|
|
- Fully validated `style.json` (Pydantic v2)
|
|
- Clean, user-friendly error messages (no stack traces)
|
|
- Solid and Gradient text fill
|
|
- Stroke (outline)
|
|
- Drop shadow
|
|
- Outer glow
|
|
- Inner shadow
|
|
- Opacity control
|
|
- Rotation
|
|
- Multi-line text
|
|
- RTL (Arabic / Persian) support
|
|
- Strict JSON schema (no extra fields allowed)
|
|
- Production-safe exit codes
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 📦 Requirements
|
|
|
|
- Python 3.10+
|
|
- uv (recommended) or pip
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 🚀 Installation
|
|
|
|
### Using uv (recommended)
|
|
|
|
``` bash
|
|
uv venv
|
|
uv pip install pillow arabic-reshaper python-bidi numpy pydantic
|
|
```
|
|
|
|
### Using pip
|
|
|
|
``` bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install pillow arabic-reshaper python-bidi numpy pydantic
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 🖼 Usage
|
|
|
|
``` bash
|
|
python main.py --image assets/input.jpg --output assets/output.png --text "Hello World" --style assets/style.json
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 📄 CLI Arguments
|
|
|
|
Argument Required Description
|
|
------------ ---------- ---------------------------
|
|
`--image` Yes Path to input image
|
|
`--output` Yes Path to save output image
|
|
`--text` Yes Text to render
|
|
`--style` Yes Path to style.json
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 🧾 style.json Example
|
|
|
|
``` json
|
|
{
|
|
"font_path": "Vazirmatn-Regular.ttf",
|
|
"font_size": 90,
|
|
"center": [800, 450],
|
|
"fill": {
|
|
"type": "gradient",
|
|
"colors": ["#ff0080", "#7928ca"],
|
|
"direction": "vertical"
|
|
},
|
|
"stroke": {
|
|
"enabled": true,
|
|
"width": 4,
|
|
"color": "#000000"
|
|
},
|
|
"shadow": {
|
|
"enabled": true,
|
|
"offset": [8, 8],
|
|
"blur": 15,
|
|
"color": "#000000",
|
|
"opacity": 0.6
|
|
},
|
|
"outer_glow": {
|
|
"enabled": true,
|
|
"offset": [0, 0],
|
|
"blur": 20,
|
|
"color": "#ff00ff",
|
|
"opacity": 0.5
|
|
},
|
|
"inner_shadow": {
|
|
"enabled": false,
|
|
"offset": [3, 3],
|
|
"blur": 10,
|
|
"color": "#000000",
|
|
"opacity": 0.5
|
|
},
|
|
"letter_spacing": 5,
|
|
"line_height": 1.2,
|
|
"rotation": 0,
|
|
"opacity": 1.0
|
|
}
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 🔒 Validation
|
|
|
|
- Invalid HEX colors are rejected
|
|
- Missing required fields produce clear error messages
|
|
- Extra JSON fields are forbidden
|
|
- Numeric ranges are enforced
|
|
- No stack traces shown to end users
|
|
|
|
Example error:
|
|
|
|
❌ Style configuration error:
|
|
• outer_glow → offset: Field required
|
|
Please fix style.json and try again.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 🌍 RTL Support
|
|
|
|
Arabic and Persian text is automatically reshaped using: -
|
|
arabic-reshaper - python-bidi
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 🧪 Exit Codes
|
|
|
|
Code Meaning
|
|
------ -----------------------------
|
|
0 Success
|
|
1 Validation or runtime error
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 📜 License
|
|
|
|
MIT License
|