SageMaker Crowd HTML Elements

The following is a list of Crowd HTML Elements that make building a custom template easier and provide a familiar UI for workers. These elements are supported in Ground Truth, Augmented AI, and Mechanical Turk.

A message that alerts the worker to a current situation.

See an interactive example of an HTML template that uses this Crowd HTML Element in CodePen.

The following is an example of a Liquid template that uses the <crowd-alert> element. Copy the following code and save it in a file with the extension .html. Open the file in any browser to preview and interact with this template.


<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>

<crowd-form>
  <div id="errorBox"></div>
   
  <crowd-keypoint
    src="{{ task.input.taskObject | grant_read_access }}"
    labels="['Item A', 'Item B', 'Item C']"        
    header="Please locate the centers of each item."
    name="annotatedResult">
    <short-instructions>
      Describe your task briefly here and give examples
    </short-instructions>
    <full-instructions>
      Give additional instructions and good/bad examples here
    </full-instructions>   
  </crowd-keypoint>
</crowd-form>

<script>
  var num_obj = 1;

  document.querySelector('crowd-form').onsubmit = function(e) {
    const keypoints = document.querySelector('crowd-keypoint').value.keypoints || document.querySelector('crowd-keypoint')._submittableValue.keypoints;
    const labels = keypoints.map(function(p) {
      return p.label;
    });

    // 1. Make sure total number of keypoints is correct.
    var original_num_labels = document.getElementsByTagName("crowd-keypoint")[0].getAttribute("labels");

    original_num_labels = original_num_labels.substring(2, original_num_labels.length - 2).split("\",\"");
    var goalNumKeypoints = num_obj*original_num_labels.length;
    if (keypoints.length != goalNumKeypoints) {
      e.preventDefault();
      errorBox.innerHTML = '<crowd-alert type="error" dismissible>You must add all keypoint annotations and use each label only once.</crowd-alert>';
      errorBox.scrollIntoView();
      return;
    }

    // 2. Make sure all labels are unique.
    labelCounts = {};
    for (var i = 0; i < labels.length; i++) {
      if (!labelCounts[labels[i]]) {
        labelCounts[labels[i]] = 0;
      }
      labelCounts[labels[i]]++;
    }
    const goalNumSingleLabel = num_obj;

    const numLabels = Object.keys(labelCounts).length;

    Object.entries(labelCounts).forEach(entry => {
      if (entry[1] != goalNumSingleLabel) {
        e.preventDefault();
        errorBox.innerHTML = '<crowd-alert type="error" dismissible>You must use each label only once.</crowd-alert>';
        errorBox.scrollIntoView();
      }
    })
  };
</script>

Attributes

The following attributes are supported by this element.

dismissible

A Boolean switch that, if present, allows the message to be closed by the worker.

type

A string that specifies the type of message to be displayed. The possible values are "info" (the default), "success", "error", and "warning".

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Attributes

The following attributes are supported by this element.

for

A string that specifies the ID of the element to which the badge is attached.

icon

A string that specifies the icon to be displayed in the badge. The string must be either the name of an icon from the open-source iron-icons set, which is pre-loaded, or the URL to a custom icon.

This attribute overrides the label attribute.

The following is an example of the syntax that you can use to add an iron-icon to a <crowd-badge> HTML element. Replace icon-name with the name of the icon you'd like to use from this Icons set.


<crowd-badge icon="icon-name" for="short-instructions"/>

label

The text to display in the badge. Three characters or less is recommended because text that is too large will overflow the badge area. An icon can be displayed instead of text by setting the icon attribute.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Attributes

The following attributes are supported by this element.

disabled

A Boolean switch that, if present, displays the button as disabled and prevents clicks.

form-action

A switch that either submits its parent crowd-form element, if set to "submit", or resets its parent <crowd-form> element, if set to "reset".

href

The URL to an online resource. Use this property if you need a link styled as a button.

icon

A string that specifies the icon to be displayed next to the button's text. The string must be the name of an icon from the open-source iron-icons set, which is pre-loaded. For example, to insert the search iron-icon, use the following:


<crowd-button>
    <iron-icon icon="search"/>
</crowd-button>

The icon is positioned to either the left or the right of the text, as specified by the icon-align attribute.

To use a custom icon see icon-url.

icon-align

The left or right position of the icon relative to the button's text. The default is "left".

icon-url

A URL to a custom image for the icon. A custom image can be used in place of a standard icon that is specified by the icon attribute.

loading

A Boolean switch that, if present, displays the button as being in a loading state. This attribute has precedence over the disabled attribute if both attributes are present.

target

When you use the href attribute to make the button act as a hyperlink to a specific URL, the target attribute optionally targets a frame or window where the linked URL should load.

variant

The general style of the button. Use "primary" for primary buttons, "normal" for secondary buttons, "link" for tertiary buttons, or "icon" to display only the icon without text.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Attributes

The following attributes are supported by this element.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

initial-value

An array of JSON objects, each of which sets a bounding box when the component is loaded. Each JSON object in the array contains the following properties. Bounding boxes set via the initial-value property can be adjusted and whether or not a worker answer was adjusted is tracked via an initialValueModified boolean in the worker answer output.

height – The height of the box in pixels.
label – The text assigned to the box as part of the labeling task. This text must match one of the labels defined in the labels attribute of the <crowd-bounding-box> element.
left – Distance of the top-left corner of the box from the left side of the image, measured in pixels.
top – Distance of the top-left corner of the box from the top of the image, measured in pixels.

width – The width of the box in pixels.

You can extract the bounding box initial value from a manifest file of a previous job in a custom template using the Liquid templating language:


initial-value="[
  {% for box in task.input.manifestLine.label-attribute-name-from-prior-job.annotations %}
    {% capture class_id %}{{ box.class_id }}{% endcapture %}
    {% assign label = task.input.manifestLine.label-attribute-name-from-prior-job-metadata.class-map[class_id] %}
    {
      label: {{label | to_json}},
      left: {{box.left}},
      top: {{box.top}},
      width: {{box.width}},
      height: {{box.height}},
    },
  {% endfor %}
 ]"

