pumaguard 21.post27__py3-none-any.whl → 21.post83__py3-none-any.whl

pumaguard-ui/UI_DEVELOPMENT_CONTEXT.md

@@ -0,0 +1,427 @@
+# PumaGuard UI Development Context
+
+This document provides context for AI assistants (like GitHub Copilot) working on the PumaGuard Flutter UI in the `pumaguard-ui` repository.
+
+## Project Overview
+
+**PumaGuard** is an AI-powered wildlife monitoring system that uses computer vision to detect pumas/mountain lions from trail camera images. The system consists of:
+
+1. **Backend (Python/Flask)**: Image processing, YOLO object detection, TensorFlow classification
+2. **Frontend (Flutter)**: Cross-platform UI (Web, Desktop, Mobile) for configuration and monitoring
+
+You are working on the **Flutter UI** which communicates with the Python backend via REST API.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Flutter UI (This Repo)                │
+│  ┌────────────┬────────────┬────────────┬─────────────┐ │
+│  │   Home     │  Settings  │ Directories│   Images    │ │
+│  │  Screen    │   Screen   │   Screen   │   Browser   │ │
+│  └────────────┴────────────┴────────────┴─────────────┘ │
+│                         │                                │
+│                    API Service                           │
+│                         │                                │
+└─────────────────────────┼────────────────────────────────┘
+                          │ HTTP/REST
+                          │
+┌─────────────────────────┼────────────────────────────────┐
+│                         │                                │
+│                  Flask Backend                           │
+│  ┌────────────┬────────────┬────────────┬─────────────┐ │
+│  │   YOLO     │Classifier  │  Folder    │    Web      │ │
+│  │  Detection │   Model    │  Monitor   │     UI      │ │
+│  └────────────┴────────────┴────────────┴─────────────┘ │
+│                  Python/TensorFlow/Flask                 │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Backend API
+
+The Flask backend runs on `http://localhost:5000` (or server IP) and provides these endpoints:
+
+### Core Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/status` | GET | Server status and info |
+| `/api/settings` | GET/PUT | Get/update detection settings |
+| `/api/directories` | GET/POST/DELETE | Manage watched folders |
+| `/api/photos` | GET | List all captured photos |
+| `/api/photos/{path}` | GET/DELETE | Access/delete specific photo |
+| `/api/folders` | GET | List folders with image counts |
+| `/api/folders/{path}/images` | GET | List images in folder |
+| `/api/sync/checksums` | POST | Compare checksums for smart sync |
+| `/api/sync/download` | POST | Download files (ZIP or single) |
+
+**See `API_REFERENCE.md` for complete API documentation.**
+
+## Key Configuration
+
+### Detection Settings (via API)
+
+```json
+{
+  "YOLO-min-size": 0.02,           // Min object size (0.0-1.0)
+  "YOLO-conf-thresh": 0.25,        // Confidence threshold (0.0-1.0)
+  "YOLO-max-dets": 12,             // Max detections per image
+  "YOLO-model-filename": "yolov8s_101425.pt",
+  "classifier-model-filename": "colorbw_111325.h5",
+  "play-sound": true               // Play deterrent sound
+}
+```
+
+### Settings Storage
+
+- **Backend**: Uses XDG Base Directory specification
+- **Default location**: `~/.config/pumaguard/settings.yaml`
+- **Legacy location**: `./pumaguard-settings.yaml`
+
+## Flutter Project Structure
+
+```
+lib/
+├── main.dart                    # App entry point
+├── models/                      # Data models
+│   ├── status.dart             # Server status
+│   └── settings.dart           # Settings model
+├── screens/                     # UI screens
+│   ├── home_screen.dart        # Main dashboard
+│   ├── settings_screen.dart    # Settings configuration
+│   ├── directories_screen.dart # Folder management
+│   ├── image_browser_screen.dart # Image browsing & download
+│   └── server_discovery_screen.dart # mDNS discovery
+├── services/                    # Business logic
+│   └── api_service.dart        # API communication
+└── utils/                       # Utilities
+```
+
+## Key Features
+
+### 1. Home Screen
+- Display server status
+- Quick access to settings, directories, image browser
+- Connection status indicator
+
+### 2. Settings Screen
+- Configure YOLO detection parameters
+- Configure classifier settings
+- Enable/disable sound playback
+- Save/load settings to/from file
+
+### 3. Directories Screen
+- Add/remove watched folders
+- View list of monitored directories
+- Integration with backend folder observer
+
+### 4. Image Browser Screen (NEW)
+- Browse watched folders
+- View image thumbnails in grid
+- Select multiple images
+- Smart sync download (rsync-like)
+- Download as ZIP or individual files
+
+## API Service Pattern
+
+All API calls go through `ApiService`:
+
+```dart
+// Example usage
+final apiService = Provider.of<ApiService>(context);
+
+// Get status
+final status = await apiService.getStatus();
+
+// Update settings
+await apiService.updateSettings(newSettings);
+
+// Get folders for image browser
+final folders = await apiService.getFolders();
+
+// Download images with smart sync
+final filesToDownload = await apiService.getFilesToSync(localChecksums);
+final zipBytes = await apiService.downloadFiles(filePaths);
+```
+
+## Smart Sync Feature
+
+The UI implements rsync-like functionality:
+
+1. **User selects images** to download
+2. **Calculate local checksums** (SHA256) of existing files
+3. **POST to `/api/sync/checksums`** with local checksums
+4. **Server compares** and returns list of files to download
+5. **Download only changed/new files** via `/api/sync/download`
+6. **Extract ZIP** if multiple files
+
+```dart
+// Smart sync workflow
+Map<String, String> localChecksums = {}; // path: checksum
+for (var file in selectedFiles) {
+  if (await localFileExists(file)) {
+    localChecksums[file] = await calculateChecksum(file);
+  } else {
+    localChecksums[file] = ""; // Empty = doesn't exist
+  }
+}
+
+// Get files that need downloading
+final toDownload = await apiService.getFilesToSync(localChecksums);
+
+// Download only necessary files
+if (toDownload.isNotEmpty) {
+  final bytes = await apiService.downloadFiles(
+    toDownload.map((f) => f['path']).toList()
+  );
+  await saveFiles(bytes);
+}
+```
+
+## State Management
+
+- **Provider** for dependency injection (ApiService)
+- **StatefulWidget** for screen-level state
+- Reload data after navigation (`.then((_) => _loadData())`)
+
+## Dependencies
+
+Key packages in `pubspec.yaml`:
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  http: ^1.1.0              # HTTP requests
+  provider: ^6.1.0          # State management
+  crypto: ^3.0.3            # SHA256 checksums
+  file_picker: ^8.0.0+1     # File/folder selection
+  multicast_dns: ^0.3.2+7   # mDNS server discovery
+  intl: ^0.19.0             # Date formatting
+  web: ^1.1.0               # Web APIs (dart:html replacement)
+```
+
+## Platform Considerations
+
+### Web
+- Uses `Uri.base.origin` to auto-detect server URL
+- Downloads via browser download API
+- Limited file system access
+
+### Desktop/Mobile
+- Configurable server URL
+- Full file system access for smart sync
+- Can store local file database
+- File picker for destination selection
+
+## Security
+
+- **No authentication** currently (local network only)
+- **Path validation**: All file paths validated server-side
+- **CORS enabled**: For web UI from any origin
+- **Path traversal protection**: Server blocks `../` attempts
+
+## Common Patterns
+
+### Making API Calls
+
+```dart
+Future<void> _loadData() async {
+  setState(() {
+    _isLoading = true;
+    _error = null;
+  });
+  
+  try {
+    final apiService = Provider.of<ApiService>(context, listen: false);
+    final data = await apiService.getSomething();
+    setState(() {
+      _data = data;
+      _isLoading = false;
+    });
+  } catch (e) {
+    setState(() {
+      _error = e.toString();
+      _isLoading = false;
+    });
+  }
+}
+```
+
+### Error Handling
+
+```dart
+if (_error != null) {
+  return Center(
+    child: Column(
+      mainAxisAlignment: MainAxisAlignment.center,
+      children: [
+        Icon(Icons.error_outline, size: 48, color: Colors.red),
+        SizedBox(height: 16),
+        Text('Error: $_error'),
+        ElevatedButton(
+          onPressed: _loadData,
+          child: Text('Retry'),
+        ),
+      ],
+    ),
+  );
+}
+```
+
+### Navigation
+
+```dart
+Navigator.push(
+  context,
+  MaterialPageRoute(
+    builder: (context) => const SettingsScreen(),
+  ),
+).then((_) => _loadStatus()); // Reload after returning
+```
+
+## Image File Types
+
+Supported formats:
+- `.jpg`, `.jpeg`
+- `.png`
+- `.gif`
+- `.bmp`
+- `.webp`
+
+## Testing
+
+### Manual Testing
+1. Start backend: `cd .. && make run-server`
+2. Run Flutter: `flutter run -d chrome` (web) or `flutter run` (desktop)
+3. Access: `http://localhost:5000`
+
+### Automated Tests
+```bash
+flutter test
+```
+
+## Theme
+
+Material 3 with custom color scheme:
+- Seed color: `#8B4513` (brown/puma color)
+- Light and dark mode support
+- System theme mode
+
+## mDNS Discovery
+
+The app can discover PumaGuard servers on the network:
+- Service type: `_pumaguard._tcp.local.`
+- Default port: `5000`
+- Use `multicast_dns` package for discovery
+
+## Best Practices
+
+1. **Always use ApiService** for backend communication
+2. **Handle errors gracefully** with user-friendly messages
+3. **Show loading states** during async operations
+4. **Reload data** after navigation or updates
+5. **Use Provider** for dependency injection
+6. **Follow Material 3** design guidelines
+7. **Support both platforms** (web and native)
+
+## Development Workflow
+
+1. Make UI changes in `pumaguard-ui/` repository
+2. Test with local backend: `cd ../pumaguard && make run-server`
+3. Build for web: `flutter build web --wasm`
+4. Backend auto-serves built UI from `pumaguard-ui/build/web/`
+
+## Common Tasks
+
+### Add New API Endpoint
+1. Add method to `lib/services/api_service.dart`
+2. Follow existing patterns (error handling, JSON parsing)
+3. Use the endpoint in screens
+
+### Add New Screen
+1. Create `lib/screens/new_screen.dart`
+2. Add navigation from home screen
+3. Reload parent data after navigation
+
+### Add New Setting
+1. Update `lib/models/settings.dart`
+2. Add UI control in `lib/screens/settings_screen.dart`
+3. Use `ApiService.updateSettings()` to save
+
+## Troubleshooting
+
+### Cannot Connect to Server
+- Check backend is running: `cd ../pumaguard && make run-server`
+- Check URL is correct (localhost:5000 or server IP)
+- Check CORS is enabled (should be by default)
+- Try mDNS discovery if on same network
+
+### Images Not Loading
+- Check paths are correct (use `apiService.getPhotoUrl(path)`)
+- Verify files exist in watched folders
+- Check browser console for network errors
+- Ensure files are in allowed directories
+
+### Downloads Not Working
+- Web: Check browser download permissions
+- Native: Check file picker permissions
+- Verify selected files are in watched folders
+- Check server logs for errors
+
+## Related Documentation
+
+- **API_REFERENCE.md**: Complete API documentation
+- **IMAGE_BROWSER.md**: Image browser feature details
+- **XDG_MIGRATION.md**: Settings file location
+- **LXC_TESTING.md**: Container testing
+- **TESTING.md**: General testing guide
+
+## Support
+
+- GitHub: https://github.com/PEEC-Nature-Youth-Group/pumaguard
+- Documentation: http://pumaguard.rtfd.io/
+
+## Quick Reference
+
+### Server Status Response
+```json
+{
+  "status": "running",
+  "version": "1.0.0",
+  "uptime": 3600,
+  "monitored_directories": ["..."],
+  "total_images": 150
+}
+```
+
+### Folder List Response
+```json
+{
+  "folders": [
+    {
+      "path": "/path/to/folder",
+      "name": "folder",
+      "image_count": 42
+    }
+  ]
+}
+```
+
+### Image List Response
+```json
+{
+  "images": [
+    {
+      "filename": "image.jpg",
+      "path": "/full/path/image.jpg",
+      "size": 1024000,
+      "modified": 1234567890.0,
+      "created": 1234567890.0
+    }
+  ],
+  "folder": "/path/to/folder"
+}
+```
+
+This context should help you understand how the PumaGuard UI interacts with the backend and guide your development work!

