{"action":"created","issue":{"url":"https://api.github.com/repos/openmicroscopy/design/issues/33","repository_url":"https://api.github.com/repos/openmicroscopy/design","labels_url":"https://api.github.com/repos/openmicroscopy/design/issues/33/labels{/name}","comments_url":"https://api.github.com/repos/openmicroscopy/design/issues/33/comments","events_url":"https://api.github.com/repos/openmicroscopy/design/issues/33/events","html_url":"https://github.com/openmicroscopy/design/issues/33","id":149770258,"number":33,"title":"ROI: Transforms","user":{"login":"chris-allan","id":487082,"avatar_url":"https://avatars.githubusercontent.com/u/487082?v=3","gravatar_id":"","url":"https://api.github.com/users/chris-allan","html_url":"https://github.com/chris-allan","followers_url":"https://api.github.com/users/chris-allan/followers","following_url":"https://api.github.com/users/chris-allan/following{/other_user}","gists_url":"https://api.github.com/users/chris-allan/gists{/gist_id}","starred_url":"https://api.github.com/users/chris-allan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chris-allan/subscriptions","organizations_url":"https://api.github.com/users/chris-allan/orgs","repos_url":"https://api.github.com/users/chris-allan/repos","events_url":"https://api.github.com/users/chris-allan/events{/privacy}","received_events_url":"https://api.github.com/users/chris-allan/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2016-04-20T13:39:26Z","updated_at":"2016-04-20T14:08:26Z","closed_at":null,"body":"# History and state of play\r\n\r\n`ROI` and `Shape` sub-types have supported an affine transformation matrix on their geometry since their promotion to the main OME data model from `OMERO.xsd` in the 2009-09 schema release. Change notes and generated schema documentation for that first pass are available:\r\n\r\n * https://www.openmicroscopy.org/site/support/ome-model/schemas/september-2009.html\r\n * http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2009-09/ome5.html#id398\r\n\r\nThe currently available generated documentation does not actually reflect what was present in the schema at the time so I have both linked to and included it inline here for convenience:\r\n\r\n * https://github.com/openmicroscopy/bioformats/blob/develop/components/specification/released-schema/2009-09/ROI.xsd#L107\r\n\r\n```\r\nThis is a matrix used to transform the the shape.\r\nIt is a string of 6 numbers \"a, b, c, d, e, f\" that\r\nrepresent the 3 by 3 matrix.\r\n--       --\r\n| a, c, e |\r\n| b, c, f |\r\n| 0, 0, 1 |\r\n--       --\r\n```\r\n\r\nThe legacy of these attributes and elements is that of the `RoiDisplayOptions` element introduced as part of `OMERO.xsd` in the 2008-09 schema release. Change notes and generated schema documentation are also available for that:\r\n\r\n * https://www.openmicroscopy.org/site/support/ome-model/schemas/september-2008.html\r\n * http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2008-09/OMERO.xsd.html#element_RoiDisplay\r\n\r\nAs referenced in the change notes, the inspiration for `RoiDisplayOptions` was that of SVG. SVG's \"transform\" attribute, which can be chained as part of a transform list is fully documented and can be reviewed:\r\n\r\n * https://www.w3.org/TR/SVG/coords.html#TransformAttribute\r\n\r\nTo my knowledge no version of `RoiDisplayOptions` was ever reflected in a released version of the OMERO data model.\r\n\r\nThat said, given the legacy of both the attributes and elements themselves and their SVG inspiration it shouldn't surprise us too much that this SVG style is the form by which OMERO.insight's measurement tool began populating them as part of the Beta4.1.0 release of OMERO in October, 2009. The mapping file for the OMERO data model at the time is available:\r\n\r\n * https://github.com/openmicroscopy/openmicroscopy/blob/v.4.1.0-omero/components/model/resources/mappings/roi.ome.xml\r\n\r\nUnfortunately this is at odds with the schema and persists to this day:\r\n\r\n * https://github.com/openmicroscopy/openmicroscopy/blob/v5.2.2/components/insight/SRC/org/openmicroscopy/shoola/util/roi/io/OutputServerStrategy.java#L555\r\n\r\nOMERO.web works around these idiosyncrasies in JavaScript:\r\n\r\n * https://github.com/openmicroscopy/openmicroscopy/blob/v5.2.2/components/tools/OmeroWeb/omeroweb/webgateway/static/webgateway/js/ome.roidisplay.js#L134\r\n\r\nIt is handling a case, `rotate(...)`, which is no longer populated by OMERO.insight but is legal SVG style. As a rotation can be handled by the `matrix(...)` style it was likely superceded.\r\n\r\nNo changes to how OMERO.insight has been populating the transform have taken place since initially committed in October, 2009 (openmicroscopy/openmicroscopy@332cd539e48ee22996467ad39e2476e0ea63c8f4).\r\n\r\nThe current list of potential forms for the transform as reflected in the OMERO.insight codebase are:\r\n\r\n * `none`\r\n * `translate(<tx> [<ty>])`\r\n * `scale(<sx> [<sy>])`\r\n * `matrix(<a> <b> <c> <d> <e> <f>)`\r\n\r\nWhen a transform is coming through the import process and passes through the series of `MetadataStore` implementations, it has an additional form:\r\n\r\n * `[ a00 a01 a02 a10 a11 a12 ]`\r\n\r\nThis is reflected in the implementation:\r\n\r\n * https://github.com/openmicroscopy/openmicroscopy/blob/v5.2.2/components/blitz/src/ome/formats/OMEROMetadataStoreClient.java#L998\r\n\r\nThe final location within the OMERO codebase where transforms are referenced is within the now deprecated `OmeroPopo` package:\r\n\r\n * https://github.com/openmicroscopy/openmicroscopy/blob/v5.2.2/components/tools/OmeroPy/src/omero/util/OmeroPopo.py#L683\r\n\r\nSince the OME data model 2012-06 schema release, `Shape` sub-types have a much more structured markup surrounding the transform property. This is reflected in the current developer documentation which is available here:\r\n\r\n * https://www.openmicroscopy.org/site/support/ome-model/developers/roi.html\r\n\r\nThe change notes and, before and after sets of generated schema documentation are available:\r\n\r\n * https://www.openmicroscopy.org/site/support/ome-model/schemas/june-2012.html\r\n * http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2011-06/ROI_xsd.html#Shape_Transform\r\n * http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2012-06/ROI_xsd.html#Shape_Transform\r\n\r\nNo changes to the OMERO data model representation of transforms have taken place since their introduction.\r\n\r\n# The issue\r\n\r\nThe current state of how `Shape` sub-type transforms are modelled in the OME or OMERO data model would be of much lesser importance if OMERO.insight were not populating the transform on every creation or update (admittedly often innocuously as `none`), **and** utilizing it exclusively for performing translations of ellipses.\r\n\r\nBoth utilizing ellipses that have been moved in OMERO.insight as a third-party or making geometric, extended or otherwise, queries against the database then must take transforms into account. This is made even more difficult by their current string syntax and worse by the fact that documentation on the form that these transforms might take is contradictory.\r\n\r\n# Suggestions for moving forward\r\n\r\n## OMERO 5.2.x\r\n\r\n * Document publicly the current, exhaustive list of transform styles that could be present in an OMERO server and how they correspond to the OME data model. This should include version, etc. Documentation should also assert that the only style that should be used is the currently documented pre-2012-06 OME data model transform style: a string of 6 numbers \"a, b, c, d, e, f\" that represent the 3 by 3 matrix.\r\n * Change publicly available code examples to not encourage the use of the transform for translations that could be performed by updating the core attributes of a `Shape` sub-type and strongly discourage this in documentation.\r\n * Extend OMERO.insight, OMERO.web and `omero-marshal` to support the exhaustive list of current transform styles and the currently documented pre-2012-06 OME data model transform style. `omero-marshal` should encode whatever form it is given in the post-2012-06 OME data model transform style and decode in the documented pre-2012-06 OME data model transform style.\r\n * Fix the metadata store implementations to populate the pre-2012-06 OME data model transform style.\r\n * Modify OMERO.insight to save **only** the pre-2012-06 OME data model style and **not** to use the transform for performing translations on ellipses.\r\n\r\n## OMERO 5.3.x\r\n\r\n * Reflect the post-2012-06 OME data model transform style in the modelling of `Shape` sub-types and the transform property itself. Database form and object model to be decided.\r\n * Write database upgrade scripts for the exhaustive list of forms.\r\n * Document the changes.\r\n * Update our clients and `omero-marshal` to reflect the new OMERO data model.\r\n\r\n/cc @jburel, @joshmoore, @sbesson, @will-moore, @mtbc, @hflynn \r\n\r\n/cc @emilroz, @knabar\r\n\r\n# Edits\r\n\r\n * `Wed Apr 20 06:57:21 PDT 2016`: Fixed references to 2016-06 schema with 2012-06."},"comment":{"url":"https://api.github.com/repos/openmicroscopy/design/issues/comments/212440578","html_url":"https://github.com/openmicroscopy/design/issues/33#issuecomment-212440578","issue_url":"https://api.github.com/repos/openmicroscopy/design/issues/33","id":212440578,"user":{"login":"jburel","id":1022396,"avatar_url":"https://avatars.githubusercontent.com/u/1022396?v=3","gravatar_id":"","url":"https://api.github.com/users/jburel","html_url":"https://github.com/jburel","followers_url":"https://api.github.com/users/jburel/followers","following_url":"https://api.github.com/users/jburel/following{/other_user}","gists_url":"https://api.github.com/users/jburel/gists{/gist_id}","starred_url":"https://api.github.com/users/jburel/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jburel/subscriptions","organizations_url":"https://api.github.com/users/jburel/orgs","repos_url":"https://api.github.com/users/jburel/repos","events_url":"https://api.github.com/users/jburel/events{/privacy}","received_events_url":"https://api.github.com/users/jburel/received_events","type":"User","site_admin":false},"created_at":"2016-04-20T14:08:26Z","updated_at":"2016-04-20T14:08:26Z","body":"This might imply a 5.2.4 since we won't be able to do the work on time for 5.2.3"}}