Create layers tab for layer manipulations and authoring

[beaudet]

Drew, Rashmi and I came to agreement on an initial design for displaying a list of layers on a canvas as well as providing for an ability to add new layers using any any image resource in the manifest. For now, the image resource list will be optionally configurable (off by default) since the initial, non-filtered, non-paginated list of images resources would be a performance concern for manifests with many images. @rsinghal can you please review the following specifications and assign to @stanislavkostadinov? I am including links to two documents @aeschylus, one an abbreviated simple (default) behavior, and one using both "alternate depictions" when in the presence of oa:Choice (oa:SpecificResource would be a top level layer) and also the image resource list turned on so that new layers can be created from them. @mikeapp, I don't think @stanislavkostadinov should build in support for the alternate depictions since we don't have a need for those yet in ConservationSpace, although I've built it into the design.

Here's a design document for a simple implementation that would provide the presentation of layers, reordering of layers, opacity, brightness, and contrast controls as well as the ability to delete a layer:

https://drive.google.com/file/d/0B8dnsz8s0G6eSnNKbWpCbnlZTWc/view?usp=sharing

The more complex implementation, some of which is required to support ConservationSpace overlays, is illustrated here:

https://drive.google.com/file/d/0B8dnsz8s0G6eRk8xZkdRaTI1Tmc/view?usp=sharing

and would provide support for creation of new layers using image resources from other canvases in the manifest as well as differentiation of oa:Choice resources as child layers of the primary resource. Requirement Specifications: Layers Dialog for Overlay Support ConservationSpace has a requirement to allow images to be overlaid on top of one another and the opacity controlled so that, for example, an infrared image can be overlaid on top of a visible light image and then transformed so that its size can be adjusted to permit alignment of the two images with subsequent adjustment of the opacity of either image in order to provide visual cues for where, on the physical object, the infrared light was transmitted.

General Feature Design • A re-orderable list of images appearing on the selected canvas shall be rendered in a scrolling “Layers” tab in Z index that includes a thumbnail of the image resource and its label. • In the Mirador 2.1 branch, an empty, hidden “layers” tab has been committed at https://github.com/IIIF/mirador/blob/release2.1/js/src/widgets/layersTab.js and you can enable it here: https://github.com/IIIF/mirador/blob/release2.1/js/src/workspaces/window.js#L46 • Images appearing in the “Layers” tab can be reordered by dragging and dropping them into position. Such changes are considered to be immediately committed, i.e. there is no cancel – the user would just have to revert to the prior order if they mess up. • Images appearing in the “Layers” tab may be deleted from the canvas if they are "unprotected images" • As shown in the design document, a dropdown arrow will appear next to each layer in the list. Clicking on this icon will cause the system to enter “layer editing” mode. o In layer editing mode, the image layer is temporarily brought to the foreground if it's not already and adorned with the same set of handles and rotation tools used for rectangles (but without a delete icon). By moving these handles, image layers can be dilated, translated, and rotated, but the aspect ratio should not be able to be changed. In addition, a set of editing controls for the layer appear in a dialog box below the line item. In the dialog, a set of sliders appears for controlling the layer’s opacity, contrast, and brightness, each with corresponding floating point text boxes next to the slider - we might also want to consider allowing the label to be edited, but it's not a requirement for ConservationSpace. Save and cancel buttons appear in the editing dialog that result in either discarding the changes or committing them in memory, including any transformations made to the image layer using the handles. Upon saving or canceling, the mode reverts to viewing mode. o When a layer is deleted, a confirmation dialog confirms the deletion before it takes effect. • When image layers are added, deleted, or edited, the Manifest within Mirador shall be updated immediately with the new configuration and, after the merge of the IIIF Manifests Layout component, OSD will be called to re-render this modified manifest.

• Since a new Manifesto-like API will not be part of the Mirador 2.1 release, the advised method for editing the manifest after image layer manipulations is to use the existing internal manifest representations of Mirador rather than regenerating the manifest externally and causing Mirador to reload it from scratch every time a layer is edited, added, or deleted. • Below the list of layers is a list of all image resources defined in the manifest. The list of image resources is formatted similarly to the list of layers, but without any action controls. Dragging one of these image resource into the layers list creates a new layer in the desired position within the list of layers. An image resource may be duplicated multiple times in this manner. This feature should be turned OFF by default but may be configured to appear if desired.

Annotation Modelling Differences between External Systems and IIIF Manifests For some applications that embed Mirador, it’s important to consider that annotations might be mapped directly to image resources with no concept of a “canvas”. While translation glue between IIIF and the external system must be written to fetch and store annotations like this, it's likely to be a typical scenario.

ConservationSpace is an external system of this type. It has no model of a canvas, generates Manifests dynamically from an image widget configuration, and stores annotations with the image for which a canvas was initially created. Due to these modelling differences, ConservationSpace does not want to permit deletion of these initial images and would like to bless them as “protected” images.