pumaguard-ui/analysis_options.yaml

@@ -0,0 +1,28 @@
+# This file configures the analyzer, which statically analyzes Dart code to
+# check for errors, warnings, and lints.
+#
+# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
+# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
+# invoked from the command line by running `flutter analyze`.
+
+# The following line activates a set of recommended lints for Flutter apps,
+# packages, and plugins designed to encourage good coding practices.
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  # The lint rules applied to this project can be customized in the
+  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
+  # included above or to enable additional rules. A list of all available lints
+  # and their documentation is published at https://dart.dev/lints.
+  #
+  # Instead of disabling a lint rule for the entire project in the
+  # section below, it can also be suppressed for a single line of code
+  # or a specific dart file by using the `// ignore: name_of_lint` and
+  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
+  # producing the lint.
+  rules:
+    # avoid_print: false  # Uncomment to disable the `avoid_print` rule
+    # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options

pumaguard-ui/android/.gitignore

@@ -0,0 +1,14 @@
+gradle-wrapper.jar
+/.gradle
+/captures/
+/gradlew
+/gradlew.bat
+/local.properties
+GeneratedPluginRegistrant.java
+.cxx/
+
+# Remember to never publicly share your keystore.
+# See https://flutter.dev/to/reference-keystore
+key.properties
+**/*.keystore
+**/*.jks

