Editor for image area selection

The editor lets you select an area of the image using either a rectangle or an arbitrary polygon:

Note. Don't add training and control tasks to the project with an image area selection editor.

Adding the editor

If you need to add an image editor without selected objects:

Connect the $TOLOKA_ASSETS/js/image-annotation.js library (click in the Task interface block on the project page).
Include the {{field type="image-annotation" name="<output field name>" src=<image URL>}} component in the HTML code of the interface. For example:
```
{{field type="image-annotation" name="result" src=image}}
```
For a complete list of parameters, see the table.
Add the fields:
- With the "link" type (if you store images on an external service) or the "string" type (if you store images on Yandex.Disk) in the input data.
- With the "json" type in output data.

The output data contains a JSON object with point coordinates. For example:

[{"data":{"p1":{"x":0.472,"y":0.413},"p2":{"x":0.932,"y":0.877}},"type":"rectangle"},
{"data":[{"x":0.143,"y":0.807},{"x":0.317,"y":0.87},{"x":0.511,"y":0.145},{"x":0.328,"y":0.096},{"x":0.096,"y":0.554}],"type":"polygon"}]

The x and y values are numbers from 0 to 1. Length and width of the image are taken as 1, with the center of coordinates in the upper-left corner of the image.

If you have images with selected objects and you want to upload them to the task:

Connect the $TOLOKA_ASSETS/js/image-annotation.js library (click in the Task interface block on the project page).
Include the {{field type="image-annotation" name="<output field name>" src=<image URL> annotations=<input field name>}} component in the interface HTML code. For example:
```
{{field type="image-annotation" name="result" src=image annotations=polygon}}
```
Add the fields:
- With the "link" type (if you store images on an external service) or the "string" type (if you store images on Yandex.Disk) in the input data.
- With the "json" type in the input data.
- With the "json" type in output data.
Escape JSON with point coordinates and add it to the TSV file with tasks.

Full list of parameters


Parameter	Description	Required	Default value
`type`	Field type: `image-annotation`, the image area selection editor.	yes	no
`name`	Attribute for the output data field. Contains the output field name.	yes	no
`src`	Image URL. Supported values: URL from the input data of the task. For example, from the field with the `url`: `src=image` ID. Direct link. The HTTPS protocol is recommended. For example, `src="https://mywebsite.ru/img1.png"`. Relative link. If you use files on Yandex.Disk, specify the `proxy` component and the name of the input data field. For example, for a field with the name `image` write `src=(proxy image)`. Change the field type to string.	yes	no
`annotations`	Attribute for the input data field. Contains the input data field name. Here you can pass the selection coordinates for further editing. The data format is a JSON object.	no	no


Parameter	Description	Required	Default value
`type`	Field type: `image-annotation`, the image area selection editor.	yes	no
`name`	Attribute for the output data field. Contains the output field name.	yes	no
`src`	Image URL. Supported values: URL from the input data of the task. For example, from the field with the `url`: `src=image` ID. Direct link. The HTTPS protocol is recommended. For example, `src="https://mywebsite.ru/img1.png"`. Relative link. If you use files on Yandex.Disk, specify the `proxy` component and the name of the input data field. For example, for a field with the name `image` write `src=(proxy image)`. Change the field type to string.	yes	no
`annotations`	Attribute for the input data field. Contains the input data field name. Here you can pass the selection coordinates for further editing. The data format is a JSON object.	no	no

Keyboard shortcuts

By default, you can use the following keyboard shortcuts in the task:

C closes a polygon connecting the first and last points with a line.
D deletes the selected point, selected object or last point when creating the polygon.
Arrows move the selected point. With Alt pressed, they move it slower. With Alt+Shift pressed, they move it faster.
Tab moves from the selected point to the next one.
Shift+Tab moves from the selected point to the previous one.

Tell performers about keyboard shortcuts in the instructions to speed up task completion.

Selection tools

