mols2grid-to-image 0.1.0
Convert molecules to grid images using mols2grid and Playwright
Requires Python: >=3.10
Keywords: chemistry, grid, image, molecules, mols2grid, rdkit, smiles

# mols2grid-to-image

[![PyPI version](https://badge.fury.io/py/mols2grid-to-image.svg)](https://pypi.org/project/mols2grid-to-image/)
[![Python](https://img.shields.io/pypi/pyversions/mols2grid-to-image.svg)](https://pypi.org/project/mols2grid-to-image/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Test](https://github.com/N283T/mols2grid_to_image/actions/workflows/test.yml/badge.svg)](https://github.com/N283T/mols2grid_to_image/actions/workflows/test.yml)
[![Lint](https://github.com/N283T/mols2grid_to_image/actions/workflows/lint.yml/badge.svg)](https://github.com/N283T/mols2grid_to_image/actions/workflows/lint.yml)

This tool is a **Python-based utility for exporting molecule grids generated by mols2grid as PNG or HTML files**.
By leveraging mols2grid, it produces **clean, well-organized molecular grid images with minimal effort**.

The CLI allows you to **input a CSV file (containing SMILES or other molecular data) and directly output a grid image**.
Image rendering and capture are handled using **Playwright**, enabling the entire workflow to run within Python.


## Example Output

![Example Output](example/output.png)

## Features

- **Pure Python**: Operates entirely in Python using `playwright` for headless browser automation.
- **Flexible Input**: Accepts CSV files containing SMILES strings.
- **Customizable Output**:
  - Control grid layout (columns, cell size, border, gap).
  - Select specific subsets of data to display.
  - Customize fonts and text alignment.
  - **Pagination**: Split large datasets into multiple images automatically.
  - **Transparent Background**: Generate PNGs with transparent backgrounds (including molecule images).
  - **Output Control**: Specify output directory and automatic zero-padded filenames for batch processing.
- **Configuration**: Support for JSON configuration files for reproducible settings.

## Installation

1.  **Install from PyPI**:
    ```bash
    pip install mols2grid-to-image
    ```

2.  **Install as a CLI tool via `uv tool install`**:
    ```bash
    uv tool install mols2grid-to-image
    ```

3.  **Install as a library via `uv add`**:
    ```bash
    uv add mols2grid-to-image
    ```

4.  **Install Playwright browser** (required for screenshot functionality):
    ```bash
    playwright install chromium
    ```

## Usage

You can use `mols2grid-to-image` as a CLI tool or as a library.

### CLI (Command Line Interface)

The package provides a `m2g-image` command.

**Basic Usage:**
```bash
uv run m2g-image input.csv -o output.png
```

**Options:**

| Option | Shorthand | Description | Default |
| :--- | :--- | :--- | :--- |
| `--version` | `-v` | Show version and exit. | |
| `--output` | `-o` | Path to output PNG file (base name). | `result.png` |
| `--output-dir` | `-od` | Directory to save output images. Overrides `--output` dir. | `None` |
| `--output-html` | `-oh` | Path to save intermediate HTML file (Optional). | `None` (Not saved) |
| `--config` | `-c` | Path to JSON configuration file. | `None` |
| `--smiles-col` | `-sc` | Column name for SMILES. | `smiles` |
| `--n-cols` | `-nc` | Number of columns in grid. | `5` |
| `--subset` | | Columns to display in grid. | `None` |
| `--cell-width` | `-w` | Cell width in pixels. | `150` |
| `--cell-height` | `-ch` | Cell height in pixels. | `150` |
| `--fontsize` | `-fs` | Font size in points. | `12` |
| `--per-page` | `-p` | Number of items per image (pagination). | `None` (All in one) |
| `--transparent` | `-t` | Enable transparent background for grid and molecules. | `False` |
| `--border` | | CSS border for cells (e.g., "1px solid black"). | `None` |
| `--gap` | | Gap between cells in pixels. | `None` |
| `--font-family` | `-ff` | Font family for text. | `None` |
| `--text-align` | `-ta` | Text alignment (left, center, right). | `None` |
| `--sort-by` | | Column to sort by. | `None` |
| `--remove-hs` | | Remove hydrogens from depiction. | `None` |
| `--use-coords` | | Use existing coordinates from input. | `None` |
| `--coord-gen` | | Use CoordGen for 2D coordinate generation. | `None` |

**Examples:**

1. **Pagination**: Split into images with 50 molecules each.
   ```bash
   uv run m2g-image data.csv --per-page 50 -o batch.png
   # Generates batch_01.png, batch_02.png, ...
   ```

2. **Transparent Background**:
   ```bash
   uv run m2g-image data.csv --transparent -o transparent.png
   ```

3. **Output Directory & Zero Padding**:
   ```bash
   uv run m2g-image data.csv --per-page 10 --output-dir results/ -o grid.png
   # Generates results/grid_01.png, results/grid_02.png, ...
   ```

### Configuration File (JSON)

You can define parameters in a JSON file to avoid long command lines.

**config.json:**
```json
{
    "output_image": "custom_output.png",
    "n_cols": 4,
    "cell_width": 200,
    "cell_height": 200,
    "n_items_per_page": 20,
    "transparent": true,
    "subset": ["ID", "SMILES", "Activity"]
}
```

**Run with config:**
```bash
uv run m2g-image data.csv -c config.json
```

### Python Library Usage

You can integrate the conversion logic into your own Python scripts.

```python
import pandas as pd
import mols2grid
from m2g_image import grid_to_image, generate_grid_image

# 1. High-level wrapper (Recommended)
generate_grid_image(
    pd.read_csv("data.csv"),
    output_image_path="output.png",
    n_cols=5,
    subset=["ID"],
    transparent=True,
)

# 2. With pagination
from m2g_image import generate_grid_images

for page_num, path in generate_grid_images(
    pd.read_csv("data.csv"),
    output_image_path="output.png",
    n_items_per_page=50,
    n_cols=5,
):
    print(f"Page {page_num}: {path}")

# 3. Low-level usage
grid = mols2grid.display(df, ...)
# Note: For transparency, you must handle CSS and MolDrawOptions manually
output_path = grid_to_image(grid, "output.png", omit_background=True)
```

## Development

**Run Tests:**
```bash
uv run pytest
```

## License

[MIT](LICENSE)