pumaguard-ui/android/app/build.gradle.kts

@@ -0,0 +1,44 @@
+plugins {
+    id("com.android.application")
+    id("kotlin-android")
+    // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+    id("dev.flutter.flutter-gradle-plugin")
+}
+
+android {
+    namespace = "com.example.pumaguard_ui"
+    compileSdk = flutter.compileSdkVersion
+    ndkVersion = flutter.ndkVersion
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_17.toString()
+    }
+
+    defaultConfig {
+        // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
+        applicationId = "com.example.pumaguard_ui"
+        // You can update the following values to match your application needs.
+        // For more information, see: https://flutter.dev/to/review-gradle-config.
+        minSdk = flutter.minSdkVersion
+        targetSdk = flutter.targetSdkVersion
+        versionCode = flutter.versionCode
+        versionName = flutter.versionName
+    }
+
+    buildTypes {
+        release {
+            // TODO: Add your own signing config for the release build.
+            // Signing with the debug keys for now, so `flutter run --release` works.
+            signingConfig = signingConfigs.getByName("debug")
+        }
+    }
+}
+
+flutter {
+    source = "../.."
+}

pumaguard-ui/android/app/src/debug/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>

pumaguard-ui/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,45 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application
+        android:label="pumaguard_ui"
+        android:name="${applicationName}"
+        android:icon="@mipmap/ic_launcher">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTop"
+            android:taskAffinity=""
+            android:theme="@style/LaunchTheme"
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
+            android:hardwareAccelerated="true"
+            android:windowSoftInputMode="adjustResize">
+            <!-- Specifies an Android theme to apply to this Activity as soon as
+                 the Android process has started. This theme is visible to the user
+                 while the Flutter UI initializes. After that, this theme continues
+                 to determine the Window background behind the Flutter UI. -->
+            <meta-data
+              android:name="io.flutter.embedding.android.NormalTheme"
+              android:resource="@style/NormalTheme"
+              />
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN"/>
+                <category android:name="android.intent.category.LAUNCHER"/>
+            </intent-filter>
+        </activity>
+        <!-- Don't delete the meta-data below.
+             This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
+        <meta-data
+            android:name="flutterEmbedding"
+            android:value="2" />
+    </application>
+    <!-- Required to query activities that can process text, see:
+         https://developer.android.com/training/package-visibility and
+         https://developer.android.com/reference/android/content/Intent#ACTION_PROCESS_TEXT.
+
+         In particular, this is used by the Flutter engine in io.flutter.plugin.text.ProcessTextPlugin. -->
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.PROCESS_TEXT"/>
+            <data android:mimeType="text/plain"/>
+        </intent>
+    </queries>
+</manifest>

