WebGateway.txt

WebGateway
==========

WebGateway is a Django app within the |OmeroWeb|. It provides a web API for
rendering images and accessing data on the OMERO server via URLs.

.. note::

    The OMERO.web client also supports URLs linking to specified data in
    OMERO. See the :help:`OMERO.web user guides <>` for more details.

Web services
------------

This list of URLs below may be incomplete or out of date. For a complete
list of URLs, see the :pythondoc:`latest
API <omeroweb/omeroweb.html#module-omeroweb.urls>`
and try the URLs out for yourself!

The HTTP request will need to include login details for creating or using a
current server connection. This will be true for any request made after
logging in to the server, e.g. login using webclient or webadmin login pages
then go to ``webgateway/…`` or if you have logged in to a server at
``http://ome.example.com/webclient`` then go to, for example,
``http://ome.example.com/webgateway/render_image/<imageid>/<z>/<t>/``

.. figure:: /images/webgateway-thumbnail.jpg
  :align: center
  :alt: Rendered thumbnail

  Rendered thumbnail


.. _urls_from_within_OMERO_web:

URLs from within OMERO web
^^^^^^^^^^^^^^^^^^^^^^^^^^

Images rendered within OMERO web templates should use Django's ``{% url %}``
tag to generate URLs for webgateway, passing in the ID of the image. This is
shown for each of the URLs below:


Image viewer
""""""""""""

-   Provides a full image viewer, with controls for scrolling Z and T, editing
    rendering settings etc.

    ::
    
        URL: https://your_host/webgateway/img_detail/<imageid>/

        Template tag: {% url 'webgateway.views.full_viewer' image_id %}



Images
""""""

-  Returns a jpeg of the specified plane with current rendering settings

   ::

       URL: https://your_host/webgateway/render_image/<imageid>/<z>/<t>/

       Template tag: {% url 'webgateway.views.render_image' image_id theZ theT %}
       
   From OMERO 4.4.4, omitting Z and T will use the default values:


   ::

       URL: https://your_host/webgateway/render_image/<imageid>/

       Template tag: {% url 'webgateway.views.render_image' image_id %}

-  Makes a jpeg laying out each active channel in a separate panel

   ::

       URL: https://your_host/webgateway/render_split_channel/<imageId>/<z>/<t>/

       Template tag: {% url 'webgateway.views.render_split_channel' image_id theZ theT %}

-  Plots the intensity of a row of pixels in an image. w is line width

   ::

       URL: https://your_host/webgateway/render_row_plot/<imageId>/<z>/<t>/<y>/<w>

       Template tag: {% url 'webgateway.views.render_row_plot' image_id theZ theT yPos width %}

-  Plots the intensity of a column of pixels in an image.

   ::

       URL: https://your_host/webgateway/render_col_plot/<imageId>/<z>/<t>/<x>/<w>/

       Template tag: {% url 'webgateway.views.render_col_plot' image_id theZ theT xPos width %}

-  Returns a jpeg of a thumbnail for an image. w and h are optional
   (default is 64). Specify just one to retain aspect ratio.
   Since OMERO 5.1 it is also possible to specify Z and T indices in the query string.

   ::

       URL: https://your_host/webgateway/render_thumbnail/<imageId>/?z=10

       Template tag: {% url 'webgateway.views.render_thumbnail' image_id %}?z=10    # default size, z=10

       URL: https://your_host/webgateway/render_thumbnail/<imageId>/<w>/<h>

       Template tag: {% url 'webgateway.views.render_thumbnail' image_id 100 %}     # size 100


Rendering settings
""""""""""""""""""

If no rendering settings are specified (as above), then the current rendering
settings will be used. To apply different settings to images returned by the
``render_image`` and ``render_split_channels`` URLs, parameters can be
specified in the request. N.B. These settings are only applied to the rendered
image and will not be saved unless specified.

Individual parameters are:

-  **Channels on/off** e.g. for a 4 channel image, to turn on all channels
   except 2:

   ::

       ?c=1,-2,3,4
       
       # From OMERO 4.4.4 you can simply specify the active channels
       ?c=3         # only Channel 3 is active
       ?c=3,4       # Channels 3 and 4 are active