labels

A JSON formatted array of strings, each of which is a label that a worker can assign to the image portion enclosed by a rectangle. Limit: 10 labels.

name

The name of this widget. It's used as a key for the widget's input in the form output.

src

The URL of the image on which to draw bounding boxes.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: full-instructions, short-instructions

Regions

The following regions are required by this element.

full-instructions

General instructions about how to draw bounding boxes.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Output

The following output is supported by this element.

boundingBoxes

An array of JSON objects, each of which specifies a bounding box that has been created by the worker. Each JSON object in the array contains the following properties.

height – The height of the box in pixels.
label – The text assigned to the box as part of the labeling task. This text must match one of the labels defined in the labels attribute of the <crowd-bounding-box> element.
left – Distance of the top-left corner of the box from the left side of the image, measured in pixels.
top – Distance of the top-left corner of the box from the top of the image, measured in pixels.
width – The width of the box in pixels.

inputImageProperties

A JSON object that specifies the dimensions of the image that is being annotated by the worker. This object contains the following properties.

height – The height, in pixels, of the image.
width – The width, in pixels, of the image.

Example : Sample Element Outputs

The following are samples of outputs from common use scenarios for this element.

Single Label, Single Box / Multiple Label, Single Box


[
  {
    "annotatedResult": {
      "boundingBoxes": [
        {
          "height": 401,
          "label": "Dog",
          "left": 243,
          "top": 117,
          "width": 187
        }
      ],
      "inputImageProperties": {
        "height": 533,
        "width": 800
      }
    }
  }
]

Single Label, Multiple Box


[
  {
    "annotatedResult": {
      "boundingBoxes": [
        {
          "height": 401,
          "label": "Dog",
          "left": 243,
          "top": 117,
          "width": 187
        },
        {
          "height": 283,
          "label": "Dog",
          "left": 684,
          "top": 120,
          "width": 116
        }
      ],
      "inputImageProperties": {
        "height": 533,
        "width": 800
      }
    }
  }
]

Multiple Label, Multiple Box


[
  {
    "annotatedResult": {
      "boundingBoxes": [
        {
          "height": 395,
          "label": "Dog",
          "left": 241,
          "top": 125,
          "width": 158
        },
        {
          "height": 298,
          "label": "Cat",
          "left": 699,
          "top": 116,
          "width": 101
        }
      ],
      "inputImageProperties": {
        "height": 533,
        "width": 800
      }
    }
  }
]

You could have many labels available, but only the ones that are used appear in the output.

Attributes

The following attributes are supported by this element.

heading

The text displayed at the top of the box.

image

A URL to an image to be displayed within the box.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Attributes

The following attributes are supported by this element.

checked

A Boolean switch that, if present, displays the check box as checked.

The following is an example of the syntx used to check a checkbox by default.


  <crowd-checkbox name="checkedBox" value="checked" checked>This box is checked</crowd-checkbox>

disabled

A Boolean switch that, if present, displays the check box as disabled and prevents it from being checked.

The following is an example of the syntax used to disable a checkbox.


  <crowd-checkbox name="disabledCheckBox" value="Disabled" disabled>Cannot be selected</crowd-checkbox>

name

A string that is used to identify the answer submitted by the worker. This value will match a key in the JSON object that specifies the answer.

required

A Boolean switch that, if present, requires the worker to provide input.

The following is an example of the syntax used to require a checkbox be selected.


  <crowd-checkbox name="work_verified" required>Instructions were clear</crowd-checkbox>

value

A string used as the name for the check box state in the output. Defaults to "on" if not specified.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Output

Provides a JSON object. The name string is the object name and the valuestring is the property name for a Boolean value based on the check box state; true if checked, false if not checked.

Example : Sample Element Outputs

Using the same name value for multiple boxes.


<!-- INPUT -->  
<div><crowd-checkbox name="image_attributes" value="blurry"> Blurry </crowd-checkbox></div>
<div><crowd-checkbox name="image_attributes" value="dim"> Too Dim </crowd-checkbox></div>
<div><crowd-checkbox name="image_attributes" value="exposed"> Too Bright </crowd-checkbox></div>


//Output with "blurry" and "dim" checked
[
  {
    "image_attributes": {
      "blurry": true,
      "dim": true,
      "exposed": false
    }
  }
]

Note that all three color values are properties of a single object.

Using different name values for each box.


<!-- INPUT -->
<div><crowd-checkbox name="Stop" value="Red"> Red </crowd-checkbox></div>
<div><crowd-checkbox name="Slow" value="Yellow"> Yellow </crowd-checkbox></div>
<div><crowd-checkbox name="Go" value="Green"> Green </crowd-checkbox></div>


//Output with "Red" checked
[
  {
    "Go": {
      "Green": false
    },
    "Slow": {
      "Yellow": false
    },
    "Stop": {
      "Red": true
    }
  }
]

Attributes

The following attributes are supported by this element.

categories

A JSON formatted array of strings, each of which is a category that a worker can assign to the text. You should include "other" as a category, otherwise the worker my not be able to provide an answer.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

name

The name of this widget. It is used as a key for the widget's input in the form output.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: classification-target, full-instructions, short-instructions

Regions

The following regions are supported by this element.

classification-target

The content to be classified by the worker. This can be plain text or HTML. Examples of how the HTML can be used include but are not limited to embedding a video or audio player, embedding a PDF, or performing a comparison of two or more images.

full-instructions

General instructions about how to do text classification.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Output

The output of this element is an object using the specified name value as a property name, and a string from the categories as the property's value.

Example : Sample Element Outputs

The following is a sample of output from this element.


[
  {
    "<name>": {
      "label": "<value>"
    }
  }
]

Attributes

The following attributes are supported by the crowd-classifier-multi-select element. Each attribute accepts a string value or string values.

categories

