API Reference¶

Complete API documentation for all FigWizz modules.

Core Modules¶

convert¶

Image format conversion functions.

`convert` ¶

Image format conversion utilities.

This module provides functions for converting images between different formats, handling various input types (paths, bytes, PIL Images, etc.), and processing SVG files.

Example

from figwizz.convert import convert_image
convert_image('input.png', 'jpg')
# Returns: 'input.jpg'

`convert_image(source_path, target_format, delete_original=False)` ¶

Convert an image file to another format.

Supports conversion between all major image formats including PNG, JPEG, PDF, WEBP, TIFF, and more. Automatically handles transparency for formats that don't support it (like JPEG).

Parameters:

Name	Type	Description	Default
`source_path`	`str or any`	Path to the source image file, or any supported image input type (PIL Image, bytes, numpy array, URL, etc.)	required
`target_format`	`str`	Target format to convert to. Supported formats include: 'jpg'/'jpeg', 'png', 'pdf', 'webp', 'tiff', 'bmp', 'gif'	required
`delete_original`	`bool`	Whether to remove the original file after conversion. Only applies if source_path is a file path string. Defaults to False.	`False`

Returns:

Name	Type	Description
`str`		Path to the converted image file

Examples:

from figwizz import convert_image

# Convert PNG to JPEG
convert_image('image.png', 'jpg')
# Creates: image.jpg

# Convert to PDF and delete original
convert_image('image.png', 'pdf', delete_original=True)
# Creates: image.pdf (and deletes image.png)

# Convert from URL
convert_image('https://example.com/image.png', 'jpg')

Note

Automatically adds white background for JPEG/PDF (no transparency support)
Leading dot in format is automatically handled ('jpg' or '.jpg' both work)
For non-path inputs, creates file with default name 'converted_image.{format}'
Output file is created in the same directory as the input file

`svg_to_image(svg_content, output_path, width=None, height=None, scale=None)` ¶

Convert SVG content to a raster image.

Requires the optional cairosvg library for SVG conversion. This function is useful for converting vector graphics to raster formats like PNG, JPEG, or PDF while maintaining quality through scaling options.

Parameters:

Name	Type	Description	Default
`svg_content`	`bytes`	Raw SVG file content as bytes	required
`output_path`	`str`	Path to save the output file. File extension determines output format. Supported: .png, .jpg, .jpeg, .pdf	required
`width`	`int`	Output width in pixels. If None, uses SVG's natural width. Defaults to None.	`None`
`height`	`int`	Output height in pixels. If None, uses SVG's natural height. Defaults to None.	`None`
`scale`	`float`	Scale factor for the output (e.g., 2.0 for 2x resolution, 3.0 for 3x). Useful for high-DPI displays. Defaults to None.	`None`

Returns:

Name	Type	Description
`bool`		True if conversion was successful, False if cairosvg is not installed or conversion failed

Raises:

Type	Description
`ValueError`	If output_path has an unsupported file extension

Examples:

from figwizz.convert import svg_to_image

# Read SVG file
with open('icon.svg', 'rb') as f:
    svg_data = f.read()

# Convert to PNG with default size
svg_to_image(svg_data, 'icon.png')

# Convert to high-resolution PNG
svg_to_image(svg_data, 'icon.png', scale=3.0)

# Convert with specific dimensions
svg_to_image(svg_data, 'icon.png', width=512, height=512)

# Convert to JPEG
svg_to_image(svg_data, 'icon.jpg', scale=2.0)

Note

Requires cairosvg: pip install cairosvg
Returns False with a warning if cairosvg is not installed
Scale and width/height can be used together
Maintains SVG quality during conversion
Prints informative error messages on failure

modify¶

Image modification and transformation functions.

`modify` ¶

Image modification and transformation utilities.

This module provides functions for modifying images, including adding opaque backgrounds and cropping to n-sided polygon shapes (hexagons, etc.).

Example

from figwizz.modify import ngon_crop, make_image_opaque

# Create hexagon-shaped crop
hexagon = ngon_crop('image.png', sides=6, border_size=5)

# Make RGBA image opaque
opaque_img = make_image_opaque(rgba_image)

`make_image_opaque(img_input, bg_color=(255, 255, 255))` ¶

Make an image opaque by adding a solid background color.

Converts images with transparency (RGBA, LA) to fully opaque images by compositing them over a solid background color. Essential for formats that don't support transparency like JPEG or PDF.

Parameters:

Name	Type	Description	Default
`img_input`		Image in any supported format (path, PIL Image, bytes, numpy array, URL, etc.). Will be normalized to PIL format automatically.	required
`bg_color`	`tuple`	Background color as RGB tuple (R, G, B) where each value is 0-255. Defaults to (255, 255, 255) for white.	`(255, 255, 255)`

Returns:

Type	Description
	PIL.Image.Image: PIL Image object in RGB mode with solid background

Examples:

from figwizz import make_image_opaque
from PIL import Image

# Make PNG with transparency opaque with white background
img = Image.open('transparent_logo.png')
opaque_img = make_image_opaque(img)
opaque_img.save('opaque_logo.jpg')  # Can save as JPEG now

# Use custom background color (light gray)
opaque_img = make_image_opaque('logo.png', bg_color=(240, 240, 240))

# Works with any input type
from PIL import Image
opaque_img = make_image_opaque('https://example.com/transparent.png')

Note

Preserves original image if it has no transparency
Automatically converts to RGB mode for consistent output
Alpha channel is used as mask for proper compositing
Particularly useful before converting to JPEG or PDF
Works with both RGBA (color + alpha) and LA (grayscale + alpha) modes

`ngon_crop(img_input, sides=6, crop_size=None, shift_x=0, shift_y=0, rotation=0, border_size=0, border_color='auto', padding=0, background_color=None)` ¶

Crop an image to an n-sided polygon (n-gon), with optional border and background.

Useful for creating tidyverse-style hexicons and other polygonal image crops.

Parameters:

Name	Description	Default
`img_input`	Image in any supported format (path, PIL Image, bytes, numpy array, etc.).	required
`sides`	Number of sides of the polygon (default: 6 for hexagon).	`6`
`crop_size`	Size of the output image as (width, height). If None, uses a square based on the smallest dimension of the input image.	`None`
`shift_x`	Horizontal shift in pixels (default: 0). Positive values shift right.	`0`
`shift_y`	Vertical shift in pixels (default: 0). Positive values shift down.	`0`
`rotation`	Rotation angle in degrees (default: 0).	`0`
`border_size`	Width of the border in pixels (default: 0, no border).	`0`
`border_color`	Border color. Can be: - "auto": Automatically select contrasting color from image - Hex code: e.g., "#FF5733" - RGB tuple: e.g., (255, 87, 51) - Color name: e.g., "red", "blue"	`'auto'`
`padding`	Padding in pixels around the image content before cropping (default: 0). This allows the n-gon to reshape without cutting into the image.	`0`
`background_color`	Background color inside the polygon (default: None for transparent). Can be hex code, RGB tuple, or color name. Area outside polygon remains transparent.	`None`

