mols2grid-to-image

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

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:

   pip install mols2grid-to-image
   

2. Install as a CLI tool via uv tool install:

   uv tool install mols2grid-to-image
   

3. Install as a library via uv add:

   uv add mols2grid-to-image
   

4. Install Playwright browser (required for screenshot functionality):

   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:

uv run m2g-image input.csv -o output.png

Options:

Examples:

1. Pagination: Split into images with 50 molecules each.

   uv run m2g-image data.csv --per-page 50 -o batch.png
   # Generates batch_01.png, batch_02.png, ...
   

2. Transparent Background:

   uv run m2g-image data.csv --transparent -o transparent.png
   

3. Output Directory & Zero Padding:

   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:

{
    "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:

uv run m2g-image data.csv -c config.json

Python Library Usage

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

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:

uv run pytest

License

MIT