Required. A JSON-formatted array of strings, each of which is a category that a worker can assign to the object.

header

Required. The text to display above the image. This is typically a question or simple instruction for workers.

name

Required. The name of this widget. In the form output, the name is used as a key for the widget's input.

exclusion-category

Optional. A JSON-formatted string with the following format: "{ text: 'default-value' }". This attribute sets a default value that workers can choose if none of the labels applies to the object shown in the worker UI.

Element Hierarchy

This element has the following parent and child elements:

Parent elements: crowd-form
Child elements: classification-target, full-instructions, short-instructions

Regions

This element uses the following regions.

classification-target

The content to be classified by the worker. Content can be plain text or an object that you specify in the template using HTML. For example, you can use HTML elements to include a video or audio player, embedding a PDF file, or include a comparison of two or more images.

full-instructions

General instructions about how to classify text.

short-instructions

Important task-specific instructions. These instructions are displayed prominently.

Output

The output of this element is an object that uses the specified name value as a property name, and a string from categories as the property's value.

Example : Sample Element Outputs

The following is a sample of output from this element.


[
  {
    "<name>": {
        labels: ["label_a", "label_b"]
    }
  }
]

Attributes

The following attributes are supported by this element.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

initial-value

A JSON formatted array of objects, each of which defines an annotation to apply to the text at initialization. Objects contain a label value that matches one in the labels attribute, an integer startOffset value for labeled span's starting unicode offset, and an integer endOffset value for the ending unicode offset.


[
  {
    label: 'person',
    startOffset: 0,
    endOffset: 16
  },
  ...
]

labels

A JSON formatted array of objects, each of which contains:

label (required): The name used to identify entities.
fullDisplayName (optional): Used for the label list in the task widget. Defaults to the label value if not specified.
shortDisplayName (optional): An abbreviation of 3-4 letters to display above selected entities. Defaults to the label value if not specified.

shortDisplayName is highly recommended
Values displayed above the selections can overlap and create difficulty managing labeled entities in the workspace. Providing a 3-4 character shortDisplayName for each label is highly recommended to prevent overlap and keep the workspace manageable for your workers.


[
  {
    label: 'person',
    shortDisplayName: 'per', 
    fullDisplayName: 'person'
  }
]

name

Serves as the widget's name in the DOM. It is also used as the label attribute name in form output and the output manifest.

text

The text to be annotated. The templating system escapes quotes and HTML strings by default. If your code is already escaped or partially escaped, see Variable filters for more ways to control escaping.

Element Hierarchy

This element has the following parent and child elements.

Child elements: full-instructions, short-instructions

Regions

The following regions are supported by this element.

full-instructions

General instructions about how to work with the widget.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Output

The following output is supported by this element.

entities

A JSON object that specifies the start, end, and label of an annotation. This object contains the following properties.

label – The assigned label.
startOffset – The Unicode offset of the beginning of the selected text.
endOffset – The Unicode offset of the first character after the selection.

Example : Sample Element Outputs

The following is a sample of the output from this element.


{
  "myAnnotatedResult": {
    "entities": [
      {
        "endOffset": 54,
        "label": "person",
        "startOffset": 47
      },
      {
        "endOffset": 97,
        "label": "event",
        "startOffset": 93
      },
      {
        "endOffset": 219,
        "label": "date",
        "startOffset": 212
      },
      {
        "endOffset": 271,
        "label": "location",
        "startOffset": 260
      }
    ]
  }
}

Attributes

The following attributes are supported by this element.

disabled

A Boolean switch that, if present, displays the floating button as disabled and prevents clicks.

icon

A string that specifies the icon to be displayed in the center of the button. The string must be either the name of an icon from the open-source iron-icons set, which is pre-loaded, or the URL to a custom icon.

The following is an example of the syntax that you can use to add an iron-icon to a <crowd-fab> HTML element. Replace icon-name with the name of the icon you'd like to use from this Icons set.


<crowd-fab "id="button1" icon="icon-name" title="Issue"/>

label

A string consisting of a single character that can be used instead of an icon. Emojis or multiple characters may result in the button displaying an ellipsis instead.

title

A string that will display as a tool tip when the mouse hovers over the button.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Element Hierarchy

This element has the following parent and child elements.

Parent elements: none
Child elements: Any of the UI Template elements

Element Events

The crowd-form element extends the standard HTML form element and inherits its events, such as onclick and onsubmit.

Attributes

The following attributes are supported by this element.

disabled

A Boolean switch that, if present, displays the button as disabled and prevents clicks.

icon

The following is an example of the syntax that you can use to add an iron-icon to a <crowd-icon-button> HTML element. Replace icon-name with the name of the icon you'd like to use from this Icons set.


<crowd-icon-button id="button1" icon="icon-name" title="Issue"/>

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Attributes

The following attributes are required by this element.

categories

A JSON formatted array of strings, each of which is a category that a worker can assign to the image. You should include "other" as a category, so that the worker can provide an answer. You can specify up to 10 categories.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

name

The name of this widget. It is used as a key for the widget's input in the form output.

overlay

Information to be overlaid on the source image. This is for verification workflows of bounding-box, semantic-segmentation, and instance-segmentation tasks.

It is a JSON object containing an object with the name of the task-type in camelCase as the key. That key's value is an object that contains the labels and other necessary information from the previous task.

An example of a crowd-image-classifier element with attributes for verifying a bounding-box task follows:


<crowd-image-classifier
    name="boundingBoxClassification"
    header="Rate the quality of the annotations based on the background section 
       in the instructions on the left hand side."
    src="https://i.imgur.com/CIPKVJo.jpg"
    categories="['good', 'bad', 'okay']"
    overlay='{
        "boundingBox": {
            labels: ["bird", "cat"], 
            value: [
                {
                  height: 284,
                  label: "bird",
                  left: 230,
                  top: 974,
                  width: 223
                },
                {
                  height: 69,
                  label: "bird",
                  left: 79,
                  top: 889,
                  width: 247
                }
            ]
        },
    }'
