text-over-image-cli 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -0
- package/dist/index.js +6595 -0
- package/package.json +32 -0
package/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# Text Over Image (toi) CLI
|
|
2
|
+
|
|
3
|
+
A powerful, lightweight CLI tool to overlay text on images with automatic scaling, wrapping, and smart resizing.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Universal Input**: Supports both local file paths and remote URLs.
|
|
8
|
+
- **Smart Resizing**: Upscale or downscale images while maintaining aspect ratios (e.g., 16:9, 4:3).
|
|
9
|
+
- **Auto-Wrapping**: Automatically wraps long text into multiple lines based on image width.
|
|
10
|
+
- **Relative Scaling**: Font sizes are relative to image height by default, ensuring consistency across different resolutions.
|
|
11
|
+
- **Precise Positioning**: Use keywords (top, center, bottom) or pixel offsets (positive/negative).
|
|
12
|
+
- **EXIF Awareness**: Automatically handles image rotation based on EXIF metadata.
|
|
13
|
+
- **High Readability**: Renders white text with a black outline for visibility on any background.
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
Ensure you have [Bun](https://bun.sh/) installed on your system.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Clone the repository
|
|
21
|
+
git clone https://github.com/your-username/text-over-image.git
|
|
22
|
+
cd text-over-image
|
|
23
|
+
|
|
24
|
+
# Install dependencies
|
|
25
|
+
bun install
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Usage
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
bun run index.ts -f <image> -t "Your Message" -p <position> [options]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Required Arguments
|
|
35
|
+
|
|
36
|
+
| Flag | Name | Description |
|
|
37
|
+
| :--- | :----------- | :------------------------------------------------------------------------------------------------ |
|
|
38
|
+
| `-f` | `--file` | Path to a local image or a URL (http/https). |
|
|
39
|
+
| `-t` | `--text` | The text message to overlay. |
|
|
40
|
+
| `-p` | `--position` | Vertical alignment: top, center, bottom, or a number (e.g., 50 for top-down, -100 for bottom-up). |
|
|
41
|
+
|
|
42
|
+
### Optional Arguments
|
|
43
|
+
|
|
44
|
+
| Flag | Name | Description |
|
|
45
|
+
| :--- | :------------ | :---------------------------------------------------------- |
|
|
46
|
+
| | `--width` | Force a specific width in pixels. |
|
|
47
|
+
| | `--height` | Force a specific height in pixels. |
|
|
48
|
+
| | `--aspect` | Target aspect ratio (e.g., 16:9, 1:1). |
|
|
49
|
+
| `-s` | `--font-size` | Custom size in pixels (40) or percentage (5%). Default: 4%. |
|
|
50
|
+
| `-o` | `--output` | Destination path. Default: output.png. |
|
|
51
|
+
| `-h` | `--help` | Show the detailed help menu. |
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Examples
|
|
56
|
+
|
|
57
|
+
### 1. Basic Local Image
|
|
58
|
+
|
|
59
|
+
Add a centered message to a local photo:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
bun run index.ts -f photo.jpg -t "Hello World" -p center
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### 2. Remote URL with Bottom Offset
|
|
66
|
+
|
|
67
|
+
Fetch an image from the web and place text 50px from the bottom:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
bun run index.ts -f https://picsum.photos/800/600 -t "Adventure Awaits" -p -50 -o travel.jpg
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 3. Creating a 16:9 Banner
|
|
74
|
+
|
|
75
|
+
Resize any image to 1920px wide with a 16:9 aspect ratio and large text:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
bun run index.ts -f input.png -t "Header" -p center --width 1920 --aspect 16:9 -s 8% -o banner.jpg
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 4. Custom Font Size (Pixels)
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
bun run index.ts -f bg.png -t "Small Print" -p top -s 20
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Development
|
|
88
|
+
|
|
89
|
+
### Type Checking
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
bun x tsc --noEmit
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Build
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
bun run build
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
MIT © [ahm0xc](https://ahm0xc.me)
|