shapeio 0.5.0b2

A library that provides functions to decode MSTS/ORTS shape files into Python objects and to encode them back into the shape file format.

shapeio

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.

When modifying shapes using this module, there are no built-in safeguards beyond the structure of the data itself. If you don't know what you're doing, your changes may result in invalid shape files that won't work with Open Rails or MSTS.

List of companion modules:

• shapeedit - provides a wrapper for modifying the shape data structure safely.
• trackshape-utils - offers additional utilities for working with track shapes.
• pyffeditc - handles compression and decompression of shape files through the ffeditc_unicode.exe utility found in MSTS installations.
• pytkutils - handles compression and decompression of shape files through the TK.MSTS.Tokens.dll library by Okrasa Ghia.

Installation

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

Install from PyPI

pip install --upgrade shapeio

Install from wheel

If you have downloaded a .whl file from the Releases page, install it with:

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

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

Install from source

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 or 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.

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.

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.

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.

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. You can also print the objects to view their attributes.

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.

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 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:

pip install pytest
pip install pytest-dependency

Then, run tests with:

pytest

Run Tests with tox

tox allows you to test across multiple Python environments.

1. Install tox

pip install tox

2. Run Tests

tox

This will execute tests in all specified Python versions.

3. tox.ini Configuration

The tox.ini file should be in your project root:

[tox]
envlist = py36, py37, py38, py39, py310

[testenv]
deps = pytest
commands = pytest

Modify envlist to match the Python versions you want to support.

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.

License

This Python module was created by Peter Grønbæk Andersen and is licensed under GNU GPL v3.