> ... </crowd-image-classifier>

A semantic segmentation verification task would use the overlay value as follows:


<crowd-image-classifier
  name='crowd-image-classifier'
  categories='["good", "bad"]'
  src='URL of image to be classified'
  header='Please classify'
  overlay='{
    "semanticSegmentation": {
      "labels": ["Cat", "Dog", "Bird", "Cow"],
      "labelMappings": {
        "Bird": {
          "color": "#ff7f0e"
        },
        "Cat": {
          "color": "#2ca02c"
        },
        "Cow": {
          "color": "#d62728"
        },
        "Dog": {
          "color": "#2acf59"
        }
      },
      "src": "URL of overlay image",
    }
  }'
> ... </crowd-image-classifier>

An instance-segmentation task would use the overlay value as follows:


<crowd-image-classifier
  name='crowd-image-classifier'
  categories='["good", "bad"]'
  src='URL of image to be classified'
  header='Please classify instances of each category'
  overlay='{
    "instanceSegmentation": {
       "labels": ["Cat", "Dog", "Bird", "Cow"],
       "instances": [
        {
         "color": "#2ca02c",
         "label": "Cat"
        },
        {
         "color": "#1f77b4",
         "label": "Cat"
        },
        {
         "color": "#d62728",
         "label": "Dog"
        }
       ],
       "src": "URL of overlay image",
    }
  }'
> ... </crowd-image-classifier>

src

The URL of the image to be classified.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: full-instructions, short-instructions, worker-comment

Regions

The following regions are used by this element.

full-instructions

General instructions for the worker on how to classify an image.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

worker-comment

Use this in verification workflows when you need workers to explain why they made the choice they did. Use the text between the opening and closing tags to provide instructions for workers on what information should be included in the comment.

It uses the following attributes:

header

A phrase with a call to action for leaving a comment. Used as the title text for a modal window where the comment is added.

Optional. Defaults to "Add a comment."

link-text

This text appears below the categories in the widget. When clicked, it opens a modal window where the worker may add a comment.

Optional. Defaults to "Add a comment."

placeholder

An example text in the comment text area that is overwritten when worker begins to type. This does not appear in output if the worker leaves the field blank.

Optional. Defaults to blank.

Output

The output of this element is a string that specifies one of the values defined in the categories attribute of the <crowd-image-classifier> element.

Example : Sample Element Outputs

The following is a sample of output from this element.


[
  {
    "<name>": {
      "label": "<value>"
      "workerComment": "Comment - if no comment is provided, this field will not be present"
    }
  }
]

Attributes

The following attributes are supported by the crowd-image-classifier-multi-select element. Each attribute accepts a string value or string values.

categories

Required. A JSON-formatted array of strings, each of which is a category that a worker can assign to the image. A worker must choose at least one category and can choose all categories.

header

Required. The text to display above the image. This is typically a question or simple instruction for workers.

name

Required. The name of this widget. In the form output, the name is used as a key for the widget's input.

src

Required. The URL of the image to be classified.

exclusion-category

Element Hierarchy

This element has the following parent and child elements:

Parent elements: crowd-form
Child elements: full-instructions, short-instructions, worker-comment

Regions

This element uses the following regions

full-instructions

General instructions for the worker on how to classify an image.

short-instructions

Important task-specific instructions. These instructions are displayed prominently.

Output

The output of this element is a string that specifies one or more of the values defined in the categories attribute of the <crowd-image-classifier-multi-select> element.

Example : Sample Element Outputs

The following is a sample of output from this element.


[
  {
    "<name>": {
        labels: ["label_a", "label_b"]
    }
  }
]

Attributes

The following attributes are supported by this element.

allowed-pattern

A regular expression that is used with the auto-validate attribute to ignore non-matching characters as the worker types.

auto-focus

When the value is set to true, the browser places focus inside the input area after loading. This way, the worker can start typing without having to select it first.

auto-validate

A Boolean switch that, if present, turns on input validation. The behavior of the validator can be modified by the error-message and allowed-pattern attributes.

disabled

A Boolean switch that, if present, displays the input area as disabled.

error-message

The text to be displayed below the input field, on the left side, if validation fails.

label

A string that is displayed inside a text field.

This text shrinks and rises up above a text field when the worker starts typing in the field or when the value attribute is set.

max-length

A maximum number of characters the input will accept. Input beyond this limit is ignored.

min-length

A minimum length for the input in the field

name

Sets the name of the input to be used in the DOM and the output of the form.

placeholder

A string value that is used as placeholder text, displayed until the worker starts entering data into the input, It is not used as a default value.

required

A Boolean switch that, if present, requires the worker to provide input.

type

Takes a string to set the HTML5 input-type behavior for the input. Examples include file and date.

value

A preset that becomes the default if the worker does not provide input. The preset appears in a text field.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Output

Provides a name string as the property name, and the text that was entered in the field as its value.

Example : Sample JSON Output

The values for multiple elements are output in the same object, with their name attribute value as their property name. Elements with no input do not appear in the output. For example, let's use three inputs:


<crowd-input name="tag1" label="Word/phrase 1"></crowd-input>
<crowd-input name="tag2" label="Word/phrase 2"></crowd-input>
<crowd-input name="tag3" label="Word/phrase 3"></crowd-input>

This is the output if only two have input:


[
  {
    "tag1": "blue",
    "tag2": "red"
  }
]

This means any code built to parse these results should be able to handle the presence or absence of each input in the answers.

Attributes

The following attributes are supported by this element.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

labels

A JSON formatted array of strings, each of which is a label that a worker can assign to an instance of an object in the image. Workers can generate different overlay colors for each relevant instance by selecting "add instance" under the label in the tool.

name

The name of this widget. It is used as a key for the labeling data in the form output.

src

The URL of the image that is to be labeled.

initial-value

A JSON object containing the color mappings of a prior instance segmentation job and a link to the overlay image output by the prior job. Include this when you want a human worker to verify the results of a prior labeling job and adjust it if necessary.

