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:

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.

   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