proper-pixel-art 1.3.4__tar.gz

proper_pixel_art-1.3.4/.github/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to Proper Pixel Art
+
+Thank you for contributing! Here's how to get started.
+
+## Development Setup
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/KennethJAllen/proper-pixel-art.git
+   cd proper-pixel-art
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+## Before Submitting a Pull Request
+
+Please ensure your code passes all checks:
+
+### 1. Format your code
+
+```bash
+uv run ruff format
+```
+
+### 2. Check for linting issues
+
+```bash
+uv run ruff check
+```
+
+### 3. Run tests
+
+```bash
+uv run pytest -s
+```
+
+- If changing the main pixelate algorithm, manualy check the results in `tests/outputs/`
+- If necessary, change the number of colors in `tests/conftest.py`

proper_pixel_art-1.3.4/.github/workflows/workflow.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+    - name: Build package
+      run: uv build
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

proper_pixel_art-1.3.4/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+output/
+tests/outputs/
+notebooks/
+.python-version
+*__pycache__*

proper_pixel_art-1.3.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kenneth Allen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proper_pixel_art-1.3.4/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: proper-pixel-art
+Version: 1.3.4
+Summary: Converts pixel-art-style images such as those from generative models or low-quality sprite web uploads to true resolution usable assets.
+Author: Kenneth Allen
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.2.4
+Requires-Dist: opencv-python>=4.11.0.86
+Requires-Dist: pillow>=11.1.0
+Provides-Extra: web
+Requires-Dist: gradio>=5.0.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# Proper Pixel Art
+
+## Summary
+
+- Converts noisy, high resolution pixel-art-style images such as those produced by generative models to true pixel resolution assets.
+
+- Clean screenshots or low-quality web uploads of sprites.
+
+## Installation
+
+### Clone the Repository
+
+```bash
+git clone git@github.com:KennethJAllen/proper-pixel-art.git
+cd proper-pixel-art
+```
+
+### Create Virtual Environment
+
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if not already installed.
+- Sync environments
+  - `uv sync`
+
+## Usage
+
+First, obtain a source pixel-art-style image (e.g. a pixel-art-style image generated by GPT-4o or a screenshot of pixel-art).
+
+### CLI
+
+```bash
+uv run ppa <input_path> -o <output_path> -c <num_colors> -s <result_scale> [-t]
+# or directly using uvx
+uvx --from https://github.com/KennethJAllen/proper-pixel-art.git ppa <input_path> -o <output_path> -c <num_colors> -s <result_scale> [-t]
+```
+
+#### Flags
+
+| Flag                             | Description                                                                                               |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| INPUT (positional)        | Source file in pixel-art-style                                                                      |
+| `-o`, `--output` `<path>`        | Output directory or file path for result. (default: '.')                                                  |
+| `-c`, `--colors` `<int>`         | Number of colors for output. May need to try a few different values. (default 16)                         |
+| `-s`, `--scale-result` `<int>`     | Width/height of each "pixel" in the output. (default: 1)                                                          |
+| `-t`, `--transparent` `<bool>`   | Output with transparent background. (default: off)                                                        |
+| `-u`, `--initial-upscale` `<int>` | Initial image upscale factor. Increasing this may help detect pixel edges. (default 2)                    |
+| `-w`, `--pixel-width` `<int>`    | Width of the pixels in the input image. If not set, it will be determined automatically. (default: None)  |
+
+#### Example
+
+`uv run ppa assets/blob/blob.png -c 16 -s 20 -t`
+
+### Python
+
+```python
+from PIL import Image
+from proper_pixel_art.pixelate import pixelate
+
+image = Image.open('path/to/input.png')
+result = pixelate(image, num_colors=16)
+result.save('path/to/output.png')
+```
+
+#### Parameters
+
+- `image` : `PIL.Image.Image`
+
+  - A PIL image to pixelate.
+
+- `num_colors` : `int`
+
+  - The number of colors in result.
+  - May need to try a few values if the colors don't look right.
+  - 8, 16, 32, or 64 typically works.
+
+- `initial_upscale` : `int`
+
+  - Upscale result after algorithm is complete if not None.
+
+- `scale_result` : `int`
+
+  - Upscale initial image. This may help detect lines.
+
+- `transparent_background` : `bool`
+  - If True, flood fills each corner of the result with transparent alpha.
+
+- `intermediate_dir` : `Path | None`
+  - Directory to save images visualizing intermediate steps of algorithm. Useful for development.
+
+- `pixel_width` : `int | None`
+  - Width of the pixels in the input image. If not set, it will be determined automatically. It may be helpful to increase this parameter if not enough pixel edges are being detected.
+
+#### Returns
+
+A PIL image with true pixel resolution and quantized colors.
+
+### Web Interface
+
+Local:
+
+```bash
+uv sync --extra web
+uv run ppa-web
+# Opens http://127.0.0.1:7860
+```
+
+Without cloning:
+
+```bash
+uvx --from "proper-pixel-art[web]" ppa-web
+```
+
+## Examples
+
+The algorithm is robust. It performs well for images that are already approximately alligned to a grid.
+
+Here are a few examples. A mesh is computed, where each cell corresponds to one pixel.
+
+### Bat
+
+- Generated by GPT-4o.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/bat/bat.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/bat/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/bat/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+### Ash
+
+- Screenshot from Google images of Pokemon asset.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/ash/ash.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/ash/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/ash/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+### Demon
+
+- Original image generated by GPT-4o.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/demon/demon.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/demon/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/demon/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+### Pumpkin
+
+- Screenshot from Google Images of Stardew Valley asset. This is an adversarial example as the source image is both low quality and the object is round.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/pumpkin/pumpkin.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/pumpkin/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/pumpkin/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+## Real Images To Pixel Art
+
+- This tool can also be used to convert real images to pixel art by first requesting a pixelated version of the original image from GPT-4o, then using the tool to get the true pixel-resolution image.
+
+- Consider this image of a mountain
+
+<img src="./assets/mountain/real.jpg" width="50%" alt="Original mountain"/>
+
+- Here are the results of first requesting a pixelated version of the mountain, then using the tool to get a true resolution pixel art version.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/mountain/mountain.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/mountain/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/mountain/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+## Challenges
+
+The result of pixel-art style images from LLMs are noisy, high resolution images with a non-uniform grid and random artifacts. Due to these issues, standard downsampling techniques do not work. How can we recover the pixel art with "true" resolution and colors?
+
+The current approach to turning pixel art into useable assets for games are either
+
+1) Use naive downsampling which does not give a result that is faithful to the original image.
+2) Manually re-create the image in the appropriate resolution pixel by pixel.
+
+## Algorithm
+
+- The main algorithm solves these challenges. Here is a high level overview. We will apply it step by step on this example image of blob pixel art that was generated from GPT-4o.
+
+<img src="./assets/blob/blob.png" width="80%" alt="blob"/>
+
+- Note that this image is high resolution and noisy.
+
+<img src="./assets/blob/zoom.png" width="80%" alt="The blob is noisy."/>
+
+1) Trim the edges of the image and zero out pixels with more than 50% alpha.
+    - This is to work around some issues with models such as GPT-4o not giving a perfectly transparent background.
+
+2) Upscale by a factor of 2 using nearest neighbor.
+    - This can help identify the correct pixel mesh.
+
+3) Find edges of the pixel art using [Canny edge detection](https://docs.opencv.org/4.x/da/d22/tutorial_py_canny.html).
+
+<img src="./assets/blob/edges.png" width="80%" alt="blob edges"/>
+
+4) Close small gaps in edges with a [morphological closing](https://docs.opencv.org/4.x/d9/d61/tutorial_py_morphological_ops.html).
+
+<img src="./assets/blob/closed_edges.png" width="80%" alt="blob closed edges"/>
+
+5) Take the [probabalistic Hough transform](https://docs.opencv.org/4.x/d3/de6/tutorial_js_houghlines.html) to get the coordinates of lines in the detected edges. Only keep lines that are close to vertical or horizontal giving some grid coordinates. Cluster lines that are closeby together.
+
+<img src="./assets/blob/lines.png" width="80%" alt="blob lines"/>
+
+6) Find the grid spacing by filtering outliers and taking the median of the spacings, then complete the mesh.
+
+<img src="./assets/blob/mesh.png" width="80%" alt="blob mesh"/>
+
+7) Quantize the original image to a small number of colors.
+    - Note: The result is sensitive to the number of colors chosen.
+    - The parameter is not difficult to tune, but the script may need to be re-run if the colors don't look right.
+    - 8, 16, 32, or 64 typically works.
+
+8) In each cell specified by the mesh, choose the most common color in the cell as the color for the pixel. Recreate the original image with one pixel per cell.
+
+    - Result upscaled by a factor of $20 \times$ using nearest neighbor.
+
+<img src="./assets/blob/result.png" width="80%" alt="blob pixelated"/>
+
+## Testing
+
+To test algorithm changes and verify output quality:
+
+```bash
+uv run pytest -s
+```
+
+The tests pixelate all assets in `assets/{name}/{name}.png` and save outputs to `tests/outputs/` for manual visual inspection.