The attribute will appear as follows:


  initial-value="{
    "instances": [
      {
        "color": "#2ca02c",
        "label": "Cat"
      },
      {
        "color": "#1f77b4",
        "label": "Cat"
      },
      {
        "color": "#d62728",
        "label": "Dog"
      }
    ],
    "src": {{ "S3 file URL for image" | grant_read_access }}
  }"

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: full-instructions, short-instructions

Regions

The following regions are supported by this element.

full-instructions

General instructions about how to do image segmentation.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Output

The following output is supported by this element.

labeledImage

A JSON Object containing a Base64 encoded PNG of the labels.

instances

A JSON Array containing objects with the instance labels and colors.

color – The hexadecimal value of the label's RGB color in the labeledImage PNG.
label – The label given to overlay(s) using that color. This value may repeat, because the different instances of the label are identified by their unique color.

inputImageProperties

A JSON object that specifies the dimensions of the image that is being annotated by the worker. This object contains the following properties.

height – The height, in pixels, of the image.
width – The width, in pixels, of the image.

Example : Sample Element Outputs

The following is an example of output from this element.


[
  {
    "annotatedResult": {
      "inputImageProperties": {
        "height": 533,
        "width": 800
      },
      "instances": [
        {
          "color": "#1f77b4",
          "label": "<Label 1>": 
        },
        {
          "color": "#2ca02c",
          "label": "<Label 1>": 
        },
        {
          "color": "#ff7f0e",
          "label": "<Label 3>": 
        },
      ],
      "labeledImage": {
        "pngImageData": "<Base-64 Encoded Data>"
      }
    }
  }
]

Attributes

The following attributes are supported by this element.

link-text

The text to display for opening the instructions. The default is Click for instructions.

link-type

A string that specifies the type of trigger for the instructions. The possible values are "link" (default) and "button".

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Regions

The following regions are supported by this element.

detailed-instructions

Content that provides specific instructions for a task. This appears on the page of the "Detailed Instructions" tab.

negative-example

Content that provides examples of inadequate task completion. This appears on the page of the "Examples" tab. More than one example may be provided within this element.

positive-example

Content that provides examples of proper task completion. This appears on the page of the "Examples" tab.

short-summary

A brief statement that summarizes the task to be completed. This appears on the page of the "Summary" tab. More than one example may be provided within this element.

Attributes

The following attributes are supported by this element.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

initial-value

An array, in JSON format, of keypoints to be applied to the image on start. For example:


initial-value="[
  {
    'label': 'Left Eye',
    'x': 1022,
    'y': 429
  },
  {
    'label': 'Beak',
    'x': 941,
    'y': 403
  }
]

Note

Please note that label values used in this attribute must have a matching value in the labels attribute or the point will not be rendered.

labels

An array, in JSON format, of strings to be used as keypoint annotation labels.

name

A string used to identify the answer submitted by the worker. This value will match a key in the JSON object that specifies the answer.

src

The source URI of the image to be annotated.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: full-instructions, short-instructions

Regions

The following regions are required by this element.

full-instructions

General instructions about how to annotate the image.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Output

The following output is supported by this element.

inputImageProperties

A JSON object that specifies the dimensions of the image that is being annotated by the worker. This object contains the following properties.

height – The height, in pixels, of the image.
width – The width, in pixels, of the image.

keypoints

An array of JSON objects containing the coordinates and label of a keypoint. Each object contains the following properties.

label – The assigned label for the keypoint.
x – The X coordinate, in pixels, of the keypoint on the image.
y – The Y coordinate, in pixels, of the keypoint on the image.

Note

X and Y coordinates are based on 0,0 being the top left corner of the image.

Example : Sample Element Outputs

The following is a sample output from using this element.


[
  {
    "crowdKeypoint": {
      "inputImageProperties": {
        "height": 1314,
        "width": 962
      },
      "keypoints": [
        {
          "label": "dog",
          "x": 155,
          "y": 275
        },
        {
          "label": "cat",
          "x": 341,
          "y": 447
        },
        {
          "label": "cat",
          "x": 491,
          "y": 513
        },
        {
          "label": "dog",
          "x": 714,
          "y": 578
        },
        {
          "label": "cat",
          "x": 712,
          "y": 763
        },
        {
          "label": "cat",
          "x": 397,
          "y": 814
        }
      ]
    }
  }
]

You may have many labels available, but only the ones that are used appear in the output.

Attributes

The following attributes are supported by this element.

header

Optional. The text to display above the image. This is typically a question or simple instruction for the worker.

initial-value

Optional. An array of JSON objects, each of which sets a line when the component is loaded. Each JSON object in the array contains the following properties:

label – The text assigned to the line as part of the labeling task. This text must match one of the labels defined in the labels attribute of the <crowd-line> element.
vertices – the x and y pixel corrdinates of the start point and end point of the line, relative to the top-left corner of the image.


initial-value="{
    lines: [
    {
        label: 'sideline', // label of this line annotation
        vertices:[         // an array of vertices which decide the position of the line
        {
            x: 84,
            y: 110
        },
        {
            x: 60,
            y: 100
        }
        ]
    },
    {
        label: 'yardline',
        vertices:[       
        {
            x: 651,
            y: 498
        },
        {
            x: 862,
            y: 869
        }
        ]
    }
   ]
}"

Lines set via the initial-value property can be adjusted. Whether or not a worker answer was adjusted is tracked via an initialValueModified boolean in the worker answer output.

labels

Required. A JSON formatted array of strings, each of which is a label that a worker can assign to the line.

Limit: 10 labels

label-colors

Optional. An array of strings. Each string is a hexadecimal (hex) code for a label.

name

Required. The name of this widget. It's used as a key for the widget's input in the form output.

src

Required. The URL of the image on which to draw lines.

Regions

The following regions are required by this element.

full-instructions

General instructions about how to draw lines.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: short-instructions, full-instructions

