318 lines
7.7 KiB
Markdown
318 lines
7.7 KiB
Markdown
# 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)! |