pulse2percept

A Python-based simulation framework for bionic vision

https://github.com/pulse2percept/pulse2percept

Keywords

Keywords from Contributors

Repository

A Python-based simulation framework for bionic vision

README.rst

.. image:: https://img.shields.io/badge/DOI-10.25080/shinma--7f4c6e7--00c-blue
   :target: https://doi.org/10.25080/shinma-7f4c6e7-00c
   :alt: DOI

.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
   :target: https://github.com/pulse2percept/pulse2percept/blob/master/LICENSE
   :alt: BSD 3-clause

.. image:: https://img.shields.io/pypi/v/pulse2percept.svg
   :target: https://pypi.org/project/pulse2percept
   :alt: PyPI

.. image:: https://github.com/pulse2percept/pulse2percept/actions/workflows/build.yml/badge.svg
   :target: https://github.com/pulse2percept/pulse2percept/actions
   :alt: build

.. image:: https://img.shields.io/github/forks/pulse2percept/pulse2percept?style=social
   :target: https://github.com/pulse2percept/pulse2percept/network/members
   :alt: GitHub forks

.. image:: https://img.shields.io/github/stars/pulse2percept/pulse2percept?style=social
   :target: https://github.com/pulse2percept/pulse2percept/stargazers
   :alt: GitHub stars

====================================================================
pulse2percept: A Python-based simulation framework for bionic vision
====================================================================

Globally, an estimated 43 million people are blind, with limited treatment 
options available for many causes of vision loss. For certain conditions, 
visual neuroprostheses - such as retinal and cortical implants - may be the
only viable intervention.

However, understanding the perceptual experience generated by these devices 
remains a significant challenge. The artificial vision they provide is 
shaped by complex interactions between neural stimulation, underlying 
neurophysiology, and device-specific parameters.

`pulse2percept`_ (p2p) is an open-source Python package that offers 
spatiotemporal models of common `retinal and cortical implants`_, 
providing a computational framework to simulate and study artificial 
vision.

.. _pulse2percept: https://github.com/pulse2percept/pulse2percept
.. _retinal and cortical implants: https://en.wikipedia.org/wiki/Visual_prosthesis

.. image:: https://raw.githubusercontent.com/pulse2percept/pulse2percept/master/doc/_static/boston-train-combined.gif
   :align: center
   :alt: Input stimulus and predicted percept

*(left: input stimulus, right: predicted percept)*

Simulations such as the above are likely to be critical for providing realistic
estimates of prosthetic vision, thus providing regulatory bodies with guidance
into  what sort of visual tests are appropriate for evaluating prosthetic
performance, and improving current and future technology.

If you use p2p in a scholarly publication, please cite as:

.. epigraph::

    M Beyeler, GM Boynton, I Fine, A Rokem (2017). pulse2percept: A
    Python-based simulation framework for bionic vision. *Proceedings of the
    16th Python in Science Conference (SciPy)*, p.81-88,
    doi:`10.25080/shinma-7f4c6e7-00c `_.

Installation
============

Once you have Python 3.9 or later, you can install the `stable release`_ 
of p2p using:

.. code-block:: bash

    pip install pulse2percept

We provide prebuilt wheels for recent versions of macOS (e.g., macOS 14), 
Linux (e.g., Ubuntu 24.04 LTS), and Windows (e.g., Windows Server 2022). 
You can find the full documentation
`here `_.

.. _stable release: https://pulse2percept.readthedocs.io/en/stable/index.html

Compatibility and Building from Source
--------------------------------------

While other platforms are not explicitly supported, you may still be able to run 
p2p with minimal modifications. If ``pip`` does not find a prebuilt wheel for 
your system, it will attempt to install from source.

.. note::

   Building from source requires NumPy and Cython. On Windows, this includes
   `Visual Studio Build Tools`_.

Supported Python versions:

+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
|        Python        | 3.13 | 3.12 | 3.11 | 3.10 | 3.9 | 3.8 | 3.7 | 3.6 | 3.5 |
+======================+======+======+======+======+=====+=====+=====+=====+=====+
| p2p 0.10             | Yes  | Yes  | Yes  | Yes  |     |     |     |     |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.9              |      | Yes  | Yes  | Yes  | Yes |     |     |     |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.8              |      |      |      | Yes  | Yes | Yes | Yes |     |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.7              |      |      |      |      | Yes | Yes | Yes | Yes |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.6              |      |      |      |      |     | Yes | Yes | Yes | Yes |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+

Our `GitHub Action Runners`_ ensure that p2p works as expected on macOS 14 Arm64,
Ubuntu 24.04, and Windows Server 2022.

.. _Visual Studio Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
.. _GitHub Action Runners: https://github.com/pulse2percept/pulse2percept/actions

Upgrading and Uninstalling
--------------------------

To upgrade p2p to the latest stable version:

.. code-block:: bash

    pip install -U pulse2percept

To uninstall:

.. code-block:: bash

    pip uninstall pulse2percept -y

Installing the Bleeding-Edge Version
------------------------------------

If you want to install the `latest development version`_ from source, first
ensure that you have **NumPy and Cython** installed.
On Windows, you will also need Visual Studio Build Tools.
Then run:

.. code-block:: bash

    pip install git+https://github.com/pulse2percept/pulse2percept

For more details, see our `Installation Guide`_.

If you encounter issues, check our `Issue Tracker`_ on GitHub for solutions
or contribute fixes for unsupported platforms.

.. _latest development version: https://pulse2percept.readthedocs.io/en/latest/index.html
.. _Installation Guide: https://pulse2percept.readthedocs.io/en/stable/install.html
.. _Issue Tracker: https://github.com/pulse2percept/pulse2percept/issues

Where to go from here
=====================

*  Have a look at some code examples from our `Example Gallery`_.
*  Familiarize yourself with `visual implants`_, `electrical stimuli`_,
   and our `computational models`_.
*  Check the `FAQ`_ to see if your question has already been answered.
*  Request features or report bugs in our on 
   `GitHub `_.

.. _Example Gallery: https://pulse2percept.readthedocs.io/en/latest/examples/index.html
.. _visual implants: https://pulse2percept.readthedocs.io/en/latest/topics/implants.html
.. _electrical stimuli: https://pulse2percept.readthedocs.io/en/latest/topics/stimuli.html
.. _computational models: https://pulse2percept.readthedocs.io/en/latest/topics/models.html
.. _FAQ: https://pulse2percept.readthedocs.io/en/latest/users/faq.html
.. _Issue Tracker: https://github.com/pulse2percept/pulse2percept/issues

Owner

GitHub Events

Committers

Last synced: over 2 years ago

Issues and Pull Requests

Last synced: 6 months ago

Packages