indoorloc 0.1.1

A unified framework for indoor localization

Open Source Indoor Localization Toolbox

English | 中文

---

Introduction

IndoorLoc is a unified framework for indoor localization, inspired by MMPretrain. It provides a one-stop solution from datasets to algorithms, enabling automatic adaptation across different localization methods.

Who is this for?

• Beginners: Get started with indoor localization quickly without worrying about implementation details
• Researchers: Reproduce and compare state-of-the-art algorithms with consistent interfaces
• Developers: Build and deploy indoor positioning systems with production-ready code

Why IndoorLoc?

• Zero Boilerplate: Load datasets, train models, and evaluate results in just a few lines of code
• Fair Comparison: All algorithms use the same data pipeline and evaluation metrics
• Easy Reproduction: Built-in configs for reproducing published results
• Rapid Prototyping: Focus on your novel ideas, not engineering details

Features

• Multi-Algorithm Support: k-NN, SVM, Random Forest, Deep Learning (CNN, LSTM, Transformer)
• Multi-Modal: WiFi, BLE, IMU, Visual, UWB signal support
• Multi-Dataset: UJIndoorLoc, Tampere, Microsoft Indoor, and more
• Unified Interface: Consistent API across all algorithms
• Easy Configuration: YAML-based configuration with inheritance
• Extensible: Registry-based plugin architecture
• PyPI Ready: Easy installation via pip

Installation

# Basic installation
pip install indoorloc

# With vision support
pip install indoorloc[vision]

# Full installation (all features)
pip install indoorloc[full]

# Development installation
git clone https://github.com/qdtiger/indoorloc.git
cd indoorloc
pip install -e ".[dev]"

Quick Start

import indoorloc as iloc
import numpy as np

# Create a k-NN localizer
model = iloc.create_model('KNNLocalizer', k=5)

# Prepare training data
train_signals = [
    iloc.WiFiSignal(rssi_values=np.random.randn(520).astype(np.float32))
    for _ in range(100)
]
train_locations = [
    iloc.Location.from_coordinates(
        x=np.random.uniform(0, 100),
        y=np.random.uniform(0, 100),
        floor=np.random.randint(0, 3)
    )
    for _ in range(100)
]

# Train the model
model.fit(train_signals, train_locations)

# Make predictions
test_signal = iloc.WiFiSignal(rssi_values=np.random.randn(520).astype(np.float32))
result = model.predict(test_signal)

print(f"Predicted position: ({result.x:.2f}, {result.y:.2f})")
print(f"Predicted floor: {result.floor}")

Using Configuration Files

# configs/wifi/knn_ujindoorloc.yaml
model:
  type: KNNLocalizer
  k: 5
  weights: distance
  metric: euclidean
  predict_floor: true
  predict_building: true

import indoorloc as iloc

# Load from config
model = iloc.create_model(config='configs/wifi/knn_ujindoorloc.yaml')

Custom Model Registration

from indoorloc.registry import LOCALIZERS
from indoorloc.localizers.base import BaseLocalizer

@LOCALIZERS.register_module()
class MyCustomLocalizer(BaseLocalizer):
    def __init__(self, custom_param=1.0, **kwargs):
        super().__init__(**kwargs)
        self.custom_param = custom_param

    @property
    def localizer_type(self) -> str:
        return 'my_custom'

    def fit(self, signals, locations, **kwargs):
        # Training logic
        self._is_trained = True
        return self

    def predict(self, signal):
        # Prediction logic
        pass

# Use the custom model
model = iloc.create_model('MyCustomLocalizer', custom_param=2.0)

Project Structure

indoorloc/
├── indoorloc/
│   ├── signals/          # Signal abstractions (WiFi, BLE, IMU, etc.)
│   ├── locations/        # Location and coordinate classes
│   ├── datasets/         # Dataset implementations
│   ├── localizers/       # Localization algorithms
│   │   ├── fingerprint/  # Traditional ML (k-NN, SVM, RF)
│   │   ├── deep/         # Deep learning (CNN, LSTM, Transformer)
│   │   └── pdr/          # Inertial navigation
│   ├── fusion/           # Multi-sensor fusion
│   ├── evaluation/       # Metrics and evaluation
│   ├── engine/           # Training utilities
│   ├── visualization/    # Plotting tools
│   ├── configs/          # Built-in configurations
│   └── utils/            # Utility functions
├── tools/                # CLI tools
├── examples/             # Usage examples
├── tests/                # Unit tests
└── docs/                 # Documentation

Supported Algorithms

Fingerprint-based

• k-NN (k-Nearest Neighbors)
• Weighted k-NN
• SVM (Support Vector Machine)
• Random Forest
• Gaussian Process

Deep Learning

• MLP (Multi-Layer Perceptron)
• CNN (Convolutional Neural Network)
• LSTM (Long Short-Term Memory)
• Transformer

Fusion

• Kalman Filter
• Extended Kalman Filter
• Particle Filter

Supported Datasets

21 datasets across multiple signal modalities with auto-download support.

RSSI	CSI	ToF/TWR	Magnetic	Multi-modal	Other
WiFi RSSI UJIndoorLoc SODIndoorLoc LongTermWiFi Tampere WLANRSSI TUJI1 RSSBased BLE RSSI iBeaconRSSI BLEIndoor BLERSSIU_UCI	CSIIndoor	UWBIndoor UWBRanging	MagneticIndoor	WiFiIMUHybrid WiFiMagneticHybrid MultiModalIndoor SensorFusion	VLCIndoor UltrasoundIndoor RFIDIndoor

Auto-Download Usage

import indoorloc as iloc

# UJIndoorLoc - Auto-download to ~/.cache/indoorloc/datasets/
dataset = iloc.UJIndoorLoc(download=True)
train = iloc.UJIndoorLoc(download=True, split='train')
test = iloc.UJIndoorLoc(download=True, split='test')

# SODIndoorLoc - Specify building
cetc_train = iloc.SODIndoorLoc(building='CETC331', download=True)
hcxy_train = iloc.SODIndoorLoc(building='HCXY', download=True)

# Or specify custom directory
dataset = iloc.UJIndoorLoc(data_root='./data', download=True)

Manual Download

You can also download datasets manually from official sources:

Dataset	Official Source	Notes
UJIndoorLoc	UCI ML Repository	Direct ZIP download
SODIndoorLoc	GitHub Repository	CSV files on GitHub
Microsoft Indoor 2.0	Microsoft Research + GitHub	Multi-sensor (WiFi, BLE, IMU, Magnetometer)
TUJI1	Tampere University + Zenodo	Multi-device collection
WiFi-RSSI	GitHub Repository	Small-scale (250 points)
OWP-IMU	arXiv	Optical wireless + IMU fusion

Evaluation Metrics

Metric	Description
Mean Position Error	Average localization error (meters)
Median Position Error	Median localization error (meters)
75th/95th Percentile	75%/95% percentile error
Floor Accuracy	Floor classification accuracy
Building Accuracy	Building classification accuracy
CDF Analysis	Cumulative distribution function analysis

License

Apache License 2.0

Citation

@software{indoorloc,
  title = {IndoorLoc: A Unified Framework for Indoor Localization},
  year = {2024},
  url = {https://github.com/qdtiger/indoorloc}
}

Acknowledgements

• OpenMMLab - Registry and config system design reference
• UJIndoorLoc - Dataset provider

Contributing

We welcome issues and pull requests!