Output

inputImageProperties

A JSON object that specifies the dimensions of the image that is being annotated by the worker. This object contains the following properties.

height – The height, in pixels, of the image.
width – The width, in pixels, of the image.

lines

A JSON Array containing objects with the line labels and vertices.

label – The label given to a line.
vertices – the x and y pixel corrdinates of the start point and end point of the line, relative to the top-left corner of the image.

Example : Sample Element Outputs

The following is an example of output from this element.


{
    "crowdLine": { //This is the name you set for the crowd-line
      "inputImageProperties": {
        "height": 1254,
        "width": 2048
      },
      "lines": [
        {
          "label": "yardline",
          "vertices": [ 
            {
              "x": 58,
              "y": 295
            },
            {
              "x": 1342,
              "y": 398
            }
          ]
        },
        {
          "label": "sideline",
          "vertices": [
            {
              "x": 472,
              "y": 910
            },
            {
              "x": 1480,
              "y": 600
            }
          ]
        }
      ]
    }
  }

Attributes

The following attributes are supported by this element.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

labels

A JSON formatted array of strings, each of which is a label that a worker can assign to the image portion enclosed by a polygon.

name

The name of this widget. It's used as a key for the widget's input in the form output.

src

The URL of the image on which to draw polygons.

initial-value

An array of JSON objects, each of which defines a polygon to be drawn when the component is loaded. Each JSON object in the array contains the following properties.

label – The text assigned to the polygon as part of the labeling task. This text must match one of the labels defined in the labels attribute of the <crowd-polygon> element.
vertices – An array of JSON objects. Each object contains an x and y coordinate value for a point in the polygon.

An initial-value attribute might look something like this.


initial-value = 
  '[
     {
     "label": "dog",
     "vertices": 
       [
         {
            "x": 570,
            "y": 239
         },
        ... 
         {
            "x": 759,
            "y": 281
         }
       ]
     }
  ]'

Because this will be within an HTML element, the JSON array must be enclosed in single or double quotes. The example above uses single quotes to encapsulate the JSON and double quotes within the JSON itself. If you must mix single and double quotes inside your JSON, replace them with their HTML entity codes (" for double quote, ' for single) to safely escape them.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: full-instructions, short-instructions

Regions

The following regions are required.

full-instructions

General instructions about how to draw polygons.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Output

The following output is supported by this element.

polygons

An array of JSON objects, each of which describes a polygon that has been created by the worker. Each JSON object in the array contains the following properties.

label – The text assigned to the polygon as part of the labeling task.
vertices – An array of JSON objects. Each object contains an x and y coordinate value for a point in the polygon. The top left corner of the image is 0,0.

inputImageProperties

A JSON object that specifies the dimensions of the image that is being annotated by the worker. This object contains the following properties.

height – The height, in pixels, of the image.
width – The width, in pixels, of the image.

Example : Sample Element Outputs

The following are samples of outputs from common use scenarios for this element.

Single Label, Single Polygon


{
    "annotatedResult": 
    {
      "inputImageProperties": {
        "height": 853,
        "width": 1280
      },
      "polygons": 
      [
        {
          "label": "dog",
          "vertices": 
          [
            {
              "x": 570,
              "y": 239
            },
            {
              "x": 603,
              "y": 513
            },
            {
              "x": 823,
              "y": 645
            },
            {
              "x": 901,
              "y": 417
            },
            {
              "x": 759,
              "y": 281
            }
          ]
        }
      ]
    }
  }
]

Single Label, Multiple Polygons


[
  {
    "annotatedResult": {
      "inputImageProperties": {
        "height": 853,
        "width": 1280
      },
      "polygons": [
        {
          "label": "dog",
          "vertices": [
            {
              "x": 570,
              "y": 239
            },
            {
              "x": 603,
              "y": 513
            },
            {
              "x": 823,
              "y": 645
            },
            {
              "x": 901,
              "y": 417
            },
            {
              "x": 759,
              "y": 281
            }
          ]
        },
        {
          "label": "dog",
          "vertices": [
            {
              "x": 870,
              "y": 278
            },
            {
              "x": 908,
              "y": 446
            },
            {
              "x": 1009,
              "y": 602
            },
            {
              "x": 1116,
              "y": 519
            },
            {
              "x": 1174,
              "y": 498
            },
            {
              "x": 1227,
              "y": 479
            },
            {
              "x": 1179,
              "y": 405
            },
            {
              "x": 1179,
              "y": 337
            }
          ]
        }
      ]
    }
  }
]

Multiple Labels, Multiple Polygons


[
  {
    "annotatedResult": {
      "inputImageProperties": {
        "height": 853,
        "width": 1280
      },
      "polygons": [
        {
          "label": "dog",
          "vertices": [
            {
              "x": 570,
              "y": 239
            },
            {
              "x": 603,
              "y": 513
            },
            {
              "x": 823,
              "y": 645
            },
            {
              "x": 901,
              "y": 417
            },
            {
              "x": 759,
              "y": 281
            }
          ]
        },
        {
          "label": "cat",
          "vertices": [
            {
              "x": 870,
              "y": 278
            },
            {
              "x": 908,
              "y": 446
            },
            {
              "x": 1009,
              "y": 602
            },
            {
              "x": 1116,
              "y": 519
            },
            {
              "x": 1174,
              "y": 498
            },
            {
              "x": 1227,
              "y": 479
            },
            {
              "x": 1179,
              "y": 405
            },
            {
              "x": 1179,
              "y": 337
            }
          ]
        }
      ]
    }
  }
]

You could have many labels available, but only the ones that are used appear in the output.

Attributes

The following attributes are supported by this element.

header

Optional. The text to display above the image. This is typically a question or simple instruction for the worker.

initial-value

Optional. An array of JSON objects, each of which sets a polyline when the component is loaded. Each JSON object in the array contains the following properties:

