| Name | imgsplatter JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Create randomized wallpapers from your favorite images |
| upload_time | 2024-10-11 17:31:37 |
| maintainer | None |
| docs_url | None |
| author | DJ Stomp |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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](#installation)
- [Usage](#usage)
- [Command-Line Options](#command-line-options)
- [Examples](#examples)
- [Notes](#notes)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
## Installation
### Prerequisites
- Python 3.6 or higher
- pip package manager
### Install via pip
You can install **imgsplatter** directly from PyPI:
```bash
pip install imgsplatter
```
## Usage
Run the `imgsplatter` module as a Python script from the command line:
```bash
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:
```bash
python -m imgsplatter -i image.png
```
#### Multiple Input Images
Use multiple images to create a more varied splatter:
```bash
python -m imgsplatter -i image1.png -i image2.png -i image3.png
```
#### Custom Canvas Size
Create a square canvas of `1024x1024` pixels:
```bash
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:
```bash
python -m imgsplatter -w 1920 -H 1080 -i image.png
```
#### Adjusting Iterations and Scale
Customize the number of iterations and scale factors:
```bash
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:
```bash
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`:
```bash
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:
```python
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](https://github.com/djstompzone/imgsplatter).
2. **Clone Your Fork**: Clone your forked repository to your local machine.
```bash
git clone https://github.com/yourusername/imgsplatter.git
```
3. **Create a New Branch**: Create a new branch for your feature or bug fix.
```bash
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.
```bash
git commit -am "Add new feature"
```
6. **Push to GitHub**: Push your changes to your GitHub repository.
```bash
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](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](https://github.com/djstompzone/imgsplatter). Alternatively, you can join the [StompZone Discord](https://discord.stomp.zone) to message me directly.
---
*Happy splattering!*
Raw data
{
"_id": null,
"home_page": null,
"name": "imgsplatter",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "DJ Stomp",
"author_email": "85457381+DJStompZone@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/75/af/18389e82d28578e3fe7fdd413850de7b907a4e8a354fe6db1e65436da0f3/imgsplatter-0.1.1.tar.gz",
"platform": null,
"description": "# imgsplatter\n\n**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.\n\n## Features\n\n- **Random Placement and Rotation**: Images are randomly resized, rotated, and placed on the canvas to create a unique splatter effect.\n- **Multiple Input Images**: Use one or multiple input images to diversify the splatter.\n- **Configurable Parameters**: Customize canvas size, number of iterations, scale factors, output quality, and more.\n- **Command-Line Interface**: Easy to use with command-line arguments and real-time progress display using `tqdm`.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Command-Line Options](#command-line-options)\n - [Examples](#examples)\n- [Notes](#notes)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## Installation\n\n### Prerequisites\n\n- Python 3.6 or higher\n- pip package manager\n\n### Install via pip\n\nYou can install **imgsplatter** directly from PyPI:\n\n```bash\npip install imgsplatter\n```\n\n## Usage\n\nRun the `imgsplatter` module as a Python script from the command line:\n\n```bash\npython -m imgsplatter [options]\n```\n\nAlternatively, you can use `imgsplatter` as a command-line tool if installed accordingly.\n\n### Command-Line Options\n\n| Option | Short | Description | Default |\n|--------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|\n| `--width WIDTH` | `-w WIDTH` | Width of the output image. If only width or height is specified, both dimensions will use that value. | `1920` |\n| `--height HEIGHT` | `-H HEIGHT`| Height of the output image. If only width or height is specified, both dimensions will use that value. | `1080` |\n| `--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 |\n| `--iterations N` | | Number of iterations (images to place). | `750` |\n| `--min-scale SCALE` | | Minimum scale factor for resizing images. | `0.15` |\n| `--max-scale SCALE` | | Maximum scale factor for resizing images. | `0.325` |\n| `--output-image FILE` | `-o FILE` | Output image filename. If not specified, defaults to `splatter-<timestamp>.jpg`. | `splatter-<timestamp>.jpg`|\n| `--jpeg-quality QUALITY` | | JPEG quality for the output image (1-95). | `95` |\n| `--help` | `-h` | Show help message and exit. | |\n\n### Examples\n\n#### Basic Usage\n\nGenerate a splatter image using a single input image:\n\n```bash\npython -m imgsplatter -i image.png\n```\n\n#### Multiple Input Images\n\nUse multiple images to create a more varied splatter:\n\n```bash\npython -m imgsplatter -i image1.png -i image2.png -i image3.png\n```\n\n#### Custom Canvas Size\n\nCreate a square canvas of `1024x1024` pixels:\n\n```bash\npython -m imgsplatter -w 1024 -i image.png\n```\n\n#### Custom Dimensions\n\nCreate a canvas with a width of `1920` pixels and a height of `1080` pixels:\n\n```bash\npython -m imgsplatter -w 1920 -H 1080 -i image.png\n```\n\n#### Adjusting Iterations and Scale\n\nCustomize the number of iterations and scale factors:\n\n```bash\npython -m imgsplatter -i image.png --iterations 1000 --min-scale 0.1 --max-scale 0.5\n```\n\n#### Specify Output File and Quality\n\nSet a custom output filename and JPEG quality:\n\n```bash\npython -m imgsplatter -i image.png -o my_splatter.jpg --jpeg-quality 85\n```\n\n#### Full Example\n\nGenerate a `1920x1080` image with 500 iterations, scaling images between 15% and 30% of their original size, and save it as `output-image.jpg`:\n\n```bash\npython -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\n```\n\n## Notes\n\n- **Canvas Size Defaults**: If neither width nor height is provided, the default canvas size is `1920x1080`.\n- **Single Dimension Provided**: If only width or height is specified, both dimensions will use that value, resulting in a square canvas.\n- **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.\n- **Iterations**: The `--iterations` option determines how many images are randomly placed onto the canvas. More iterations result in a denser splatter.\n- **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`.\n\n## Importing in Python Scripts:\n If you wish to use `imgsplatter` within your own Python scripts, you can import the `splatter` function:\n\n ```python\n import argparse\n from imgsplatter.splatter.splatter import splatter\n\n # Prepare arguments as needed\n args = argparse.Namespace(\n width=1920,\n height=1080,\n input_image=['image1.png', 'image2.png'],\n iterations=500,\n min_scale=0.15,\n max_scale=0.3,\n output_image='output-image.jpg',\n jpeg_quality=95\n )\n\n splatter(args)\n ```\n\n Ensure that you import `argparse` if you are creating an `argparse.Namespace` object.\n\n## Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Fork the Repository**: Click the \"Fork\" button at the top right corner of the [GitHub repository](https://github.com/djstompzone/imgsplatter).\n\n2. **Clone Your Fork**: Clone your forked repository to your local machine.\n\n ```bash\n git clone https://github.com/yourusername/imgsplatter.git\n ```\n\n3. **Create a New Branch**: Create a new branch for your feature or bug fix.\n\n ```bash\n git checkout -b feature/your-feature-name\n ```\n\n4. **Make Changes**: Implement your feature or bug fix.\n\n5. **Commit Changes**: Commit your changes with a descriptive commit message.\n\n ```bash\n git commit -am \"Add new feature\"\n ```\n\n6. **Push to GitHub**: Push your changes to your GitHub repository.\n\n ```bash\n git push origin feature/your-feature-name\n ```\n\n7. **Submit a Pull Request**: Open a pull request to the `main` branch of the original repository.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE). You are free to use, modify, and distribute this software in accordance with the terms of the license.\n\n## Contact\n\nFor any questions or suggestions, please open an issue on the [GitHub repository](https://github.com/djstompzone/imgsplatter). Alternatively, you can join the [StompZone Discord](https://discord.stomp.zone) to message me directly.\n\n---\n\n*Happy splattering!*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Create randomized wallpapers from your favorite images",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8ca2e75931a396afde73497d7747cb35442d9ee49d430023603b51cfc27f13e0",
"md5": "6e3cd6f4d30ae9e58f1fdbcd0f331101",
"sha256": "de84aa2d8c30a5f9370f7bc1e2d47a109fc35fdec4a1753e664a087e5b575b50"
},
"downloads": -1,
"filename": "imgsplatter-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e3cd6f4d30ae9e58f1fdbcd0f331101",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 5651,
"upload_time": "2024-10-11T17:31:35",
"upload_time_iso_8601": "2024-10-11T17:31:35.925627Z",
"url": "https://files.pythonhosted.org/packages/8c/a2/e75931a396afde73497d7747cb35442d9ee49d430023603b51cfc27f13e0/imgsplatter-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75af18389e82d28578e3fe7fdd413850de7b907a4e8a354fe6db1e65436da0f3",
"md5": "14d320065bb1b3db1eb6dc6574a75b3c",
"sha256": "ec48bdc5698ab5917c1122f98cc73f739d2b82e569c24c498c191d2a91425d6f"
},
"downloads": -1,
"filename": "imgsplatter-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "14d320065bb1b3db1eb6dc6574a75b3c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 4721,
"upload_time": "2024-10-11T17:31:37",
"upload_time_iso_8601": "2024-10-11T17:31:37.922022Z",
"url": "https://files.pythonhosted.org/packages/75/af/18389e82d28578e3fe7fdd413850de7b907a4e8a354fe6db1e65436da0f3/imgsplatter-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-11 17:31:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "imgsplatter"
}
