Merge pull request #15 from imr-framework/ISMRM2019

Release 1.0.0

.gitignore

@@ -1,104 +1,120 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-.hypothesis/
-.pytest_cache/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# database
+.db
+
+# Work in progress code
+src_working/
+
+# PyCharm idea files
+\.idea/
+/.idea/
+
+serverlog\.txt
+
+src/server/registration/subject\.db
+
+\.DS_Store

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to Virtual-Scanner
+:thumbsup: :tada: First off, thanks for taking time to contribute! :thumbsup: :tada:
+
+The following is a set of guidelines for contributing to Virtual-Scanner. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+## Table of contents
+1. [Code of Conduct](#code-of-conduct)
+2. [PEP Style Guide for Python coding](#style-guide-for-python-code)
+3. [Source code header](#source-code-header)
+
+## Code of Conduct
+This project and everyone participating in it is governed by the [Virtual-Scanner Code of Conduct](https://github.com/imr-framework/Virtual-Scanner/blob/ISMRM2019/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to imr.framework2018@github.com.
+
+## Style Guide for Python Code
+Read through the [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/) and follow the coding conventions. If you notice any of Virtual-Scanner's code not adhering to PEP8, submit a pull request or open an issue.
+
+## Source code header
+Insert and fill out the following header comments at the top of every script in your source code:
+```
+Institution : (your university/research facility)
+Version : 1.0.0 
+```
+Note that "Version" refers to the Virtual Scanner release you developed your code on. You can add more fields if needed. 
+
+## Documenting source code
+Please add a top-level description of code functionality in each script. In addition, document every class and method in your source code using the [Numpy docstring guide](https://numpydoc.readthedocs.io/en/latest/format.html). An example is shown below.
+
+```python
+def addition(a, b):
+  """
+  Addition of two numbers.
+  
+  Parameters
+  ----------
+  a : int, float
+    Operand 1
+  b : int, float
+    Operand 2
+    
+  Returns
+  -------
+  Arthimetic sum of operand 1 and operand 2.
+  """
+  return a + b
+```

MANIFEST.in

@@ -0,0 +1,8 @@
+# Include front-end assets
+recursive-include virtualscanner/coms/coms_ui *.*
+
+# DRUNCK Recon
+# Exclude Keras model
+global-exclude virtualscanner/server/recon/drunck/assets *.hdf5
+# Include unit test assets
+include virtualscanner/server/recon/drunck/assets *.jpg

Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+SPHINXAPIDOC = sphinx-apidoc
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+

README.md

@@ -1,4 +1,47 @@
-# Virtual-Scanner
-An end-to-end hybrid MR simulator/console
+<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>
 
-Please find the detailed API documentation [here.](https://imr-framework.github.io/virtual-scanner/)
+Virtual Scanner is an end-to-end hybrid MR simulator/console designed to be easily accessible, modular, and supported by open-source standards. 
+
+The project is a response to the [ISMRM 2019 Junior Fellow Challenge (Africa)](https://www.ismrm.org/2019-junior-fellow-challenge/africa/).
+
+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 MR signal chain may be performed.  
+
+## Quick Start
+First, clone the repository. Make sure you have all packages listed in requirements.txt installed in your Virtual Environment.
+
+Then, run [`coms_server_flask.py`](https://github.com/imr-framework/virtual-scanner/blob/ISMRM2019/virtualscanner/coms/coms_ui/coms_server_flask.py) to start the browser GUI.
+
+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 server laptop or different ones connected to 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).
+
+Alternatively, you can 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. 
+
+## References
+
+Kose, R., & Kose, K. (2017). BlochSolver: a GPU-optimized fast 3D MRI simulator for experimentally compatible pulse sequences. Journal of Magnetic Resonance, 281, 51-65.
+
+Layton, K. J., Kroboth, S., Jia, F., Littin, S., Yu, H., Leupold, J., ... & Zaitsev, M. (2017). Pulseq: a rapid and hardware-independent pulse sequence prototyping framework. Magnetic resonance in medicine, 77(4), 1544-1552.

_build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 14fc5499e589c9041f99f1d6f3bd5787
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_build/_sources/docs/source/modules.rst.txt

@@ -0,0 +1,7 @@
+Virtual Scanner
+===============
+
+.. toctree::
+   :maxdepth: 4
+
+   virtualscanner

_build/_sources/docs/source/virtualscanner.coms.coms_ui.rst.txt

@@ -0,0 +1,19 @@
+virtualscanner.coms.coms\_ui
+============================
+Communications with front end
+
+coms\_server\_flask.py
+-------------------------------------------------------
+
+.. automodule:: virtualscanner.coms.coms_ui.coms_server_flask
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+coms\_ui.py
+---------------------------------------------------
+
+.. automodule:: virtualscanner.coms.coms_ui.utest_coms_ui
+   :members:
+   :undoc-members:
+   :show-inheritance:

_build/_sources/docs/source/virtualscanner.coms.rst.txt

@@ -0,0 +1,7 @@
+virtualscanner.coms
+===========================
+
+
+.. toctree::
+
+   virtualscanner.coms.coms_ui