label – The text assigned to the polyline as part of the labeling task. This text must match one of the labels defined in the labels attribute of the <crowd-polyline> element.
vertices – the x and y pixel corrdinates of the vertices of a polyline, relative to the top-left corner of the image.


 initial-value= "{
    polylines: [
    {
        label: 'sideline', // label of this line annotation
        vertices:[         // an array of vertices which decide the position of the line
        {
            x: 84,
            y: 110
        },
        {
            x: 60,
            y: 100
        }
        ]
    },
    {
        label: 'yardline',
        vertices:[       
        {
            x: 651,
            y: 498
        },
        {
            x: 862,
            y: 869
        },
        {
            x: 1000,
            y: 869
        }
        ]
    }
   ]
}"

Polylines set via the initial-value property can be adjusted. Whether or not a worker answer was adjusted is tracked via an initialValueModified boolean in the worker answer output.

labels

Required. A JSON formatted array of strings, each of which is a label that a worker can assign to the line.

Limit: 10 labels

label-colors

Optional. An array of strings. Each string is a hexadecimal (hex) code for a label.

name

Required. The name of this widget. It's used as a key for the widget's input in the form output.

src

Required. The URL of the image on which to draw polylines.

Regions

The following regions are required by this element.

full-instructions

General instructions about how to draw polylines.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: short-instructions, full-instructions

Output

inputImageProperties

A JSON object that specifies the dimensions of the image that is being annotated by the worker. This object contains the following properties.

height – The height, in pixels, of the image.
width – The width, in pixels, of the image.

polylines

A JSON Array containing objects with polylines' labels and vertices.

label – The label given to a line.
vertices – the x and y pixel corrdinates of the vertices of a polyline, relative to the top-left corner of the image.

Example : Sample Element Outputs

The following is an example of output from this element.


 {
    "crowdPolyline": { //This is the name you set for the crowd-polyline
      "inputImageProperties": {
        "height": 1254,
        "width": 2048
      },
      "polylines": [
        {
          "label": "sideline",
          "vertices": [
            {
              "x": 651,
              "y": 498
            },
            {
              "x": 862,
              "y": 869
            },
            {
              "x": 1449,
              "y": 611
            }
          ]
        },
        {
          "label": "yardline",
          "vertices": [
            {
              "x": 1148,
              "y": 322
            },
            {
              "x": 1705,
              "y": 474
            },
            ,
            {
              "x": 1755,
              "y": 474
            }
          ]
        }
      ]
    }
  }

Attributes

The following attributes are supported by this element.

checked

A Boolean switch that, if present, displays the radio button as checked.

disabled

A Boolean switch that, if present, displays the button as disabled and prevents it from being checked.

name

A string that is used to identify the answer submitted by the worker. This value will match a key in the JSON object that specifies the answer.

Note

If you use the buttons outside of a crowd-radio-group element, but with the same name string and different value strings, the name object in the output will contain a Boolean value for each value string. To ensure that only one button in a group is selected, make them children of a crowd-radio-group element and use different name values.

value

A property name for the element's boolean value. If not specified, it uses "on" as the default, e.g. { "<name>": { "<value>": <true or false> } }.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-radio-group
Child elements: none

Output

Outputs an object with the following pattern: { "<name>": { "<value>": <true or false> } }. If you use the buttons outside of a crowd-radio-group element, but with the same name string and different value strings, the name object will contain a Boolean value for each value string. To ensure that only one in a group of buttons is selected, make them children of a crowd-radio-group element and use different name values.

Example Sample output of this element


[
  {
    "btn1": {
      "yes": true
    },
    "btn2": {
      "no": false
    }
  }
]

Attributes

No special attributes are supported by this element.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: crowd-radio-button

Output

Outputs an array of objects representing the crowd-radio-button elements within it.

Example Sample of Element Output


[
  {
    "btn1": {
      "yes": true
    },
    "btn2": {
      "no": false
    }
  }
]

Attributes

The following attributes are supported by this element.

header

The text to display above the image. This is typically a question or simple instruction for the worker.

initial-value

A JSON object containing the color mappings of a prior semantic segmentation job and a link to the overlay image output by the prior job. Include this when you want a human worker to verify the results of a prior labeling job and adjust it if necessary.

The attribute would appear as follows:


  initial-value='{
    "labelMappings": {
        "Bird": {
          "color": "#ff7f0e"
        },
        "Cat": {
          "color": "#2ca02c"
        },
        "Cow": {
          "color": "#d62728"
        },
        "Dog": {
          "color": "#1f77b4"
        }
      },
    "src": {{ "S3 file URL for image" | grant_read_access }}
  }'

When using Ground Truth built in task types with annotation consolidation (where more than one worker labels a single image), label mappings are included in individual worker output records, however the overall result is represented as the internal-color-map in the consolidated results.

You can convert the internal-color-map to label-mappings in a custom template using the Liquid templating language:


initial-value="{
  'src' : '{{ task.input.manifestLine.label-attribute-name-from-prior-job| grant_read_access }}',
  'labelMappings': {
     {% for box in task.input.manifestLine.label-attribute-name-from-prior-job-metadata.internal-color-map %}
       {% if box[1]['class-name'] != 'BACKGROUND' %}
         {{ box[1]['class-name'] | to_json }}: {
           'color': {{ box[1]['hex-color'] | to_json }}
         },
       {% endif %} 
     {% endfor %}
   } 
}"

labels

A JSON formatted array of strings, each of which is a label that a worker can assign to a segment of the image.

name

The name of this widget. It is used as a key for the widget's input in the form output.

src

The URL of the image that is to be segmented.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: full-instructions, short-instructions

Regions

The following regions are supported by this element.

full-instructions

General instructions about how to do image segmentation.

short-instructions

Important task-specific instructions that are displayed in a prominent place.

Output

The following output is supported by this element.

labeledImage

A JSON Object containing a Base64 encoded PNG of the labels.

labelMappings

A JSON Object containing objects with named with the segmentation labels.

color – The hexadecimal value of the label's RGB color in the labeledImage PNG.