-  **Channel colour** e.g. to set the colours for channels 1 to red and 2
   to green and 3 to blue:

   ::

       ?c=1|$FF0000,2|$00FF00,3|$0000FF

-  **Rendering levels** e.g. to set the cut-in and cut-out values for a 3 Channel image.

   ::

       ?c=1|400:505,2|463:2409,3|620:3879
       ?c=-1|400:505,2|463:2409,3|620:3879      # First channel inactive "-1"
       ?c=2|463:2409,3|620:3879     # OMERO 4.4.4 only: inactive channels can be omitted

-  **Z-projection**: Maximum intensity, Mean intensity or None (normal). By
   default we use all z-sections, but a range can be specified.

   ::

       ?p=intmax
       ?p=intmax|0:10       # Use z-sections 0-10 inclusive
       ?p=intmean
       ?p=normal

-  **Rendering 'Mode'**: greyscale or colour.

   ::

       ?m=g    # greyscale (only the first active channel will be shown in grey)
       ?m=c    # colour

-  Parameters can be combined, e.g.

   ::

       https://your_host/webgateway/render_image/2602/10/0/?c=1|100:505$0000FF,2|463:2409$00FF00,3|620:3879$FF0000,-4|447:4136$FF0000&p=normal

JSON methods
""""""""""""

-  List of projects:
   ``webgateway/proj/list/``

   ::

       [{"description": "", "id": 269, "name": "Aurora"},
       {"description": "", "id": 269, "name": "Drugs"} ]

-  Project info: ``webgateway/proj/<projectId>/detail/``

   ::

       {"description": "", "type": "Project", "id": 269, "name": "CenpA"}

-  List of Datasets in a Project: ``webgateway/proj/<projectId>/children/``

   ::

       [{"child\_count": 9, "description": "", "type": "Dataset", "id": 270,
            "name": "Control"}, ]

-  Dataset, same as for Project: ``webgateway/dataset/<datasetId>/detail/``

-  Details of Images in the dataset:
   ``webgateway/dataset/<datasetId>/children/``

-  Lots of metadata for the image. See
   below: ``webgateway/imgData/<imageId>/``


Saving etc
""""""""""

-  ``webgateway/saveImgRDef/<imageId>/``
-  ``webgateway/compatImgRDef/<imageId>/``
-  ``webgateway/copyImgRDef/``

ImgData
"""""""

The following is sample JSON data generated by
``/webgateway/imgData/<imageId>/``

::

    {
    "split_channel": {
        "c": {"width": 1448, "gridy": 2, "border": 2, "gridx": 3, "height": 966},
        "g": {"width": 966, "gridy": 2, "border": 2, "gridx": 2, "height": 966}
        },
    "rdefs": {"defaultT": 0, "model": "color",
                "projection": "normal", "defaultZ": 15},
    "pixel_range": [-32768, 32767],
    "channels": [
        {"color": "0000FF", "active": true,
            "window": {"max": 449.0, "end": 314, "start": 70, "min": 51.0},
            "emissionWave": "DAPI",
            "label": "DAPI"},
        {"color": "00FF00", "active": true,
            "window": {"max": 7226.0, "end": 1564, "start": 396, "min": 37.0},
            "emissionWave": "FITC",
            "label": "FITC"}
        ], 
    "meta": {
        "projectDescription": "",
        "datasetName": "survivin",
        "projectId": 2,
        "imageDescription": "",
        "imageTimestamp": 1277977808.0,
        "imageId": 12,
        "imageAuthor": "Will Moore",
        "imageName": "CSFV-siRNAi02_R3D_D3D.dv",
        "datasetDescription": "",
        "projectName": "siRNAi",
        "datasetId": 3
    }, 
    "id": 12,
    "pixel_size": {"y": 0.0663, "x": 0.0663, "z": 0.2},
    "size": {
        "width": 480,
        "c": 4,
        "z": 31,
        "t": 1,
        "height": 480
    },
    "tiles": false
    }


For large tiled images, the following data is also included:

::

    {
    "tiles": true,
    "tile_size": {
        width: 256,
        height: 256
    },
    "levels": 5,
    "zoomLevelScaling": {
        0: 1,
        1: 0.25,
        2: 0.0625,
        3: 0.0312,
        4: 0.0150
    },
    }