OMERO.figure

An app for creating figures from images.

The app can be used standalone with OME-Zarr images or installed within OMERO.web to work with OMERO images.

The standalone app is available at https://ome.github.io/omero-figure/.

For full details see SUPPORT.md.

Requirements

• OMERO.web 5.6.0 or newer.

Installing from PyPI

This section assumes that an OMERO.web is already installed.

Install the app using pip:

NB: You need to ensure that you are running pip from the python environment where omero-web is installed. Depending on your install, you may need to call pip with, for example: /path/to_web_venv/venv/bin/pip install ...

$ pip install -U omero-figure

Add figure custom app to your installed web apps:

$ omero config append omero.web.apps '"omero_figure"'

Display a link to 'Figure' at the top of the webclient:

$ omero config append omero.web.ui.top_links '["Figure", "figure_index",
  {"title": "Open Figure in new tab", "target": "_blank"}]'

Add 'Figure' to the 'Open with' options, available from context menu on the webclient tree:

$ omero config append omero.web.open_with '["omero_figure", "new_figure",
  {"supported_objects":["images"], "target": "_blank", "label": "OMERO.figure"}]'

Optional: To change the maximum active channel count from the default of 10:

$ omero config set omero.figure.max_active_channels 15

Now restart OMERO.web as normal.

Enabling figure export from OMERO

This section assumes that an OMERO.server is already installed.

Figures can be exported as PDF or TIFF files using a script that runs on the OMERO.server. This script needs to be uploaded to the OMERO.server and its dependencies installed in the OMERO.server virtual environment.

The script can be uploaded using various workflows, all of which require you to have the correct admin privileges.

Option 1: Log in to the webclient as an Admin and open the OMERO.figure app. If the OMERO script is not found or is not up to date, you will see a warning message with a button to upload the script. Click the button to upload the script from the OMERO.figure app.

Option 2: Upload the script from the installation directory. To find where OMERO.figure has been installed using pip, run:

$ pip show omero-figure

The command will display the absolute path to the directory where the application is installed e.g. ~/<virtualenv_name>/lib/python3.6/site-packages. Go to that directory.

Connect to the OMERO server and upload the script via the CLI. It is important to be in the correct directory when uploading so that the script is uploaded with the full path: omero/figure_scripts/Figure_To_Pdf.py:

$ cd omero_figure/scripts
$ omero script upload omero/figure_scripts/Figure_To_Pdf.py --official

Option 3: Alternatively, before starting the OMERO.server, copy the script from the figure install /omero_figure/scripts/omero/figure_scripts/Figure_To_Pdf.py to the OMERO.server path/to/OMERO.server/lib/scripts/omero/figure_scripts. Then restart the OMERO.server.

Now install the script's dependencies:

• Install reportlab PDF python package. This needs to be installed in the virtual environment where the OMERO.server is installed. Depending on your install, you may need to call pip with, for example: /path/to_server_venv/venv/bin/pip install ...

$ pip install reportlab

• Optional: Figure legends can be formatted using Markdown syntax. To see this correctly in the exported PDF info page, we need Python Markdown:

$ pip install markdown

Run Figure export locally

If your figure contains only OME-Zarr images (no images from OMERO), then the export script can be run locally to convert a figure JSON file to PDF or TIFF. NB: the OME-Zarr URLs must be accessible from the machine where the export script is run. NB: channel LUTs are not currently supported when rendering OME-Zarr images for PDF or TIFFs. Any LUTs will be rendered with white color.

Download the figure JSON (File > Save, in the standalone app) then install the export script. Here, we create a new conda environment and install the export script:

$ conda create --name figure_export python=3.12
$ conda activate figure_export
$ pip install "omero-figure[export]"

To export the figure as PDF or TIFF, run the script with the path to the figure JSON and the output file path as arguments: Use the .pdf extension for PDF export and .tiff for TIFF export. This example exports the downloaded figure_json/my_figure.json to my_figure.pdf in the current directory:

$ figure_export figure_json/my_figure.json my_figure.pdf

Upgrading OMERO.figure

After upgrading OMERO.figure with:

$ pip install -U omero-figure

You need to update the Figure export script using one of the 3 options described above. If using Option 1, you need to replace the existing script:

# Get the ID of the existing Figure_To_Pdf script:
$ omero script list

# Replace the script
$ cd omero_figure/scripts
$ omero script replace <SCRIPT_ID> omero/figure_scripts/Figure_To_Pdf.py

Development

See docs/contributing.md for information on code layout and other details.

We use vite.js to build and serve the app during development.

Install Node from https://nodejs.org, then:

$ cd omero-figure
$ npm install

You can deploy the app during development in two ways: using the vite dev server or from OMERO.web.

Deploying with vite dev server

To serve the app at http://localhost:8080/ using the vite dev server (this will automatically refresh the page when changes are saved):

$ npm run dev     # or npm run start

The app will run as a standalone app that can load OME-Zarr images. A global variable APP_SERVED_BY_OMERO will be false and this is used to determine the behaviour of various features such as File Open/Save and the figure Export dialog.

If you are editing the Shape-Editor code, you can view the test page at http://localhost:8080/shapeEditorTest.html

Deploying from OMERO.web

To deploy the app from OMERO.web during development, you should checkout the code and install from there into your OMERO.web python environment:

$ cd omero-figure
$ pip install -e .

Then configure your local OMERO.web as described above and restart OMERO.web. You will need to build the app with:

$ npm run build

To build whenever changes are saved within the src/ directory:

$ npm run watch

You will need to refresh the OMERO.figure app to see changes when using this workflow.

Deploying the standalone app

The standalone app is deployed to GitHub pages at https://ome.github.io/omero-figure/ via a GitHub action defined in .github/workflows/pages.yml which acts on push to the master branch. The action then builds the app and pushes the built files to the gh-pages branch.

To deploy the app from your own fork, you can push to your own master branch and set up GitHub pages to deploy from the root of your gh-pages branch.

Release process

This repository uses bump2version to manage version numbers. To tag a release run:

$ bumpversion release

This will remove the .dev0 suffix from the current version, commit, and tag the release.

To switch back to a development version run:

$ bumpversion --no-tag [major|minor|patch]

specifying major, minor or patch depending on whether the development branch will be a major, minor or patch release. This will also add the .dev0 suffix.

Remember to git push all commits and tags.

License

OMERO.figure is released under the AGPL.

Copyright

2016-2024, The Open Microscopy Environment