dev

OPTIMIZATION_NOTES.md

@@ -0,0 +1,111 @@
+# VisionFlow Automator - Performance Optimizations
+
+## Overview
+This document outlines the performance and memory optimizations implemented to prevent the application from being killed or stalled during scenario execution.
+
+## Key Optimizations Implemented
+
+### 1. Memory Management
+- **Template Caching**: Added `TemplateCache` class to cache loaded CV2 templates instead of reloading from disk every loop iteration
+- **Screenshot Caching**: Implemented screenshot caching with 50ms duration to reduce memory allocations
+- **Resource Cleanup**: Added proper cleanup in `cleanup_resources()` method and `closeEvent()`
+- **Garbage Collection**: Strategic `gc.collect()` calls to force memory cleanup at appropriate times
+- **Pixmap Memory Management**: Optimized image preview handling to prevent large pixmap memory leaks
+
+### 2. Performance Improvements
+- **Optimized Loop Structure**: Redesigned automation loop to be more efficient
+- **Step Cooldown System**: Prevents rapid re-execution of the same step (1-second cooldown)
+- **Priority Execution**: Only executes one step per loop iteration to prevent blocking
+- **Dynamic Sleep**: Adjusts sleep time based on loop performance (0.05-0.2s)
+- **Performance Monitoring**: Added loop time tracking and warnings for slow performance
+
+### 3. Threading Improvements
+- **Proper Thread Management**: Added timeout for thread joining in `stop_automation()`
+- **Background Processing**: Improved worker thread handling with better error recovery
+- **Non-blocking Operations**: Reduced blocking operations in the main thread
+
+### 4. UI Optimizations
+- **Reduced Logging**: Changed default log level from DEBUG to INFO to reduce I/O overhead
+- **Efficient Image Previews**: Optimized image scaling and memory usage in dialogs
+- **State Update Throttling**: Reduced frequency of UI state updates
+
+### 5. Resource Monitoring
+- **Performance Timer**: Added 10-second monitoring timer to track application health
+- **Memory Usage Tracking**: Optional psutil integration for detailed memory monitoring
+- **Cache Size Monitoring**: Tracks template cache size and warns when it grows large
+
+### 6. Error Handling
+- **Graceful Degradation**: Better error handling in screenshot capture and template matching
+- **Resource Recovery**: Automatic cleanup on errors to prevent resource leaks
+- **Hotkey Error Handling**: Continues operation even if hotkey setup fails
+
+## Configuration Changes
+
+### PyAutoGUI Optimizations
+- Set `pyautogui.PAUSE = 0.01` (reduced from default 0.1s)
+- Set `pyautogui.MINIMUM_DURATION = 0` for faster actions
+- Kept `pyautogui.FAILSAFE = False` for automation reliability
+
+### Screenshot Optimization
+- Added minimum size validation (10x10 pixels)
+- Improved tkinter screenshot tool with better UX
+- Memory-efficient PIL image handling with proper cleanup
+
+### Template Matching
+- LRU cache with automatic cleanup of old entries
+- Maximum cache size of 50 templates
+- Force reload option for template updates
+
+## Performance Targets
+
+### Memory Usage
+- Template cache limited to 50 entries
+- Screenshot cache duration: 50ms
+- Automatic cleanup every 100 loop iterations
+- Garbage collection after major operations
+
+### Timing
+- Target loop time: 50-200ms
+- Step cooldown: 1 second
+- Performance warning threshold: 1 second average loop time
+- Monitoring interval: 10 seconds
+
+### Thread Safety
+- Worker thread timeout: 2 seconds
+- Daemon threads for automatic cleanup
+- Proper resource locking where needed
+
+## Usage Recommendations
+
+1. **Monitor Performance**: Check logs for performance warnings
+2. **Resource Management**: Regularly restart long-running sessions
+3. **Template Optimization**: Use appropriately sized template images
+4. **Step Design**: Avoid too many simultaneous image detections
+5. **System Resources**: Ensure adequate RAM for screenshot operations
+
+## Future Improvements
+
+1. **Multi-threading**: Consider separate threads for image processing
+2. **Image Compression**: Compress cached templates to save memory
+3. **Region Optimization**: Use smaller detection regions when possible
+4. **GPU Acceleration**: Consider OpenCV GPU operations for template matching
+5. **Background Processing**: Process non-critical operations in background
+
+## Troubleshooting
+
+### High Memory Usage
+- Check template cache size in logs
+- Reduce number of simultaneous steps
+- Restart application periodically
+
+### Slow Performance
+- Check average loop times in logs
+- Reduce image template sizes
+- Simplify detection regions
+- Consider fewer simultaneous detections
+
+### Application Crashes
+- Check log files for error patterns
+- Monitor system memory usage
+- Verify image file integrity
+- Check for corrupted templates