Metadata-Version: 2.4
Name: py3dst
Version: 1.3.1
Summary: Python module to read/edit 3DST textures.
Author-email: STBrian <brichap100@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/STBrian/py3dst
Keywords: 3dst
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: pillow>=10.0.0
Dynamic: license-file

py3dst is a module that allows to read, edit and convert 3DST textures

# Installation

You can use the latest stable release from PyPi
```bash
pip install py3dst
```

Or install from the repository for latest changes but with the risk of unstability
```bash
pip install git+https://github.com/STBrian/py3dst.git
```

# Command-line interface
The module has a simple command-line interface to perform certain tasks such as displaying the provided file on screen or other conversion tasks between formats

```bash
python -m py3dst -h
```

The previous command shows this help message

```
usage: py3dst [-h] [-c] [-r] [-f FORMAT] [-o OUT] [-v] [path]

Display or convert 3DST textures

positional arguments:
  path                  path to file to open and show        

options:
  -h, --help            show this help message and exit
  -c, --convert         indicates whether to convert the provided file
  -r, --recursive       convert files recursively in the directory
  -f FORMAT, --format FORMAT
                        (optional) color format for the output ('rgba8', 'rgb8', 'rgba5551', 'rgb565', 'rgba4', 'la8', 'la4')        
  -o OUT, --output OUT  destination file or directory if multiple output files
  -v, --version         show program's version number and exit
```

# Supported formats:
- RGBA8
- RGB8
- RGBA5551
- RGB565
- RGBA4
- LA8
- LA4

# How to use
### Open a texture
The open() function decodes and loads the texture at the provided path
```python
from py3dst import Texture3dst

texture = Texture3dst().open("path/to/file")
```

### Create a texture
The new() function allows to create a blank new texture
```python
from py3dst import Texture3dst

texture = Texture3dst().new(128, 128)
```
new() takes 2 arguments: width, height

Optionally you can specify the 'mip_level' and 'format'

### Export a texture
The export() function converts the data and writes the output data to the specified location
```python
texture.export("path/to/out/file")
```

### Convert to PIL Image
The copy() function will create an output of PIL Image type that you can then export to other image format
```python
image = texture.copy(0, 0, texture.size[0], texture.size[1])
image.save("path/to/out/image/")
```
copy() takes 4 arguments: x1, y1, x2, y2

Being the coordinates that indicate the area to copy

### Convert from PIL Image
The fromImage() function will take the PIL Image object and create a new texture with it. Example:
```python
from py3dst import Texture3dst
from PIL import Image

image = Image.open("path/to/image/")
texture = Texture3dst().fromImage(image)
```
fromImage() takes 1 argument: image

image must be a PIL.Image object
