{"id":23864476,"url":"https://github.com/scanmountgoat/ssbh_data_py","last_synced_at":"2025-09-08T12:32:49.387Z","repository":{"id":61953996,"uuid":"347509006","full_name":"ScanMountGoat/ssbh_data_py","owner":"ScanMountGoat","description":"Python bindings to the ssbh_data Rust library","archived":false,"fork":false,"pushed_at":"2024-12-31T20:44:25.000Z","size":311,"stargazers_count":7,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-31T21:27:07.841Z","etag":null,"topics":["python","smash-ultimate"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ScanMountGoat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-14T00:20:46.000Z","updated_at":"2024-12-31T20:44:29.000Z","dependencies_parsed_at":"2024-06-15T19:37:53.930Z","dependency_job_id":"adde8ec1-8493-4921-8030-5dc5a8e55dd6","html_url":"https://github.com/ScanMountGoat/ssbh_data_py","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScanMountGoat%2Fssbh_data_py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScanMountGoat%2Fssbh_data_py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScanMountGoat%2Fssbh_data_py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScanMountGoat%2Fssbh_data_py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ScanMountGoat","download_url":"https://codeload.github.com/ScanMountGoat/ssbh_data_py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232310577,"owners_count":18503477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","smash-ultimate"],"created_at":"2025-01-03T08:26:26.917Z","updated_at":"2025-01-03T08:26:27.488Z","avatar_url":"https://github.com/ScanMountGoat.png","language":"Rust","readme":"# ssbh_data_py [![PyPI](https://img.shields.io/pypi/v/ssbh_data_py)](https://pypi.org/project/ssbh-data-py/)\nPython bindings to the [ssbh_data](https://github.com/ultimate-research/ssbh_lib) Rust library. ssbh_data_py provides a higher level abstraction over \nthe binary data stored in SSBH files such as a \"model.numshb\". SSBH files can be created from scratch or modified from existing files entirely in Python.  \n\nReport bugs and request new features in [issues](https://github.com/ScanMountGoat/ssbh_data_py/issues). Check the requirements before reporting on any installation issues.\n\n## Supported Formats\n| Format | Supported Versions (major.minor) | Read | Save |\n| --- | --- | --- | --- |\n| Modl (`.numdlb`, `.nusrcmdlb`) | 1.7 | :heavy_check_mark: | :heavy_check_mark: |\n| Mesh (`.numshb`) | 1.8, 1.9, 1.10 | :heavy_check_mark: | :heavy_check_mark: |\n| Skel (`.nusktb`) | 1.0 | :heavy_check_mark: | :heavy_check_mark: |\n| Anim (`.nuanmb`) | 2.0, 2.1 | :heavy_check_mark: | :heavy_check_mark: (2.0 only) |\n| Matl (`.numatb`) | 1.5, 1.6 | :heavy_check_mark: | :heavy_check_mark: |\n| Hlpb (`.nuhlpb`) | 1.1 | :heavy_check_mark: | :heavy_check_mark: |\n| Adj (`.adjb`) |  | :heavy_check_mark: | :heavy_check_mark: |\n| MeshEx (`.numshexb`) |  | :heavy_check_mark: | :heavy_check_mark: |\n\n## Installing\nThe package can be installed for a supported python version using `pip` on the latest version of Windows, Linux, or MacOS. The prebuilt wheels (`.whl` files) are included only for situations where `pip` might not be available such as for plugin development for applications. \n\nInstalling: `pip install ssbh_data_py`  \nUpdating: `pip install ssbh_data_py --upgrade`\n\nThe minimum supported pip version is 20.3. \n\n## Requirements\nThe package is available on [PyPi](https://pypi.org/project/ssbh_data_py/) for Python 3.9, 3.10, 3.11, 3.12, and 3.13 for newer versions of Windows, Linux, and Mac OS. For other Python versions, build ssbh_data_py from source. ssbh_data_py requires the `numpy` package for transforms and attribute data.\n\n## Getting Started\nEach supported SSBH type has an associated data struct that can be created reading from a file.\n```python\nimport ssbh_data_py\n\nmesh = ssbh_data_py.mesh_data.read_mesh(\"model.numshb\")\nmodl = ssbh_data_py.modl_data.read_modl(\"model.numdlb\")\nskel = ssbh_data_py.skel_data.read_skel(\"model.nusktb\")\n```\n\nIt's also possible to construct new objects. Specify the major and minor version to use a particular file format revision. Note that this only impacts the binary output when calling the save method. Not all versions are supported, so it's recommended to use the default values.  \n```python\n\nmesh = ssbh_data_py.mesh_data.MeshData(major_version=1, minor_version=8)\nmodl = ssbh_data_py.modl_data.ModlData()\nskel = ssbh_data_py.skel_data.SkelData()\n```\n\nssbh_data_py uses standard Python types whenever possible. Conversion to the appropriate binary format is handled automatically on saving. For example, the 4x4 transformation matrix for bone data is simply a numpy array. \n\n\u003e [!IMPORTANT]\n\u003e Specify `dtype=numpy.float32` for float arrays and `dtype=numpy.uint32` for integer arrays to prevent conversion errors.\n\n```python\nimport numpy\n\n# Assign the identity transform to each bone.\nfor bone in skel.bones:\n    bone.transform = numpy.eye((4), dtype=numpy.float32)\n\n# Assign the X coordinate for positions\nfor o in mesh.objects:\n    o.positions[0].data[:, 0] += 1.0\n```\n\nAfter making any changes, the results can be saved back to a file. Using the same path used to read the files will overwrite the file. Even if no edits are made, the resulting file will likely not be binary identical with the original due to floating point rounding errors or the use of different algorithms.\n```python\nmesh.save(\"model_new.numshb\")\nmodl.save(\"model_new.numdlb\")\nskel.save(\"model_new.nusktb\")\n```\n\n## Documentation\nThe Python API is best summarized by the type stub (.pyi) files, which can be found [here](https://github.com/ScanMountGoat/ssbh_data_py/tree/main/ssbh_data_py/ssbh_data_py). The Python API matches the underlying Rust types and functions as closely as possible. The Rust documentation has much more detailed documentation and can be found at https://docs.rs/ssbh_data. For more advanced sample Python scripts, see the [examples](https://github.com/ScanMountGoat/ssbh_data_py/tree/main/examples).\n\n## Building\nRequires a recent version of Rust. The builds published to PyPi are built using [Maturin](https://github.com/PyO3/maturin). Aftering succesfully installing Maturin, running `maturin develop --release` in the ssbh_data_py directory will build and install the module into the current virtual environment. \n\n`maturin build --release` builds the `ssbh_data_py` module that can be imported into Python. The resulting binary can only be used with the current Python version, processor type, and operating system. Rename the `.dll` to `.pyd` on Windows and the `.dylib` to `.so` on Linux or MacOS.\n\nIf the import fails, check that the `.pyd` or `.so` file exists in the appropriate location. Importing may also fail if `ssbh_data_py` was built from source for an operating system or Python interpreter version that isn't compatible with the current Python environment.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscanmountgoat%2Fssbh_data_py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscanmountgoat%2Fssbh_data_py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscanmountgoat%2Fssbh_data_py/lists"}