proper_pixel_art-1.3.4/README.md

@@ -0,0 +1,289 @@
+# Proper Pixel Art
+
+## Summary
+
+- Converts noisy, high resolution pixel-art-style images such as those produced by generative models to true pixel resolution assets.
+
+- Clean screenshots or low-quality web uploads of sprites.
+
+## Installation
+
+### Clone the Repository
+
+```bash
+git clone git@github.com:KennethJAllen/proper-pixel-art.git
+cd proper-pixel-art
+```
+
+### Create Virtual Environment
+
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if not already installed.
+- Sync environments
+  - `uv sync`
+
+## Usage
+
+First, obtain a source pixel-art-style image (e.g. a pixel-art-style image generated by GPT-4o or a screenshot of pixel-art).
+
+### CLI
+
+```bash
+uv run ppa <input_path> -o <output_path> -c <num_colors> -s <result_scale> [-t]
+# or directly using uvx
+uvx --from https://github.com/KennethJAllen/proper-pixel-art.git ppa <input_path> -o <output_path> -c <num_colors> -s <result_scale> [-t]
+```
+
+#### Flags
+
+| Flag                             | Description                                                                                               |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| INPUT (positional)        | Source file in pixel-art-style                                                                      |
+| `-o`, `--output` `<path>`        | Output directory or file path for result. (default: '.')                                                  |
+| `-c`, `--colors` `<int>`         | Number of colors for output. May need to try a few different values. (default 16)                         |
+| `-s`, `--scale-result` `<int>`     | Width/height of each "pixel" in the output. (default: 1)                                                          |
+| `-t`, `--transparent` `<bool>`   | Output with transparent background. (default: off)                                                        |
+| `-u`, `--initial-upscale` `<int>` | Initial image upscale factor. Increasing this may help detect pixel edges. (default 2)                    |
+| `-w`, `--pixel-width` `<int>`    | Width of the pixels in the input image. If not set, it will be determined automatically. (default: None)  |
+
+#### Example
+
+`uv run ppa assets/blob/blob.png -c 16 -s 20 -t`
+
+### Python
+
+```python
+from PIL import Image
+from proper_pixel_art.pixelate import pixelate
+
+image = Image.open('path/to/input.png')
+result = pixelate(image, num_colors=16)
+result.save('path/to/output.png')
+```
+
+#### Parameters
+
+- `image` : `PIL.Image.Image`
+
+  - A PIL image to pixelate.
+
+- `num_colors` : `int`
+
+  - The number of colors in result.
+  - May need to try a few values if the colors don't look right.
+  - 8, 16, 32, or 64 typically works.
+
+- `initial_upscale` : `int`
+
+  - Upscale result after algorithm is complete if not None.
+
+- `scale_result` : `int`
+
+  - Upscale initial image. This may help detect lines.
+
+- `transparent_background` : `bool`
+  - If True, flood fills each corner of the result with transparent alpha.
+
+- `intermediate_dir` : `Path | None`
+  - Directory to save images visualizing intermediate steps of algorithm. Useful for development.
+
+- `pixel_width` : `int | None`
+  - Width of the pixels in the input image. If not set, it will be determined automatically. It may be helpful to increase this parameter if not enough pixel edges are being detected.
+
+#### Returns
+
+A PIL image with true pixel resolution and quantized colors.
+
+### Web Interface
+
+Local:
+
+```bash
+uv sync --extra web
+uv run ppa-web
+# Opens http://127.0.0.1:7860
+```
+
+Without cloning:
+
+```bash
+uvx --from "proper-pixel-art[web]" ppa-web
+```
+
+## Examples
+
+The algorithm is robust. It performs well for images that are already approximately alligned to a grid.
+
+Here are a few examples. A mesh is computed, where each cell corresponds to one pixel.
+
+### Bat
+
+- Generated by GPT-4o.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/bat/bat.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/bat/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/bat/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+### Ash
+
+- Screenshot from Google images of Pokemon asset.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/ash/ash.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/ash/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/ash/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+### Demon
+
+- Original image generated by GPT-4o.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/demon/demon.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/demon/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/demon/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+### Pumpkin
+
+- Screenshot from Google Images of Stardew Valley asset. This is an adversarial example as the source image is both low quality and the object is round.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/pumpkin/pumpkin.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/pumpkin/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/pumpkin/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+## Real Images To Pixel Art
+
+- This tool can also be used to convert real images to pixel art by first requesting a pixelated version of the original image from GPT-4o, then using the tool to get the true pixel-resolution image.
+
+- Consider this image of a mountain
+
+<img src="./assets/mountain/real.jpg" width="50%" alt="Original mountain"/>
+
+- Here are the results of first requesting a pixelated version of the mountain, then using the tool to get a true resolution pixel art version.
+
+<table align="center" width="100%">
+  <tr>
+    <td width="33%">
+      <img src="./assets/mountain/mountain.png" style="width:100%;" />
+      <br><small>Noisy, High Resolution</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/mountain/mesh.png" style="width:100%;" />
+      <br><small>Mesh</small>
+    </td>
+    <td width="33%">
+      <img src="./assets/mountain/result.png" style="width:100%;" />
+      <br><small>True Pixel Resolution</small>
+    </td>
+  </tr>
+</table>
+
+## Challenges
+
+The result of pixel-art style images from LLMs are noisy, high resolution images with a non-uniform grid and random artifacts. Due to these issues, standard downsampling techniques do not work. How can we recover the pixel art with "true" resolution and colors?
+
+The current approach to turning pixel art into useable assets for games are either
+
+1) Use naive downsampling which does not give a result that is faithful to the original image.
+2) Manually re-create the image in the appropriate resolution pixel by pixel.
+
+## Algorithm
+
+- The main algorithm solves these challenges. Here is a high level overview. We will apply it step by step on this example image of blob pixel art that was generated from GPT-4o.
+
+<img src="./assets/blob/blob.png" width="80%" alt="blob"/>
+
+- Note that this image is high resolution and noisy.
+
+<img src="./assets/blob/zoom.png" width="80%" alt="The blob is noisy."/>
+
+1) Trim the edges of the image and zero out pixels with more than 50% alpha.
+    - This is to work around some issues with models such as GPT-4o not giving a perfectly transparent background.
+
+2) Upscale by a factor of 2 using nearest neighbor.
+    - This can help identify the correct pixel mesh.
+
+3) Find edges of the pixel art using [Canny edge detection](https://docs.opencv.org/4.x/da/d22/tutorial_py_canny.html).
+
+<img src="./assets/blob/edges.png" width="80%" alt="blob edges"/>
+
+4) Close small gaps in edges with a [morphological closing](https://docs.opencv.org/4.x/d9/d61/tutorial_py_morphological_ops.html).
+
+<img src="./assets/blob/closed_edges.png" width="80%" alt="blob closed edges"/>
+
+5) Take the [probabalistic Hough transform](https://docs.opencv.org/4.x/d3/de6/tutorial_js_houghlines.html) to get the coordinates of lines in the detected edges. Only keep lines that are close to vertical or horizontal giving some grid coordinates. Cluster lines that are closeby together.
+
+<img src="./assets/blob/lines.png" width="80%" alt="blob lines"/>
+
+6) Find the grid spacing by filtering outliers and taking the median of the spacings, then complete the mesh.
+
+<img src="./assets/blob/mesh.png" width="80%" alt="blob mesh"/>
+
+7) Quantize the original image to a small number of colors.
+    - Note: The result is sensitive to the number of colors chosen.
+    - The parameter is not difficult to tune, but the script may need to be re-run if the colors don't look right.
+    - 8, 16, 32, or 64 typically works.
+
+8) In each cell specified by the mesh, choose the most common color in the cell as the color for the pixel. Recreate the original image with one pixel per cell.
+
+    - Result upscaled by a factor of $20 \times$ using nearest neighbor.
+
+<img src="./assets/blob/result.png" width="80%" alt="blob pixelated"/>
+
+## Testing
+
+To test algorithm changes and verify output quality:
+
+```bash
+uv run pytest -s
+```
+
+The tests pixelate all assets in `assets/{name}/{name}.png` and save outputs to `tests/outputs/` for manual visual inspection.