giglez/docs/GPS_AUTO_EXTRACTION.md

GPS Auto-Extraction from Filenames

Feature Overview

The web interface now automatically detects and extracts GPS coordinates from filenames, eliminating the need for manual coordinate entry when filenames contain location data.

Supported Filename Patterns

1. N/S/E/W Format (Primary)

Pattern: LAT[NS]_LON[EW]

Examples:

• 34.0478N_118.2348W_1637_raw_8.sub → 34.0478, -118.2348
• 34.0478N_118.2349W_1351_raw_10.sub → 34.0478, -118.2349
• 40.7128N_74.0060W_capture.sub → 40.7128, -74.0060

Notes:

• Most common format from T-Embed RF captures
• N = positive latitude, S = negative latitude
• E = positive longitude, W = negative longitude

2. lat/lon Prefix Format

Pattern: latLATlonLON

Examples:

• lat34.0478lon-118.2348_test.sub → 34.0478, -118.2348
• lat40.7128lon-74.0060_capture.sub → 40.7128, -74.0060

Notes:

• Allows signed decimal notation
• Case-insensitive (LAT/LON also works)

3. Signed Decimal Format

Pattern: LAT_LON (with optional negative signs)

Examples:

• -34.0478_118.2348_capture.sub → -34.0478, 118.2348
• 40.7128_-74.0060_test.sub → 40.7128, -74.0060

Notes:

• Simple signed decimal degrees
• Less common but supported

How It Works

1. File Upload Detection

When user selects/drops .sub files:

1. Files are added to upload queue
2. First file with GPS coordinates is automatically detected
3. GPS fields are auto-populated
4. User sees notification toast

2. UI Indicators

• GPS Detection Notification: Green toast shows which file provided coordinates
• File List Badge: Files with GPS show 📍 GPS badge
• Coordinate Display: Extracted coordinates appear next to filename

3. Validation

• Latitude range: -90 to 90
• Longitude range: -180 to 180
• Invalid coordinates are rejected
• Malformed patterns are skipped

User Experience

Upload Flow with GPS in Filename

1. Drop/Select File: User uploads 34.0478N_118.2348W_capture.sub
2. Auto-Detection: System extracts GPS (34.0478, -118.2348)
3. Notification: Green toast appears:

   📍 GPS Auto-Detected!
   From: 34.0478N_118.2348W_capture.sub
   Coordinates: 34.047800, -118.234800
   

4. Form Population: Latitude and longitude fields auto-fill
5. Upload: User clicks "Upload Files" (no manual GPS entry needed)

Upload Flow WITHOUT GPS in Filename

1. Drop/Select File: User uploads raw_7.sub
2. No Detection: No GPS found in filename
3. Manual Entry: User must manually enter GPS or use "Use Current Location"
4. Validation: System checks for valid coordinates before upload

Implementation Details

JavaScript GPS Extractor Class

Location: static/js/upload.js

class GPSFilenameExtractor {
    extract(filename) {
        // Try each pattern in order
        return this.tryNSEW(filename) ||
               this.tryLatLon(filename) ||
               this.trySigned(filename);
    }
}

Pattern Matching

• PATTERN_NSEW: /(\d+\.?\d*)([NS])_(\d+\.?\d*)([EW])/i
• PATTERN_LATLON: /lat(-?\d+\.?\d+)lon(-?\d+\.?\d+)/i
• PATTERN_SIGNED: /(-?\d+\.?\d+)_(-?\d+\.?\d+)/

Auto-Population Logic

function addFiles(files) {
    // Try to extract GPS from first file with coordinates
    if (!autoDetectedGPS) {
        for (const file of files) {
            const coords = gpsExtractor.extract(file.name);
            if (coords) {
                autoDetectedGPS = coords;
                document.getElementById('default-lat').value = coords.latitude.toFixed(6);
                document.getElementById('default-lon').value = coords.longitude.toFixed(6);
                showGPSDetectionNotification(file.name, coords);
                break;
            }
        }
    }
}

Testing

Test Suite

Location: test_gps_extraction.html

Open in browser to verify all patterns:

firefox test_gps_extraction.html
# or
chromium test_gps_extraction.html

Test Coverage

• ✅ N/S/E/W format (3 test cases)
• ✅ lat/lon prefix format
• ✅ Signed decimal format
• ✅ Negative detection (files without GPS)

Python Compatibility

The JavaScript implementation matches the Python GPSFilenameExtractor class:

• Same pattern support
• Same validation rules
• Same coordinate transformation logic

T-Embed RF Compatibility

Tested Files

From signatures/t-embed-rf/:

• ✅ 34.0478N_118.2348W_1637_raw_8.sub → Auto-detected
• ✅ 34.0478N_118.2349W_1351_raw_10.sub → Auto-detected
• ✅ 34.0478N_118.2349W_1650_test_raw.sub → Auto-detected
• ⏭️ raw_4.sub → Manual entry required
• ⏭️ raw_5.sub → Manual entry required

Success Rate: 37.5% (3 of 8 files) auto-detected

Error Messages

GPS Required

If no GPS provided (manual or filename):

Please provide GPS coordinates (manually or via filename like: 34.0478N_118.2349W_filename.sub)

GPS Detected but Not Populated

If GPS exists in filename but form is empty:

GPS detected in filename but not populated. Please refresh and try again.

Out of Range

If coordinates exceed valid ranges:

GPS coordinates out of range

Benefits

1. Faster Uploads: No manual GPS entry for T-Embed captures
2. Fewer Errors: Eliminates coordinate typos
3. Better UX: Clear feedback when GPS is detected
4. Flexible: Still allows manual entry for files without GPS
5. Compatible: Matches Python backend extraction logic

Future Enhancements

Additional Patterns

• DMS format: 34d02m52sN_118d14m05sW
• Compact format: N34.0478W118.2348
• Plus codes: 8762+MXP_capture.sub

Multi-File GPS

Currently uses first file's GPS for all uploads. Future enhancement:

• Per-file GPS extraction
• Mixed batch uploads (some with GPS, some without)
• GPS override UI per file

Companion JSON

Check for .json files alongside .sub files:

{
    "capture.sub": {
        "latitude": 34.0478,
        "longitude": -118.2348,
        "accuracy": 5.0
    }
}

Related Files

• static/js/upload.js - Frontend GPS extraction
• src/parser/gps_extractor.py - Backend GPS extraction
• scripts/test_gps_extraction.py - Python test suite
• test_gps_extraction.html - JavaScript test suite

Summary

GPS auto-extraction is LIVE and working with the format 34.0478N_118.2349W_filename.sub. Users can now simply drag and drop T-Embed captures without manually entering coordinates!