# CoreImR 📸

Hey there! CoreImR is a blazing-fast, lightweight, and zero-dependency converter written in Python that can seamlessly transform HTML, CSS, JS (and even native PHP or Markdown files!) into beautiful images and vector PDFs.
Everything runs on a headless Chromium engine under the hood (utilizing your system's existing Chrome or Edge browser), which guarantees pixel-perfect rendering quality—exactly as it would appear in a real browser.

## What's New in Version 1.2.0?
I sat down and heavily refactored the library to make it incredibly developer-friendly (inspired by the elegant API style of `dynimg`). Here is what's new in the mega update:

- **Elegant API**: New `RenderOptions` (for super convenient configuration) and `Image` objects (to handle the render directly in your RAM).
- **Automatic Dependencies**: No more manual installations! When you install `coreimr`, it automatically pulls `Pillow` (for image manipulation) and `markdown` (for compiling `.md` files natively).
- **Video and Animations**: We added frame-by-frame recording of CSS/JS animations! You can seamlessly capture and save looping `.gif` files or highly compressed `.mp4` videos.
- **Native PHP**: Pass a path to an `index.php` file, and CoreImR will automatically trigger your local PHP CLI, execute the backend code, grab the output HTML, and take a screenshot!
- **Markdown Compiler**: Throw raw `# Markdown` text (or a `.md` file path) at it, and the library will natively style it with a beautiful GitHub-like CSS theme and render it into a PDF!
- **Base64 On-The-Fly**: No need to save files to your disk anymore. The `image.to_base64()` method generates a ready-to-use string of your graphic/video to immediately embed into an `<img>` tag or JSON API.
- **Scraping Superpowers**: Added options to bypass broken SSL certificates (`ignore_ssl_errors=True`), bypass CORS/local file restrictions (`allow_net=False`), and spoof devices.

## Installation

Simply run:
```bash
pip install coreimr
```
*When you run this, pip will intelligently pull the required `Pillow` and `markdown` dependencies automatically.*

## Terminal CLI (Command Line Interface)
You don't even need to write Python files to use CoreImR! Once installed, it becomes available system-wide in your terminal, acting like a modern `wkhtmltopdf` replacement.

Just open your console and type:
```bash
# Render a website into a beautiful PDF
coreimr https://google.com -o result.pdf

# Render a local Markdown file into a 4K PNG with Dark Mode
coreimr my_docs.md -o output.png --dark-mode --scale 2.0

# Render a PHP file bypassing JS and security barriers
coreimr invoice.php -o invoice.pdf --disable-js --disable-web-security
```
Run `coreimr -h` to see all available terminal arguments!

## Quick Start Guide (Python)

### 1. Render to Memory (and save to disk)
Once you type `RenderOptions(...)` in your IDE, our bundled `py.typed` hints will automatically light up with all available arguments for super-fast development!

```python
import coreimr
from coreimr import RenderOptions

# Provide HTML code with a gradient and a nice font
html = '''
<body style="background: linear-gradient(135deg, #667eea, #764ba2); height: 100vh; margin: 0; display: flex; align-items: center; justify-content: center;">
    <h1 style="color: white; font-family: system-ui; font-size: 64px;">CoreImR 1.2.0!</h1>
</body>
'''

# Dimensions, Retina scale (x2), and dark mode
options = RenderOptions(width=1200, height=630, scale=2.0, dark_mode=True)

# The render process happens entirely in memory
image = coreimr.render(html=html, options=options)

# Save to disk however you like:
image.save_png("test.png")
image.save_webp("compressed.webp", quality=85) # Great for saving space!

# Generate a Base64 string for your front-end:
print(image.to_base64(format='WEBP', quality=85))
```

### 2. Fast Render from a PHP file (with CSS injection)
If you have an invoice generated in PHP:
```python
import coreimr
from coreimr import RenderOptions

# You can inject your own styles into the final file on the fly
options = RenderOptions(inject_css="body { font-size: 30px !important; }")

# Executes the PHP file via system CLI and saves the resulting image
coreimr.render_to_file(
    path="result.pdf",          # Automatically chooses format (.pdf / .png / etc) based on the extension
    file_path="invoice.php", 
    options=options
)
```

### 3. Rendering HTML Animations to `.mp4` and `.gif`
```python
import coreimr

html = "<style>@keyframes s { to { transform: rotate(360deg); } } div { animation: s 2s linear infinite; }</style><div></div>"

# We capture 2 seconds of the animation at 24 frames per second!
animation = coreimr.render_animation(html=html, duration=2.0, fps=24)

animation.save_gif("test.gif")
animation.save_mp4("test.mp4") # Note: MP4 rendering requires 'ffmpeg' to be installed on your system.
```

### 4. Compiling Markdown to PDF
```python
import coreimr

md_text = """
# Report
Check out my **Markdown** table:
| Test | Result |
|---|---|
| Database | ✅ |
"""

coreimr.render_to_file(
    "report.pdf", 
    markdown=md_text, 
    options=coreimr.RenderOptions(dark_mode=True)
)
```

## Troubleshooting & FAQ

**It throws `Browser command failed with exit code 1`?**
This usually means your page (especially if you are rendering a local file from `C:\..`) is trying to load a local resource (like a font or an image), and Chromium blocks it due to security reasons (CORS). Just add `allow_net=False` to your `RenderOptions` and it will bypass it smoothly!

**The screenshot is taken too fast, before JS or animations finish loading!**
Large frameworks (like Angular or React) need a moment to boot up. Add `delay=2000` (which implies 2000 milliseconds, or 2 seconds) to your `RenderOptions`. The browser will wait exactly that long before snapping the picture.

**The HTTPS site returns a white screen (or throws errors).**
If the server (e.g., a localhost XAMPP environment) is using a "fake" or self-signed SSL certificate, Chromium refuses to connect. You can bypass this by setting: `ignore_ssl_errors=True`.

**Why are these PNG files so massive?**
Because a PNG from Chromium is an uncompressed, lossless capture of the entire viewport - often in 4K Retina resolution. Start using `.webp` and set `quality=60`. There is visually no difference, but the file size drops a hundredfold!

----
Feel free to use it and let us know about any cool integrations you make. The library remains "Zero-dependency" when it comes to heavy browser-control packages!