Metadata-Version: 2.4
Name: omero-figure
Version: 8.0.1
Summary: OMERO figure creation app
Home-page: https://github.com/ome/omero-figure
Download-URL: https://github.com/ome/omero-figure/archive/v8.0.1.tar.gz
Author: The Open Microscopy Team
Author-email: ome-devel@lists.openmicroscopy.org.uk
License: AGPL-3.0
Keywords: OMERO.web,figure
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3
License-File: LICENSE
Provides-Extra: omero
Requires-Dist: omero-web>=5.6.0; extra == "omero"
Provides-Extra: export
Requires-Dist: pillow; extra == "export"
Requires-Dist: reportlab; extra == "export"
Requires-Dist: markdown; extra == "export"
Requires-Dist: zarr; extra == "export"
Requires-Dist: dask; extra == "export"
Requires-Dist: fsspec[http]; extra == "export"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

.. image:: https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftags%2Fomero-figure.json&query=%24.topic_list.tags.0.topic_count&colorB=brightgreen&suffix=%20topics&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC
    :target: https://forum.image.sc/tag/omero-figure
    :alt: Image.sc forum

.. image:: https://github.com/ome/omero-figure/workflows/OMERO/badge.svg
    :target: https://github.com/ome/omero-figure/actions

.. image:: https://badge.fury.io/py/omero-figure.svg
    :target: https://badge.fury.io/py/omero-figure


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/ <https://ome.github.io/omero-figure/>`_.

For full details see `SUPPORT.md <https://github.com/ome/omero-figure/blob/master/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 <https://pip.pypa.io/en/stable/>`_:

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.

First install the script's dependencies:

* Install `reportlab <https://bitbucket.org/rptlab/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 ...``. The install of `Python Markdown <https://python-markdown.github.io/>`_ is optional
  but is required to format any figure legends that use Markdown syntax.

::

    $ pip install reportlab markdown

* Optional (v8.0.2 and later): If your figure contains OME-Zarr images, you will also need to install the dependencies for rendering
  OME-Zarr images in the export script. These are `zarr`, `dask` and `fsspec[http]`:

::

    $ pip install zarr dask fsspec[http]


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.


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 publicly accessible. Also, you need to be able to access the URLs 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 <https://vitejs.dev/>`_ 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 <https://pypi.org/project/bump2version/>`_ to manage version numbers.
To create a release-candidate (RC) from a development version run::

    $ bumpversion release    # e.g. 8.0.1.dev0 -> 8.0.1.rc0
    $ bumpversion build      # e.g. 8.0.1.rc0 -> 8.0.1.rc1

This creates commits and tags by default.

To tag a stable release from RC run::

    $ bumpversion release    # e.g. 8.0.1.rc1 -> 8.0.1

To create a stable release directly from ``.dev0`` (without RC), set an explicit version and tag it, for example::

    $ bumpversion --new-version 8.0.1 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 <https://semver.org/>`_. This will also add the ``.dev0`` suffix.

Remember to ``git push`` all commits and tags.

PyPI publishing notes:

* Publishing is triggered by Git tags in the GitHub action.
* The published package version comes from ``omero_figure/utils.py`` (not from tag text alone).
* The workflow validates that the tag version and package version match before publishing.

License
-------

OMERO.figure is released under the AGPL.

Copyright
---------

2016-2026, The Open Microscopy Environment
