https://github.com/neurobionics/pyopensim
Portable python bindings for OpenSim with comprehensive type hints.
https://github.com/neurobionics/pyopensim
biomechanical-simulations biomechanics opensim python python3 robotics robotics-simulation simulation
Last synced: 10 months ago
JSON representation
Portable python bindings for OpenSim with comprehensive type hints.
- Host: GitHub
- URL: https://github.com/neurobionics/pyopensim
- Owner: neurobionics
- License: apache-2.0
- Created: 2025-08-01T13:40:14.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-16T20:31:26.000Z (10 months ago)
- Last Synced: 2025-08-29T08:44:40.916Z (10 months ago)
- Topics: biomechanical-simulations, biomechanics, opensim, python, python3, robotics, robotics-simulation, simulation
- Language: Python
- Homepage:
- Size: 383 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pyopensim
Portable Python bindings for [OpenSim](https://opensim.stanford.edu/) with comprehensive type hints.
[](https://badge.fury.io/py/pyopensim)
[](https://opensource.org/licenses/Apache-2.0)
## Key Features
- **Portable**: Self-contained Python wheels with bundled OpenSim libraries
- **Type Hints**: Comprehensive `.pyi` stub files for excellent IDE support and type checking
- **Cross-Platform**: Native support for Windows (work in progress), macOS, and Linux
- **Official Bindings**: Uses OpenSim's native SWIG bindings for full API compatibility
- **PyPI Ready**: Simple `pip install` - integrates with standard Python packaging
## Installation
Install directly from PyPI:
```bash
pip install pyopensim
```
No additional setup required! All OpenSim libraries are bundled in the wheel.
## Why pyopensim?
While the OpenSim team provides excellent [conda packages](https://anaconda.org/opensim-org/opensim), pyopensim offers complementary benefits for specific use cases:
- **PyPI Integration**: Available through standard `pip install` for seamless integration with PyPI-based workflows
- **Enhanced IDE Support**: Comprehensive type hints (`.pyi` stubs) provide excellent autocomplete, type checking, and documentation in modern IDEs
- **Wheel Distribution**: Self-contained wheels make it easy to bundle OpenSim with your applications without requiring users to manage conda environments
- **Flexible Deployment**: Works well in environments where conda isn't preferred (Docker containers, CI/CD pipelines)
## Quick Start
```python
import pyopensim as osim
# Create a simple model
model = osim.Model()
model.setName("MyModel")
# Add a body
body = osim.Body("body", 1.0, osim.Vec3(0), osim.Inertia(1))
model.addComponent(body)
# Build and initialize
state = model.initSystem()
print(f"Model has {model.getNumBodies()} bodies")
```
## PyPI Distribution
pyopensim is automatically built and deployed to [PyPI](https://pypi.org/project/pyopensim/) using:
- **Automated Builds**: GitHub Actions CI/CD builds wheels for all platforms
- **cibuildwheel**: Ensures compatibility across Python versions and platforms
- **Bundled Libraries**: All OpenSim dependencies are included in the wheels
- **Version Management**: Semantic versioning aligned with OpenSim releases
- **Automated Tests**: Automated testing ensures each release works correctly
This provides an alternative distribution method that complements the official OpenSim library.
## Contributing
We welcome contributions of all kinds! Whether you're fixing bugs, improving type stubs, or enhancing documentation, your help is appreciated.
**[Contributing Guidelines](CONTRIBUTING.md)** - Complete guide for contributors
**Key areas where you can help:**
- **Type Stub Improvements**: Enhance IDE support and type checking
- **Documentation**: Add examples and usage guides
- **Testing**: Cross-platform validation and edge cases
- **Bug Reports**: Help us improve reliability
## Relationship to OpenSim
pyopensim is an unofficial python package that is built on top of the official [OpenSim](https://github.com/opensim-org/opensim-core) project:
- **Same API**: Identical to the official OpenSim Python bindings
- **Same Functionality**: Full access to all OpenSim features and capabilities
- **Regular Updates**: Tracks OpenSim releases to provide latest features
To use the official OpenSim conda package, checkout this [package](https://anaconda.org/opensim-org/opensim).
## Development
This project builds OpenSim from source to create self-contained Python wheels:
```bash
# Clone the repository
git clone https://github.com/neurobionics/pyopensim.git
cd pyopensim
# Build OpenSim and dependencies
make setup
# Build Python wheels
make build
```
The build process includes:
- Compiling OpenSim's C++ libraries and dependencies
- Generating SWIG Python bindings
- Creating comprehensive type stubs for IDE support
- Bundling everything into portable wheels
## License
This project is licensed under [Apache License 2.0](LICENSE). OpenSim is licensed under the Apache License 2.0.
See the [OpenSim license](https://github.com/opensim-org/opensim-core/blob/main/LICENSE.txt) for details.
## Issues
If you encounter any issues or have questions regarding pyopensim, please open an issue [here](https://github.com/neurobionics/pyopensim/issues).
## Community & Support
- **[Report Issues](https://github.com/neurobionics/pyopensim/issues)** - Bug reports and feature requests
- **[Discussions](https://github.com/neurobionics/pyopensim/discussions)** - Questions and community support
- **[OpenSim Documentation](https://simtk-confluence.stanford.edu/display/OpenSim/Documentation)** - Official OpenSim resources
- **[OpenSim Website](https://opensim.stanford.edu/)** - OpenSim project