Metadata-Version: 2.4
Name: indoorloc
Version: 0.1.0
Summary: A unified framework for indoor localization
Author: IndoorLoc Team
Maintainer: IndoorLoc Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/indoorloc/indoorloc
Project-URL: Documentation, https://indoorloc.readthedocs.io
Project-URL: Repository, https://github.com/indoorloc/indoorloc
Project-URL: Issues, https://github.com/indoorloc/indoorloc/issues
Keywords: indoor localization,WiFi fingerprinting,positioning,deep learning,machine learning,location,RSSI
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.10.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: vision
Requires-Dist: torchvision>=0.11.0; extra == "vision"
Requires-Dist: opencv-python>=4.5.0; extra == "vision"
Provides-Extra: full
Requires-Dist: torchvision>=0.11.0; extra == "full"
Requires-Dist: opencv-python>=4.5.0; extra == "full"
Requires-Dist: matplotlib>=3.4.0; extra == "full"
Requires-Dist: seaborn>=0.11.0; extra == "full"
Requires-Dist: scipy>=1.7.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Dynamic: license-file

<div align="center">

<img src="assets/logo.png" width="600">

**Open Source Indoor Localization Toolbox**

[![Build](https://github.com/qdtiger/indoorloc/actions/workflows/ci.yml/badge.svg)](https://github.com/qdtiger/indoorloc/actions)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Stars](https://img.shields.io/github/stars/qdtiger/indoorloc?style=social)](https://github.com/qdtiger/indoorloc)

[![Issues](https://img.shields.io/github/issues/qdtiger/indoorloc)](https://github.com/qdtiger/indoorloc/issues)
[![Last Commit](https://img.shields.io/github/last-commit/qdtiger/indoorloc)](https://github.com/qdtiger/indoorloc/commits/main)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/qdtiger/indoorloc/pulls)

[English](README.md) | [中文](README_zh.md)

</div>

---

## Introduction

IndoorLoc is a unified framework for indoor localization, inspired by [MMPretrain](https://github.com/open-mmlab/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

```bash
# 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

```python
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

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

```python
import indoorloc as iloc

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

## Custom Model Registration

```python
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
- [x] k-NN (k-Nearest Neighbors)
- [x] 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

- [x] UJIndoorLoc
- [ ] Tampere
- [ ] Microsoft Indoor Localization
- [ ] Custom datasets

## 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

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

## Acknowledgements

- [OpenMMLab](https://github.com/open-mmlab) - Registry and config system design reference
- [UJIndoorLoc](https://archive.ics.uci.edu/dataset/310/ujiindoorloc) - Dataset provider

## Contributing

We welcome issues and pull requests!