ConservationSpace will therefore add a capability in Mirador for an external API to designate one or more images per canvas as “protected”. Protected images will not be able to be deleted from the layers list nor transformed, although brightness, contrast, and opacity should be able to be modified as should the ordering of the protected image in the list of layers. Since this status cannot be modeled with the current version of IIIF Manifests, the blessing of “protected images” must be called separately by an external application after a canvas, or perhaps a manifest, is loaded.

The work can probably be split up into the following PRs to make merging easier: PR #1: {Create layer list within new layers tab, with support for reordering layers within the list – reordering is immediately committed to in-memory manifest} PR #2: {Layer editing dialog; reveal within list when arrow at far right is clicked – contains sliders for opacity, brightness, and contrast as well as rotation, each with a floating point text box that the user can alternatively enter numeric values into. Has OK, Cancel, and Delete Layer buttons. delete removes the layer; build in support for blessing a layer as “protected” which prevents the layer from being deleted} Reference design document PR #3: {Layer transformations; when layer dialog is displayed for a layer and the layer is unprotected, the layer is outlined with lines and has handles for scaling and rotating it – these behave similarly to rectangular transformations except there is no delete icon displayed next to the shape} PR #4: {Image resources list; below the list of layers is a list of all image resources associated with the manifest; these can be dragged into the layer list to create a new layer;} reference design document

[rsinghal]

related to #632

[radpet]

@rsinghal

In the Mirador 2.1 branch, an empty, hidden “layers” tab has been committed athttps://github.com/IIIF/mirador/blob/release2.1/js/src/workspaces/window.js#L46

Changing it to true/'layersTab' does not show anything? Would you please tell me what I should change and shoud I expect ui change :) ?

[radpet]

@beaudet

Below the list of layers is a list of all image resources defined for the canvas. The list of image resources is formatted similarly to the list of layers, but without any action controls. Dragging one of these image resource into the layers list creates a new layer in the desired position within the list of layers. An image resource may be duplicated multiple times in this manner. This feature should be turned OFF by default but may be configured to appear if desired.

You are talking about the whole feature called 'list all image resources used for the canvas', aren't you?

[beaudet]

Yes, but it should actually read "list of all resources defined in the manifest" - I edited the proposal to state as much.

[radpet]

@aeschylus @rsinghal to what extent this functionality is ready?

[snydman]

Please see results of a design review from the Stanford Libraries design team here:

https://docs.google.com/document/d/1WaL5Vkkp3SvYy03VdVOFmQjwbh1SUvRfeSRzldwMAtU/edit?ts=58012e3e

The team focussed only on the ready only experience for this first pass in the hopes of readying an actionable first phase of implementation along with IIIFManifestLayers.

[beaudet]

This is great! Thanks!

[radpet]

@beaudet @snydman

Hello, These are my design notes on how I plan to implement the layers functionality. Feel free to share your opinion.

MiradorLayersDesign.pdf

[sdellis]

@radpet I have thought about a layers panel for some of the svg-draw component I've been working on. I'm curious about the relationship between annotations and layers, which I don't see addressed in your design document. As far as I understand the Presentation API, annotations target Canvases or portions of Canvases. I have a use case where someone would want to annotate on different images/layers... essentially "annotate an annotation". I'm a bit confused about how to go about that, and I'm curious if you've thought about it at all.

[radpet]

@sdellis Thanks for your feedback. Well, to be honest I haven't. Most probably we will treat the annotations as they are for the master image resource (the image which the canvas showed initially) since the layers will be additional image resources to the canvas.Mapping the annotation to them is out of my scope.

[sdellis]

Ok, no worries and thanks for the reply. Out of curiosity, how are you determining the master image resource that you show first? Is it simply the first in the images list?

[radpet]

Well initially only one image is inside the canvas in image view. This is what I call the master image. The next images (layers) will be stored in a model that will eventually be serialized to the manifest (might be out of scope too, but I will try to provide proper data model, because our manifests are dynamical and we can't store anything there). Anyway if the data model is serialized to the manifest I suppose the image resources should have a specific order so the master image can be easily found.

[azaroth42]

There is a model for this in IIIF -- Choice. It allows the "master" image to be the default, and to have a set of other options.

[aeschylus]

How to programmatically deal with choice by means of the spec has been extensively described here (based on 2.1):

https://github.com/sul-dlss/iiifManifestLayouts/issues/40#issuecomment-159741392 https://github.com/sul-dlss/iiifManifestLayouts/issues/98

And here is the implementation: https://github.com/sul-dlss/iiifManifestLayouts/blob/master/src/imageResourceFactory.js

[cbeer]

Mirador 3 supports layers.