GitHub - peterretief/biometric

5 min read Original article ↗

📱 AI Tremor-Print: Biometric Identification System

A cutting-edge biometric identification system using smartphone magnetometer sensors and fine-tuned AI models to capture neuromuscular micro-tremors for individual identification.

Perfect for: Researchers, neuromuscular analysis, accessibility applications, and low-cost biometric authentication.

🎯 What is This?

This project demonstrates how to:

  • Capture hand tremors using a smartphone's magnetometer sensor
  • Extract biometric signatures from magnetic field variations
  • Train an AI model (DistilGPT2) to recognize individuals based on tremor patterns
  • Verify identity in real-time with sensor data

Key Innovation: Hand tremors are involuntary, reproducible, and unique to each person—making them ideal biometric markers!

🌟 Features

  • ✅ Low-Cost Hardware - Uses only a smartphone (no special equipment)
  • ✅ GPU Optimized - Works on consumer GPUs (2GB+ VRAM) or CPU
  • ✅ Real-time Verification - Identify individuals in seconds
  • ✅ Privacy-First - All processing done locally, no cloud dependence
  • ✅ Research-Ready - Includes full pipeline: data → training → testing
  • ✅ Well Documented - Comprehensive guides for setup and troubleshooting

📋 Project Components

Component Purpose File
Data Collection Record tremor data from sensors *_data.py
Feature Extraction Convert raw sensor data to biometric signatures conversion.py
AI Training Fine-tune DistilGPT2 on tremor patterns train.py
Verification Test model accuracy on unknown samples test_sensor.py

🚀 Quick Start

Total time: ~30 minutes (10 min setup + 20 min training)

# 1. Clone & Setup (5 min)
git clone https://github.com/peterretief/biometric.git
cd biometric
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 2. Prepare Data (5 min)
# Place desk.csv, peter.csv, jason.csv in folder (or record new ones)
python conversion.py

# 3. Train Model (20 min)
python train.py

# 4. Test (1 min)
python test_sensor.py

Expected output:

File: desk.csv | Result: The device is on a stationary desk.
File: peter.csv | Result: The device is held by Peter.
File: jason.csv | Result: The device is held by Jason.

📁 Project Structure

biometric/
├── README.md              # This file
├── HOWTO.md              # Step-by-step setup guide
├── requirements.txt      # Python dependencies
├── .gitignore           # Exclude large files
│
├── train.py             # Main training script
├── conversion.py        # CSV → JSON feature extraction
├── test_sensor.py       # Model verification
├── gen_real_data.py     # Optional: generate test data
│
├── *.csv                # Sensor data files
│   ├── desk.csv         # Baseline (stationary)
│   ├── peter.csv        # Person A
│   └── jason.csv        # Person B
│
├── data.json            # Extracted features (auto-generated)
├── my_trained_model/    # Final trained model (auto-generated)
└── results/             # Training checkpoints (auto-generated)

🔧 Requirements

  • Python: 3.8+
  • GPU: Optional (CUDA 11.0+) — ~2GB VRAM minimum
  • Storage: ~500MB free (for models & data)
  • Time: ~20 minutes for training on GPU

📚 Documentation

  • HOWTO.md — Complete step-by-step guide for beginners
  • train.py — Inline comments explaining training logic
  • conversion.py — Feature extraction details

🔬 How It Works

Phase 1: Data Collection

  • Use Physics Toolbox Sensor Suite app on Android/iOS
  • Record 30 seconds of magnetometer data for each person
  • Save as CSV files (Bx, By, Bz magnetic field components)

Phase 2: Feature Extraction

  • Split 30-second recordings into 2-second windows
  • Calculate Noise (std) = tremor amplitude
  • Calculate Mean = grip orientation
  • Create JSON with instruction-response pairs

Phase 3: AI Training

  • Tokenize biometric signatures as text
  • Fine-tune DistilGPT2 for 50 epochs
  • Learn to map tremor patterns → person identity

Phase 4: Verification

  • Feed unknown sensor data to trained model
  • Model outputs predicted identity
  • Compare to ground truth

📊 Performance

Metric Expected Notes
Training Loss < 0.5 Error rate on training data
Accuracy > 90% Correct identifications
Inference Time < 1 sec Time to identify per sample
False Positive Rate < 5% Wrong identity identification

🛠️ Customization

Add More People

  1. Record new CSV files: alice.csv, bob.csv, etc.
  2. Edit conversion.py to include them
  3. Re-run: python conversion.py && python train.py

Change Model Size

In train.py, replace distilgpt2:

model_name = "gpt2"  # Larger, slower, more powerful

Adjust Training Duration

In train.py:

num_train_epochs=100  # Train longer for better accuracy

⚡ GPU Acceleration

Check GPU

python -c "import torch; print(torch.cuda.is_available())"

Install CUDA Support

pip install torch --index-url https://download.pytorch.org/whl/cu118

🐛 Troubleshooting

Issue Solution
ModuleNotFoundError Run pip install -r requirements.txt
Out of Memory (OOM) Reduce per_device_train_batch_size in train.py
No GPU CPU falls back automatically (slower)
Data not found Ensure *.csv files in project root
Poor accuracy Collect more data or increase epochs

See HOWTO.md for detailed troubleshooting.

📚 Medical/Clinical Context

This project is relevant for:

  • Neuromuscular Disorders - Detect changes in tremor patterns
  • Parkinson's Disease Monitoring - Track motor control progression
  • Accessibility Tech - Alternative biometric for those with limitations
  • Rehabilitation - Monitor recovery through tremor analysis

Key insight: Standard deviation of magnetic field ≈ Power Spectral Density (PSD) of tremor frequencies, making smartphone sensors viable for clinical applications.

📜 License

MIT License — Use freely for research, education, and commercial projects.

Copyright (c) 2024-2026 Peter Retief

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

🤝 Contributing

Have improvements? Found a bug? Want to add features?

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-idea
  3. Commit changes: git commit -m "Add feature description"
  4. Push to branch: git push origin feature/your-idea
  5. Open a Pull Request

📞 Support

  • Questions? Open an Issue
  • Bug report? Include error message + steps to reproduce
  • Feature request? Describe use case and expected behavior

🎓 Learning Resources

  • Transformers Library Documentation - For model fine-tuning details
  • Medical journals - Search for "tremor analysis" and "accelerometer biometrics"
  • Smartphone sensor calibration - Research your phone's magnetometer specifications

🚀 Next Steps

  1. Read HOWTO.md for detailed setup instructions
  2. Collect sensor data using Physics Toolbox app
  3. Run training and verify accuracy
  4. Customize for your use case

Let's build the future of biometric authentication! 🎯

Author: Peter Retief
Last Updated: April 2026
Repository: https://github.com/peterretief/biometric