{"id":13722793,"url":"https://github.com/gante/mmWave-localization-learning","last_synced_at":"2025-05-07T16:30:49.363Z","repository":{"id":31539868,"uuid":"128225040","full_name":"gante/mmWave-localization-learning","owner":"gante","description":"🎯 ML-based positioning method from mmWave transmissions - with high accuracy and energy efficiency","archived":false,"fork":false,"pushed_at":"2024-07-30T21:16:46.000Z","size":2224,"stargazers_count":122,"open_issues_count":5,"forks_count":43,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T19:37:26.956Z","etag":null,"topics":["5g","beamforming","cnn","deep-learning","jetson-tx2","lstm","machine-learning","mmwave","nlos","positioning","tcn","tracking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gante.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["paypal.me/joaogante"]}},"created_at":"2018-04-05T15:20:48.000Z","updated_at":"2025-03-14T15:42:46.000Z","dependencies_parsed_at":"2024-10-23T04:06:03.358Z","dependency_job_id":null,"html_url":"https://github.com/gante/mmWave-localization-learning","commit_stats":{"total_commits":88,"total_committers":5,"mean_commits":17.6,"dds":0.1477272727272727,"last_synced_commit":"2549fd500766a3a5ec7c417b7c01ac8eaad18fa3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gante%2FmmWave-localization-learning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gante%2FmmWave-localization-learning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gante%2FmmWave-localization-learning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gante%2FmmWave-localization-learning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gante","download_url":"https://codeload.github.com/gante/mmWave-localization-learning/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252915216,"owners_count":21824523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["5g","beamforming","cnn","deep-learning","jetson-tx2","lstm","machine-learning","mmwave","nlos","positioning","tcn","tracking"],"created_at":"2024-08-03T01:01:33.047Z","updated_at":"2025-05-07T16:30:48.730Z","avatar_url":"https://github.com/gante.png","language":"Python","funding_links":["paypal.me/joaogante"],"categories":["Localization and State Estimation","Research"],"sub_categories":["Lidar and Point Cloud Processing","Diameter"],"readme":"# Beamformed Fingerprint Learning\n\nAn ML-based algorithm that enables energy efficient accurate positioning from mmWave transmissions, with and without tracking.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"extra/repo_images/error_vs_position.PNG\" width=\"400\"/\u003e\n  \u003cimg src=\"extra/repo_images/energy.png\" width=\"425\"/\u003e\n\u003c/p\u003e\n\n\n### Table of Contents\n1. [Background](#background)\n2. [Papers](#papers)\n    - [Citation](#citation)\n    - [List of Papers](#list-of-papers)\n3. [Getting Started](#getting-started)\n    - [Before Installing](#before-installing)\n    - [Installation](#installation)\n    - [Dataset](#dataset)\n4. [Experiments](#experiments)\n   - [Configuration](#configuration)\n   - [Tracking](#tracking)\n   - [Running an Experiment](#running-an-experiment)\n   - [Evaluate performance on an Nvidia Jetson](#evaluate-performance-on-an-nvidia-jetson)\n5. [License](#license)\n6. [Acknowledgments](#acknowledgments)\n\n\n## Background\n\nWith **5G millimeter wave wireless communications**, the resulting radiation reflects on most visible objects, creating rich multipath environments, as depicted in the simulation below. The radiation is thus significantly shaped by the obstacles it interacts with, carrying latent information regarding the relative positions of the transmitter, the obstacles, and the mobile receiver.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"extra/repo_images/propagation.PNG\" width=\"400\"/\u003e\n\u003c/p\u003e\n\n\nIn this work, the creation of **beamformed fingerprints** is achieved through a pre-established codebook of beamforming patterns transmitted by a **single base station**. Making use of the aforementioned hidden information, deep learning techniques are employed to convert the received beamformed fingerprints (see examples below) into a mobile device’s position. Average errors of down to **3.30/1.78 meters (non-tracking/tracking)** are obtained on realistic outdoor scenarios, containing **mostly non-line-of-sight positions**.\n\nMoreover, it was shown that this system is **47x** and **85x** more energy efficient than conventional A-GPS low-power implementations (for continuous and sporadic position fixes, respectively), making it a very competitive and promising alternative for **outdoor positioning**.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"extra/repo_images/bff_examples.PNG\" width=\"480\"/\u003e\n\u003c/p\u003e\n\nThe image shown at the top (left) contains the simulated results for the average error per covered position. Given that the transmitter is the red triangle at the center of the image, and most of the solid yellow shapes are buildings, it is possible to confirm that **being in a NLOS position is not a constraint for the proposed system**. It is able to provide an estimative for every position that has mmWave signal.\n\nThis repository also contains tools to evaluate the model performance on a low-power embedded system (Nvidia Jetson TX2), which demonstrates the low energy requirements of this solution - \\\u003c 10 mJ per position estimate, if the position inference is done at the mobile device. The comparison results are also observable at the top (right).\n\nFor more information, refer to [papers](#papers) section of this README file. If you find any issue, please contact me (joao.gante@tecnico.ulisboa.pt).\n\n\n## Papers\n### Citation\n\nThere are two main citations for this work.\n\nBy default, consider using the following:\n\n```\n@Article{Gante2019,\n  author=\"Gante, Jo{\\~a}o and Falc{\\~a}o, Gabriel and Sousa, Leonel\",\n  title=\"{Deep Learning Architectures for Accurate Millimeter Wave Positioning in 5G}\",\n  journal=\"Neural Processing Letters\",\n  year=\"2019\",\n  month=\"Aug\",\n  day=\"13\",\n  issn=\"1573-773X\",\n  doi=\"10.1007/s11063-019-10073-1\",\n  url=\"https://doi.org/10.1007/s11063-019-10073-1\"\n}\n```\n\nIf you are concerned about the energy efficiency of positioning methods or ML-enabled mobile applications, please use:\n\n```\n@ARTICLE{Gante2020,\n  author={J. {Gante} and L. {Sousa} and G. {Falcao}},\n  journal={IEEE Journal on Emerging and Selected Topics in Circuits and Systems},\n  title={Dethroning GPS: Low-Power Accurate 5G Positioning Systems Using Machine Learning},\n  year={2020},\n  volume={10},\n  number={2},\n  pages={240-252},\n}\n```\n\n\n### List of Papers\n\n(From newest to oldest)\n\n- \"Dethroning GPS: Low-Power Accurate 5G Positioning Systems using Machine Learning\" --- IEEE JETCAS ([ieeexplore](https://ieeexplore.ieee.org/document/9080126) -- a copy is also available [here](https://drive.google.com/open?id=1fUZQeUSIYGUNn7S7aXLiNUhF0OOc04_M))\n\n- \"Deep Learning Architectures for Accurate Millimeter Wave Positioning in 5G\" --- Neural Processing Letters ([link](https://rdcu.be/bOOpk) -- a post-peer-review, pre-copyedit version is also available [here](https://drive.google.com/open?id=19P7Ebg80pVqyHNkfPDQNweozl4k4S6RC))\n\n- \"Enhancing Beamformed Fingerprint Outdoor Positioning with Hierarchical Convolutional Neural Networks\" --- ICASSP 2019 ([ieeexplore](https://ieeexplore.ieee.org/document/8683782))\n\n- \"Beamformed Fingerprint Learning for Accurate Millimeter Wave Positioning\" --- VTC Fall 2018 ([ieeexplore](https://ieeexplore.ieee.org/document/8690987) , also on [arxiv](https://arxiv.org/abs/1804.04112))\n\n\n\n## Getting Started\n\nThese instructions will get you a copy of the project up and running on your local machine for development and testing purposes.\n\n\n### Before Installing\n\nTo ensure a smooth process, please ensure you have the following requirements.\n\n**Hardware**\n- Nvidia GPU with Compute Capability 3.5 or higher\n- at least 16GB of RAM (32GB recommended)\n\n**Software**\n- Python 3.6 or higher\n- Tensorflow 2.4\n- CUDA 11.0\n\n### Installation\n\nClone this repository, and then install it and its requirements. It should be something similar to this:\n\n```\ngit clone https://github.com/gante/mmWave-localization-learning.git\npip3 install -e mmWave-localization-learning/\npip3 install -r mmWave-localization-learning/requirements.txt\n```\n\n### Dataset\n\nThe data was generated using the [Wireless InSite ray-tracing simulator](https://www.remcom.com/wireless-insite-em-propagation-software/) and a [high precision open-source 3D map of New York](http://www1.nyc.gov/site/doitt/initiatives/3d-building.page), made available by the New York City Department of Information Technology \u0026 Telecommunications.\nThe simulation consists of a 400 by 400 meters area, centered at the [Kaufman Management Center](https://goo.gl/maps/xrqvT9VS59K2). If you would like to have the 3D files for this or other sections of NYC, feel free to email me.\n\nThe dataset is available [here](https://drive.google.com/drive/folders/1gfbZKCsq4D1tvPzPHLftWljsVaL2pjg_?usp=sharing) -- if the link is broken or something is not working properly, please raise an issue in the repository. This file is the result of some additional processing on top of the from Wireless InSite output files, check [here](extra/parsing) if you'd like to know more details.\n\n\n## Experiments\n\n### Configuration\n\nAll experiments steps are controled by the *configuration file*, a `.yaml` file with all the options for the desired experiment.\nI recommend the creation of a new configuration file for each experiment, and a few examples are available [here](examples/).\nThese examples can reproduce the results of [this](#citation) paper, and the available options are either self-explainatory,\nor have plenty of comments in the file.\n\n\n### Tracking\n\nThe use of a tracking or a non-tracking dataset is entirely defined by the model architecture, defined in the `model_type` option in the configuration file (`lstm` and `tcn` are the tracking options). A non-tracking dataset will be built from noisy instances of each position's data. On the other hand, the tracking dataset is first built by generating synthetic paths (as seen below), and then drawing noisy instances of the dataset for each position in a path.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"extra/repo_images/paths.PNG\" width=\"480\"/\u003e\n\u003c/p\u003e\n\n\n### Running an Experiment\n\nAssuming you have set a configuration file in `/path/to/config.yaml`, and the configuration file's `input_file` option contains the path to the downloaded `final_table`, these are the steps to fully run an experiment:\n\n```\npython3 bin/preprocess_dataset.py /path/to/config.yaml\npython3 bin/train_model.py /path/to/config.yaml\npython3 bin/test_model.py /path/to/config.yaml\n```\n\nThe last step ends with the key metrics being printed to your terminal. If you want to visualize additional results, you can use the visualization tools provided [here](/bff_positioning/visualization). E.g.:\n\n```\npython3 bff_positioning/visualization/plot_histogram.py /path/to/config.yaml\n```\n\nFor the settings defined in `examples/tcn_experiment.yaml`, the aforementioned set of commands should yield the following plot.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"extra/repo_images/histogram_tracking.PNG\" width=\"480\"/\u003e\n\u003c/p\u003e\n\n*Note - If different sampling frequencies are desired, the original, text-based data (`CIR32_zip`) must be parsed again.*\n*Unfortunatelly, the archaic tool I built for that is written in C, and requires extra steps (see instructions [here](/extra/parsing)).*\n*The `final_table` file, available in the link to the used data, contains the output of that parsing for a sampling frequency of 20MHz.*\n\n\n### Evaluate performance on an Nvidia Jetson\n\nIf you wish to evaluate the performance (power consumption and throughput) of a model on an embedded system,\nthis sub-section is for you. The tools in this sub-section were designed for this repository, but can easily be\nmodified to work with any TF model on an Nvidia Jetson TX2 device.\n\nAssuming you have copied your experiment configuration file to `/path/to/config.yaml`, and that the corresponding\ntrained model is in the folder pointed by the aforementioned file, you can evaluate the model performance by running:\n\n```\nsudo python3 extra/jetson/jetson_performance.py /path/to/config.yaml\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"extra/repo_images/jetson.PNG\" width=\"480\"/\u003e\n\u003c/p\u003e\n\nThe script will print throughput-related information to the screen (right part of the image), and the power-related data\nwill be stored to `$HOME/monitor_results.txt` (left part of the image, where the values depict power in mW).\nIt is important that you run this script with `sudo`, as it might not be able to use the device GPU otherwise.\nThe image above contains results for the model in `examples/cnn_experiment.yaml`, which has an average energy\nconsumption of 1.196 mJ per position estimate.\n\nNOTE: The above was working as of commit [6220366](https://github.com/gante/mmWave-localization-learning/commit/6220366084fba85a0bc3dc8b0aff26ce875c0713), using CUDA 10 and TF 1.14.\nMeanwhile, I've lost access the machine, and can no longer confirm that the above works with the current code base.\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details\n\n\n## Acknowledgments\n\n* **Leonel Sousa** and **Gabriel Falcão**, my PhD supervisors;\n* **IST** and **INESC-ID**, who hosted my PhD;\n* **FCT**, who funded my PhD.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgante%2FmmWave-localization-learning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgante%2FmmWave-localization-learning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgante%2FmmWave-localization-learning/lists"}