A real-time hand detection system that helps prevent trichotillomania (hair-pulling) episodes by providing visual warnings when hands approach the face area. Features smart camera detection, external camera prioritization, and performance optimizations for various hardware configurations.
- Real-time hand detection using MediaPipe
- Visual warning system with full-screen overlay
- Customizable danger zones for face area detection
- Session statistics and monitoring
- Multi-threaded processing with resource management
- Automatic camera discovery and classification
- External camera prioritization over integrated cameras
- Camera type identification (USB, Logitech, etc.)
- Docker installed on your system
- X11 forwarding support (Linux/macOS)
- At least one camera connected to your system
- Camera permissions properly configured
-
Clone the repository:
git clone https://github.com/virtualbeck/trichshot.git cd trichshot -
Build the Docker image:
docker build -t trichshot:latest . -
Make the run script executable; Run:
chmod +x run_trichshot.sh ./run_trichshot.sh
The application provides a comprehensive GUI for configuration and monitoring:
- Camera Selection: Choose from automatically detected cameras
- Detection Configuration: Customize danger zone areas
- Session Monitoring: Track warnings and session time
- Start/Stop Monitoring: Begin or end the detection session
- Camera Selection: Switch between available cameras
- Refresh Cameras: Re-detect available cameras
- Danger Zone Sliders: Adjust the detection area
The application automatically detects and prioritizes cameras in this order:
- External USB cameras (Logitech, Microsoft, Creative, etc.)
- Unknown cameras with index > 0
- Integrated laptop cameras
- Top Slider: Adjusts the upper boundary of the detection zone
- Bottom Slider: Adjusts the lower boundary of the detection zone
- Local Processing: All detection happens locally, no data sent externally
- No Recording: Frames are processed in memory and not stored
- Minimal Permissions: Docker container runs with least-privilege access
- Camera Access: Only accesses cameras you explicitly grant access to
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
- Fork the repository
- Create a feature branch
- Make your changes with appropriate tests
- Submit a pull request
When reporting issues, please include:
- System specifications (OS, CPU, RAM)
- Camera information (model, type)
- Performance mode used
- Error messages or logs
- Steps to reproduce
This project is licensed under the MIT License - see the LICENSE file for details.
- MediaPipe team for the excellent hand detection framework
- OpenCV community for computer vision tools
- Docker for containerization platform
- Contributors and users who provide feedback and improvements
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: This README and inline code comments
Disclaimer: TrichShot is a tool designed to assist with awareness of hand-to-face movements. It is not a medical device and should not replace professional medical advice or treatment. If you're struggling with trichotillomania or similar conditions, please consult with a healthcare professional.
Also, TrichShot was vibe-coded into existence. I'm putting this out there after I spent a few hours tweaking it. It has greatly minimized my compulsion to twist/pull while at the computer, and I'm already seeing positive results away from the computer. Hopefully this will be a positive reinforcement loop that can help me (and you!) to alleviate this impulse control disorder.