README.rst
SnappySonic
===============================
.. image:: https://github.com/SciKit-Surgery/snappysonic/raw/master/snappysonic.gif
:height: 134px
:target: https://github.com/SciKit-Surgery/snappysonic
:alt: Logo
|
.. image:: https://github.com/SciKit-Surgery/snappysonic/workflows/.github/workflows/ci.yml/badge.svg
:target: https://github.com/SciKit-Surgery/snappysonic/actions
:alt: GitHub Actions CI status
.. image:: https://coveralls.io/repos/github/SciKit-Surgery/snappysonic/badge.svg?branch=master&service=github
:target: https://coveralls.io/github/SciKit-Surgery/snappysonic?branch=master
:alt: Test coverage
.. image:: https://readthedocs.org/projects/snappysonic/badge/?version=latest
:target: http://snappysonic.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://img.shields.io/badge/DOI-10.5334%2Fjors.289-blue
:target: http://doi.org/10.5334/jors.289
:alt: The SnappySonic Paper
.. image:: https://api.codeclimate.com/v1/badges/78440062319f61c55177/maintainability
:target: https://codeclimate.com/github/SciKit-Surgery/snappysonic/maintainability
:alt: Maintainability
.. image:: https://img.shields.io/badge/-Video%20Tutorial-blueviolet?style=flat&logo=youtube
:target: https://www.youtube.com/watch?v=BI4qyg9NEOk
:alt: Tutorial on YouTube
.. image:: https://img.shields.io/twitter/follow/scikit_surgery?style=social
:target: https://twitter.com/scikit_surgery?ref_src=twsrc%5Etfw
:alt: Follow scikit_surgery on twitter
Author: Stephen Thompson
SnappySonic can be used as an ultrasound acquisition simulator. The output from a tracking system (NDI or AruCo tags) is to select a frame of pre-recorded video to show. A suitable video of ultrasound data is included in the data directory, however the user can select a video of their choosing. The software and its use is described in the `SnappySonic paper`_.
SnappySonic is part of the `SciKit-Surgery`_ software project, developed at the `Wellcome EPSRC Centre for Interventional and Surgical Sciences`_, part of `University College London (UCL)`_.
SnappySonic supports Python 3.6.
::
pip install snappysonic
python snappysonic.py --config config.json
The config file defines the tracking parameters and image buffer, e.g.
::
{
"ultrasound buffer": "data/usbuffer.mp4",
"buffer descriptions": [
{
"name": "glove",
"start frame": 0,
"end frame": 284,
"x0": 20, "x1": 200,
"y0": 200, "y1": 260,
"scan direction": "x"
},
]
....
"tracker config": {
"tracker type": "aruco",
"video source": 2,
"debug": true,
"capture properties": {
"CAP_PROP_FRAME_WIDTH": 640,
"CAP_PROP_FRAME_HEIGHT": 480
}
}
An example configuration file can be downloaded from `here`_ and an image buffer from `source code repository data directory`_
Developing
----------
Cloning
^^^^^^^
You can clone the repository using the following command:
::
git clone https://github.com/SciKit-Surgery/snappysonic
Running tests
^^^^^^^^^^^^^
Unit tests are performed in stand alone environments using tox, which also checks coding style.
::
tox
Installing
----------
You can pip install from pypi with
::
pip install snappysonic
or You can pip install directly from the repository as follows:
::
pip install git+https://github.com/SciKit-Surgery/snappysonic
How to Cite
-----------
If you use this software in your research or teaching, please cite:
Thompson, S., Dowrick, T., Xiao, G., Ramalhinho, J., Robu, M., Ahmad, M., Taylor, D. and Clarkson, M.J., 2020. SnappySonic: An Ultrasound Acquisition Replay Simulator. Journal of Open Research Software, 8(1), p.8. DOI: http://doi.org/10.5334/jors.289
Contributing
^^^^^^^^^^^^
Please see the `contributing guidelines`_.
Useful links
^^^^^^^^^^^^
* `Source code repository`_
* `Documentation`_
Licensing and copyright
-----------------------
Copyright 2019 University College London.
snappysonic is released under the BSD-3 license. Please see the `license file`_ for details.
Acknowledgements
----------------
Supported by `Wellcome`_ and `EPSRC`_.
.. _`Wellcome EPSRC Centre for Interventional and Surgical Sciences`: http://www.ucl.ac.uk/weiss
.. _`source code repository`: https://github.com/SciKit-Surgery/snappysonic
.. _`here`: https://github.com/SciKit-Surgery/snappysonic/blob/master/config.json
.. _`source code repository data directory`: https://github.com/SciKit-Surgery/snappysonic/blob/master/data
.. _`Documentation`: https://snappysonic.readthedocs.io
.. _`SciKit-Surgery`: https://github.com/SciKit-Surgery
.. _`University College London (UCL)`: http://www.ucl.ac.uk/
.. _`Wellcome`: https://wellcome.ac.uk/
.. _`EPSRC`: https://www.epsrc.ac.uk/
.. _`contributing guidelines`: https://github.com/SciKit-Surgery/snappysonic/blob/master/CONTRIBUTING.rst
.. _`license file`: https://github.com/SciKit-Surgery/snappysonic/blob/master/LICENSE
.. _`SnappySonic paper`: http://doi.org/10.5334/jors.289