pyeyesweb 1.0.0b1

PyEyesWeb is a research toolkit for extracting quantitative features from human movement data.

PyEyesWeb

Expressive movement analysis toolkit

A modern, modular, and accessible Python library for expressive movement analysis — bridging research, health, and the arts

[!WARNING] This library is currently being refactored. Expect breaking API changes and frequent updates in the short term. Please use with caution and report any issues.

PyEyesWeb is a research toolkit for extracting quantitative features from human movement data.
It builds on the Expressive Gesture Analysis library of EyesWeb, bringing expressive movement analysis into Python as a core aim of the project. The library provides computational methods to analyze different qualities of movement, supporting applications in research, health, and the arts.
It is designed to facilitate adoption in artificial intelligence and machine learning pipelines, while also enabling seamless integration with creative and interactive platforms such as TouchDesigner, Unity, and Max/MSP.

Installation

pip install pyeyesweb

Usage

A minimal example of extracting movement features with PyEyesWeb :

from pyeyesweb.data_models import SlidingWindow
from pyeyesweb.low_level import Smoothness

# Movement smoothness analysis
# 1. Initialize the feature extractor (e.g., 50Hz sampling rate)
smoothness = Smoothness(rate_hz=50.0)

# 2. Initialize a sliding window for speed data (1 signal, 1 dimension)
window = SlidingWindow(max_length=60, n_signals=1, n_dims=1)

# 3. Process data frame by frame (simulating a real-time loop)
# here `speed_value` is a float representing the instantaneous speed
window.append(speed_value) 

# 4. Compute the feature (only after the window is full)
if len(window) >= window.max_length:
    result = smoothness(window)
    print(f"SPARC: {result.sparc}, Jerk: {result.jerk_rms}")

[!TIP] For more advanced and complete use cases see the Documentation and the examples folder.

Documentation

Documentation for PyEyesWeb is available online and includes tutorials, API references, and the theoretical and scientific background of the implemented metrics:

• Getting Started: step-by-step guide to installation and basic usage.
• API Reference: technical descriptions of modules, classes, and functions.
• Theoretical Foundation: background on the scientific principles and research behind the metrics.

Support

If you encounter issues or have questions about PyEyesWeb, you can get help through the following channels:

• GitHub Issues: report bugs, request features, or ask technical questions on the PyEyesWeb GitHub Issues page.
• Discussions / Q&A: participate in conversations or seek advice in GitHub Discussions.
• Email: Reach out to the maintainers at [e-mail] for direct support or collaboration inquiries.

Please provide clear descriptions, minimal reproducible examples, and version information when submitting issues—it helps us respond faster.

Roadmap

PyEyesWeb is under active development, and several features are planned for upcoming releases:

• Expanded feature extraction: addition of more movement expressivity metrics (you can find an example of which features to expect in related conceptual layer guide.
• Improved examples and tutorials: more interactive Jupyter notebooks and example datasets to facilitate learning and adoption.
• Cross-platform compatibility: streamlined integration with creative and interactive platforms (e.g., TouchDesigner plugin, Unity, Max/MSP).

Future development priorities may evolve based on user feedback and research needs. Users are encouraged to suggest features or improvements via GitHub Issues.

Contributing

Contributions to PyEyesWeb are welcome! Whether it's reporting bugs, adding features, improving documentation, or providing examples, your help is appreciated.

How to Contribute

1. Fork the repository.

2. Clone the forked repository set up the development environment

   git clone https://github.com/<YOUR_USERNAME>/PyEyesWeb.git
   cd pyeyesweb
   pip install -e .[dev]
   

3. Create a branch for your feature or bug fix:

   git checkout -b feature/your-feature-name
   

4. Make your changes, ensuring code quality and adherence to the project's coding standards.

5. Submit a pull request to the main branch, with a clear description of your changes.

6. Engage in code reviews and address any feedback provided by maintainers.

Authors & Acknowledgments

PyEyesWeb is developed by InfoMus Lab – Casa Paganini, University of Genoa, with the partial support of the EU ICT STARTS Resilence Project.

Maintainers & Contributors

License

MIT License