Returns:

Type	Description
	PIL Image object with transparent background outside polygon and polygon crop applied.

Examples:

# Create a hexagon with auto border
img = ngon_crop("input.png", sides=6, border_size=5, border_color="auto")

# Create an octagon with red border and padding
img = ngon_crop("input.png", sides=8, border_size=3, border_color="red", padding=20)

# Create a pentagon with no border
img = ngon_crop("input.png", sides=5)

# Create a hexagon with white background inside
img = ngon_crop("input.png", sides=6, background_color="white")

# Create a hexagon with custom background color
img = ngon_crop("input.png", sides=6, background_color="#F0F0F0")

display¶

Functions for displaying and visualizing images.

`display` ¶

Image display and grid layout utilities.

This module provides functions for displaying images in matplotlib-based grid layouts with customizable configurations.

Example

from figwizz.display import make_image_grid
images = ['img1.png', 'img2.png', 'img3.png']
fig, axes = make_image_grid(images, titles=['A', 'B', 'C'])
plt.show()

`make_image_grid(images, titles=None, max_cols=None, show_index=False, figsize=None, title_fontsize=10, show_axes=False)` ¶

Plot a list of images in a grid layout using matplotlib.

Creates a publication-ready grid display of images with optional titles and indexing. Automatically calculates optimal grid dimensions and figure size. Perfect for comparing multiple images, showing results, or creating figure panels for papers and presentations.

Parameters:

Name	Type	Description	Default
`images`	`list`	List of images in any supported format (paths, PIL Images, bytes, numpy arrays, URLs, etc.). All images will be normalized to PIL format automatically.	required
`titles`	`list[str]`	List of titles for each image. Length should match the number of images. Defaults to None.	`None`
`max_cols`	`int`	Maximum number of columns in the grid. If None, defaults to min(4, number_of_images). Defaults to None.	`None`
`show_index`	`bool`	If True, shows "Image N" label in the corner of each subplot. Defaults to False.	`False`
`figsize`	`tuple`	Figure size as (width, height) in inches. If None, automatically calculated as (max_cols3, num_rows3). Defaults to None.	`None`
`title_fontsize`	`int`	Font size for image titles in points. Defaults to 10.	`10`
`show_axes`	`bool`	If True, shows axes with tick marks around each image. If False, axes are hidden for a cleaner look. Defaults to False.	`False`

Returns:

Name	Type	Description
`tuple`		(fig, axes) - Matplotlib Figure and Axes objects that can be further customized or saved. Returns (None, None) if images list is empty.

Examples:

from figwizz import make_image_grid
import matplotlib.pyplot as plt

# Simple grid of images
images = ['img1.png', 'img2.png', 'img3.png', 'img4.png']
fig, axes = make_image_grid(images)
plt.show()

# Grid with titles and custom columns
fig, axes = make_image_grid(
    images,
    titles=['Original', 'Processed', 'Enhanced', 'Final'],
    max_cols=2
)
plt.savefig('comparison.png', dpi=300, bbox_inches='tight')

# Grid with image indices
fig, axes = make_image_grid(
    images,
    show_index=True,
    figsize=(12, 8)
)

# Mix different input types
mixed_images = [
    'local_image.png',
    'https://example.com/image.jpg',
    pil_image_object,
    numpy_array
]
fig, axes = make_image_grid(mixed_images)

Note

