https://github.com/ambicuity/trackpad-weight
Turn your MacBook trackpad into a digital weighing scale using Force Touch pressure data.
https://github.com/ambicuity/trackpad-weight
force-touch macos multi swift touch trackpad weighing-scale weighing-scales
Last synced: 5 months ago
JSON representation
Turn your MacBook trackpad into a digital weighing scale using Force Touch pressure data.
- Host: GitHub
- URL: https://github.com/ambicuity/trackpad-weight
- Owner: ambicuity
- License: mit
- Created: 2025-07-25T19:34:06.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-04T04:54:51.000Z (11 months ago)
- Last Synced: 2025-08-04T05:04:29.099Z (11 months ago)
- Topics: force-touch, macos, multi, swift, touch, trackpad, weighing-scale, weighing-scales
- Language: Swift
- Homepage: https://github.com/ambicuity/trackpad-weight
- Size: 115 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TrackPad Weight Scale
A powerful macOS application that transforms your Force Touch trackpad into a precision digital weighing scale using advanced multitouch pressure sensing technology.
[](https://www.apple.com/macos/)
[](https://swift.org/)
[](LICENSE)
[]()
## ✨ Key Features
### 🎯 **Precision Measurement**
- **Multi-layered Pressure Detection**: Primary multitouch support with Force Touch fallback
- **High Accuracy**: ±0.1-0.5g precision depending on MacBook model
- **Real-time Updates**: Live weight display with sub-second response time
- **Smart Calibration**: Advanced zero-point calibration with drift compensation
### 🖥️ **Native macOS Integration**
- **Menu Bar Integration**: Always-accessible weight display in your menu bar
- **Native UI Components**: Built with SwiftUI/Cocoa for seamless macOS experience
- **Multiple Display Options**: Main window, compact widget, and menu bar views
- **Accessibility Support**: Full VoiceOver compatibility and keyboard navigation
### 📊 **Advanced Features**
- **Auto-Tare System**: Automatically zero the scale for new measurement sessions
- **Comparison Mode**: Compare weights against reference items with tolerance checking
- **Data Logging**: Comprehensive weight logging with CSV/JSON export
- **API Integration**: Built-in REST API server with webhook support
- **Theme Customization**: Multiple themes and font sizes for personalization
### 🔧 **Professional Tools**
- **Session Management**: Organized measurement sessions with detailed statistics
- **Export Capabilities**: Multiple export formats for data analysis
- **Remote Control**: API endpoints for programmatic control and monitoring
- **Compact Widget**: Always-on-top floating weight display
## 🧠 How It Works
### Advanced Pressure Detection System
TrackWeight employs a sophisticated multi-layered approach to trackpad pressure sensing:
#### **Primary Method: Open Multi-Touch Support**
- Utilizes enhanced Open Multi-Touch Support library integration
- Direct access to private macOS multitouch APIs
- Captures detailed pressure data from multiple touch points simultaneously
- Provides the highest accuracy and sensitivity
#### **Fallback Method: Force Touch Events**
- NSEvent-based Force Touch monitoring for compatibility
- Ensures functionality across all supported MacBook models
- Automatic fallback when multitouch access is unavailable
#### **Smart Pressure Processing**
- **Capacitance Detection**: Pressure readings only available with finger contact on trackpad
- **Multi-point Aggregation**: Combines pressure from multiple simultaneous touches
- **Real-time Calibration**: Continuous drift compensation and environmental adjustment
- **Noise Filtering**: Advanced algorithms to eliminate measurement noise
### Weight Calculation Algorithm
```
Raw Pressure → Calibration Offset → Environmental Compensation → Weight (grams)
```
Our extensive testing reveals that **MultitouchSupport pressure data is pre-calibrated in grams**, providing exceptional accuracy without complex conversion algorithms.
## 📋 Requirements & Compatibility
### ✅ **Fully Supported Models**
| Model | Years | Weight Limit | Accuracy | Status |
|-------|-------|--------------|----------|---------|
| **MacBook Pro** | 2015+ (13", 14", 15", 16") | 300-400g | ±0.1-0.2g | ✅ Excellent |
| **MacBook Air** | 2018+ (13", 15") | 280-320g | ±0.1-0.15g | ✅ Excellent |
| **MacBook** | 2016-2017 (12") | 250g | ±0.2g | ✅ Good |
### ❌ **Not Compatible**
- MacBook Pro (2014 and earlier)
- MacBook Air (2017 and earlier)
- iMac, Mac Mini, Mac Pro (no Force Touch trackpad)
### 💻 **System Requirements**
- **OS**: macOS 13.0 (Ventura) or later
- **Hardware**: MacBook with Force Touch trackpad
- **Memory**: 50MB RAM minimum
- **Storage**: 10MB disk space
- **Development**: Swift 5.9+, Xcode 16.0+ (for building from source)
> **🔍 Quick Compatibility Check**: System Preferences → Trackpad → "Force Click and haptic feedback" should be available
### ⚠️ **Important Safety Limits**
**Never exceed these weight limits to avoid trackpad damage:**
| Model Category | Recommended Max | Absolute Max | Risk Level |
|----------------|-----------------|--------------|------------|
| MacBook Pro 13" | 300g | 500g | ⚠️ Medium |
| MacBook Pro 15-16" | 350-400g | 600-700g | ⚠️ Medium |
| MacBook Air | 280-320g | 450-500g | ⚠️ Medium |
| MacBook 12" | 250g | 400g | 🔴 High |
> **⚠️ Warranty Warning**: Exceeding absolute maximums may void your warranty and cause permanent trackpad damage.
## 🚀 Quick Start Guide
### Method 1: One-Command Install (Recommended)
```bash
# Clone and run in one step
git clone https://github.com/ambicuity/trackpad-weight.git && cd trackpad-weight && swift run TrackpadWeight
```
### Method 2: Production Build
```bash
# Build optimized version
git clone https://github.com/ambicuity/trackpad-weight.git
cd trackpad-weight
swift build -c release
# Run the optimized build
./.build/release/TrackpadWeight
```
### Method 3: App Bundle
```bash
# Create proper macOS app (see INSTALLATION.md for details)
git clone https://github.com/ambicuity/trackpad-weight.git
cd trackpad-weight
# Follow detailed app bundle creation steps in INSTALLATION.md
```
> **📚 Need detailed instructions?** See our comprehensive [Installation Guide](INSTALLATION.md) with troubleshooting, permissions setup, and advanced configuration options.
## 📖 Usage Guide
### Basic Operation
1. **🚀 Launch**: Application appears in menu bar with scale icon (⚖️)
2. **⚖️ Calibrate**: Click menu bar → "Calibrate" (essential for accuracy)
3. **📱 View**: Click menu bar → "Show Weight Scale" for main window
4. **📏 Measure**: Place items on trackpad while maintaining finger contact
### Essential Tips for Accurate Measurements
#### ✅ **Best Practices**
```
✓ Calibrate before each session
✓ Maintain consistent finger contact
✓ Place items gently in trackpad center
✓ Use clean, dry trackpad surface
✓ Ensure stable, vibration-free surface
```
#### ❌ **Avoid These**
```
✗ Exceeding weight limits
✗ Sharp or pointed objects
✗ Wet or dirty items
✗ Sudden movements during measurement
✗ Multiple items without proper spacing
```
### Real-World Examples
#### 📮 **Mail & Shipping**
- Standard letter (up to 28g): ±0.2g accuracy
- Large letter (up to 100g): ±0.3g accuracy
- Small packet (up to 500g): Use with caution
#### 💍 **Jewelry & Precious Items**
- Rings, earrings (1-10g): ±0.1g accuracy
- Chains, bracelets (5-25g): ±0.2g accuracy
- Small coins for calibration reference
#### 🔬 **Educational & Hobby**
- Electronic components: Excellent precision
- Model building materials: Good for balancing
- Kitchen ingredients: Approximate portions
> **📋 Want detailed examples?** Check our [Examples & Use Cases Guide](EXAMPLES.md) with real-world scenarios and step-by-step instructions.
## 🔧 Advanced Features
### 🤖 **Auto-Tare System**
Automatically zeroes the scale when starting new measurement sessions.
```bash
Menu Bar → "Auto-Tare" → Enable
Configure: Menu Bar → "Auto-Tare Settings"
```
### 📊 **Comparison Mode**
Compare current measurements against reference weights with tolerance checking.
```bash
Enable: Menu Bar → "Comparison Mode"
Set Reference: Menu Bar → "Comparison Tools" → "Set Reference Weight"
```
### 📈 **Data Logging & Export**
Comprehensive measurement logging with multiple export formats.
```bash
Enable: Menu Bar → "Enable Logging"
Export: Menu Bar → "Export Weight Log (CSV/JSON)"
Location: ~/Documents/TrackpadWeight/
```
### 🖥️ **Compact Widget**
Always-on-top floating weight display for continuous monitoring.
```bash
Show: Menu Bar → "Show Compact Widget"
Configure: Menu Bar → "Widget Options" → Position/Size
```
### 🌐 **REST API Server**
Built-in HTTP API for programmatic access and integration.
```bash
Enable: Menu Bar → "API Server"
Access: http://localhost:8080/api
Docs: http://localhost:8080/docs
```
### 🎨 **Customization Options**
- **Themes**: System, Light, Dark, High Contrast
- **Font Sizes**: Small, Medium, Large, Extra Large
- **Accessibility**: Full VoiceOver support
- **Positioning**: Customizable widget placement
> **🔧 Need API integration?** See our complete [API Documentation](API.md) with endpoints, examples, and client libraries.
## ⚠️ Safety & Risk Assessment
### 🚨 **Critical Safety Guidelines**
#### **Physical Risks to Avoid**
- **🔴 High Risk**: Exceeding weight limits, sharp objects, liquids, hot items
- **🟡 Medium Risk**: Metal objects, static-sensitive items, magnetic materials
- **🟢 Low Risk**: Paper, coins, small electronics, dry food items
#### **Weight Limits by Model**
| MacBook Model | Safe Limit | Damage Risk |
|---------------|------------|-------------|
| Pro 13" (2015+) | 300g | >500g |
| Pro 15-16" (2015+) | 350-400g | >600-700g |
| Air 13-15" (2018+) | 280-320g | >450-500g |
| 12" (2016-2017) | 250g | >400g |
#### **Placement Guidelines**
```
✅ DO: Gentle placement, center positioning, finger contact
❌ DON'T: Sharp edges, excessive force, liquid contact
```
### 📊 **Accuracy Specifications**
#### **Expected Precision by Weight Range**
| Weight Range | Typical Accuracy | Best Use Cases |
|-------------|------------------|----------------|
| 0.1-1.0g | ±0.05-0.1g | Electronics, small jewelry |
| 1-10g | ±0.1-0.2g | Coins, medium jewelry |
| 10-50g | ±0.2-0.5g | Documents, food portions |
| 50-200g | ±0.5-1.0g | Packages, containers |
| 200g+ | ±1.0-2.0g | Large items (approach limits) |
#### **Environmental Factors**
- **Temperature**: ±5°C from calibration affects accuracy
- **Humidity**: Extreme conditions impact sensor performance
- **Vibration**: Stable surface required for precise measurements
### 🚫 **Important Limitations**
#### **Not Suitable For**
- Legal/commercial trade measurements
- Medical dosing or pharmaceutical use
- Precious metals trading
- Scientific research requiring high precision
- Safety-critical applications
#### **Recommended For**
- Educational demonstrations and learning
- Hobby projects and crafting
- Approximate measurements and estimations
- Quick weight checks and comparisons
> **⚠️ Legal Disclaimer**: This application is for demonstration and educational purposes only. Not certified for commercial use. Use at your own risk. See [COMPATIBILITY.md](COMPATIBILITY.md) for detailed risk assessment.
## 🏗️ Technical Architecture
### 🧠 **Core Components**
```
📱 SwiftUI/Cocoa Interface
↓
🔄 Combine Reactive Framework
↓
📊 TrackpadMonitor (Pressure Detection)
↓
🎯 MultitouchSupport Integration ← 🔄 → NSEvent Force Touch (Fallback)
↓
⚖️ Weight Calculation Engine
```
### 📁 **Project Structure**
```
Sources/TrackpadWeight/
├── 🚀 main.swift # Application entry point & menu bar
├── 🎯 MultitouchSupport.swift # Open Multi-Touch Support integration
├── 📊 TrackpadMonitor.swift # Enhanced pressure sensing logic
├── 🖥️ WeightDisplayView.swift # Native UI components
├── 📈 WeightLogger.swift # Data logging & export system
├── 🤖 AutoTareManager.swift # Automatic tare functionality
├── 📊 ComparisonManager.swift # Weight comparison features
├── 🎨 ThemeManager.swift # UI themes & accessibility
├── 📱 CompactWeightWidget.swift # Floating widget display
└── 🌐 APIServer.swift # REST API & webhook server
Tests/TrackpadWeightTests/
└── ✅ TrackpadWeightTests.swift # Comprehensive unit tests (21 tests)
```
### 🔧 **Enhanced Architecture Features**
#### **Multi-layered Pressure Detection**
- **Primary**: Open Multi-Touch Support library integration
- **Fallback**: NSEvent Force Touch monitoring
- **Smart Switching**: Automatic method selection based on availability
#### **Real-time Processing Pipeline**
```
Raw Sensor Data → Noise Filtering → Calibration → Environmental Compensation → Weight Output
```
#### **Data Flow Architecture**
- **Reactive**: Combine framework for real-time updates
- **Thread-safe**: Concurrent pressure processing
- **Memory efficient**: Optimized for continuous operation
### 🧪 **Validation & Testing**
#### **Calibration Methodology**
Our weight calculations are validated through rigorous testing:
1. **Reference Scale Comparison**: MacBook placed on certified digital scale
2. **Known Weight Testing**: Verified using certified calibration weights
3. **Cross-model Validation**: Testing across multiple MacBook models
4. **Environmental Testing**: Various temperature and humidity conditions
#### **Test Coverage**
- ✅ **21 Unit Tests**: Core functionality validation
- ✅ **Edge Case Testing**: Boundary conditions and error scenarios
- ✅ **Performance Testing**: Memory usage and CPU optimization
- ✅ **Accuracy Validation**: Real-world measurement verification
> **🔬 Key Discovery**: MultitouchSupport pressure data is pre-calibrated in grams, providing exceptional accuracy without complex conversion algorithms.
## 📚 Documentation
### 📖 **Complete Guide Collection**
| Document | Description | Key Contents |
|----------|-------------|--------------|
| **[📋 Examples & Use Cases](EXAMPLES.md)** | Detailed real-world examples | API integration, troubleshooting, performance benchmarks |
| **[🔧 Installation Guide](INSTALLATION.md)** | Complete setup instructions | Multiple install methods, permissions, troubleshooting |
| **[📱 Compatibility Guide](COMPATIBILITY.md)** | Model compatibility & risk assessment | Weight limits, safety guidelines, accuracy specs |
| **[🌐 API Documentation](API.md)** | REST API & webhook integration | Endpoints, client libraries, webhook system |
### 🚀 **Quick Links**
- **⚡ Quick Start**: [Installation Guide - Method 1](INSTALLATION.md#method-1-quick-install-recommended)
- **📏 Weight Limits**: [Compatibility Guide - Weight Limits](COMPATIBILITY.md#weight-limits-by-model)
- **💻 API Examples**: [API Documentation - Examples](API.md#examples)
- **🛠️ Troubleshooting**: [Examples Guide - Troubleshooting](EXAMPLES.md#troubleshooting-common-issues)
### 🧪 **Development & Building**
```bash
# 🏗️ Development Setup
git clone https://github.com/ambicuity/trackpad-weight.git
cd trackpad-weight
# 🔨 Build & Test
swift build # Development build
swift test # Run all tests (21 tests)
swift build -c release # Optimized build
# 📱 Xcode Development
swift package generate-xcodeproj
open TrackpadWeight.xcodeproj
```
### 🙏 **Acknowledgments**
This project builds upon the excellent [Open Multi-Touch Support library](https://github.com/Kyome22/OpenMultitouchSupport) by Takuto Nakamura (@Kyome22), which provides:
- 🎯 Direct access to global multitouch events
- 📊 Detailed touch data (position, pressure, angle, density)
- 🔒 Thread-safe async/await touch event streams
- 📈 Comprehensive sensor data and touch state tracking
## 🤝 Contributing
We welcome contributions! Here's how to get started:
### 🛠️ **Development Process**
1. **🍴 Fork** the repository
2. **🌟 Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **✨ Make** your changes with comprehensive tests
4. **✅ Test** thoroughly (`swift test` should pass all 21+ tests)
5. **📝 Document** new features and update relevant guides
6. **🚀 Submit** a pull request with detailed description
### 📋 **Contribution Guidelines**
- **🔧 Code Style**: Follow Swift conventions and existing patterns
- **🧪 Testing**: Add tests for new functionality (maintain >90% coverage)
- **📚 Documentation**: Update relevant `.md` files for new features
- **⚡ Performance**: Ensure changes don't impact measurement accuracy
- **🔒 Security**: Consider security implications for trackpad access
### 🐛 **Bug Reports & Feature Requests**
- **🐞 Issues**: [Report bugs](https://github.com/ambicuity/trackpad-weight/issues) with reproduction steps
- **💡 Features**: [Request features](https://github.com/ambicuity/trackpad-weight/issues) with use case details
- **💬 Discussions**: [Community support](https://github.com/ambicuity/trackpad-weight/discussions)
## 📄 License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
```
Copyright (c) 2025 TrackPad Weight Scale Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...
```
## ⚠️ Legal Disclaimer
**Important**: This application is provided for **demonstration and educational purposes only**.
### 🚫 **Not Suitable For**
- ❌ Commercial trade or legal measurements
- ❌ Medical dosing or pharmaceutical applications
- ❌ Precious metals trading or valuation
- ❌ Scientific research requiring certified accuracy
- ❌ Safety-critical applications
### ✅ **Recommended Uses**
- ✅ Educational demonstrations and learning
- ✅ Hobby projects and maker activities
- ✅ Approximate measurements and estimations
- ✅ Quick weight checks and comparisons
### 📋 **Liability & Warranty**
- **No Warranty**: Software provided "as-is" without warranties
- **Use at Risk**: Users assume all risks for trackpad damage
- **No Liability**: Authors not responsible for decisions based on readings
- **Educational Only**: Not certified for commercial or professional use
---
**⚖️ TrackPad Weight Scale** - *Transform your MacBook trackpad into a precision digital scale*
[](https://www.apple.com/macos/)
[](https://swift.org/)
[](LICENSE)
[]()
*Built with ❤️ for the macOS community*