README.md

metadata

title: Lanternfly Field Capture
emoji: 🦋
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 4.36.0
app_file: app.py
pinned: false
license: mit
short_description: Mobile field data capture with GPS coordinates

🦋 Lanternfly Field Capture Space

A Hugging Face Gradio Space for capturing field photos with GPS coordinates and automatically saving them to a Hugging Face dataset repository. Perfect for field research data collection on mobile devices.

Features

• 📷 Camera Capture: Take photos directly in the browser
• 📍 GPS Integration: Automatic GPS coordinate capture with accuracy data
• ⏰ Timestamp Recording: Both device and server timestamps
• 💾 Direct Dataset Integration: Saves directly to Hugging Face datasets
• 📱 Mobile Optimized: Works on iOS Safari and Android Chrome
• 🔒 Secure: Uses HTTPS for GPS functionality

Setup Instructions

1. Create a Hugging Face Dataset Repository

1. Go to Hugging Face Hub
2. Create a new dataset repository (e.g., your-username/lanternfly-data)
3. Note the repository name for the next step

2. Configure Space Secrets

In your Hugging Face Space settings, add these secrets:

1. Go to your Space → Settings → Secrets
2. Add the following secrets:

HF_TOKEN = your_huggingface_write_token
DATASET_REPO = your-username/lanternfly-data

To get your HF_TOKEN:

• Go to Hugging Face Settings
• Create a new token with "Write" permissions
• Copy the token value

3. Deploy the Space

1. Fork this Space or create a new Space
2. Upload the files: app.py, requirements.txt, README.md
3. Set the Space to "Public" if you want others to use it
4. The Space will automatically build and deploy

Usage

On Mobile (Recommended)

1. Open the Space on your phone's browser (iOS Safari or Android Chrome)
2. Allow camera and location permissions when prompted
3. Take a photo using the camera interface
4. Click "Get GPS + Time" to capture your location and timestamp
5. Click "Save to Dataset" to commit the data to your Hugging Face dataset

Data Structure

The app saves data in the following structure in your dataset repository:

your-dataset/
├── images/
│   └── 20250124/
│       ├── 123e4567-e89b-12d3-a456-426614174000.jpg
│       └── 456e7890-e89b-12d3-a456-426614174001.jpg
└── data/
    └── records.jsonl

JSONL Format

Each record in data/records.jsonl follows this schema:

{
  "image_path": "images/20250124/123e4567-e89b-12d3-a456-426614174000.jpg",
  "lat": 40.742,
  "lon": -73.987,
  "accuracy_m": 7.2,
  "device_ts": "2025-01-24T17:04:12.123Z",
  "server_ts": "2025-01-24T17:04:13.456Z"
}

Loading Data in Python

Quick JSONL Access

import json

# Read the JSONL file directly
with open("data/records.jsonl", "r") as f:
    for line in f:
        record = json.loads(line.strip())
        print(f"Image: {record['image_path']}")
        print(f"Location: {record['lat']}, {record['lon']}")
        print(f"Timestamp: {record['device_ts']}")

Using Hugging Face Datasets (if loading script provided)

from datasets import load_dataset

# Load the dataset
dataset = load_dataset("your-username/lanternfly-data")

# Access images and metadata
for example in dataset["train"]:
    image = example["image"]
    metadata = example["metadata"]
    print(f"Location: {metadata['lat']}, {metadata['lon']}")

Troubleshooting

GPS Issues

• Permission Denied: Make sure to allow location access in your browser
• Position Unavailable: Try moving to an area with better GPS signal
• Timeout: The GPS request times out after 10 seconds

Camera Issues

• No Camera: Ensure you're using HTTPS (required for camera access)
• Permission Denied: Allow camera permissions when prompted

Dataset Issues

• Commit Failed: Check that your HF_TOKEN has write permissions
• Repository Not Found: Verify DATASET_REPO is correctly set

Technical Details

• Framework: Gradio 4.36+ with Blocks interface
• Image Format: JPEG with 90% quality, RGB color space
• GPS Accuracy: Uses enableHighAccuracy: true for best precision
• Concurrency: Handles concurrent commits with retry logic
• Mobile Support: Optimized for touch interfaces

File Structure

├── app.py              # Main Gradio application
├── requirements.txt    # Python dependencies
├── README.md          # This file
└── lanternfly.py      # Optional dataset loading script

Privacy & Security

• All data is stored in your own Hugging Face dataset repository
• No external servers or third-party services are used
• GPS data is only captured when you explicitly request it
• Images are stored with UUID filenames for privacy

Contributing

Feel free to submit issues or pull requests to improve the application!

License

This project is open source and available under the MIT License.