Introduction to OMERO.scripts ============================= OMERO.scripts are the OME version of plugins, allowing you to extend the functionality of your OMERO installation. The OMERO scripting service allows scripts to be uploaded to the server so that image processing and analysis, and other functionality, can be carried out there rather than on your local machine. Scripts are generally written in Python, but other languages are also supported, like Jython. MATLAB scripts are supported natively as well as via a Python wrapper as described in :doc:`matlab-scripts`. Scripts can be run from the OMERO clients, using a UI generated from the script and the results should also be handled where relevant e.g. allowing users to view OMERO Images or Datasets created by the script, or download files or images. .. figure:: /images/omero-scripting-context.png :align: center :alt: OMERO script context menu Scripts menu in OMERO.insight .. figure:: /images/scriptActivity.png :align: center :alt: Scripts Running and completed Running a script from an OMERO client .. figure:: /images/scriptUI.png :align: center :alt: Scripts user interface A script user interface Finding scripts --------------- `Core scripts `_ are bundled with every OMERO.server release and automatically available to all users. You can find additional scripts on GitHub by looking for forks of `ome/omero-user-scripts `_. Some examples include: - `OMERO scripts `_ - Glencoe Software - `Example scripts `_ - OME Team - `Fixing scripts `_ - Pierre Pouchin - `GDSC OMERO user scripts `_ - Alex Herbert - `QBI-Microscopy scripts `_ - Queensland Brain Institute - `OMEROscripts `_ - Damir Sudar All of the included scripts and repositories can be downloaded following the instructions below in order to run the scripts locally (although some of them are intended as examples only—check the associated README). Downloading and installing scripts ---------------------------------- The easiest way to make use of scripts is for someone with admin rights to upload them to the OMERO.server as described in the :doc:`user-guide`. Once a script has been added under the lib/scripts directory, you can run them from the OMERO clients or the command line. However, you will not be notified of any updates to the script, nor will you be able to automatically update them. This means that when your OMERO installation is upgraded, all your additional scripts will be lost. To keep your scripts up to date, we recommend you use a Github repository to manage your scripts. If you are not familiar with :devs_doc:`using git `, you can use the `GitHub app for your OS `_ (available for Mac and Windows but not Linux). The basic workflow is: - fork our `omero-user-script `_ repository or any other repository you trust (``_) - clone it in your lib/scripts directory :: cd lib/scripts git clone git@github.com:YOURGITUSERNAME/omero-user-scripts.git YOUR_SCRIPTS - save the scripts you want to use into the appropriate sub-directory in your cloned location lib/scripts/YOUR_SCRIPTS If all you want to do is add scripts from someone else's repository to your server, you can simply clone that repository in your lib/scripts directory and the scripts within it will be added to your script list as described in the `OMERO-user-script repository readme `_. As your new scripts will then show up in the script menu in the clients, alongside the core 'omero' scripts which are shipped with each release, you should try to pick unique names to avoid future clashes e.g. Custom_Scripts/Search_Scripts/original_metadata_search.py: .. figure:: /images/omero-user-script-menu.png :align: center :alt: OMERO.web script menu Custom scripts in OMERO.web menu The OME developers use Github to co-ordinate all our development work so joining the network will help you access help and support, and see what other people are doing with scripts. Cloning our repository also means you have an example script to get you started with developing your own. Developing your own scripts --------------------------- The easiest way to get started developing scripts for your own site is to fork the `github.com/ome/omero-user-scripts `_ repository and clone it somewhere under lib/scripts as described above. Then go into YOUR_SCRIPTS and rename the existing script to match your needs:: cd lib/scripts/YOUR_SCRIPTS git mv Example.py util_scripts/New_function.py Once you have done that, you can edit and test run the script and then when you are happy with it, you can save it and push it back to your fork for others to see and share. :doc:`user-guide` describes the workflows for developing and running your own scripts. You should use the :doc:`style-guide` to ensure your script interacts with the OMERO clients in a usable way. Contributing back to the community ---------------------------------- If you have modified one of the core scripts or developed your own that you would like to contribute back to the community, please get in touch. If the script is likely to have wide appeal, we can look into adding it to the core scripts that are distributed with an OMERO release. .. seealso:: :doc:`user-guide`, :doc:`style-guide`, :doc:`advanced` and :doc:`matlab-scripts`