initialValueModified

A boolean representing whether the initial values have been modified. This is only included when the output is from an adjustment task.

inputImageProperties

A JSON object that specifies the dimensions of the image that is being annotated by the worker. This object contains the following properties.

height – The height, in pixels, of the image.
width – The width, in pixels, of the image.

Example : Sample Element Outputs

The following is a sample of output from this element.


[
  {
    "annotatedResult": {
      "inputImageProperties": {
        "height": 533,
        "width": 800
      },
      "labelMappings": {
        "<Label 2>": {
          "color": "#ff7f0e"
        },
        "<label 3>": {
          "color": "#2ca02c"
        },
        "<label 1>": {
          "color": "#1f77b4"
        }
      },
      "labeledImage": {
        "pngImageData": "<Base-64 Encoded Data>"
      }
    }
  }
]

Attributes

The following attributes are supported by this element.

disabled

A Boolean switch that, if present, displays the slider as disabled.

editable

A Boolean switch that, if present, displays an up/down button that can be chosen to select the value.

Selecting the value via the up/down button is an alternative to selecting the value by moving the knob on the slider. The knob on the slider will move synchronously with the up/down button choices.

max

A number that specifies the maximum value on the slider.

min

A number that specifies the minimum value on the slider.

name

A string that is used to identify the answer submitted by the worker. This value will match a key in the JSON object that specifies the answer.

A Boolean switch that, if present, displays the current value above the knob as the knob is moved.

required

A Boolean switch that, if present, requires the worker to provide input.

secondary-progress

When used with a crowd-slider-secondary-color CSS attribute, the progress bar is colored to the point represented by the secondary-progress. For example, if this was representing the progress on a streaming video, the value would represent where the viewer was in the video timeline. The secondary-progress value would represent the point on the timeline to which the video had buffered.

step

A number that specifies the difference between selectable values on the slider.

value

A preset that becomes the default if the worker does not provide input.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Attributes

The following attributes are supported by this element.

header

The text appearing on the tab. This is usually some short descriptive name indicative of the information contained below the tab.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-tabs
Child elements: none

Attributes

This element has no attributes.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: crowd-tab

Attributes

The following attributes are supported by this element.

allowed-pattern

A regular expression that is used with the auto-validate attribute to ignore non-matching characters as the worker types.

auto-focus

A Boolean switch that, if present, puts the cursor in this element on-load so that users can immediately begin typing without having to click inside the element.

auto-validate

A Boolean switch that, if present, turns on input validation. The behavior of the validator can be modified by the error-message and allowed-pattern attributes.

char-counter

A Boolean switch that, if present, puts a small text field beneath the lower-right corner of the element, displaying the number of characters inside the element.

disabled

A Boolean switch that, if present, displays the input area as disabled.

error-message

The text to be displayed below the input field, on the left side, if validation fails.

label

A string that is displayed inside a text field.

This text shrinks and rises up above a text field when the worker starts typing in the field or when the value attribute is set.

max-length

An integer that specifies the maximum number of characters allowed by the element. Characters typed or pasted beyond the maximum are ignored.

max-rows

An integer that specifies the maximum number of rows of text that are allowed within a crowd-text-area. Normally the element expands to accommodate new rows. If this is set, after the number of rows exceeds it, content scrolls upward out of view and a scrollbar control appears.

name

A string used to represent the element's data in the output.

placeholder

A string presented to the user as placeholder text. It disappears after the user puts something in the input area.

rows

An integer that specifies the height of the element in rows of text.

value

A preset that becomes the default if the worker does not provide input. The preset appears in a text field.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Output

This element outputs the name as a property name and the element's text contents as the value. Carriage returns in the text are represented as \n.

Example Sample output for this element


[
  {
    "textInput1": "This is the text; the text that\nmakes the crowd go wild."
  }
]

Attributes

The following attributes are supported by this element.

duration

A number that specifies the duration, in milliseconds, that the notification appears on the screen.

text

The text to display in the notification.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Attributes

The following attributes are supported by this element.

checked

A Boolean switch that, if present, displays the button switched to the ON position.

disabled

A Boolean switch that, if present, displays the button as disabled and prevents toggling.

invalid

When in an off position, a button using this attribute, will display in an alert color. The standard is red, but may be changed in CSS. When toggled on, the button will display in the same color as other buttons in the on position.

name

A string that is used to identify the answer submitted by the worker. This value matches a key in the JSON object that specifies the answer.

required

A Boolean switch that, if present, requires the worker to provide input.

value

A value used in the output as the property name for the element's Boolean state. Defaults to "on" if not provided.

Element Hierarchy

This element has the following parent and child elements.

Parent elements: crowd-form
Child elements: none

Output

This element outputs the name as the name of an object, containing the value as a property name and the element's state as Boolean value for the property. If no value for the element is specified, the property name defaults to "on."

Example Sample output for this element


[
  {
    "theToggler": {
      "on": true
    }
  }
]

SageMaker Crowd HTML Elements

Attributes

dismissible

type

Element Hierarchy

See Also

Attributes

for

icon

label

Element Hierarchy

See Also

Attributes

disabled

form-action

href

icon

icon-align

icon-url

loading

target

variant

Element Hierarchy

See Also

Attributes

header

initial-value

labels

name

src

Element Hierarchy

Regions

full-instructions

short-instructions

Output

boundingBoxes

inputImageProperties

Example : Sample Element Outputs

See Also

Attributes

heading

image

Element Hierarchy

See Also

Attributes

checked

disabled

name

required

value

Element Hierarchy

Output

Example : Sample Element Outputs

See Also

Attributes

categories

header

name

Element Hierarchy

Regions

classification-target

full-instructions

short-instructions

Output

Example : Sample Element Outputs

See Also

Attributes

categories

header

name

exclusion-category

Element Hierarchy

Regions

classification-target

full-instructions

short-instructions

Output

Example : Sample Element Outputs

See Also

Important: Self-contained Widget