# 🎮 AVGCS - Ashwath-Visual Game Control System
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/avgcs)
**AVGCS** is a Python module for real-time motion tracking and game control. It enables you to control game characters using your body movements captured through a camera.
## ✨ Features
- **Real-time Motion Tracking**: Uses OpenCV and MediaPipe for accurate body part detection
- **Flexible Character Mapping**: Map any body part to any character part (humanoid, animals, vehicles, etc.)
- **Custom Action Rules**: Define custom gestures and movements to trigger specific actions
- **Multiple Tracking Modes**: Support for both MediaPipe (advanced) and basic camera tracking
- **Easy Integration**: Simple API for integrating with any game engine or application
- **Cross-platform**: Works on Windows, macOS, and Linux
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI
pip install avgcs
```
### Basic Usage
```python
from avgcs import MediaPipeTracker, CharacterMapper, MotionInterpreter
# Initialize motion tracking
tracker = MediaPipeTracker(camera_index=0)
tracker.start_tracking()
# Set up character mapping
mapper = CharacterMapper()
mapper.add_mapping("left_shoulder", "left_arm")
mapper.add_mapping("right_shoulder", "right_arm")
mapper.add_mapping("left_wrist", "left_hand")
# Create motion interpreter
interpreter = MotionInterpreter(mapper.get_part_mapper())
# Main loop
while True:
motion_data = tracker.get_motion_data()
if motion_data:
commands = interpreter.interpret_motion(motion_data)
for command in commands:
print(f"{command.character_part}: {command.action}")
```
## 📖 Documentation
### Core Components
#### MotionTracker
Abstract base class for motion tracking systems.
```python
from avgcs import MediaPipeTracker, CameraTracker
# Advanced tracking with MediaPipe
tracker = MediaPipeTracker(camera_index=0)
# Basic tracking with OpenCV
tracker = CameraTracker(camera_index=0)
```
#### CharacterMapper
Manages mappings between body parts and character parts.
```python
from avgcs import CharacterMapper
mapper = CharacterMapper()
# Add mappings
mapper.add_mapping("left_shoulder", "left_arm")
mapper.add_mapping("right_shoulder", "right_arm")
mapper.add_mapping("left_wrist", "left_hand")
# Set movement thresholds
mapper.set_threshold("left_arm", 0.05)
mapper.set_threshold("right_arm", 0.05)
```
#### MotionInterpreter
Interprets motion data and generates game commands.
```python
from avgcs import MotionInterpreter
interpreter = MotionInterpreter(mapper.get_part_mapper())
# Add action rules
interpreter.add_action_rule("left_hand", "wave", {
"min_movement": 0.1,
"position_range": {
"x": [0.0, 0.3],
"y": [0.0, 0.5],
"z": [-0.5, 0.5]
}
})
```
### Character Types
AVGCS supports various character types:
#### Humanoid Characters
```python
mappings = {
"left_shoulder": "left_arm",
"right_shoulder": "right_arm",
"left_wrist": "left_hand",
"right_wrist": "right_hand",
"nose": "head"
}
```
#### Dragon/Creature Characters
```python
mappings = {
"left_shoulder": "left_wing",
"right_shoulder": "right_wing",
"left_wrist": "left_claw",
"right_wrist": "right_claw",
"nose": "head"
}
```
#### Vehicle/Spaceship Characters
```python
mappings = {
"left_wrist": "thrust_control",
"right_wrist": "weapon_control",
"left_shoulder": "roll_control",
"right_shoulder": "pitch_control"
}
```
## 🎯 Examples
### Basic Demo
Run the basic demo to see motion tracking in action:
```bash
python examples/basic_demo.py
```
### Pygame Demo
Run the visual Pygame demo:
```bash
python examples/pygame_demo.py
```
### Custom Configuration
Create your own character mapping:
```python
from avgcs import CharacterMapper, MappingConfig
mapper = CharacterMapper()
# Create a custom configuration
config = mapper.create_config(
name="my_character",
description="My custom character",
character_type="custom"
)
# Add your mappings
mapper.add_mapping("left_shoulder", "custom_part_1")
mapper.add_mapping("right_shoulder", "custom_part_2")
# Save configuration
mapper.save_config(config)
```
## 🧪 Testing
Run the test suite:
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=avgcs
# Run specific test file
pytest tests/test_core.py
```
## 📦 Project Structure
```
avgcs/
├── avgcs/ # Main package
│ ├── __init__.py # Package initialization
│ ├── core.py # Core classes and data structures
│ ├── tracking.py # Motion tracking implementations
│ ├── mapping.py # Character mapping system
│ └── utils.py # Utility functions
├── examples/ # Example applications
│ ├── basic_demo.py # Basic motion tracking demo
│ └── pygame_demo.py # Visual Pygame demo
├── tests/ # Test suite
│ └── test_core.py # Core functionality tests
├── configs/ # Configuration files
├── pyproject.toml # Project configuration
└── README.md # This file
```
## 🔧 Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/avgcs/avgcs.git
cd avgcs
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
```
### Code Quality
```bash
# Format code
black avgcs/ tests/ examples/
# Lint code
flake8 avgcs/ tests/ examples/
# Type checking
mypy avgcs/
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Workflow
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [MediaPipe](https://mediapipe.dev/) for advanced pose detection
- [OpenCV](https://opencv.org/) for computer vision capabilities
- [Pygame](https://www.pygame.org/) for the visual demo
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/avgcs/avgcs/issues)
- **Discussions**: [GitHub Discussions](https://github.com/avgcs/avgcs/discussions)
- **Email**: team@avgcs.dev
## 🗺️ Roadmap
- [ ] GUI mapping tool
- [ ] Gesture learning system
- [ ] Pre-built character profiles
- [ ] Support for multiple cameras
- [ ] Integration with popular game engines
- [ ] Mobile device support
- [ ] VR/AR integration
---
**Made with ❤️ by the AVGCS Team**
Raw data
{
"_id": null,
"home_page": "https://github.com/avgcs/avgcs",
"name": "avgcs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "AVGCS Team <team@avgcs.dev>",
"keywords": "motion-tracking, game-control, mediapipe, opencv, computer-vision",
"author": "AVGCS Team",
"author_email": "AVGCS Team <team@avgcs.dev>",
"download_url": "https://files.pythonhosted.org/packages/55/df/efd394376e93d0a1b7d2faa276f5dc03dfd0025baaf4604736ebddf258b1/avgcs-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83c\udfae AVGCS - Ashwath-Visual Game Control System\r\n\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://badge.fury.io/py/avgcs)\r\n\r\n**AVGCS** is a Python module for real-time motion tracking and game control. It enables you to control game characters using your body movements captured through a camera.\r\n\r\n## \u2728 Features\r\n\r\n- **Real-time Motion Tracking**: Uses OpenCV and MediaPipe for accurate body part detection\r\n- **Flexible Character Mapping**: Map any body part to any character part (humanoid, animals, vehicles, etc.)\r\n- **Custom Action Rules**: Define custom gestures and movements to trigger specific actions\r\n- **Multiple Tracking Modes**: Support for both MediaPipe (advanced) and basic camera tracking\r\n- **Easy Integration**: Simple API for integrating with any game engine or application\r\n- **Cross-platform**: Works on Windows, macOS, and Linux\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\n# Install from PyPI\r\npip install avgcs\r\n```\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom avgcs import MediaPipeTracker, CharacterMapper, MotionInterpreter\r\n\r\n# Initialize motion tracking\r\ntracker = MediaPipeTracker(camera_index=0)\r\ntracker.start_tracking()\r\n\r\n# Set up character mapping\r\nmapper = CharacterMapper()\r\nmapper.add_mapping(\"left_shoulder\", \"left_arm\")\r\nmapper.add_mapping(\"right_shoulder\", \"right_arm\")\r\nmapper.add_mapping(\"left_wrist\", \"left_hand\")\r\n\r\n# Create motion interpreter\r\ninterpreter = MotionInterpreter(mapper.get_part_mapper())\r\n\r\n# Main loop\r\nwhile True:\r\n motion_data = tracker.get_motion_data()\r\n if motion_data:\r\n commands = interpreter.interpret_motion(motion_data)\r\n for command in commands:\r\n print(f\"{command.character_part}: {command.action}\")\r\n```\r\n\r\n## \ud83d\udcd6 Documentation\r\n\r\n### Core Components\r\n\r\n#### MotionTracker\r\nAbstract base class for motion tracking systems.\r\n\r\n```python\r\nfrom avgcs import MediaPipeTracker, CameraTracker\r\n\r\n# Advanced tracking with MediaPipe\r\ntracker = MediaPipeTracker(camera_index=0)\r\n\r\n# Basic tracking with OpenCV\r\ntracker = CameraTracker(camera_index=0)\r\n```\r\n\r\n#### CharacterMapper\r\nManages mappings between body parts and character parts.\r\n\r\n```python\r\nfrom avgcs import CharacterMapper\r\n\r\nmapper = CharacterMapper()\r\n\r\n# Add mappings\r\nmapper.add_mapping(\"left_shoulder\", \"left_arm\")\r\nmapper.add_mapping(\"right_shoulder\", \"right_arm\")\r\nmapper.add_mapping(\"left_wrist\", \"left_hand\")\r\n\r\n# Set movement thresholds\r\nmapper.set_threshold(\"left_arm\", 0.05)\r\nmapper.set_threshold(\"right_arm\", 0.05)\r\n```\r\n\r\n#### MotionInterpreter\r\nInterprets motion data and generates game commands.\r\n\r\n```python\r\nfrom avgcs import MotionInterpreter\r\n\r\ninterpreter = MotionInterpreter(mapper.get_part_mapper())\r\n\r\n# Add action rules\r\ninterpreter.add_action_rule(\"left_hand\", \"wave\", {\r\n \"min_movement\": 0.1,\r\n \"position_range\": {\r\n \"x\": [0.0, 0.3],\r\n \"y\": [0.0, 0.5],\r\n \"z\": [-0.5, 0.5]\r\n }\r\n})\r\n```\r\n\r\n### Character Types\r\n\r\nAVGCS supports various character types:\r\n\r\n#### Humanoid Characters\r\n```python\r\nmappings = {\r\n \"left_shoulder\": \"left_arm\",\r\n \"right_shoulder\": \"right_arm\",\r\n \"left_wrist\": \"left_hand\",\r\n \"right_wrist\": \"right_hand\",\r\n \"nose\": \"head\"\r\n}\r\n```\r\n\r\n#### Dragon/Creature Characters\r\n```python\r\nmappings = {\r\n \"left_shoulder\": \"left_wing\",\r\n \"right_shoulder\": \"right_wing\",\r\n \"left_wrist\": \"left_claw\",\r\n \"right_wrist\": \"right_claw\",\r\n \"nose\": \"head\"\r\n}\r\n```\r\n\r\n#### Vehicle/Spaceship Characters\r\n```python\r\nmappings = {\r\n \"left_wrist\": \"thrust_control\",\r\n \"right_wrist\": \"weapon_control\",\r\n \"left_shoulder\": \"roll_control\",\r\n \"right_shoulder\": \"pitch_control\"\r\n}\r\n```\r\n\r\n## \ud83c\udfaf Examples\r\n\r\n### Basic Demo\r\nRun the basic demo to see motion tracking in action:\r\n\r\n```bash\r\npython examples/basic_demo.py\r\n```\r\n\r\n### Pygame Demo\r\nRun the visual Pygame demo:\r\n\r\n```bash\r\npython examples/pygame_demo.py\r\n```\r\n\r\n### Custom Configuration\r\nCreate your own character mapping:\r\n\r\n```python\r\nfrom avgcs import CharacterMapper, MappingConfig\r\n\r\nmapper = CharacterMapper()\r\n\r\n# Create a custom configuration\r\nconfig = mapper.create_config(\r\n name=\"my_character\",\r\n description=\"My custom character\",\r\n character_type=\"custom\"\r\n)\r\n\r\n# Add your mappings\r\nmapper.add_mapping(\"left_shoulder\", \"custom_part_1\")\r\nmapper.add_mapping(\"right_shoulder\", \"custom_part_2\")\r\n\r\n# Save configuration\r\nmapper.save_config(config)\r\n```\r\n\r\n## \ud83e\uddea Testing\r\n\r\nRun the test suite:\r\n\r\n```bash\r\n# Run all tests\r\npytest\r\n\r\n# Run with coverage\r\npytest --cov=avgcs\r\n\r\n# Run specific test file\r\npytest tests/test_core.py\r\n```\r\n\r\n## \ud83d\udce6 Project Structure\r\n\r\n```\r\navgcs/\r\n\u251c\u2500\u2500 avgcs/ # Main package\r\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\r\n\u2502 \u251c\u2500\u2500 core.py # Core classes and data structures\r\n\u2502 \u251c\u2500\u2500 tracking.py # Motion tracking implementations\r\n\u2502 \u251c\u2500\u2500 mapping.py # Character mapping system\r\n\u2502 \u2514\u2500\u2500 utils.py # Utility functions\r\n\u251c\u2500\u2500 examples/ # Example applications\r\n\u2502 \u251c\u2500\u2500 basic_demo.py # Basic motion tracking demo\r\n\u2502 \u2514\u2500\u2500 pygame_demo.py # Visual Pygame demo\r\n\u251c\u2500\u2500 tests/ # Test suite\r\n\u2502 \u2514\u2500\u2500 test_core.py # Core functionality tests\r\n\u251c\u2500\u2500 configs/ # Configuration files\r\n\u251c\u2500\u2500 pyproject.toml # Project configuration\r\n\u2514\u2500\u2500 README.md # This file\r\n```\r\n\r\n## \ud83d\udd27 Development\r\n\r\n### Setup Development Environment\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/avgcs/avgcs.git\r\ncd avgcs\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Code Quality\r\n\r\n```bash\r\n# Format code\r\nblack avgcs/ tests/ examples/\r\n\r\n# Lint code\r\nflake8 avgcs/ tests/ examples/\r\n\r\n# Type checking\r\nmypy avgcs/\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Development Workflow\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests for new functionality\r\n5. Run the test suite\r\n6. Submit a pull request\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- [MediaPipe](https://mediapipe.dev/) for advanced pose detection\r\n- [OpenCV](https://opencv.org/) for computer vision capabilities\r\n- [Pygame](https://www.pygame.org/) for the visual demo\r\n\r\n## \ud83d\udcde Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/avgcs/avgcs/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/avgcs/avgcs/discussions)\r\n- **Email**: team@avgcs.dev\r\n\r\n## \ud83d\uddfa\ufe0f Roadmap\r\n\r\n- [ ] GUI mapping tool\r\n- [ ] Gesture learning system\r\n- [ ] Pre-built character profiles\r\n- [ ] Support for multiple cameras\r\n- [ ] Integration with popular game engines\r\n- [ ] Mobile device support\r\n- [ ] VR/AR integration\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f by the AVGCS Team** \r\n",
"bugtrack_url": null,
"license": null,
"summary": "Audio-Visual Game Control System - Real-time motion tracking and game control",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/avgcs/avgcs/issues",
"Documentation": "https://avgcs.readthedocs.io/",
"Homepage": "https://github.com/avgcs/avgcs",
"Repository": "https://github.com/avgcs/avgcs.git"
},
"split_keywords": [
"motion-tracking",
" game-control",
" mediapipe",
" opencv",
" computer-vision"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1b1c81b8e9f8ed3eb169f23e8fc27ab286f132f2dfe01ddff52a013279e33c46",
"md5": "2f67bb1a9b450cd66dd9f1e09731c354",
"sha256": "baea4ac5cf8be00bb418202c3be228ebee75acbe1054220d51b76ac5883087f5"
},
"downloads": -1,
"filename": "avgcs-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f67bb1a9b450cd66dd9f1e09731c354",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14261,
"upload_time": "2025-07-13T08:15:48",
"upload_time_iso_8601": "2025-07-13T08:15:48.799282Z",
"url": "https://files.pythonhosted.org/packages/1b/1c/81b8e9f8ed3eb169f23e8fc27ab286f132f2dfe01ddff52a013279e33c46/avgcs-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "55dfefd394376e93d0a1b7d2faa276f5dc03dfd0025baaf4604736ebddf258b1",
"md5": "6a1ab9514f3eda9196038a1b0a03fc95",
"sha256": "d7d46084ec3c4ca28b36a013fd6a348ac782dd692769362426b459f95ff0949e"
},
"downloads": -1,
"filename": "avgcs-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6a1ab9514f3eda9196038a1b0a03fc95",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17673,
"upload_time": "2025-07-13T08:15:50",
"upload_time_iso_8601": "2025-07-13T08:15:50.308486Z",
"url": "https://files.pythonhosted.org/packages/55/df/efd394376e93d0a1b7d2faa276f5dc03dfd0025baaf4604736ebddf258b1/avgcs-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 08:15:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avgcs",
"github_project": "avgcs",
"github_not_found": true,
"lcname": "avgcs"
}
JSON
