imgsplatter 0.1.1

Create randomized wallpapers from your favorite images

imgsplatter

imgsplatter is a Python module that creates a splatter image by randomly placing and rotating images on a canvas. It's perfect for generating abstract backgrounds, artistic wallpapers, or creative collages from your own images.

Features

• Random Placement and Rotation: Images are randomly resized, rotated, and placed on the canvas to create a unique splatter effect.
• Multiple Input Images: Use one or multiple input images to diversify the splatter.
• Configurable Parameters: Customize canvas size, number of iterations, scale factors, output quality, and more.
• Command-Line Interface: Easy to use with command-line arguments and real-time progress display using tqdm.

Table of Contents

• Installation
• Usage
  • Command-Line Options
  • Examples
• Notes
• Contributing
• License
• Contact

Installation

Prerequisites

• Python 3.6 or higher
• pip package manager

Install via pip

You can install imgsplatter directly from PyPI:

pip install imgsplatter

Usage

Run the imgsplatter module as a Python script from the command line:

python -m imgsplatter [options]

Alternatively, you can use imgsplatter as a command-line tool if installed accordingly.

Command-Line Options

Option	Short	Description	Default
--width WIDTH	-w WIDTH	Width of the output image. If only width or height is specified, both dimensions will use that value.	1920
--height HEIGHT	-H HEIGHT	Height of the output image. If only width or height is specified, both dimensions will use that value.	1080
--input-image IMAGE	-i IMAGE	Input image(s) to use. At least one is required. Can be specified multiple times to include multiple images.	Required
--iterations N		Number of iterations (images to place).	750
--min-scale SCALE		Minimum scale factor for resizing images.	0.15
--max-scale SCALE		Maximum scale factor for resizing images.	0.325
--output-image FILE	-o FILE	Output image filename. If not specified, defaults to splatter-<timestamp>.jpg.	splatter-<timestamp>.jpg
--jpeg-quality QUALITY		JPEG quality for the output image (1-95).	95
--help	-h	Show help message and exit.

Examples

Basic Usage

Generate a splatter image using a single input image:

python -m imgsplatter -i image.png

Multiple Input Images

Use multiple images to create a more varied splatter:

python -m imgsplatter -i image1.png -i image2.png -i image3.png

Custom Canvas Size

Create a square canvas of 1024x1024 pixels:

python -m imgsplatter -w 1024 -i image.png

Custom Dimensions

Create a canvas with a width of 1920 pixels and a height of 1080 pixels:

python -m imgsplatter -w 1920 -H 1080 -i image.png

Adjusting Iterations and Scale

Customize the number of iterations and scale factors:

python -m imgsplatter -i image.png --iterations 1000 --min-scale 0.1 --max-scale 0.5

Specify Output File and Quality

Set a custom output filename and JPEG quality:

python -m imgsplatter -i image.png -o my_splatter.jpg --jpeg-quality 85

Full Example

Generate a 1920x1080 image with 500 iterations, scaling images between 15% and 30% of their original size, and save it as output-image.jpg:

python -m imgsplatter -w 1920 -H 1080 -i image1.png -i image2.png --iterations 500 --min-scale 0.15 --max-scale 0.3 -o output-image.jpg

Notes

• Canvas Size Defaults: If neither width nor height is provided, the default canvas size is 1920x1080.
• Single Dimension Provided: If only width or height is specified, both dimensions will use that value, resulting in a square canvas.
• Scale Factors: The --min-scale and --max-scale options determine the range for randomly resizing the input images. Scale factors are relative to the original image size.
• Iterations: The --iterations option determines how many images are randomly placed onto the canvas. More iterations result in a denser splatter.
• JPEG Quality: The --jpeg-quality option sets the quality of the output JPEG image. Higher values mean better quality but larger file sizes. The maximum recommended value is 95.

Importing in Python Scripts:

If you wish to use imgsplatter within your own Python scripts, you can import the splatter function:

import argparse
from imgsplatter.splatter.splatter import splatter

# Prepare arguments as needed
args = argparse.Namespace(
    width=1920,
    height=1080,
    input_image=['image1.png', 'image2.png'],
    iterations=500,
    min_scale=0.15,
    max_scale=0.3,
    output_image='output-image.jpg',
    jpeg_quality=95
)

splatter(args)

Ensure that you import argparse if you are creating an argparse.Namespace object.

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the Repository: Click the "Fork" button at the top right corner of the GitHub repository.

2. Clone Your Fork: Clone your forked repository to your local machine.

   git clone https://github.com/yourusername/imgsplatter.git
   

3. Create a New Branch: Create a new branch for your feature or bug fix.

   git checkout -b feature/your-feature-name
   

4. Make Changes: Implement your feature or bug fix.

5. Commit Changes: Commit your changes with a descriptive commit message.

   git commit -am "Add new feature"
   

6. Push to GitHub: Push your changes to your GitHub repository.

   git push origin feature/your-feature-name
   

7. Submit a Pull Request: Open a pull request to the main branch of the original repository.

License

This project is licensed under the MIT License. You are free to use, modify, and distribute this software in accordance with the terms of the license.

Contact

For any questions or suggestions, please open an issue on the GitHub repository. Alternatively, you can join the StompZone Discord to message me directly.

---

Happy splattering!