diff --git a/Build/.gitignore b/Build/.gitignore new file mode 100644 index 0000000..72e8ffc --- /dev/null +++ b/Build/.gitignore @@ -0,0 +1 @@ +* diff --git a/README.md b/README.md index 6d6671b..a907468 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,18 @@ A tutorial on how to write a python module can be found below. Example modules c ### Compile from source code -The Plugin is organized so that it can be compiled as much as possible outside of the main open-ephys source tree. Under Linux, a symlink to the Source/Plugins directory is however necessary. +The Plugin is organized so that it can be compiled as much as possible outside of the main open-ephys source tree. A recent Python version is required. -The Plugin needs to link to a recent enough version of Python. Development work was done with a recent [Anaconda Python](https://www.continuum.io/why-anaconda) distribution, supporting python 3.5 to 3.7. Windows users must use python 3.6 (see below). +The Plugin needs to link to a recent enough version of Python. +Development work was done with a recent [Anaconda Python](https://www.continuum.io/why-anaconda) distribution, supporting python 3.5 to 3.8. +Windows users must use python 3.6 (see below). +Onlinux it also work with standard pip+virtualenv installation. + +Currently, only Cython version 0.28.2 is supported. +Recently downloaded or upgraded versions of Anaconda will come with version 0.29.2, +which will cause the application to crash upon loading a python module. +To avoid this, create a virtual enviroment with the correct versions of python and cython. See below. + To compile the plugin, extract in a folder just outside the Open Ephys plugin-GUI source tree e.g. @@ -24,54 +33,112 @@ etc... The rest of the procedure is system dependent -#### Linux +#### Linux with conda + +Example with python3.6 + +``` +conda create -n oeEnv python=3.6 +``` + +``` +source activate oeEnv +conda install cython=0.28.2 numpy +``` + + +``` +cd /home/XXXX/PythonPlugin/Build +make +make install +``` + +#### Linux with pip + virtualenv -The script `build-linux.sh` should detect the version and location of the python installation automatically. It will use the one of the executable that is at the top of the PATH, so make sure that the shell you are running it from is properly configured +Here a recipe that need to be adapted depending the virtual system. -Under Ubuntu 16.04 and later: -- with default python install. This comes by default without a proper `distutils` package, and without the Python development environment, to install those run +Here a working recipe with : **Unbutu 20.04 + python3.8 + plugin-GUI 0.5** + +Install system packge ``` sudo apt install python3-distutils sudo apt install python3-dev +sudo apt install virtualenvwrapper +sudo apt install gcc-8 g++-8 ``` -To compile the python modules you will need (at least) Cython and numpy which may be installed by +Create environement ``` -pip install cython -pip install numpy +mkvirtualenv --python=/usr/bin/python3.8 oeEnv ``` +Enter in env and update pip **(very important!!!)** +``` +workon oeEnv +# (or source /home/myusername/.virtualenvs/oeEnv/bin/activate) +pip install --upgarde pip +``` -- With Anaconda: everything should be detected automatically, so no further action is needed at compilation time. -To compile the python modules you will need Cython which may be installed by +And install package ``` -conda install cython numpy +pip install cython==0.28.2 +``` + +Build the C++ +gcc must forced to version 8 because due to juice the system have gcc-9 by default +``` +cd /home/myusername/path_to_oe/PythonPlugin/Build +export CC=gcc-8 && export CXX=g++-8 +export CONDA_HOME=/home/myusername/.virtualenvs/oeEnv +cmake -DPYTHON_PATH=/home/myusername/.virtualenvs/oeEnv/lib/python3.8/site-packages .. +make +make install ``` -or even better make your virtual environment with all the packages that are needed by your module. -- run `./build-linux.sh`. The Plugin should be compiled and copied to the neighboring plugin-GUI source tree. #### MacOSX -- With Anaconda: a detection script runs at compilation. Because the compilation environment gets evaluated by XCode before any of the build phases are run, you may need to build the project *twice*, the second time should succeed. If any XCode guru has a solution for that, that would be welcome. + +- With Anaconda: a detection script runs at compilation. Because the compilation environment gets evaluated +by XCode before any of the build phases are run, you may need to build the project *twice*, +the second time should succeed. If any XCode guru has a solution for that, that would be welcome. + #### Windows -- Install Anaconda, python3.6 ONLY (see compilation section), then add the required modules: -``` -conda install cython numpy -``` -- Copy the folder `PythonPlugin` to your plugin-GUI source tree under `Source\Plugins`. +**TODO : the following is not tested** + +- Install Anaconda, python3.6 ONLY (see compilation section) -- Copy the contents of `WindowsPlugin` to a new folder in your plugin-GUI source tree called `Builds\VisualStudio2013\Plugins\PythonPlugin`. -- Open the Plugins solution in Visual Studio and add the Python plugin by right-clicking the top-level solution in the Solution Explorer, selecting `Add > Existing Project`, and opening the `Python.vcxproj` project file that you just copied into the `PythonPlugin` build folder. -- If you created a virtual environment for Open Ephys (as suggested below) or installed Anaconda in somewhere other than the default (your home directory), you need to tell the plugin where your Python root is by setting the `CONDA_HOME` environment variable. Follow these steps: + + +If you created a virtual environment for Open Ephys (as suggested below) or installed Anaconda in somewhere other than the default (your home directory), you need to tell the plugin where your Python root is by setting the `CONDA_HOME` environment variable. Follow these steps: 1. From the Start menu, start typing "environment" and then select "Edit environment variables for your account" 2. Click "New..." to create a new variable. Enter `CONDA_HOME` as the name and the path to your Python 3.6 root folder as the value. For example, if you are using a conda environment called `oeEnv`, this would be something like `C:\Users\your_username\Anaconda3\envs\oeEnv`. Do _not_ use a trailing slash. Click OK twice to save. 3. Restart Visual Studio completely if you have it open. Open the Plugins solution and select Project > Rescan Solution to make sure the `PYTHON_HOME_NAME` macro gets updated. +``` +activate oeEnv +``` + +Install required modules: + +``` +conda install cython=0.28.2 numpy +``` + + +``` +cd c:\Users\myusername\path_to_oe\PythonPlugin\Build +cmake .. +make +make install +``` + + + ## Usage ### Create New Module Directory and Framework Code @@ -84,7 +151,8 @@ cd PythonPlugin/python_modules python generatePlugin.py YourPluginName ``` ### Modifying Template Code -- Place data to be held in RAM within the __init__(self) function. For example, if you want to hold an "electrodes" variable accessible by other functions in the class, initialize it as follows: +- Place data to be held in RAM within the __init__(self) function. For example, if you want to hold an "electrodes" + variable accessible by other functions in the class, initialize it as follows: ``` def __init__(self): """initialize object data""" @@ -92,7 +160,8 @@ def __init__(self): self.electrodes = 16 ``` -- The startup(self, sr) function is called after selecting the .so file. This allows for the sampling rate (sr) to be passed off to the python plugin. This is also a useful place to connect to an arduino (after importing the serial library), shown as follows: +- The startup(self, sr) function is called after selecting the .so file. This allows for the sampling rate (sr) + to be passed off to the python plugin. This is also a useful place to connect to an arduino (after importing the serial library), shown as follows: ``` def startup(self, sr): self.samplingRate = sr @@ -101,14 +170,19 @@ def startup(self, sr): print ("Arduino: ", self.arduino) ``` -- The params_config(self) functions allows for the python plugin to have various buttons and sliders. This allows for the module to be more dynamic. The following code shows how to create a toggle button: +- The params_config(self) functions allows for the python plugin to have various buttons and sliders. + This allows for the module to be more dynamic. The following code shows how to create a toggle button: ``` def param_config(self): """return button, sliders, etc to be present in the editor OE side""" return [("toggle", "Enabled", True)] ``` -- The bufferfunction(self,n_arr) function is where the voltage data comes in and events go out to the rest of the OE signal chain. The variable "n_arr" is a matrix of the voltage data, accessed as `n_arr[electode][sample]`. The function must return events, even if the events are empty. The following code shows how to send out an event if the minimum value in the buffer on electrode 12 is below a predefined threshold. +- The bufferfunction(self,n_arr) function is where the voltage data comes in and events go out to the + rest of the OE signal chain. The variable "n_arr" is a matrix of the voltage data, accessed + as `n_arr[electode][sample]`. The function must return events, even if the events are empty. + The following code shows how to send out an event if the minimum value in the buffer on electrode + 12 is below a predefined threshold. ``` def bufferfunction(self, n_arr): events = [] @@ -118,29 +192,44 @@ def bufferfunction(self, n_arr): return events ``` -- The handleEvents(eventType,sourceID,subProcessorIdx,timestamp,sourceIndex) function passes on events (but not spike events) generated elsewhere in the OE signal chain to the python plugin. The following code shows how to save the timestamps of these events. +- The handleEvents(eventType,sourceID,subProcessorIdx,timestamp,sourceIndex) function passes on events + (but not spike events) generated elsewhere in the OE signal chain to the python plugin. + The following code shows how to save the timestamps of these events. ``` def handleEvents(eventType,sourceID,subProcessorIdx,timestamp,sourceIndex): """handle events passed from OE""" self.eventBuffer.append(timestamp) ```` -- The handleSpike(self,electrode,sortedID,n_arr) function passes on spike events generated elsewhere in the OE signal chain to the python plugin. the n_arr is an 18 element long spike waveform. +- The handleSpike(self,electrode,sortedID,n_arr) function passes on spike events generated elsewhere + in the OE signal chain to the python plugin. the n_arr is an 18 element long spike waveform. + +### Compilation of a python plugin -### Compilation -Currently, only Cython version 0.28.2 is supported. Recently downloaded or upgraded versions of Anaconda will come with version 0.29.2, which will cause the application to crash upon loading a python module. To avoid this, create a virtual enviroment with the correct versions of python and cython by running: + +Be sure that you have a gcc version 8 ``` -conda create -n oeEnv python=3.6 cython=0.28.2 +export CC=gcc-8 && export CXX=g++-8 ``` + To activate the enviroment on Linux or Mac: ``` source activate oeEnv ``` -To activate the enviroment on Windows: + +or for virtualenvwrapper: +``` +workon oeEnv +``` + +or for windows: ``` activate oeEnv ``` + + + For more information on virtual enviroments, please click [here](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). - To compile the python module with cython, run setup.py in the module's directory (i.e. "YourPluginName/"). diff --git a/python_modules/.config.py b/python_modules/.config.py index 2c7c68a..ebabd1c 100644 --- a/python_modules/.config.py +++ b/python_modules/.config.py @@ -1,2 +1,2 @@ # Location of Python Plugin source (absolute or relative to the location of setup.py) -PYTHON_PLUGIN_SRC_DIR = "../../PythonPlugin" +PYTHON_PLUGIN_SRC_DIR = "../../Source"