By default, rectangle tool is added to the task interface.

You can change the tools set:

To add a rectangle, delete the CSS selector:

.image-annotation-editor__shape-rectangle {
  display: none;
}

To hide a polygon, add the CSS selector:

.image-annotation-editor__shape-polygon {
  display: none;
}

To hide a rectangle, add the CSS selector:

.image-annotation-editor__shape-rectangle {
  display: none;
}

Annotation

To let the performer enter annotation for the selected area or choose it from the list, add an interface element to the task (for example, a text field or a drop-down list):

Get the editor object getEditor() and annotation interface getField('result') in the onRender() method:
```
var field = this.getField('result');     
var editor = field.getEditor();
```

Implement the annotation interface in these methods:

createInterfaceElement() — Calls the interface DOM element (the method is called once during the initialization of the object).
onShow(shape, options) — Displays the annotation interface element when the performer points the mouse at the selected area. Accepts JSON with polygon point coordinates. This JSON can also be used to save annotations entered by the performer.

The sample editor code with annotation:

exports.Task = extend(TolokaHandlebarsTask, function (options) {
    TolokaHandlebarsTask.call(this, options);
}, {
    onRender: function() {
        var field = this.getField('result');     
        var editor = field.getEditor();
        editor.annotationInterface = field.createAnnotationInterface({
            createInterfaceElement: function() {
                this._input = document.createElement('input');
                this._input.addEventListener('input', function() {
                    this._shape.annotation = this._input.value;
                }.bind(this));
                return this._input;
            },
            onShow: function(shape) {
                this._shape = shape;
                this._input.value = shape.annotation;
            }
        });
   }

var listOption = 
[["Animals","Cat","Dog","Bird"]];
var listValues = 
[
["-","Cat","Dog","Bird"]
];
var bigListValues = [];
for(var i=0;i<listValues.length;i++){
    for (var j=0;j<listValues[i].length;j++){
        if(j != 0){
            bigListValues[bigListValues.length] = listValues[i][j];
        }
    }
}

exports.Task = extend(TolokaHandlebarsTask, function (options) {
    TolokaHandlebarsTask.call(this, options);
}, {
    onRender: function() {
        var field = this.getField('result');     
        var editor = field.getEditor();
        editor.annotationInterface = field.createAnnotationInterface({
            createInterfaceElement: function() {
                this._select = document.createElement('select');
                for(var j=0;j<listOption.length;j++){
                    var listGroup = listOption[j];
                    var valuesGroup = listValues[j];
                    var optgroup = document.createElement("optgroup");
                    optgroup.setAttribute('label', listGroup[0]);
                    for (var i = 1; i < listGroup.length; i++) {
                        var option = document.createElement("option");
                        if (i == 0) {
                            option.setAttribute('disabled', 'disabled');
                        }
                        option.value = valuesGroup[i];
                        option.className = "seletOpt";
                        var oText = document.createTextNode(listGroup[i]);
                        option.appendChild(oText);
                        optgroup.appendChild(option);
                    }
                    this._select.appendChild(optgroup);
                }
                this._select.addEventListener('change', function() {
                    this._shape.annotation = this._select.value;
                    _.each(bigListValues, function(value) {
                        this._polygonEl.classList.remove(value.toLowerCase());
                    }.bind(this));
                    this._polygonEl.classList.add(this._select.value.toLowerCase());
                }.bind(this));
                return this._select;
            },
            onShow: function(shape, el) {
                console.log("shape: ", shape)
                console.log("el: ", el)  
                this._shape = shape;
                this._select.value = shape.annotation;
                this._polygonEl = el;
            }
        });
   }

The following events occur when the performer interacts with the editor:

shape:start — Start of area selection.
shape:finish — End of area selection.
shape:cancel — Removal of a polygon point.
shape:remove — Removal of area selection.

To subscribe to these events:

editor.on('shape:start', function() { 
    /* event handling */ 
});