Skip to content

Commit 0e51cfd

Browse files
mscoutermarshmscoutermarsh
committed
improve debugging blurry image guide
1 parent cf829dd commit 0e51cfd

File tree

1 file changed

+271
-14
lines changed

1 file changed

+271
-14
lines changed

‎guides/debugging-blurry-images.md‎

Lines changed: 271 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,16 @@ permalink: /guides/debugging-blurry-images/
55
parent: Guides
66
nav_order: 10
77
description: >-
8-
How to fix getting a blurry image on HTML/CSS to Image API
8+
Complete guide to understanding and fixing blurry images with pixel density, resolution, and device scaling
99
---
10-
# Debugging blury images
10+
11+
# Debugging Blurry Images
1112
{: .no_toc }
1213
{: .fs-9 }
1314

14-
Troubleshooting guide
15+
The complete guide to crystal-clear, high-resolution images
1516
{: .fs-6 .fw-300 }
17+
1618
<hr>
1719

1820
Table of contents
@@ -22,21 +24,276 @@ Table of contents
2224

2325
<hr>
2426

25-
## Why is my image blurry?
26-
If your rendered image looks low quality, the problem can often be solved with a few quick changes.
27+
## Why Images Look Blurry
28+
29+
Blurry images are almost always caused by **insufficient pixel density** for the display they're viewed on. Modern screens—especially smartphones, tablets, and high-resolution monitors—pack many more pixels into the same physical space than older displays.
30+
31+
The HTML/CSS to Image API automatically generates **high-resolution images by default** to ensure your images look crisp on all devices. Here's everything you need to know about creating pixel-perfect images.
32+
33+
{% include hint.md title="Default High Resolution" text="The HCTI API defaults to 2x resolution (device_scale: 2) for HTML images to prioritize image quality. This ensures your images look sharp on both standard and high-DPI displays." %}
34+
35+
## Understanding Pixel Density
36+
37+
### The Modern Display Challenge
38+
39+
Today's screens vary dramatically in pixel density:
40+
41+
- **Standard displays**: 1 physical pixel = 1 CSS pixel (1x)
42+
- **Retina/High-DPI displays**: 2-4 physical pixels = 1 CSS pixel (2x-4x)
43+
- **Ultra-high resolution**: 3+ physical pixels = 1 CSS pixel (3x+)
44+
45+
When you create an image at standard resolution (1x) and display it on a high-density screen, the browser must **stretch** those pixels to fill the available space—resulting in a blurry, pixelated appearance.
46+
47+
### The 2x Rule Explained
48+
49+
The **2x rule** is simple: **create images at double your intended display size**.
50+
51+
**Example:**
52+
- Display size needed: `400×400px`
53+
- Image source size: `800×800px` (2x)
54+
- Result: Sharp image on all screens
55+
56+
This ensures you have enough pixel data to satisfy high-density displays while still looking great on standard screens.
57+
58+
## Device Scale Settings
59+
60+
The HCTI API uses the `device_scale` parameter to control image resolution:
61+
62+
| Setting | Resolution | Use Case | File Size |
63+
|---------|------------|----------|-----------|
64+
| `1` | Standard (1x) | Legacy screens, thumbnails | Smallest |
65+
| `2` | High (2x) | **Recommended for web** | Medium |
66+
| `3` | Maximum (3x) | Print, premium displays | Largest |
67+
68+
### Default Behavior
69+
70+
- **HTML images**: `device_scale: 2` (high resolution by default)
71+
- **URL screenshots**: `device_scale: 1` (standard resolution)
72+
73+
## Common Causes of Blurry Images
74+
75+
### 1. Insufficient Source Image Resolution
76+
77+
**Problem**: Your source images are too small for high-DPI rendering.
78+
79+
**Example**: Using a `200×200px` image that needs to display at `200×200px` on a 2x display.
80+
81+
**Solution**: Use source images at 2x your display size:
82+
```html
83+
<!-- Instead of this -->
84+
<img src="logo-200x200.png" width="200" height="200">
85+
86+
<!-- Use this -->
87+
<img src="logo-400x400.png" width="200" height="200">
88+
```
89+
90+
### 2. Incorrect Device Scale for URLs
91+
92+
**Problem**: URL screenshots default to `device_scale: 1`.
93+
94+
**Solution**: Explicitly set `device_scale: 2` for URL images:
95+
```json
96+
{
97+
"url": "https://example.com",
98+
"device_scale": 2
99+
}
100+
```
101+
102+
### 3. Mixed Resolution Assets
103+
104+
**Problem**: Some images in your HTML are high-resolution while others are not.
105+
106+
**Solution**: Ensure ALL images follow the 2x rule:
107+
```html
108+
<!-- Good: All images are 2x their display size -->
109+
<img src="header-800x200.png" width="400" height="100">
110+
<img src="logo-200x200.png" width="100" height="100">
111+
<img src="photo-1200x800.png" width="600" height="400">
112+
```
113+
114+
## Step-by-Step Debugging
115+
116+
### Step 1: Check Your Device Scale
117+
118+
For HTML images, verify your API request:
119+
```json
120+
{
121+
"html": "<div>Your content</div>",
122+
"device_scale": 2 // Ensure this is set to 2
123+
}
124+
```
125+
126+
For URL images, always specify device scale:
127+
```json
128+
{
129+
"url": "https://your-site.com",
130+
"device_scale": 2 // Add this for sharp screenshots
131+
}
132+
```
133+
134+
### Step 2: Audit Your Source Images
135+
136+
Calculate if your images meet the 2x requirement:
137+
138+
1. **Intended display size**: How big will the image appear? (e.g., 300px wide)
139+
2. **Required source size**: Multiply by device scale (300px × 2 = 600px wide)
140+
3. **Actual source size**: Check your image file dimensions
141+
142+
**Quick audit checklist:**
143+
- [ ] All images are 2x their CSS display size
144+
- [ ] External images from CDNs have high-res versions
145+
- [ ] Icons and logos have sufficient resolution
146+
- [ ] Background images are appropriately sized
147+
148+
### Step 3: Test on Different Displays
149+
150+
View your generated image on:
151+
- Standard resolution monitor
152+
- High-DPI laptop screen (MacBook, high-end Windows laptops)
153+
- Mobile device (iPhone, Android phone)
154+
- Tablet (iPad, Android tablet)
155+
156+
The image should look equally sharp on all devices.
157+
158+
## Real-World Examples
159+
160+
### Example 1: Social Media Card
161+
162+
**Bad approach:**
163+
```html
164+
<div style="width: 1200px; height: 630px;">
165+
<img src="avatar-150x150.jpg" width="150" height="150">
166+
<!-- Image will be blurry on high-DPI displays -->
167+
</div>
168+
```
169+
170+
**Good approach:**
171+
```html
172+
<div style="width: 1200px; height: 630px;">
173+
<img src="avatar-300x300.jpg" width="150" height="150">
174+
<!-- Image will be sharp on all displays -->
175+
</div>
176+
```
177+
178+
### Example 2: Company Logo
179+
180+
**Bad approach:**
181+
```css
182+
.logo {
183+
width: 200px;
184+
height: 60px;
185+
background-image: url('logo-200x60.png');
186+
}
187+
```
188+
189+
**Good approach:**
190+
```css
191+
.logo {
192+
width: 200px;
193+
height: 60px;
194+
background-image: url('logo-400x120.png');
195+
background-size: 200px 60px; /* Scale down to intended size */
196+
}
197+
```
198+
199+
## Advanced Techniques
200+
201+
### Responsive Images with srcset
202+
203+
For external images, use responsive image techniques:
204+
```html
205+
<img src="photo-600x400.jpg"
206+
srcset="photo-600x400.jpg 1x, photo-1200x800.jpg 2x"
207+
width="600" height="400">
208+
```
209+
210+
### CSS Media Queries for High-DPI
211+
212+
Target high-resolution displays specifically:
213+
```css
214+
@media only screen and (-webkit-min-device-pixel-ratio: 2),
215+
only screen and (min-resolution: 192dpi) {
216+
.hero-image {
217+
background-image: url('hero-2x.jpg');
218+
}
219+
}
220+
```
221+
222+
### Vector Graphics for Perfect Scaling
223+
224+
Use SVG for logos and icons that scale perfectly at any resolution:
225+
```html
226+
<img src="logo.svg" width="200" height="60">
227+
<!-- SVG automatically scales to any device -->
228+
```
229+
230+
## Performance Considerations
231+
232+
### File Size Impact
233+
234+
Higher resolution means larger files:
235+
- `device_scale: 1` → Base file size
236+
- `device_scale: 2` → ~4x larger files
237+
- `device_scale: 3` → ~9x larger files
238+
239+
### Optimization Strategies
240+
241+
1. **Use appropriate compression**: Balance quality vs. file size
242+
2. **Choose the right format**:
243+
- PNG for graphics with transparency
244+
- JPG for photographs
245+
- WebP for modern browsers (when supported)
246+
3. **Consider bandwidth**: Higher resolution may impact load times
247+
248+
{% include hint.md title="Performance Tip" text="Use device_scale: 2 as the sweet spot for web usage. It provides excellent quality on all displays while keeping file sizes reasonable." %}
249+
250+
## Troubleshooting Checklist
251+
252+
When your image still looks blurry:
253+
254+
- [ ] **Device scale is set to 2** (for HTML) or explicitly specified (for URLs)
255+
- [ ] **All source images are 2x their display size**
256+
- [ ] **External CDN images have high-resolution versions available**
257+
- [ ] **CSS background images use appropriately sized sources**
258+
- [ ] **Vector graphics (SVG) are used where possible**
259+
- [ ] **The generated image is being displayed at the correct size**
260+
261+
## Browser Testing
262+
263+
Test your images across different scenarios:
27264