pumaguard-ui/android/app/src/main/kotlin/com/example/pumaguard_ui/MainActivity.kt

@@ -0,0 +1,5 @@
+package com.example.pumaguard_ui
+
+import io.flutter.embedding.android.FlutterActivity
+
+class MainActivity : FlutterActivity()

pumaguard-ui/android/app/src/main/res/drawable/launch_background.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Modify this file to customize your launch splash screen -->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="@android:color/white" />
+
+    <!-- You can insert your own image assets here -->
+    <!-- <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@mipmap/launch_image" />
+    </item> -->
+</layer-list>

pumaguard-ui/android/app/src/main/res/drawable-v21/launch_background.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Modify this file to customize your launch splash screen -->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="?android:colorBackground" />
+
+    <!-- You can insert your own image assets here -->
+    <!-- <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@mipmap/launch_image" />
+    </item> -->
+</layer-list>

pumaguard-ui/android/app/src/main/res/values/styles.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is off -->
+    <style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar">
+        <!-- Show a splash screen on the activity. Automatically removed when
+             the Flutter engine draws its first frame -->
+        <item name="android:windowBackground">@drawable/launch_background</item>
+    </style>
+    <!-- Theme applied to the Android Window as soon as the process has started.
+         This theme determines the color of the Android Window while your
+         Flutter UI initializes, as well as behind your Flutter UI while its
+         running.
+
+         This Theme is only used starting with V2 of Flutter's Android embedding. -->
+    <style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
+        <item name="android:windowBackground">?android:colorBackground</item>
+    </style>
+</resources>

pumaguard-ui/android/app/src/main/res/values-night/styles.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is on -->
+    <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
+        <!-- Show a splash screen on the activity. Automatically removed when
+             the Flutter engine draws its first frame -->
+        <item name="android:windowBackground">@drawable/launch_background</item>
+    </style>
+    <!-- Theme applied to the Android Window as soon as the process has started.
+         This theme determines the color of the Android Window while your
+         Flutter UI initializes, as well as behind your Flutter UI while its
+         running.
+
+         This Theme is only used starting with V2 of Flutter's Android embedding. -->
+    <style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
+        <item name="android:windowBackground">?android:colorBackground</item>
+    </style>
+</resources>

pumaguard-ui/android/app/src/profile/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>