Consistent Behavior for Rendering Settings Query Parameters

[kkoz]

This issue is to document some unexpected/inconsistent/undocumented behavior for rendering settings query parameters.

• The tile parameter should require 5 values. If 3 or 4 are provided, and the second and third values are 0, the whole image will be returned. If they are not zero, the server experiences the following error: serverStackTrace = ome.conditions.InternalException: Wrapped Exception: (java.lang.RuntimeException): Invalid Region, the width must be positive:0
  And the client gets a 404. If 2 or fewer values are provided, the client gets a 400 with the message “malformed tile argument, tile=0,0”. We suggest that the client get the 400 error with the message anytime fewer than 5 values are supplied.
• tile/region parameter are not specified at all in https://omero.readthedocs.io/en/stable/developers/Web/WebGateway.html. We should provide documentation specifying that x,y,w,h for region and resolution,tileX,tileY,tileWidth,tileHeight must be specified for region and tile respectively. Also should specify behavior when x,y lies outside the image bounds. We suggest returning a 400 with an error message if x,y is out of bounds and returning a cropped image if x,y is in bounds but x+w, y+h is out of bounds.
• If a window or color is not provided for a channel in “c”, the user’s rendering settings will be applied for that window. This is true whether other windows or colors are specified. This seems like it could be both confusing and buggy. The choice to use saved settings might be unexpected behavior (the client won't really know what settings are being applied), and there may be issues with caching based on URLs.
• If the “m” query parameter is not supplied, it will default to the user’s saved rendering settings. The user’s saved settings will also be used if the “m” value supplied is not recognized by omero-web.
  We suggest that m always be provided and that it be required to be a valid value otherwise a 400 will be returned with an informative error message

[sbesson]

Originally posted by @sbesson in #441 (comment)

As we review rendering settings query parameters across OMERO.web, we should be able to clarify the expectations for the API associated with saving rendering settings. As for the various render endpoints, a lot of the logic happens in _get_prepared_image with the following sequence of calls:

• windows, colors and inversions are applied to the channels
• the default Z/T are applied to the image
• img.saveDefaults() captures the rendering settings in the database

As mentioned in the discussion linked above, the current logic is confusing and potentially error-porne.
In particular, it's unclear whether this API support subset of channels passed as query parameters(as described in https://omero.readthedocs.io/en/stable/developers/Web/WebGateway.html#rendering-settings) or if all channels are expected to be specified.

Additionally, the logic was updated in ome/openmicroscopy#5010 to ensure that the settings are saved for both active and inactive channels by making two consecutive calls to setActiveChannels. It should be possible to replace the deprecated setActiveChannels API by set_active_channels and make use the new set_inactive flag to make a single call setting the channels settings.