28-
## Solution: `device_scale`
265+
```html
266+
<!-- Test HTML - put this in your browser -->
267+
<!DOCTYPE html>
268+
<html lang="en">
269+
<head>
270+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
271+
</head>
272+
<body>
273+
<h1>Image Quality Test</h1>
274+
275+
<!-- Your generated image -->
276+
<img src="your-generated-image.png" width="400" height="300">
277+
278+
<!-- View at different sizes -->
279+
<img src="your-generated-image.png" width="200" height="150">
280+
<img src="your-generated-image.png" width="800" height="600">
281+
</body>
282+
</html>
283+
```
29284

30-
For URL images, by default we set the `device_scale` to 1. Try setting it to 2 and seeing if it improves the image quality.
31-
Device scale indicates the pixel density of the browser when generating the image. A setting of 2 is similar to a high resolution screen,
32-
such as an Apple retina screen.
285+
## Need Help?
33286

34-
## Solution: verify resolution of your images
287+
Still experiencing blurry images? We're here to help debug your specific case.
35288

36-
If an image within your HTML looks blurry, it is possible that it has been sized incorrectly.
37-
Check the size of the original included image. If it is 400x400. Then the maximum size it can be rendered as at a 2 `device_scale` is
38-
200x200.
289+
**Email us**: [[email protected]](mailto:[email protected])
39290

291+
Include:
292+
- Your API request (HTML/CSS or URL)
293+
- Expected vs. actual results
294+
- What devices/screens you're testing on
295+
- Any specific requirements for your use case
40296

297+
We love solving tricky rendering problems and helping you achieve pixel-perfect results.
41298

42-
{% include code_footer.md version=1 %}
299+
{% include code_footer.md version=2 %}

0 commit comments

Comments
 (0)