Metadata-Version: 2.4
Name: shapeio
Version: 0.5.0b4
Summary: DEPRECATED: Use 'simisa' instead.
Author: Peter Grønbæk Andersen
Author-email: Peter Grønbæk Andersen <peter@grnbk.io>
License: GNU GPL v3
Project-URL: Homepage, https://github.com/pgroenbaek/shapeio
Project-URL: Issues, https://github.com/pgroenbaek/shapeio/issues
Project-URL: Source, https://github.com/pgroenbaek/shapeio
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# shapeio

[![GitHub release (latest by date)](https://img.shields.io/github/v/release/pgroenbaek/shapeio?style=flat&label=Latest%20Version)](https://github.com/pgroenbaek/shapeio/releases)
[![Python 3.7+](https://img.shields.io/badge/Python-3.7%2B-blue?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![License GNU GPL v3](https://img.shields.io/badge/License-%20%20GNU%20GPL%20v3%20-lightgrey?style=flat&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NDAgNTEyIj4KICA8IS0tIEZvbnQgQXdlc29tZSBGcmVlIDYuNy4yIGJ5IEBmb250YXdlc29tZSAtIGh0dHBzOi8vZm9udGF3ZXNvbWUuY29tIExpY2Vuc2UgLSBodHRwczovL2ZvbnRhd2Vzb21lLmNvbS9saWNlbnNlL2ZyZWUgQ29weXJpZ2h0IDIwMjUgRm9udGljb25zLCBJbmMuIC0tPgogIDxwYXRoIGZpbGw9IndoaXRlIiBkPSJNMzg0IDMybDEyOCAwYzE3LjcgMCAzMiAxNC4zIDMyIDMycy0xNC4zIDMyLTMyIDMyTDM5OC40IDk2Yy01LjIgMjUuOC0yMi45IDQ3LjEtNDYuNCA1Ny4zTDM1MiA0NDhsMTYwIDBjMTcuNyAwIDMyIDE0LjMgMzIgMzJzLTE0LjMgMzItMzIgMzJsLTE5MiAwLTE5MiAwYy0xNy43IDAtMzItMTQuMy0zMi0zMnMxNC4zLTMyIDMyLTMybDE2MCAwIDAtMjk0LjdjLTIzLjUtMTAuMy00MS4yLTMxLjYtNDYuNC01Ny4zTDEyOCA5NmMtMTcuNyAwLTMyLTE0LjMtMzItMzJzMTQuMy0zMiAzMi0zMmwxMjggMGMxNC42LTE5LjQgMzcuOC0zMiA2NC0zMnM0OS40IDEyLjYgNjQgMzJ6bTU1LjYgMjg4bDE0NC45IDBMNTEyIDE5NS44IDQzOS42IDMyMHpNNTEyIDQxNmMtNjIuOSAwLTExNS4yLTM0LTEyNi03OC45Yy0yLjYtMTEgMS0yMi4zIDYuNy0zMi4xbDk1LjItMTYzLjJjNS04LjYgMTQuMi0xMy44IDI0LjEtMTMuOHMxOS4xIDUuMyAyNC4xIDEzLjhsOTUuMiAxNjMuMmM1LjcgOS44IDkuMyAyMS4xIDYuNyAzMi4xQzYyNy4yIDM4MiA1NzQuOSA0MTYgNTEyIDQxNnpNMTI2LjggMTk1LjhMNTQuNCAzMjBsMTQ0LjkgMEwxMjYuOCAxOTUuOHpNLjkgMzM3LjFjLTIuNi0xMSAxLTIyLjMgNi43LTMyLjFsOTUuMi0xNjMuMmM1LTguNiAxNC4yLTEzLjggMjQuMS0xMy44czE5LjEgNS4zIDI0LjEgMTMuOGw5NS4yIDE2My4yYzUuNyA5LjggOS4zIDIxLjEgNi43IDMyLjFDMjQyIDM4MiAxODkuNyA0MTYgMTI2LjggNDE2UzExLjcgMzgyIC45IDMzNy4xeiIvPgo8L3N2Zz4=&logoColor=%23ffffff)](https://github.com/pgroenbaek/shapeio/blob/master/LICENSE)

This Python module provides functions to decode MSTS/ORTS shape files into Python objects and to encode them back into the shape file format. The API is very similar to that of the `json` module.

## ⚠️ Deprecation Notice ⚠️

This library is deprecated and will no longer be actively maintained.

**Please migrate to [simisa](https://github.com/pgroenbaek/simisa) for continued development, updates, and support.**

The new `simisa` library also supports reading and writing shapes in compressed/binary format without relying upon external tools like `ffeditc_unicode.exe`.

This package will remain available for existing users, but new projects should use the replacement library instead.


## Installation

The Python module itself can be installed in the following ways:

### Install from PyPI

```sh
pip install --upgrade shapeio
```

### Install from wheel

If you have downloaded a `.whl` file from the [Releases](https://github.com/pgroenbaek/shapeio/releases) page, install it with:

```sh
pip install path/to/shapeio‑<version>‑py3‑none‑any.whl
```

Replace `<version>` with the actual version number in the filename.

### Install from source

```sh
git clone https://github.com/pgroenbaek/shapeio.git
pip install --upgrade ./shapeio
```

## Usage

### Load a shape from a file

To load a shape from disk, use the `shapeio.load` function. Note that the shape file must be decompressed beforehand. Otherwise, you will get a `ShapeCompressedError`.

See the [pyffeditc](https://github.com/pgroenbaek/pyffeditc) or [pytkutils](https://github.com/pgroenbaek/pytkutils) modules for how to decompress a shape, depending on if you want to use the `ffeditc_unicode.exe` utility or the `TK.MSTS.Tokens.dll` library by Okrasa Ghia.

```python
import shapeio

my_shape = shapeio.load("./path/to/example.s")

print(my_shape)
```

### Save a shape to a file

To save a shape to disk, you can use the `shapeio.dump` function. This will serialize the shape object, including any changes made to it, into the structured text format and save it to the specified path.

```python
import shapeio

shapeio.dump(my_shape, "./path/to/output.s")
```

### Serialize a shape to a string

If you want to serialize the object into a string without saving it to a file on disk, you can use `shapeio.dumps`.

```python
import shapeio

shape_string = shapeio.dumps(my_shape)
print(shape_string)
```

### Parse a shape from a string

Similarly, you can use `shapeio.loads` to parse a shape from a string instead of reading it from a file on disk.

```python
import shapeio

shape_text = """
SIMISA@@@@@@@@@@JINX0s1t______

shape (
	shape_header ( 00000000 00000000 )
	volumes ( 12
		vol_sphere (
			vector ( -1.23867 3.5875 40 ) 42.452
		)
		vol_sphere (
			vector ( -1.23867 0.495151 40 ) 40.1839
		)
        ...
"""
shape = shapeio.loads(shape_text)
```

### Accessing shape data

The functions that load shapes return a `Shape` object, allowing you to access all the data defined in the shape file.

To explore the full data structure, see [shape.py](https://github.com/pgroenbaek/shapeio/blob/master/shapeio/shape.py). You can also print the objects to view their attributes.

```python
import shapeio

my_shape = shapeio.load("./path/to/example.s")

# Print the point at index 17.
print(my_shape.points[17])

# Iterate over uv_points, print uv_point at index 10.
for idx, uv_point in enumerate(my_shape.uv_points):
    if idx == 10:
        print(uv_point)
```

### Modifying shape data

You can modify values, add or remove items from lists, and reorder items in the lists. The serialized shape data will reflect any changes you make.

```python
import shapeio
from shapeio import shape

my_shape = shapeio.load("./path/to/example.s")

# Modify an existing point.
my_shape.points[1].x = 17

# Add a new uv_point.
new_uv_point = shape.UVPoint(0.2, 0.5)
my_shape.uv_points.append(new_uv_point)

shapeio.dump(my_shape, "./path/to/output.s")
```

When using this module by itself, there are no built-in safeguards beyond the data structure to ensure that modifications will result in a shape usable in MSTS or Open Rails.

See [shapeedit](https://github.com/pgroenbaek/shapeedit) for a wrapper that allows performing complex operations on the data structure safely.

However, this module will ensure that list counts in the serialized data are correct. It also enforces strict type checking during serialization, which prevents adding items to lists and setting values of attributes that are not of the expected type.

## Running Tests

You can run tests manually or use `tox` to test across multiple Python versions.

### Run Tests Manually
First, install the required dependencies:

```sh
pip install pytest pytest-dependency
```

Then, run tests with:

```sh
pytest
```

### Run Tests with `tox`

First, install the required dependencies:

```sh
pip install tox pytest pytest-dependency
```

Then, run tests with:

```sh
tox
```

This will execute tests for all Python versions specified in `tox.ini`.

## Roadmap

Possible future features to be added:
- Reading compressed shapes
- Writing compressed shapes

## Contributing

Contributions of all kinds are welcome. These could be suggestions, issues, bug fixes, documentation improvements, or new features.

For more details see the [contribution guidelines](https://github.com/pgroenbaek/shapeio/blob/master/CONTRIBUTING.md).

## License

This Python module was created by Peter Grønbæk Andersen and is licensed under [GNU GPL v3](https://github.com/pgroenbaek/shapeio/blob/master/LICENSE).
