Enhance README.md with badges, installation instructions, and community support details. Improved project structure and added quick contribution guidelines.
This commit is contained in:
defiQUG
318
docs/quickstart.md
Normal file
318
docs/quickstart.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# Quick Start Guide
|
||||
|
||||
Welcome to NowYouSeeMe! This guide will get you up and running with the holodeck environment in under 10 minutes.
|
||||
|
||||
## 🎯 What You'll Learn
|
||||
|
||||
- Install NowYouSeeMe on your system
|
||||
- Configure your camera and WiFi hardware
|
||||
- Run your first holodeck session
|
||||
- Understand the basic interface
|
||||
- Troubleshoot common issues
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
Before starting, ensure you have:
|
||||
|
||||
### Hardware Requirements
|
||||
- **Camera**: USB camera (720p+ recommended)
|
||||
- **WiFi Card**: Intel 5300 or compatible with Nexmon support
|
||||
- **GPU**: CUDA-capable GPU (NVIDIA GTX 1060+)
|
||||
- **RAM**: 8GB+ recommended
|
||||
- **Storage**: 10GB+ free space
|
||||
|
||||
### Software Requirements
|
||||
- **OS**: Ubuntu 20.04+ or Windows 10+
|
||||
- **Python**: 3.8 or higher
|
||||
- **Git**: For cloning the repository
|
||||
|
||||
## 🚀 Installation Options
|
||||
|
||||
### Option 1: Docker (Recommended)
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-org/NowYouSeeMe.git
|
||||
cd NowYouSeeMe
|
||||
|
||||
# Start with Docker Compose
|
||||
docker-compose up -d
|
||||
|
||||
# Access the application
|
||||
# Open your browser to http://localhost:8080
|
||||
```
|
||||
|
||||
### Option 2: PyPI Package
|
||||
|
||||
```bash
|
||||
# Install from PyPI
|
||||
pip install nowyouseeme[gpu,azure]
|
||||
|
||||
# Run the application
|
||||
nowyouseeme
|
||||
```
|
||||
|
||||
### Option 3: Manual Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-org/NowYouSeeMe.git
|
||||
cd NowYouSeeMe
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -e .[dev]
|
||||
|
||||
# Build C++ components
|
||||
./tools/build.sh
|
||||
```
|
||||
|
||||
## 🔧 Hardware Setup
|
||||
|
||||
### Camera Configuration
|
||||
|
||||
1. **Connect your camera** to a USB port
|
||||
2. **Verify detection**:
|
||||
```bash
|
||||
ls /dev/video*
|
||||
# Should show /dev/video0 or similar
|
||||
```
|
||||
|
||||
3. **Test camera**:
|
||||
```bash
|
||||
# Test with OpenCV
|
||||
python -c "import cv2; cap = cv2.VideoCapture(0); print('Camera working:', cap.isOpened())"
|
||||
```
|
||||
|
||||
### WiFi CSI Setup
|
||||
|
||||
1. **Check WiFi card compatibility**:
|
||||
```bash
|
||||
lspci | grep -i network
|
||||
# Look for Intel 5300 or compatible card
|
||||
```
|
||||
|
||||
2. **Install Nexmon** (if needed):
|
||||
```bash
|
||||
# Follow Nexmon installation guide
|
||||
# https://github.com/seemoo-lab/nexmon
|
||||
```
|
||||
|
||||
3. **Configure CSI capture**:
|
||||
```bash
|
||||
# Edit config/csi_config.json
|
||||
# Set your WiFi interface and parameters
|
||||
```
|
||||
|
||||
## 🎮 First Run
|
||||
|
||||
### Starting the Application
|
||||
|
||||
```bash
|
||||
# From the project directory
|
||||
python -m src.ui.holodeck_ui
|
||||
|
||||
# Or if installed via PyPI
|
||||
nowyouseeme
|
||||
```
|
||||
|
||||
### Initial Setup Wizard
|
||||
|
||||
When you first run NowYouSeeMe, you'll see a setup wizard:
|
||||
|
||||
1. **Welcome Screen** - Click "Next"
|
||||
2. **Hardware Detection** - Verify camera and WiFi are detected
|
||||
3. **Calibration** - Follow the calibration process
|
||||
4. **Configuration** - Set your preferences
|
||||
5. **Finish** - Start your first session
|
||||
|
||||
### Calibration Process
|
||||
|
||||
1. **Camera Calibration**:
|
||||
- Print the calibration pattern
|
||||
- Hold it at different angles
|
||||
- Follow the on-screen instructions
|
||||
|
||||
2. **RF Calibration**:
|
||||
- Move around the room slowly
|
||||
- Let the system learn the environment
|
||||
- Complete the RF mapping
|
||||
|
||||
## 🖥️ Interface Overview
|
||||
|
||||
### Main Window
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ NowYouSeeMe Holodeck Environment │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 📷 Camera View │ 📡 RF Map │ 🎯 3D Scene │
|
||||
│ │ │ │
|
||||
│ [Live Camera] │ [RF Coverage] │ [3D Rendering] │
|
||||
│ │ │ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 📊 Status Panel │ ⚙️ Controls │ 📈 Performance │
|
||||
│ Latency: 18ms │ [Start/Stop] │ FPS: 45 │
|
||||
│ Accuracy: 8cm │ [Calibrate] │ CSI: 120 pkt/s │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Key Controls
|
||||
|
||||
- **🎬 Start/Stop**: Begin or pause tracking
|
||||
- **🎯 Calibrate**: Re-run calibration
|
||||
- **📊 Settings**: Configure parameters
|
||||
- **💾 Save**: Save current session
|
||||
- **📤 Export**: Export to Unity/Unreal
|
||||
|
||||
### View Modes
|
||||
|
||||
1. **3D Scene**: Real-time 3D visualization
|
||||
2. **RF Map**: WiFi CSI coverage map
|
||||
3. **Camera Feed**: Raw camera input
|
||||
4. **Fusion View**: Combined sensor data
|
||||
|
||||
## 🎯 Basic Usage
|
||||
|
||||
### Starting a Session
|
||||
|
||||
1. **Launch the application**
|
||||
2. **Wait for hardware detection**
|
||||
3. **Click "Start Tracking"**
|
||||
4. **Move around slowly** to let the system learn
|
||||
5. **Observe the 3D scene** updating in real-time
|
||||
|
||||
### Understanding the Display
|
||||
|
||||
- **Green dots**: Confident tracking points
|
||||
- **Yellow dots**: Uncertain measurements
|
||||
- **Red areas**: RF coverage gaps
|
||||
- **Blue lines**: Trajectory path
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
Watch the status panel for:
|
||||
- **Latency**: Should be <20ms
|
||||
- **Accuracy**: Should be <10cm
|
||||
- **Frame Rate**: Should be 30-60 FPS
|
||||
- **CSI Rate**: Should be ≥100 packets/second
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Camera Settings
|
||||
|
||||
Edit `config/camera_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"camera": {
|
||||
"device_id": 0,
|
||||
"width": 1280,
|
||||
"height": 720,
|
||||
"fps": 30,
|
||||
"exposure": "auto"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### CSI Settings
|
||||
|
||||
Edit `config/csi_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"csi": {
|
||||
"interface": "wlan0",
|
||||
"channel": 6,
|
||||
"bandwidth": 20,
|
||||
"packet_rate": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Camera Not Detected
|
||||
```bash
|
||||
# Check camera permissions
|
||||
sudo usermod -a -G video $USER
|
||||
|
||||
# Verify camera device
|
||||
ls -la /dev/video*
|
||||
|
||||
# Test with OpenCV
|
||||
python -c "import cv2; print(cv2.__version__)"
|
||||
```
|
||||
|
||||
#### WiFi CSI Not Working
|
||||
```bash
|
||||
# Check WiFi card
|
||||
lspci | grep -i network
|
||||
|
||||
# Verify Nexmon installation
|
||||
lsmod | grep nexmon
|
||||
|
||||
# Test CSI capture
|
||||
sudo ./tools/test_csi.sh
|
||||
```
|
||||
|
||||
#### Low Performance
|
||||
```bash
|
||||
# Check GPU
|
||||
nvidia-smi
|
||||
|
||||
# Monitor system resources
|
||||
htop
|
||||
|
||||
# Reduce quality settings
|
||||
# Edit config files to lower resolution/FPS
|
||||
```
|
||||
|
||||
#### Application Crashes
|
||||
```bash
|
||||
# Check logs
|
||||
tail -f logs/nowyouseeme.log
|
||||
|
||||
# Run in debug mode
|
||||
python -m src.ui.holodeck_ui --debug
|
||||
|
||||
# Check dependencies
|
||||
pip list | grep -E "(opencv|numpy|PyQt6)"
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. **Check the logs**: `tail -f logs/nowyouseeme.log`
|
||||
2. **Run in debug mode**: Add `--debug` flag
|
||||
3. **Search issues**: [GitHub Issues](https://github.com/your-org/NowYouSeeMe/issues)
|
||||
4. **Ask community**: [Discord Server](https://discord.gg/nowyouseeme)
|
||||
5. **Email support**: support@nowyouseeme.dev
|
||||
|
||||
## 🎉 Next Steps
|
||||
|
||||
Congratulations! You've successfully set up NowYouSeeMe. Here's what to explore next:
|
||||
|
||||
### Advanced Features
|
||||
- [Neural Rendering](docs/neural_rendering.md) - NeRF integration
|
||||
- [Sensor Fusion](docs/sensor_fusion.md) - Advanced algorithms
|
||||
- [Azure Integration](docs/azure_integration.md) - Cloud GPU support
|
||||
- [Unity Export](docs/unity_export.md) - VR/AR integration
|
||||
|
||||
### Development
|
||||
- [API Reference](docs/API_REFERENCE.md) - Complete API documentation
|
||||
- [Contributing](CONTRIBUTING.md) - How to contribute
|
||||
- [Architecture](docs/architecture.md) - System design
|
||||
|
||||
### Community
|
||||
- [Discord](https://discord.gg/nowyouseeme) - Join the community
|
||||
- [GitHub Discussions](https://github.com/your-org/NowYouSeeMe/discussions) - Share ideas
|
||||
- [Blog](https://nowyouseeme.dev/blog) - Latest updates
|
||||
|
||||
---
|
||||
|
||||
**Need help?** Check our [Troubleshooting Guide](troubleshooting.md) or ask the [community](https://discord.gg/nowyouseeme)!
|
||||
Reference in New Issue
Block a user