<p align="center"> <a>
<img title="Virtual Scanner Logo" src="https://github.com/imr-framework/imr-framework.github.io/blob/master/img/portfolio/virtual-scanner.png" width="225">
</a></p>
<h1 align="center"> Virtual Scanner </h1> <br>
<img title="PyPulseq Badge" src="https://img.shields.io/badge/made%20using-pypulseq-brightgreen" width="100">
Virtual Scanner is an end-to-end hybrid Magnetic Resonance Imaging (MRI) simulator/console designed to be zero-footprint, modular, and supported by open-source standards.
This project is a winning response to the [ISMRM 2019 Junior Fellow Challenge (Africa)](https://www.ismrm.org/2019-junior-fellow-challenge/africa/), which poses the task of boosting accessibility to MRI training resources for underserved areas such as sub-Saharan Africa. We designed Virtual Scanner to help develop local expertise in these areas so that sustained deployment of MRI hardware is possible. Importantly, Virtual Scanner will be continually developed as a research tool that provides functionalities for simulating and prototyping MRI acquisition methods as well as services for sharing computational methods and resources with researchers around the world. Please read our publication in the journal of open souce software [here](https://joss.theoj.org/papers/10.21105/joss.01637).
Virtual Scanner consists of two modes: in Standard Mode, a console-like GUI allows users to perform virtual scans and conduct basic analysis; in Advanced Mode, modular simulation/analysis of the entire signal chain may be performed.
## Quick Start
If you just want to get started with using Virtual Scanner:
1. Install Python 3.6.x.
2. Create and activate a virtual environment of your choice.
3. In your terminal: `pip install virtual-scanner`, and finally,
4. In macOS, run the command: `virtualscanner`; in Windows, run this longer command within the main folder where you created your virtual environment: `python Lib/site-packages/virtualscanner/coms/coms_ui/coms_server_flask.py`
The browser application should have started running. To access the browser app, there are two ways:
* Local hosting (only on the laptop running the script): go to the generated link (http://0.0.0.0:5000/) if you are a mac user, and this link (http://127.0.0.1:5000) if you are a windows user.
* Remote hosting : look up your IP address. Suppose it's 123.45.67.890, then you can go to (http://123.45.67.890:5000) to connect to the server remotely, either on the serving machine or different machines on the same network.
Now you can start playing with Virtual Scanner! Log in with your email address, select Standard or Advanced mode, and click "Begin Scan". Instructions for each tab are given in the [Wiki](https://github.com/imr-framework/virtual-scanner/wiki).
## Docker Start
This would be a good solution if you don't want to install the large number of dependencies to your host. We have tested Docker on Windows and Mac.
If you use a Windows 10 Pro system, first download Docker desktop and then run the following in the command line:
```bash
$ docker run -p 5000:5000 imrframework/virtual-scanner:latest
```
This downloads the pre-built image from Docker. You can then open up your browser to [127.0.0.1:5000](127.0.0.1:5000) to see the interface.
If you use a Windows 10 Home system, please use an alternate approach (clone the repository or pip install) because Docker isn't supported on this system and we have not succeeded in using the image with Docker Toolbox.
If you use a Mac, you can either download the image as described above or you can locally build a Docker container to run the application in the following way:
First, build the container from the [Dockerfile](Dockerfile):
```bash
$ docker build -t virtualscanner .
```
Then you can run the container and bind port 5000 to expose the application to the host:
```bash
$ docker run -p 5000:5000 virtualscanner
```
And open up your browser to [0.0.0.0:5000](0.0.0.0:5000)to see the interface.
The container is **not intended** for a production deployment, but rather is appropriate for local usage.
## Pro Start
If you want to hack around with the code:
1. Install Python 3.6.x.
2. Create and activate a virtual environment of your choice. Here's a [tutorial][pycharm-venv] if you are using the
PyCharm IDE, for example.
3. Clone the repo and `cd` into it.
4. `pip install -e .`.
5. Open the repo in your favourite IDE, hack around with the code.
6. Run `virtualscanner/coms/coms_ui/coms_server_flask.py` to run your changes.
Read the API documentation [here](https://imr-framework.github.io/virtual-scanner/) and run the Python test scripts in each module with more options available than allowed on the GUI.
## Standard Mode
* The **Register** page allows you to choose a phantom for simulation. Its format is similar to the form for entering information of the subject when conducting real scans. Choose the "Numerical" phantom for all simulations now.
* The **Acquire** page allows the user to choose either a Gradient Echo (GRE) or a Spin Echo (SE, with optional inversion recovery) sequence, enter the parameters, and simulate them on a cylindrical phantom ("Numerical") containing spheres with different T1, T2, and PD values.
* The **Analyze** page allows the user to load a series of data acquired in ISMRM/NIST phantom for T1 or T2 mapping and conduct curve fitting to obtain T1 and T2 maps. In addition, it can detect spheres in the phantom, a feature useful for comparing generated parameter values to literature values.
## Advanced Mode
* The **Tx** (RF transmit) page allows one to calculate and plot SAR from pulseq .seq files. *This feature is under development.*
* The **Rx** (RF receive) page allows one to visualize time-domain MR signal, generated from an arbitrary grayscale image, and see the effects of using different demodulation frequencies and ADC sampling rate. *This feature is under development.*
* Other features, including phantom and sequence viewers and reconstruction methods, are in active development.
## Known Issues
Please refer to the [Known Issues](https://github.com/imr-framework/virtual-scanner/blob/master/KNOWN_ISSUES.md) document.
## Contributing
If you would like to contribute to Virtual Scanner, please take a look at the [Community Guidelines](https://github.com/imr-framework/virtual-scanner/blob/master/CONTRIBUTING.md) document.
[pycharm-venv]: https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html
Raw data
{
"_id": null,
"home_page": "https://github.com/imr-framework/virtual-scanner",
"name": "virtual-scanner",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "imr-framework",
"author_email": "imr.framework2018@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/56/37/3a1e6121107ba2050222e6c28d2070bac5a282eb003d2057eb733719ce2a/virtual-scanner-2.0.0.post5.tar.gz",
"platform": null,
"description": "<p align=\"center\"> <a>\n<img title=\"Virtual Scanner Logo\" src=\"https://github.com/imr-framework/imr-framework.github.io/blob/master/img/portfolio/virtual-scanner.png\" width=\"225\">\n</a></p>\n<h1 align=\"center\"> Virtual Scanner </h1> <br>\n\n<img title=\"PyPulseq Badge\" src=\"https://img.shields.io/badge/made%20using-pypulseq-brightgreen\" width=\"100\">\n\n\nVirtual Scanner is an end-to-end hybrid Magnetic Resonance Imaging (MRI) simulator/console designed to be zero-footprint, modular, and supported by open-source standards.\n\nThis project is a winning response to the [ISMRM 2019 Junior Fellow Challenge (Africa)](https://www.ismrm.org/2019-junior-fellow-challenge/africa/), which poses the task of boosting accessibility to MRI training resources for underserved areas such as sub-Saharan Africa. We designed Virtual Scanner to help develop local expertise in these areas so that sustained deployment of MRI hardware is possible. Importantly, Virtual Scanner will be continually developed as a research tool that provides functionalities for simulating and prototyping MRI acquisition methods as well as services for sharing computational methods and resources with researchers around the world. Please read our publication in the journal of open souce software [here](https://joss.theoj.org/papers/10.21105/joss.01637).\n\nVirtual Scanner consists of two modes: in Standard Mode, a console-like GUI allows users to perform virtual scans and conduct basic analysis; in Advanced Mode, modular simulation/analysis of the entire signal chain may be performed. \n\n## Quick Start\nIf you just want to get started with using Virtual Scanner:\n1. Install Python 3.6.x.\n2. Create and activate a virtual environment of your choice.\n3. In your terminal: `pip install virtual-scanner`, and finally,\n4. In macOS, run the command: `virtualscanner`; in Windows, run this longer command within the main folder where you created your virtual environment: `python Lib/site-packages/virtualscanner/coms/coms_ui/coms_server_flask.py`\n\nThe browser application should have started running. To access the browser app, there are two ways:\n* Local hosting (only on the laptop running the script): go to the generated link (http://0.0.0.0:5000/) if you are a mac user, and this link (http://127.0.0.1:5000) if you are a windows user. \n* Remote hosting : look up your IP address. Suppose it's 123.45.67.890, then you can go to (http://123.45.67.890:5000) to connect to the server remotely, either on the serving machine or different machines on the same network.\n\nNow you can start playing with Virtual Scanner! Log in with your email address, select Standard or Advanced mode, and click \"Begin Scan\". Instructions for each tab are given in the [Wiki](https://github.com/imr-framework/virtual-scanner/wiki).\n\n## Docker Start\nThis would be a good solution if you don't want to install the large number of dependencies to your host. We have tested Docker on Windows and Mac.\n\nIf you use a Windows 10 Pro system, first download Docker desktop and then run the following in the command line:\n\n```bash\n$ docker run -p 5000:5000 imrframework/virtual-scanner:latest\n```\n\nThis downloads the pre-built image from Docker. You can then open up your browser to [127.0.0.1:5000](127.0.0.1:5000) to see the interface. \n\nIf you use a Windows 10 Home system, please use an alternate approach (clone the repository or pip install) because Docker isn't supported on this system and we have not succeeded in using the image with Docker Toolbox. \n\nIf you use a Mac, you can either download the image as described above or you can locally build a Docker container to run the application in the following way:\n\nFirst, build the container from the [Dockerfile](Dockerfile):\n\n```bash\n$ docker build -t virtualscanner .\n```\n\nThen you can run the container and bind port 5000 to expose the application to the host:\n\n```bash\n$ docker run -p 5000:5000 virtualscanner\n```\n\nAnd open up your browser to [0.0.0.0:5000](0.0.0.0:5000)to see the interface.\nThe container is **not intended** for a production deployment, but rather is appropriate for local usage.\n\n\n## Pro Start\nIf you want to hack around with the code:\n1. Install Python 3.6.x.\n2. Create and activate a virtual environment of your choice. Here's a [tutorial][pycharm-venv] if you are using the \nPyCharm IDE, for example.\n3. Clone the repo and `cd` into it.\n4. `pip install -e .`.\n5. Open the repo in your favourite IDE, hack around with the code.\n6. Run `virtualscanner/coms/coms_ui/coms_server_flask.py` to run your changes.\n\nRead the API documentation [here](https://imr-framework.github.io/virtual-scanner/) and run the Python test scripts in each module with more options available than allowed on the GUI.\n\n## Standard Mode\n* The **Register** page allows you to choose a phantom for simulation. Its format is similar to the form for entering information of the subject when conducting real scans. Choose the \"Numerical\" phantom for all simulations now.\n\n* The **Acquire** page allows the user to choose either a Gradient Echo (GRE) or a Spin Echo (SE, with optional inversion recovery) sequence, enter the parameters, and simulate them on a cylindrical phantom (\"Numerical\") containing spheres with different T1, T2, and PD values.\n\n* The **Analyze** page allows the user to load a series of data acquired in ISMRM/NIST phantom for T1 or T2 mapping and conduct curve fitting to obtain T1 and T2 maps. In addition, it can detect spheres in the phantom, a feature useful for comparing generated parameter values to literature values.\n\n## Advanced Mode\n* The **Tx** (RF transmit) page allows one to calculate and plot SAR from pulseq .seq files. *This feature is under development.*\n\n* The **Rx** (RF receive) page allows one to visualize time-domain MR signal, generated from an arbitrary grayscale image, and see the effects of using different demodulation frequencies and ADC sampling rate. *This feature is under development.*\n\n* Other features, including phantom and sequence viewers and reconstruction methods, are in active development.\n\n## Known Issues\nPlease refer to the [Known Issues](https://github.com/imr-framework/virtual-scanner/blob/master/KNOWN_ISSUES.md) document.\n\n## Contributing\nIf you would like to contribute to Virtual Scanner, please take a look at the [Community Guidelines](https://github.com/imr-framework/virtual-scanner/blob/master/CONTRIBUTING.md) document.\n\n[pycharm-venv]: https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html\n",
"bugtrack_url": null,
"license": "License :: OSI Approved :: GNU Affero General Public License v3",
"summary": "Virtual Scanner educational tool for MRI",
"version": "2.0.0.post5",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5800b540bab88afdd28e0351a98bc01d03f18faefde4e1a6b6a0088aea239106",
"md5": "a8f64e7cc0304f4c202d797ba497098f",
"sha256": "d52caf7c2a1f225e286ac61cb75cad0ed5f40042595e6abe4a62497a0aae704f"
},
"downloads": -1,
"filename": "virtual_scanner-2.0.0.post5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8f64e7cc0304f4c202d797ba497098f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 2748799,
"upload_time": "2022-09-29T22:42:28",
"upload_time_iso_8601": "2022-09-29T22:42:28.908062Z",
"url": "https://files.pythonhosted.org/packages/58/00/b540bab88afdd28e0351a98bc01d03f18faefde4e1a6b6a0088aea239106/virtual_scanner-2.0.0.post5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "56373a1e6121107ba2050222e6c28d2070bac5a282eb003d2057eb733719ce2a",
"md5": "65bf3fc238e6a7ba2535d8d34d431649",
"sha256": "ad9063bb158c85a1304ee37a813f5ea3c5787664d0f6284639251be4869abe20"
},
"downloads": -1,
"filename": "virtual-scanner-2.0.0.post5.tar.gz",
"has_sig": false,
"md5_digest": "65bf3fc238e6a7ba2535d8d34d431649",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2655292,
"upload_time": "2022-09-29T22:42:34",
"upload_time_iso_8601": "2022-09-29T22:42:34.699854Z",
"url": "https://files.pythonhosted.org/packages/56/37/3a1e6121107ba2050222e6c28d2070bac5a282eb003d2057eb733719ce2a/virtual-scanner-2.0.0.post5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-09-29 22:42:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "imr-framework",
"github_project": "virtual-scanner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "absl-py",
"specs": [
[
"==",
"0.7.1"
]
]
},
{
"name": "astor",
"specs": [
[
"==",
"0.7.1"
]
]
},
{
"name": "Click",
"specs": [
[
"==",
"7.0"
]
]
},
{
"name": "cycler",
"specs": [
[
"==",
"0.10.0"
]
]
},
{
"name": "Flask",
"specs": [
[
"==",
"1.0.2"
]
]
},
{
"name": "gast",
"specs": [
[
"==",
"0.2.2"
]
]
},
{
"name": "grpcio",
"specs": [
[
"==",
"1.20.0"
]
]
},
{
"name": "h5py",
"specs": [
[
"==",
"2.9.0"
]
]
},
{
"name": "itsdangerous",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"==",
"2.10.1"
]
]
},
{
"name": "Keras",
"specs": [
[
"==",
"2.2.4"
]
]
},
{
"name": "Keras-Applications",
"specs": [
[
">=",
"1.0.7"
]
]
},
{
"name": "Keras-Preprocessing",
"specs": [
[
"==",
"1.0.9"
]
]
},
{
"name": "kiwisolver",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "Markdown",
"specs": [
[
"==",
"3.1"
]
]
},
{
"name": "MarkupSafe",
"specs": [
[
"==",
"1.1.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.3.4"
]
]
},
{
"name": "mock",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "nibabel",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.16.2"
]
]
},
{
"name": "opencv-python",
"specs": [
[
"==",
"4.0.0.21"
]
]
},
{
"name": "pbr",
"specs": [
[
"==",
"5.1.3"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "protobuf",
"specs": [
[
"==",
"3.7.1"
]
]
},
{
"name": "pydicom",
"specs": [
[
"==",
"1.2.2"
]
]
},
{
"name": "pyparsing",
"specs": [
[
"==",
"2.3.1"
]
]
},
{
"name": "pypulseq",
"specs": [
[
"==",
"1.3.1.post1"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"5.1"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.2.1"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.12.0"
]
]
},
{
"name": "tensorboard",
"specs": [
[
">=",
"1.13.1"
]
]
},
{
"name": "tensorflow",
"specs": [
[
"==",
"1.15.2"
]
]
},
{
"name": "tensorflow-estimator",
"specs": [
[
">=",
"1.13.0"
]
]
},
{
"name": "termcolor",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "Werkzeug",
"specs": [
[
"==",
"0.15.2"
]
]
},
{
"name": "scikit-image",
"specs": [
[
"==",
"0.15.0"
]
]
},
{
"name": "h5py",
"specs": [
[
"==",
"2.9.0"
]
]
},
{
"name": "selenium",
"specs": [
[
"==",
"3.141.0"
]
]
}
],
"lcname": "virtual-scanner"
}
JSON