Empty image list returns (None, None)
Grid dimensions are automatically calculated for optimal layout
Unused subplots (when images don't fill the grid) are hidden
All images are normalized to PIL format internally
Figure can be saved with plt.savefig() or displayed with plt.show()
Axes are hidden by default for cleaner appearance
Index labels appear with semi-transparent background for readability

scrape¶

Web scraping and image extraction from URLs and PDFs.

`scrape` ¶

Figure and image scraping utilities.

This module provides functions for downloading images from various sources including: - Stock image providers (Pixabay, Unsplash) - PDF documents (local files or URLs) - Web pages (extracting embedded images)

Supports automatic metadata collection and handles various image formats including raster images (PNG, JPEG) and vector graphics (SVG with optional conversion).

Example

from figwizz import download_stock_images, extract_images_from_pdf

# Download stock images
images = download_stock_images('mountains', 5, 'output/')

# Extract from PDF
extract_images_from_pdf('paper.pdf', 'figures/')

`download_pdf_from_url(url)` ¶

Download a PDF from a URL to a temporary file.

Parameters:

Name	Type	Description	Default
`url`		URL of the PDF file	required

Returns:

Type	Description
	Path to the temporary PDF file

`download_pixabay_images(query, n_images, output_dir, api_key=None)` ¶

Download images from Pixabay API.

This function queries the Pixabay API for images matching the search query and downloads high-resolution versions along with comprehensive metadata.

Parameters:

Name	Type	Description	Default
`query`	`str`	Search query string to find images on Pixabay	required
`n_images`	`int`	Maximum number of images to download (up to 200 per request)	required
`output_dir`	`str`	Directory path where images and metadata will be saved	required
`api_key`	`str`	Pixabay API key. If None, reads from PIXABAY_API_KEY environment variable. Defaults to None.	`None`

Returns:

Name	Type	Description
`list`		List of paths to successfully downloaded images

Raises:

Type	Description
`ValueError`	If PIXABAY_API_KEY is not set and api_key is None
`RuntimeError`	If API request fails or returns unexpected format

Examples:

from figwizz.scrape import download_pixabay_images

# Download 10 nature images
images = download_pixabay_images('nature', 10, 'pixabay_images')
print(f"Downloaded {len(images)} images")

Note

Images are downloaded in 'largeImageURL' format (typically 1280px width)
Metadata includes image URL, dimensions, tags, user info, and more
Sequential numbering continues from existing images in the directory
Failed downloads are skipped with a warning message

`download_stock_images(query, n_images, output_dir, provider='pixabay', api_key=None)` ¶

Download stock images from various providers (Pixabay or Unsplash).

This function provides a unified interface for downloading stock images from multiple providers. Each downloaded image is saved with accompanying metadata in JSON format.

Parameters:

Name	Type	Description	Default
`query`	`str`	Search query string to find images	required
`n_images`	`int`	Number of images to download	required
`output_dir`	`str`	Directory path where images and metadata will be saved	required
`provider`	`str`	Image provider to use. Options: 'pixabay' or 'unsplash'. Defaults to 'pixabay'.	`'pixabay'`
`api_key`	`str`	API key for the selected provider. If None, attempts to read from environment variables (PIXABAY_API_KEY or UNSPLASH_ACCESS_KEY). Defaults to None.	`None`

Returns:

Name	Type	Description
`list`		List of paths to successfully downloaded images

Raises:

Type	Description
`ValueError`	If provider is not 'pixabay' or 'unsplash'
`ValueError`	If API key is not provided and not found in environment
`RuntimeError`	If API request fails or returns unexpected format

Examples:

from figwizz import download_stock_images

# Download 5 images of mountains from Pixabay
images = download_stock_images('mountains', 5, 'output/mountains')

# Download from Unsplash with explicit API key
images = download_stock_images(
    'sunset', 10, 'output/sunsets',
    provider='unsplash',
    api_key='your_api_key_here'
)

Note

Each image is saved as a .jpg file with a sequential name (e.g., image_1.jpg)
Metadata for each image is saved in a corresponding .json file
If the output directory already contains images, numbering continues from the last image
Requires valid API keys from the respective providers (Pixabay or Unsplash)

`download_unsplash_images(query, n_images, output_dir, api_key=None)` ¶

Download images from Unsplash API.

This function queries the Unsplash API for images matching the search query and downloads full-resolution versions along with photographer attribution and comprehensive metadata.

Parameters:

Name	Type	Description	Default
`query`	`str`	Search query string to find images on Unsplash	required
`n_images`	`int`	Maximum number of images to download (up to 30 per request)	required
`output_dir`	`str`	Directory path where images and metadata will be saved	required
`api_key`	`str`	Unsplash Access Key. If None, reads from UNSPLASH_ACCESS_KEY environment variable. Defaults to None.	`None`

Returns:

Name	Type	Description
`list`		List of paths to successfully downloaded images

Raises:

Type	Description
`ValueError`	If UNSPLASH_ACCESS_KEY is not set and api_key is None
`RuntimeError`	If API request fails or returns unexpected format

Examples:

from figwizz.scrape import download_unsplash_images

# Download 5 landscape photos
images = download_unsplash_images('landscape', 5, 'unsplash_images')

Note

Images are downloaded in 'full' resolution (highest quality available)
Metadata includes photographer attribution, description, tags, likes, and more
Sequential numbering continues from existing images in the directory
Failed downloads are skipped with a warning message
Please respect Unsplash's API guidelines and attribution requirements

`extract_images_from_pdf(pdf_path, output_dir, min_width=100, min_height=100, name_prefix='figure')` ¶

Extract images from a PDF file.

Parameters:

Name	Description	Default
`pdf_path`	Path to the PDF file	required
`output_dir`	Directory to save extracted images	required
`min_width`	Minimum image width to keep (filters out small icons)	`100`
`min_height`	Minimum image height to keep (filters out small icons)	`100`
`name_prefix`	Prefix for saved image filenames	`'figure'`

Returns:

Type	Description
	List of saved image paths

`extract_images_from_url(url, output_dir, min_width=100, min_height=100, name_prefix='figure', convert_svg=False, svg_scale=3.0)` ¶

Extract images from a web page URL.

Parameters:

Name	Description	Default
`url`	URL of the web page	required
`output_dir`	Directory to save downloaded images	required
`min_width`	Minimum image width to keep	`100`
`min_height`	Minimum image height to keep	`100`
`name_prefix`	Prefix for saved image filenames	`'figure'`
`convert_svg`	Whether to convert SVG files to PNG	`False`
`svg_scale`	Scale factor for SVG to PNG conversion (default: 3.0 for high quality)	`3.0`

Returns:

Type	Description
	List of saved image paths

generate¶

AI-powered image generation using various models.

`generate` ¶

Image generation with generative AI models.

This module provides functions for generating images using AI models through the litellm library. Requires optional dependency: litellm.

Example

from figwizz.generate import generate_images
prompts = ["a red apple", "a blue ocean"]
images = generate_images(prompts, output_dir="generated")

`extract_image_data(response)` ¶

Extract image data from a generative AI response.

This is a convenience wrapper around extract_image_from_genai_response. It handles various response formats from different AI providers.

Parameters:

Name	Type	Description	Default
`response`	`Any`	The response object from a generative AI model (e.g., OpenAI, Google, OpenRouter). Can be a dictionary or custom response object.	required

Returns:

Type	Description
`tuple[bytes, Dict[str, Any]]`	tuple[bytes, dict]: A tuple containing: - bytes: Raw image data ready to be saved - dict: Metadata about the extraction method and format

Examples:

from figwizz.generate import extract_image_data
from litellm import image_generation

# Generate image
response = image_generation(prompt="a sunset", model="gpt-image-1.5")

# Extract image bytes
image_bytes, metadata = extract_image_data(response)

# Save to file
with open('sunset.png', 'wb') as f:
    f.write(image_bytes)

Note

Supports base64 and URL-based image responses
Automatically handles various AI provider response formats
See extract_image_from_genai_response for detailed format support

`generate_images(prompts, output_dir, n_images=1, model='gpt-image-1.5', seed_image=None, api_key=None, return_images=True, disable_seed_warning=False)` ¶

Generate images from text prompts using generative AI models.

Uses the litellm library to generate images from various AI providers including OpenAI, Google, and OpenRouter. Each generated image is saved with comprehensive metadata including the prompt, model, timestamp, and API response details.

When a seed_image is provided, the function uses the image editing endpoint (litellm.image_edit) to generate images that reference the seed image. This is useful for style transfer, modifications, or using an existing image as a starting point. The seed_image is normalized via figwizz's image handlers, so it can be a file path, URL, PIL Image, bytes, numpy array, or base64 string.

A list of seed images can also be provided; in that case, each prompt is applied to every seed image, producing n_images per (prompt, seed_image) pair. The user is warned about the total image count and asked for confirmation before proceeding (this can be suppressed with disable_seed_warning=True). When seed images are used, outputs are organized into per-seed subfolders within each prompt directory.

Parameters:

Name	Type	Description	Default
`prompts`	`str or list[str]`	Text prompt(s) describing the desired image(s). Can be a single string or a list of strings for batch generation.	required
`output_dir`	`str`	Directory where generated images and metadata will be saved. Created automatically if it doesn't exist.	required
`n_images`	`int`	Number of images to generate per (prompt, seed_image) pair. Defaults to 1.	`1`
`model`	`str`	Model identifier for image generation. Common options: - 'gpt-image-1.5' (OpenAI GPT Image 1.5, latest) - 'gpt-image-1' (OpenAI GPT Image 1) - 'dall-e-3' (OpenAI DALL-E 3) - 'dall-e-2' (OpenAI DALL-E 2) Defaults to 'gpt-image-1.5'.	`'gpt-image-1.5'`
`seed_image`	`optional`	A reference image (or list of reference images) to use as a starting point for generation. Each element accepts any format supported by normalize_image_input: file path, URL, PIL Image, bytes, numpy array, base64 string, or file-like object. When provided, the image editing endpoint is used instead of the generation endpoint. If a list is provided, each prompt is applied to every seed image, and outputs are organized into per-seed subfolders. Defaults to None.	`None`
`api_key`	`str`	API key for the AI service. If None, reads from OPENAI_API_KEY environment variable. Defaults to None.	`None`
`return_images`	`bool`	If True, returns list of PIL Image objects. If False, only saves images and returns None. Defaults to True.	`True`
`disable_seed_warning`	`bool`	If True, suppresses the confirmation prompt that appears when multiple seed images would multiply the total image count. Defaults to False.	`False`

Returns:

Type	Description
	list[PIL.Image.Image] or None: List of PIL Image objects if return_images=True, otherwise None

Raises:

Type	Description
`ImportError`	If litellm is not installed
`ValueError`	If OPENAI_API_KEY is not set and api_key is None

Examples:

from figwizz import generate_images

# Generate a single image
images = generate_images(
    "a serene mountain landscape at sunset",
    output_dir="generated_images"
)
images[0].show()

# Generate multiple images from multiple prompts
prompts = [
    "a red apple on a wooden table",
    "a blue ocean with white clouds",
    "a futuristic city at night"
]
images = generate_images(
    prompts,
    output_dir="ai_art",
    n_images=2,  # 2 variations per prompt
    model="gpt-image-1"
)

# Generate with a single seed image (uses image editing endpoint)
images = generate_images(
    "transform this into a watercolor painting",
    output_dir="edited_images",
    seed_image="reference_photo.png"
)

# Generate with multiple seed images
# This will produce 3 prompts x 2 seeds x 1 image = 6 total images
images = generate_images(
    prompts,
    output_dir="multi_seed",
    seed_image=["photo_a.png", "photo_b.png"]
)

# Suppress the confirmation prompt for batch seed generation
images = generate_images(
    prompts,
    output_dir="multi_seed",
    seed_image=["photo_a.png", "photo_b.png"],
    disable_seed_warning=True
)

# Generate without returning images (saves memory)
generate_images(
    prompts,
    output_dir="batch_output",
    return_images=False
)

Note

Requires litellm: pip install litellm or pip install 'figwizz[genai]'
Each prompt creates a subdirectory named after the prompt (sanitized)
When seed images are used, an additional subfolder level is created per seed image (named after the source file, or seed_1, seed_2, etc.)
For each image, saves:
image_N.png - The generated image
image_N_response.json - Full API response
image_N_metadata.json - Curated metadata (prompt, model, timestamp, etc.)
Failed generations are skipped with error messages
Progress is displayed via tqdm progress bars
Image numbering continues from existing images in subdirectories
Prompt text is sanitized for use in directory names (removes special chars)
When seed_image is provided, litellm.image_edit() is used instead of litellm.image_generation(), routing through OpenAI's /images/edits endpoint

stitchkit¶

Presentation processing and PDF stitching utilities.

`stitchkit` ¶

Slide conversion and PDF stitching utilities.

This module provides functions for converting presentation slides (PowerPoint, Keynote) to images and PDFs, with support for whitespace cropping and batch processing.

Platform Support

macOS: Uses AppleScript for Keynote and PowerPoint
Windows: Uses COM interface for PowerPoint
Linux: Uses LibreOffice command-line tools

Example

from figwizz.stitchkit import slides_to_images
slides_to_images('presentation.pptx', 'output_folder', crop_images=True)

`convert_images_to_pdf(input_path, dpi=300, **kwargs)` ¶

Convert all images in a directory and its subdirectories to PDF files.

Recursively searches through all subdirectories and converts every PNG, JPEG, and TIFF image to PDF format. Useful for batch processing entire folder structures.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path to the root directory containing images. All subdirectories will be searched recursively.	required
`dpi`	`int`	DPI (dots per inch) for all output PDF files. Defaults to 300.	`300`
`**kwargs`		Additional keyword arguments passed to convert_to_pdf: - pdf_only (bool): If True, removes original image files after conversion. Defaults to False.	`{}`

Examples:

from figwizz.stitchkit import convert_images_to_pdf

# Convert all images in directory tree
convert_images_to_pdf('project_figures/')

# High-resolution conversion
convert_images_to_pdf('images/', dpi=600)

# Convert and remove originals
convert_images_to_pdf('temp_images/', pdf_only=True)

Note

Searches recursively through all subdirectories
Supported formats: PNG, JPG, JPEG, TIFF, TIF
Each image is converted in its current location
PDF files are created alongside original images
Use pdf_only=True with caution as it deletes original images
Does not follow symbolic links

`convert_to_pdf(image_path, output_path=None, dpi=300, **kwargs)` ¶

Convert PNG, JPEG, or TIFF images to high-quality PDF files.

Creates publication-quality PDF files from raster images with specified resolution. Automatically handles transparency by adding white backgrounds where needed.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to an image file or a directory containing image files. Supported formats: PNG, JPG, JPEG, TIFF, TIF	required
`output_path`	`str`	Path where the PDF files will be saved. - If None, uses same location as input with .pdf extension - For single files, specify output file path - For directories, processes all images in place Defaults to None.	`None`
`dpi`	`int`	DPI (dots per inch) for the output PDF. Common values: - 72: screen resolution (smallest file size) - 150: draft print quality - 300: standard print quality (default) - 600: high-quality print Defaults to 300.	`300`
`**kwargs`		Additional keyword arguments: - pdf_only (bool): If True, removes original image files after conversion. Defaults to False.	`{}`

Returns:

Type	Description
	None

Examples:

from figwizz.stitchkit import convert_to_pdf

# Convert single image
convert_to_pdf('figure.png')  # Creates figure.pdf

# Convert with custom output path
convert_to_pdf('image.jpg', 'document.pdf')

# Convert all images in directory
convert_to_pdf('figures_folder/')

# High-resolution PDF
convert_to_pdf('figure.png', dpi=600)

# Convert and delete original
convert_to_pdf('image.png', pdf_only=True)

# Batch convert to new directory
convert_to_pdf('input_images/', 'pdf_output/')

Note

Automatically converts RGBA/LA images to RGB with white background
Preserves image quality and dimensions
PDF resolution is embedded in the file
When processing directories, converts each image to PDF with same filename
Output directory is created if it doesn't exist
Use pdf_only=True with caution as it deletes original images

`crop_whitespace(image_path, output_path=None, margin_size='1cm', dpi=300)` ¶

Crop whitespace around images and add a specified margin.

Intelligently removes white borders and backgrounds from images while preserving the important content. Optionally adds a clean margin around the cropped content. Perfect for cleaning up screenshots, slides, or figures with excess whitespace.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to an image file or a directory containing image files. If a directory, processes all PNG, JPG, and JPEG files within it.	required
`output_path`	`str`	Path where cropped images will be saved. - If None, overwrites the original files - For single files, specify output file path - For directories, specify output directory path Defaults to None.	`None`
`margin_size`	`str`	Margin to add around cropped content (e.g., '1cm', '0.5cm', '2cm'). Converted to pixels based on DPI. Defaults to '1cm'.	`'1cm'`
`dpi`	`int`	DPI (dots per inch) for margin calculation. Standard values: - 72: screen resolution - 150: draft print quality - 300: standard print quality (default) - 600: high-quality print Defaults to 300.	`300`

Examples:

from figwizz.stitchkit import crop_whitespace

# Crop single image with default 1cm margin
crop_whitespace('screenshot.png')  # Overwrites original

# Crop and save to new file
crop_whitespace('slide.png', 'cropped_slide.png')

# Crop all images in directory
crop_whitespace('slides_folder/')

# Custom margin and DPI
crop_whitespace(
    'figures/',
    output_path='cropped_figures/',
    margin_size='2cm',
    dpi=600
)

# No margin (tight crop)
crop_whitespace('image.png', margin_size='0cm')

Note

Uses intelligent bounding box detection to find content
Converts RGBA images to RGB with white background before cropping
Margin size is converted from centimeters to pixels: pixels = (cm * dpi) / 2.54
When processing directories, preserves original filenames
Supports PNG, JPG, and JPEG formats
Creates output directory if it doesn't exist
Original images are preserved if output_path is specified

`keynote_to_images(input_path, output_path, filename_format='figure{:01d}.png')` ¶

Convert Keynote slides to image files using AppleScript.

Uses macOS AppleScript automation to export all slides from a Keynote presentation as individual PNG images. This is the native method for Keynote conversion on macOS.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path to the Keynote (.key) file	required
`output_path`	`str`	Directory path where the images will be saved. Created automatically if it doesn't exist.	required
`filename_format`	`str`	Python format string for output filenames. Must include a placeholder for slide number. Defaults to 'figure{:01d}.png'.	`'figure{:01d}.png'`

Examples:

from figwizz.stitchkit import keynote_to_images

# Convert Keynote to images
keynote_to_images('presentation.key', 'slides/')

# Custom filename format
keynote_to_images(
    'deck.key',
    'output/',
    filename_format='slide_{:03d}.png'
)

Note

macOS only: Requires Keynote to be installed
Uses AppleScript automation via osascript command
Keynote application will briefly open during conversion
All slides are exported, including hidden/skipped slides
Images are exported in PNG format with transparency
Source: https://iworkautomation.com/keynote/document-export.html

Raises:

Type	Description
`SystemError`	If run on non-macOS platform
`FileNotFoundError`	If Keynote is not installed

`mogrify_images_to_pdf(input_path, **kwargs)` ¶

Convert images to PDF using ImageMagick's mogrify command.

Alternative to convert_images_to_pdf that uses ImageMagick for conversion. Provides high-quality conversion with ImageMagick's robust processing engine. Recursively processes all images in subdirectories.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path to the directory containing images. All subdirectories will be searched recursively.	required
`**kwargs`		Additional keyword arguments: - pdf_only (bool): If True, removes original image files after conversion. Defaults to False.	`{}`

Examples:

from figwizz.stitchkit import mogrify_images_to_pdf

# Convert using ImageMagick
mogrify_images_to_pdf('figures/')

# Convert and remove originals
mogrify_images_to_pdf('temp_images/', pdf_only=True)

Note

Requires ImageMagick: Install with:
macOS: brew install imagemagick
Ubuntu/Debian: sudo apt install imagemagick
Windows: Download from https://imagemagick.org
Uses fixed settings: quality=100, density=300 DPI
Searches recursively through all subdirectories
Supported formats: PNG, JPG, JPEG, TIFF, TIF
Each image is converted in its current location
Generally faster than PIL-based conversion for large batches
Use pdf_only=True with caution as it deletes original images

Raises:

Type	Description
`FileNotFoundError`	If ImageMagick's mogrify command is not found in PATH
`CalledProcessError`	If mogrify command fails

`powerpoint_to_images(input_path, output_path, filename_format='figure{:01d}.png')` ¶

Convert PowerPoint slides to image files.

Platform-aware conversion that automatically uses the best method available for your operating system. Exports all slides from PowerPoint presentations (.ppt, .pptx) as individual PNG images.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path to the PowerPoint file (.ppt or .pptx)	required
`output_path`	`str`	Directory path where the images will be saved. Created automatically if it doesn't exist.	required
`filename_format`	`str`	Python format string for output filenames. Must include a placeholder for slide number. Defaults to 'figure{:01d}.png'.	`'figure{:01d}.png'`

Examples:

from figwizz.stitchkit import powerpoint_to_images

# Convert PowerPoint to images
powerpoint_to_images('presentation.pptx', 'slides/')

# Custom filename format
powerpoint_to_images(
    'deck.pptx',
    'output/',
    filename_format='slide_{:03d}.png'
)

Platform-specific behavior

macOS: - Uses AppleScript with Microsoft PowerPoint - Requires PowerPoint for Mac to be installed - PowerPoint will briefly open during conversion

Windows: - Uses COM interface via win32com.client - Requires PowerPoint and pywin32: pip install pywin32 - PowerPoint runs in background (visible)

Linux/Other: - Uses LibreOffice command-line interface - Requires LibreOffice: sudo apt install libreoffice - Falls back to python-pptx with limited functionality

Note

All slides are exported, including hidden/skipped slides
Images are exported in PNG format
Original slide dimensions are preserved
Output directory is created if it doesn't exist
Existing images with same names are overwritten

Raises:

Type	Description
`ImportError`	If required libraries (pywin32, python-pptx) are not installed
`FileNotFoundError`	If PowerPoint/LibreOffice is not found
`CalledProcessError`	If LibreOffice conversion fails

`reformat_image_filenames(output_path, reformat_pattern)` ¶

Rename image files based on a specified pattern.

Renames all PNG files in a directory to follow a consistent naming pattern. Extracts existing numbers from filenames and applies the new format.

Parameters:

Name	Type	Description	Default
`output_path`	`str`	Directory containing the PNG image files to rename	required
`reformat_pattern`	`str`	Python format string for new filenames (e.g., 'figure{:01d}.png' or 'slide_{:03d}.png'). Must contain a numeric placeholder that will be filled with the extracted slide/image number.	required

Examples:

from figwizz.stitchkit import reformat_image_filenames

# Rename Slide1.png, Slide2.png, etc. to figure1.png, figure2.png
reformat_image_filenames('slides/', 'figure{:01d}.png')

# Rename to zero-padded format: img001.png, img002.png, etc.
reformat_image_filenames('images/', 'img{:03d}.png')

Note

Only processes PNG files
Extracts the first numeric value found in each filename
Files are renamed in place within the same directory
Original files are overwritten with new names
Useful after slides_to_images to standardize naming

`slides_to_images(input_path, output_path, filename_format='figure{:01d}.png', crop_images=True, margin_size='1cm', dpi=300)` ¶

Convert presentation slides to image files.

Extracts all slides from PowerPoint (.ppt, .pptx) or Keynote (.key) presentations as individual PNG images. Automatically detects the presentation format and uses platform-appropriate tools for conversion. Optionally crops whitespace and adds margins for professional-looking figures.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path to the presentation file. Supported formats: - PowerPoint: .ppt, .pptx - Keynote: .key (macOS only)	required
`output_path`	`str`	Directory path where the images will be saved. Created automatically if it doesn't exist.	required
`filename_format`	`str`	Python format string for output filenames. Must include a placeholder for slide number (e.g., '{:01d}' for 1-digit, '{:03d}' for 3-digit with leading zeros). Defaults to 'figure{:01d}.png'.	`'figure{:01d}.png'`
`crop_images`	`bool`	If True, removes whitespace around slides and adds specified margin. If False, keeps original slide dimensions. Defaults to True.	`True`
`margin_size`	`str`	Margin to add around cropped slides (e.g., '1cm', '0.5cm', '2cm'). Only used when crop_images=True. Defaults to '1cm'.	`'1cm'`
`dpi`	`int`	Resolution for output images in dots per inch. Higher values produce larger, higher-quality images. Defaults to 300.	`300`

Examples:

from figwizz import slides_to_images

# Basic conversion
slides_to_images('presentation.pptx', 'output_slides/')

# Without cropping
slides_to_images('slides.pptx', 'figures/', crop_images=False)

# Custom filename format with 3-digit numbering
slides_to_images(
    'deck.key',
    'keynote_slides/',
    filename_format='slide_{:03d}.png'
)

# High resolution with custom margin
slides_to_images(
    'presentation.pptx',
    'high_res_figures/',
    margin_size='2cm',
    dpi=600
)

Note

Platform compatibility: - macOS: Supports both PowerPoint (.ppt, .pptx) and Keynote (.key) Uses AppleScript for automation - Windows: Supports PowerPoint (.ppt, .pptx) only Uses COM interface (pywin32 required) - Linux: Supports PowerPoint via LibreOffice Requires LibreOffice installed

Additional notes: - Output directory is created if it doesn't exist - Existing images with same names are overwritten - Cropping uses intelligent whitespace detection - Margin size is converted to pixels using the specified DPI - Progress is shown for multi-step operations

Supporting Modules¶

colors¶

Color manipulation and analysis utilities.

`colors` ¶

Color processing utilities for FigWizz.

This module provides functions for parsing, extracting, and manipulating colors in images. It supports multiple color input formats and provides intelligent color analysis for automatic color selection.

Key features: - Parse colors from multiple formats (hex, RGB, color names) - Extract dominant colors from images - Generate contrasting colors for borders and text

Example

from figwizz.colors import parse_color, extract_dominant_color, get_contrasting_color
from PIL import Image

# Parse different color formats
rgb = parse_color('#FF5733')
rgb = parse_color('red')
rgb = parse_color((255, 87, 51))

# Extract dominant color from image
img = Image.open('image.png')
dominant = extract_dominant_color(img)

# Get contrasting color
contrast = get_contrasting_color(dominant)

`extract_dominant_color(img, num_colors=5)` ¶

Extract the dominant color from an image using color quantization.

Uses color quantization to reduce the image to a small palette and then identifies the most frequent color, excluding very light colors that are likely backgrounds.

Parameters:

Name	Type	Description	Default
`img`	`Image`	PIL Image object to analyze	required
`num_colors`	`int`	Number of colors to quantize to. Higher values provide more precision but slower processing. Defaults to 5.	`5`

Returns:

Name	Type	Description
`tuple`		RGB tuple (R, G, B) of the dominant color, where each value is in range 0-255

Examples:

from figwizz.colors import extract_dominant_color
from PIL import Image

img = Image.open('photo.jpg')
dominant = extract_dominant_color(img)
print(f"Dominant color: RGB{dominant}")

# Use more colors for better precision
dominant = extract_dominant_color(img, num_colors=10)

Note

Image is resized to 100x100 for faster processing
Very light colors (potential backgrounds) are automatically skipped
Returns the most frequent color after filtering

`get_contrasting_color(rgb, prefer_dark=True)` ¶

Generate a contrasting color for the given RGB color.

Uses relative luminance calculation to determine if the input color is light or dark, then generates an appropriate contrasting color. Useful for creating borders, text overlays, or UI elements that need to stand out against an image.

Parameters:

Name	Type	Description	Default
`rgb`	`tuple`	RGB tuple (R, G, B) where each value is in range 0-255	required
`prefer_dark`	`bool`	If True, prefers dark contrasting colors even for dark inputs (creating darker shades). If False, uses pure black/white contrast. Defaults to True.	`True`

Returns:

Name	Type	Description
`tuple`		RGB tuple (R, G, B) of the contrasting color

Examples:

from figwizz.colors import get_contrasting_color

# Get contrast for a light color (returns dark)
contrast = get_contrasting_color((200, 200, 200))
# Returns: (40, 40, 40)

# Get contrast for a dark color with prefer_dark=False
contrast = get_contrasting_color((50, 50, 50), prefer_dark=False)
# Returns: (255, 255, 255)

# Use with extracted dominant color
from figwizz.colors import extract_dominant_color
dominant = extract_dominant_color(img)
border_color = get_contrasting_color(dominant)

Note

Uses standard relative luminance formula (0.299R + 0.587G + 0.114*B)
When prefer_dark=True, creates darker/more saturated versions for dark inputs
When prefer_dark=False, returns pure black (0,0,0) or white (255,255,255)

`parse_color(color_input)` ¶

Parse color input to RGB tuple.

Parameters:

Name	Type	Description	Default
`color_input`		Hex code ('#RRGGBB'), RGB tuple (R, G, B), or color name ('red', 'blue', etc.)	required

Returns:

Type	Description
	RGB tuple (R, G, B)

Examples:

parse_color('#FF5733')
# Returns: (255, 87, 51)

parse_color((255, 87, 51))
# Returns: (255, 87, 51)

parse_color('red')
# Returns: (255, 0, 0)

webkit¶

Web-related utilities for URL handling and response processing.

`webkit` ¶

Web utilities for URL handling and response processing.

This module provides utilities for working with web resources, including PDF detection and response object conversion.

Example

from figwizz.webkit import is_url_a_pdf
is_pdf = is_url_a_pdf('http://example.com/document.pdf')

`convert_response_to_dict(response, keep_keys=None)` ¶

Convert a webkit response to a dictionary.

Parameters:

Name	Type	Description	Default
`response`		The response from a web request.	required
`keep_keys`	`list[str]`	The keys to keep in the dictionary.	`None`

Returns:

Type	Description
	A dictionary of the response.

`is_url_a_pdf(url)` ¶

Check if a URL points to a PDF file.

Parameters:

Name	Type	Description	Default
`url`		URL to check	required

Returns:

Type	Description
	True if the URL likely points to a PDF

Utilities¶

utils.images¶

Unified image input/output handling.

`images` ¶

Unified image input/output handling utilities.

This module provides a comprehensive system for handling images in various input formats and converting between different representations. It eliminates the need to manually handle different image types throughout the codebase.

Supported input formats: - File paths (local files) - URLs (http/https) - PIL Image objects - Bytes (raw image data) - NumPy arrays - File-like objects (BytesIO, etc.) - Base64 encoded strings

The normalize_image_input function is used extensively throughout figwizz to provide a consistent interface for image operations.

Example

from figwizz.utils.images import normalize_image_input, save_image

# All these work the same way
img1 = normalize_image_input('path/to/image.png')
img2 = normalize_image_input('https://example.com/image.jpg')
img3 = normalize_image_input(bytes_data)
img4 = normalize_image_input(numpy_array)

# Save with automatic format handling
save_image(img1, 'output.jpg', quality=95)

`is_image_path(input_str)` ¶

Check if a string is a valid image file path.

`is_url(input_str)` ¶

Check if a string is a URL.

`normalize_image_input(image_input, return_type='pil')` ¶

Normalize various image input types to a consistent format.

Supports: - Path strings (local file paths) - PIL Image objects - bytes (raw image data) - numpy arrays - file-like objects (BytesIO, BufferedReader, etc.) - base64 encoded strings - URLs (http/https)

Parameters:

Name	Type	Description	Default
`image_input`		Image in any supported format	required
`return_type`		Desired output format ('pil', 'bytes', 'numpy', 'array')	`'pil'`

Returns:

Type	Description
	Image in requested format (default: PIL Image)

Raises:

Type	Description
`ValueError`	If image_input type is not recognized
`FileNotFoundError`	If path doesn't exist
`RuntimeError`	If URL fetch fails

Examples:

img = normalize_image_input('/path/to/image.png')
img = normalize_image_input(bytes_data)
arr = normalize_image_input(img, return_type='numpy')

`normalize_image_output(image, output_format='pil')` ¶

Convert image to specified output format.

Parameters:

Name	Type	Description	Default
`image`		PIL Image object	required
`output_format`		Desired format ('pil', 'bytes', 'numpy', 'array')	`'pil'`

Returns:

Type	Description
	Image in requested format

`save_image(image, output_path, format=None, make_opaque=None, **kwargs)` ¶

Save image to file with automatic format detection and handling.

Parameters:

Name	Description	Default
`image`	Image in any supported format (will be normalized to PIL)	required
`output_path`	Path where image should be saved	required
`format`	Image format (e.g., 'PNG', 'JPEG'). Auto-detected from path if None.	`None`
`make_opaque`	Whether to add white background for formats that don't support transparency. Auto-detected if None (True for JPEG/PDF, False otherwise).	`None`
`**kwargs`	Additional arguments passed to PIL Image.save()	`{}`

Returns:

Type	Description
	Path to saved image

Examples:

save_image(img, 'output.png')
save_image(img, 'output.jpg', quality=95)

utils.environ¶

Environment variable loading and management.

`environ` ¶

Environment variable loading and capability checking functions.

This module provides utilities for managing environment variables and detecting available API capabilities based on configured keys. It handles .env file loading and provides helpful capability reports for optional features.

Key features: - Automatic .env file discovery in current and parent directories - Support for multiple .env file naming conventions - Capability detection for stock image providers and AI services - Verbose reporting of available features

The auto_load_env function is called automatically when importing figwizz, making environment setup seamless.

Example

from figwizz.utils.environ import check_capabilities, load_env_variables

# Check what features are available
capabilities = check_capabilities(verbose=True)

# Manually load specific .env file
load_env_variables('.env.production')

`auto_load_env(verbose=False, silent_on_missing=True)` ¶

Automatically search for and load environment variables on import.

Parameters¶

verbose : bool If True, print capability information silent_on_missing : bool If True, don't raise an error if no .env file is found

Returns¶

dict or None Dictionary of available capabilities, or None if silent_on_missing=True

`check_capabilities(verbose=False)` ¶

Check which capabilities are available based on environment variables.

Parameters¶

verbose : bool If True, print detailed capability information

Returns¶

dict Dictionary mapping capability categories to available providers

`load_env_variables(env_file='auto', update_environ=True, **kwargs)` ¶

Load environment variables from a .env file.

This function reads key-value pairs from a .env file and optionally updates the system environment variables. It handles common .env file formats including quoted values, inline comments, and empty lines.

Parameters:

Name	Type	Description	Default
`env_file`	`str`	Path to .env file, or 'auto' to search for it. When 'auto', uses search_for_env_file() to locate the file. Defaults to 'auto'.	`'auto'`
`update_environ`	`bool`	If True, updates os.environ with the loaded variables. If False, returns the variables as a dictionary without updating the environment. Defaults to True.	`True`
`**kwargs`		Additional keyword arguments passed to search_for_env_file() (e.g., max_parents, abspath)	`{}`

Returns:

Type	Description
	dict or None: Dictionary of environment variables if update_environ=False, otherwise None

Raises:

Type	Description
`FileNotFoundError`	If no .env file is found

Examples:

from figwizz.utils.environ import load_env_variables

# Load and update environment
load_env_variables()

# Load without updating environment
env_vars = load_env_variables(update_environ=False)
print(env_vars)

# Load specific file
load_env_variables(env_file='.env.production')

Note

Handles quoted values (single or double quotes)
Strips inline comments (text after '#')
Skips empty lines and comment-only lines
Malformed lines are skipped with a warning
Supports values containing '=' characters

`search_for_env_file(env_file='auto', max_parents=3, abspath=False)` ¶

Search for environment variable files in the current and parent directories.

This function searches for .env files starting from the current working directory and traversing up to a specified number of parent directories. It supports multiple .env file naming conventions.

Parameters:

Name	Type	Description	Default
`env_file`	`str`	Specific .env file name to search for, or 'auto' to search for common variants. Defaults to 'auto'. When 'auto', searches for: .env, .env.local, .env.development, .env.production	`'auto'`
`max_parents`	`int`	Maximum number of parent directories to search. Defaults to 3.	`3`
`abspath`	`bool`	If True, returns absolute path. If False, returns relative path. Defaults to False.	`False`

Returns:

Type	Description
	str or None: Path to the found .env file, or None if not found

Examples:

from figwizz.utils.environ import search_for_env_file

# Search for any common .env file
env_path = search_for_env_file()

# Search for a specific .env file
env_path = search_for_env_file(env_file='production')

# Get absolute path
env_path = search_for_env_file(abspath=True)

Note

Searches in order: current directory, parent, grandparent, etc.
Stops at first match found
Prints the path of the found file

Workflows¶

workflows.icons¶

Hexicon and icon generation workflows.

`icons` ¶

Icon workflow and convenience functions.

This module provides high-level workflows for creating icons from images, particularly tidyverse-style hexagonal icons (hexicons) commonly used in the R community for package logos.

The make_hexicon function is a convenient wrapper around the ngon_crop function with sensible defaults for creating hexagonal icons.

Example

from figwizz import make_hexicon

# Create a simple hexicon
hexicon = make_hexicon('logo.png')
hexicon.save('hexicon.png')

# Create hexicon with border
hexicon = make_hexicon('logo.png', border_size=5, border_color='auto')

`make_hexicon(input_image, size=None, **kwargs)` ¶

Make a tidyverse-style Hexicon from an input image.

Parameters:

Name	Description	Default
`input_image`	Image in any supported format (path, PIL Image, bytes, numpy array, URL, etc.).	required
`size`	Size of the output image as (width, height). If None, uses a square based on the smallest dimension of the input image.	`None`
`**kwargs`	Additional keyword arguments for ngon_crop. shift_x: Horizontal shift in pixels (default: 0). Positive values shift right. shift_y: Vertical shift in pixels (default: 0). Positive values shift down. rotation: Rotation angle in degrees (default: 0). border_size: Width of the border in pixels (default: 0, no border). border_color: Border color. Can be: - "auto": Automatically select contrasting color from image - Hex code: e.g., "#FF5733" - RGB tuple: e.g., (255, 87, 51) - Color name: e.g., "red", "blue" background_color: Background color inside the hexagon (default: None for transparent). Can be hex code, RGB tuple, or color name. Area outside hexagon remains transparent.	`{}`

Returns: PIL Image object with the hexicon applied.

Examples:

# Make a hexicon with no border
img = make_hexicon("input.png")

# Make a hexicon with red border and padding
img = make_hexicon("input.png", border_size=3, border_color="red", padding=20)

# Make hexicon with slight upwards shift
img = make_hexicon("input.png", shift_y=10)

# Make hexicon with white background inside
img = make_hexicon("input.png", background_color="white")

API Reference¶

Core Modules¶

convert¶

convert ¶

convert_image(source_path, target_format, delete_original=False) ¶

svg_to_image(svg_content, output_path, width=None, height=None, scale=None) ¶

modify¶

modify ¶

make_image_opaque(img_input, bg_color=(255, 255, 255)) ¶

ngon_crop(img_input, sides=6, crop_size=None, shift_x=0, shift_y=0, rotation=0, border_size=0, border_color='auto', padding=0, background_color=None) ¶

display¶

display ¶

make_image_grid(images, titles=None, max_cols=None, show_index=False, figsize=None, title_fontsize=10, show_axes=False) ¶

scrape¶

scrape ¶

download_pdf_from_url(url) ¶

download_pixabay_images(query, n_images, output_dir, api_key=None) ¶

download_stock_images(query, n_images, output_dir, provider='pixabay', api_key=None) ¶

download_unsplash_images(query, n_images, output_dir, api_key=None) ¶

extract_images_from_pdf(pdf_path, output_dir, min_width=100, min_height=100, name_prefix='figure') ¶

extract_images_from_url(url, output_dir, min_width=100, min_height=100, name_prefix='figure', convert_svg=False, svg_scale=3.0) ¶

generate¶

generate ¶

extract_image_data(response) ¶

generate_images(prompts, output_dir, n_images=1, model='gpt-image-1.5', seed_image=None, api_key=None, return_images=True, disable_seed_warning=False) ¶

stitchkit¶

stitchkit ¶

convert_images_to_pdf(input_path, dpi=300, **kwargs) ¶

convert_to_pdf(image_path, output_path=None, dpi=300, **kwargs) ¶

crop_whitespace(image_path, output_path=None, margin_size='1cm', dpi=300) ¶

keynote_to_images(input_path, output_path, filename_format='figure{:01d}.png') ¶

mogrify_images_to_pdf(input_path, **kwargs) ¶

powerpoint_to_images(input_path, output_path, filename_format='figure{:01d}.png') ¶

reformat_image_filenames(output_path, reformat_pattern) ¶

slides_to_images(input_path, output_path, filename_format='figure{:01d}.png', crop_images=True, margin_size='1cm', dpi=300) ¶

Supporting Modules¶

colors¶

colors ¶

extract_dominant_color(img, num_colors=5) ¶

get_contrasting_color(rgb, prefer_dark=True) ¶

parse_color(color_input) ¶

webkit¶

webkit ¶

convert_response_to_dict(response, keep_keys=None) ¶

is_url_a_pdf(url) ¶

Utilities¶

utils.images¶

images ¶

is_image_path(input_str) ¶

is_url(input_str) ¶

normalize_image_input(image_input, return_type='pil') ¶

normalize_image_output(image, output_format='pil') ¶

save_image(image, output_path, format=None, make_opaque=None, **kwargs) ¶

utils.environ¶

environ ¶

auto_load_env(verbose=False, silent_on_missing=True) ¶

Parameters¶

Returns¶

check_capabilities(verbose=False) ¶

Parameters¶

Returns¶

load_env_variables(env_file='auto', update_environ=True, **kwargs) ¶

search_for_env_file(env_file='auto', max_parents=3, abspath=False) ¶

Workflows¶

workflows.icons¶

icons ¶

make_hexicon(input_image, size=None, **kwargs) ¶

`convert` ¶

`convert_image(source_path, target_format, delete_original=False)` ¶

`svg_to_image(svg_content, output_path, width=None, height=None, scale=None)` ¶

`modify` ¶

`make_image_opaque(img_input, bg_color=(255, 255, 255))` ¶

`ngon_crop(img_input, sides=6, crop_size=None, shift_x=0, shift_y=0, rotation=0, border_size=0, border_color='auto', padding=0, background_color=None)` ¶

`display` ¶

`make_image_grid(images, titles=None, max_cols=None, show_index=False, figsize=None, title_fontsize=10, show_axes=False)` ¶

`scrape` ¶

`download_pdf_from_url(url)` ¶

`download_pixabay_images(query, n_images, output_dir, api_key=None)` ¶

`download_stock_images(query, n_images, output_dir, provider='pixabay', api_key=None)` ¶

`download_unsplash_images(query, n_images, output_dir, api_key=None)` ¶

`extract_images_from_pdf(pdf_path, output_dir, min_width=100, min_height=100, name_prefix='figure')` ¶

`extract_images_from_url(url, output_dir, min_width=100, min_height=100, name_prefix='figure', convert_svg=False, svg_scale=3.0)` ¶

`generate` ¶

`extract_image_data(response)` ¶

`generate_images(prompts, output_dir, n_images=1, model='gpt-image-1.5', seed_image=None, api_key=None, return_images=True, disable_seed_warning=False)` ¶

`stitchkit` ¶

`convert_images_to_pdf(input_path, dpi=300, **kwargs)` ¶

`convert_to_pdf(image_path, output_path=None, dpi=300, **kwargs)` ¶

`crop_whitespace(image_path, output_path=None, margin_size='1cm', dpi=300)` ¶

`keynote_to_images(input_path, output_path, filename_format='figure{:01d}.png')` ¶

`mogrify_images_to_pdf(input_path, **kwargs)` ¶

`powerpoint_to_images(input_path, output_path, filename_format='figure{:01d}.png')` ¶

`reformat_image_filenames(output_path, reformat_pattern)` ¶

`slides_to_images(input_path, output_path, filename_format='figure{:01d}.png', crop_images=True, margin_size='1cm', dpi=300)` ¶

`colors` ¶

`extract_dominant_color(img, num_colors=5)` ¶

`get_contrasting_color(rgb, prefer_dark=True)` ¶

`parse_color(color_input)` ¶

`webkit` ¶

`convert_response_to_dict(response, keep_keys=None)` ¶

`is_url_a_pdf(url)` ¶

`images` ¶

`is_image_path(input_str)` ¶

`is_url(input_str)` ¶

`normalize_image_input(image_input, return_type='pil')` ¶

`normalize_image_output(image, output_format='pil')` ¶

`save_image(image, output_path, format=None, make_opaque=None, **kwargs)` ¶

`environ` ¶

`auto_load_env(verbose=False, silent_on_missing=True)` ¶

`check_capabilities(verbose=False)` ¶

`load_env_variables(env_file='auto', update_environ=True, **kwargs)` ¶

`search_for_env_file(env_file='auto', max_parents=3, abspath=False)` ¶

`icons` ¶

`make_hexicon(input_image, size=None, **kwargs)` ¶