Metadata-Version: 2.4
Name: ardu-imconvert
Version: 2.0.3
Summary: Image converter for Arduboy with real-time preview and multiple output formats
Author-email: zeduckmaster <zeduckmaster@outlook.com>
License-Expression: GPL-3.0-only
Project-URL: Repository, https://gitlab.com/zeduckmaster/ardu-imconvert-v2
Keywords: arduboy,image,converter,sprite
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# ardu-imconvert

A simple image converter for Arduboy which focuses on real-time display and formatting of converted data.

This is a Python rewrite of the original [C++ version](https://gitlab.com/zeduckmaster/ardu-imconvert), using PySide6.

![ardu-imconvert](./screen.png "ardu-imconvert screenshot")

## Fast start

install it:

- from PyPI (requires Python >= 3.12): `pip install ardu-imconvert`.
- download an executable from [releases page](https://gitlab.com/zeduckmaster/ardu-imconvert-v2/-/releases) (Windows and Linux only).

then run it:

- as a GUI application, directly without option: `ardu-imconvert` or `python -m arduimconvert` (if installed from PyPI).
- as a CLI application, with options (see below).

## Features

- Real-time data visualization.
- Supports `.png` and `.gif` image formats.
- Preview function.
- Animation playback.
- Simple raw data format display.
- Extracts mask data from alpha channel.
- Single or multiple source file export (C/C++ header format).
- Support for RLE Cabi compression mode (compatible with `Arduboy2::drawCompressed`).
- Support for ArdBitmap compression mode (compatible with ArdBitmap library).
- Simple assets directory browser (fast switching between images in the same directory).
- Format data for multiple drawing functions:
  - `Arduboy2::drawBitmap`
  - `Arduboy2::drawCompressed`
  - `Sprites::drawExternalMask`
  - `Sprites::drawOverwrite`
  - `Sprites::drawErase`
  - `Sprites::drawSelfMasked`
  - `ArdBitmap::drawCompressed`
- Basic image operations:
  - Negative (invert black and white)
  - Slice tiling
- CLI mode for scripted/batch conversions.

## How to use (GUI)

- Use the mouse wheel to zoom in/out and drag to pan the image in the preview.
- Change format to display ready-to-use converted data for a specific drawing function.
- Use the `Slice` function to split your image into tiles (useful for tilemaps) or sprite frames.
- `Export` exports the current image using the selected format, creating a C/C++ header file next to the source image.
- `Export Selected` exports all selected images from the directory browser.
- `Export All` exports all images from the directory browser.
- `Export As` exports one or multiple images into a single C/C++ header file.

## How to use (CLI)

When called with arguments, `ardu-imconvert` runs in CLI mode. By default it generates a complete C/C++ header file to stdout.

For example:

```
ardu-imconvert image.png                          # output full .h to stdout
ardu-imconvert image.png --output sprite.h        # write to file
ardu-imconvert image.png -f Sprites_drawOverwrite # use a specific format
ardu-imconvert image.png --data                   # output only the data array
ardu-imconvert image.png --mask                   # output only the mask array
ardu-imconvert tilemap.png --slice 8x8            # slice into 8x8 tiles
ardu-imconvert image.png --negative               # invert image before conversion
```

| Option | Description |
|---|---|
| `-f`, `--format` | Output format: `Default`, `RLECabi`, `Arduboy2_drawBitmap`, `Arduboy2_drawCompressed`, `Sprites_drawExternalMask`, `Sprites_drawOverwrite`, `Sprites_drawErase`, `Sprites_drawSelfMasked`, `ArdBitmap_drawCompressed` |
| `--data` | Output only the data array (mutually exclusive with `--mask`) |
| `--mask` | Output only the mask array (mutually exclusive with `--data`) |
| `--output FILE` | Write output to a file instead of stdout |
| `--slice WxH` | Slice the image into tiles of WxH pixels (e.g. `8x8`) |
| `--negative` | Invert the image before conversion |
| `--version` | Show version and exit |

## Development

```
git clone https://gitlab.com/zeduckmaster/ardu-imconvert-v2.git
cd ardu-imconvert-v2
pip install -e .[dev]
python -m pytest            # run tests
python -m arduimconvert     # run the GUI from source
```

## Related Links

- Arduboy2 library: https://github.com/MLXXXp/Arduboy2
- ArdBitmap library: https://github.com/igvina/ArdBitmap
- Icon used: http://www.visualpharm.com/

## License

[GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)
