# Create a Labeling Job You can create a labeling job in the Amazon SageMaker AI console and by using an Amazon SDK in your preferred language to run `CreateLabelingJob`. After a labeling job has been created, you can track worker metrics (for private workforces) and your labeling job status using [CloudWatch](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-monitor-cloud-watch.html). Before you create a labeling job it is recommended that you review the following pages, as applicable: + You can specify your input data using an automatic data setup in the console, or an input manifest file in either the console or when using `CreateLabelingJob` API. For automated data setup, see [Automate data setup for labeling jobs](sms-console-create-manifest-file.md). To learn how to create an input manifest file, see [Input manifest files](sms-input-data-input-manifest.md). + Review labeling job input data quotas: [Input Data Quotas](input-data-limits.md). After you have chosen your task type, use the topics on this page to learn how to create a labeling job. If you are a new Ground Truth user, we recommend that you start by walking through the demo in [Getting started: Create a bounding box labeling job with Ground Truth](sms-getting-started.md). **Important** Ground Truth requires all S3 buckets that contain labeling job input image data to have a CORS policy attached. To learn more, see [CORS Requirement for Input Image Data](sms-cors-update.md). **Topics** + [ # Built-in Task Types ](sms-task-types.md) + [ # Create instruction pages ](sms-creating-instruction-pages.md) + [ # Create a Labeling Job (Console) ](sms-create-labeling-job-console.md) + [ # Create a Labeling Job (API) ](sms-create-labeling-job-api.md) + [ # Create a streaming labeling job ](sms-streaming-create-job.md) + [ # Labeling category configuration file with label category and frame attributes reference ](sms-label-cat-config-attributes.md) # Built-in Task Types Amazon SageMaker Ground Truth has several built-in task types. Ground Truth provides a worker task template for built-in task types. Additionally, some built in task types support [Automate data labeling](sms-automated-labeling.md). The following topics describe each built-in task type and demo the worker task templates that are provided by Ground Truth in the console. To learn how to create a labeling job in the console using one of these task types, select the task type page. **** | Label Images | Label Text | Label Videos and Video Frames | Label 3D Point Clouds | | --- | --- | --- | --- | | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/sagemaker/latest/dg/sms-task-types.html) | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/sagemaker/latest/dg/sms-task-types.html) | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/sagemaker/latest/dg/sms-task-types.html) | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/sagemaker/latest/dg/sms-task-types.html) | **Note** Each of the video frame and 3D point cloud task types has an *adjustment* task type that you use to verify and adjust labels from a previous labeling job. Select a video frame or 3D point cloud task type page above to learn how to adjust labels created using that task type. # Create instruction pages Create custom instructions for labeling jobs to improve your worker's accuracy in completing their task. You can modify the default instructions that are provided in the console or you can create your own. The instructions are shown to the worker on the page where they complete their labeling task. There are two kinds of instructions: + *Short instructions*—instructions that are shown on the same webpage where the worker completes their task. These instructions should provide an easy reference to show the worker the correct way to label an object. + *Full instructions*—instructions that are shown on a dialog box that overlays the page where the worker completes their task. We recommend that you provide detailed instructions for completing the task with multiple examples showing edge cases and other difficult situations for labeling objects. Create instructions in the console when you are creating your labeling job. Start with the existing instructions for the task and use the editor to modify them to suit your labeling job. **Note** Once you create your labeling job, it will automatically start and you will not be able to modify your worker instructions. If you need to change your worker instructions, stop the labeling job that you created, clone it, and modify your worker instructions before creating a new job. You can clone a labeling job in the console by selecting the labeling job and then selecting **Clone** in the **Actions** menu. To clone a labeling job using the Amazon SageMaker API or your preferred Amazon SageMaker SDK, make a new request to the `CreateLabelingJob` operation with the same specifications as your original job after modifying your worker instructions. For 3D point cloud and video frame labeling jobs, you can add worker instructions to your label category configuration file. You can use a single string to create instructions or you can add HTML mark up to customize the appearance of your instructions and add images. Make sure that any images you include in your instructions are publicly available, or if your instructions are in Amazon S3, that your workers have read access so that they can view them. For more information about the label category configuration file, see [Labeling category configuration file with label category and frame attributes reference](sms-label-cat-config-attributes.md). ## Short Instructions Short instructions appear on the same web page that workers use to label your data object. For example, the following is the editing page for a bounding box task. The short instructions panel is on the left. ![\[\]](http://docs.amazonaws.cn/en_us/sagemaker/latest/dg/images/sms-instructions-10.png) Keep in mind that a worker will only spend seconds looking at the short instructions. Workers must be able to scan and understand your information quickly. In all cases it should take less time to understand the instructions than it takes to complete the task. Keep these points in mind: + Your instructions should be clear and simple. + Pictures are better than words. Create a simple illustration of your task that your workers can immediately understand. + If you must use words, use short, concise examples. + Your short instructions are more important than your full instructions. The Amazon SageMaker Ground Truth console provides an editor so that you can create your short instructions. Replace the placeholder text and images with instructions for your task. Preview the worker's task page by choosing **Preview**. The preview will open in a new window, be sure to turn off pop-up blocking so that the window will show. ## Full Instructions You can provide additional instructions for your workers in a dialog box that overlays the page where workers label your data objects. Use full instructions to explain more complex tasks and to show workers the proper way to label edge cases or other difficult objects. You can create full instructions using an editor in the Ground Truth console. As with quick instructions, keep the following in mind: + Workers will want detailed instruction the first few times that the complete your task. Any information that they *must* have should be in the quick instructions. + Pictures are more important than words. + Text should be concise. + Full instructions should supplement the short instructions. Don't repeat information that appears in the short instructions. The Ground Truth console provides an editor so that you can create your full instructions. Replace the placeholder text and images with instructions for your task. Preview the full instruction page by choosing **Preview**. The preview will open in a new window, be sure to turn off pop-up blocking so that the window will show. ## Add example images to your instructions Images provide useful examples for your workers. To add a publicly accessible image to your instructions: + Place the cursor where the image should go in the instructions editor. + Click the image icon in the editor toolbar. + Enter the URL of your image. If your instruction image in Amazon S3 is not publicly accessible: + As the image URL, enter: `{{ 'https://s3.amazonaws.com/your-bucket-name/image-file-name' | grant_read_access }}`. + This renders the image URL with a short-lived, one-time access code appended so the worker's browser can display it. A broken image icon is displayed in the instructions editor, but previewing the tool displays the image in the rendered preview. # Create a Labeling Job (Console) You can use the Amazon SageMaker AI console to create a labeling job for all of the Ground Truth built-in task types and custom labeling workflows. For built-in task types, we recommend that you use this page alongside the [page for your task type](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-task-types.html). Each task type page includes specific details on creating a labeling job using that task type. You need to provide the following to create a labeling job in the SageMaker AI console: + An input manifest file in Amazon S3. You can place your input dataset in Amazon S3 and automatically generate a manifest file using the Ground Truth console (not supported for 3D point cloud labeling jobs). Alternatively, you can manually create an input manifest file. To learn how, see [Input data](sms-data-input.md). + An Amazon S3 bucket to store your output data. + An IAM role with permission to access your resources in Amazon S3 and with a SageMaker AI execution policy attached. For a general solution, you can attach the managed policy, AmazonSageMakerFullAccess, to an IAM role and include `sagemaker` in your bucket name. For more granular policies, see [Assign IAM Permissions to Use Ground Truth](sms-security-permission.md). 3D point cloud task types have additional security considerations. [Learn more](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-point-cloud-general-information.html#sms-security-permission-3d-point-cloud). + A work team. You create a work team from a workforce made up of Amazon Mechanical Turk workers, vendors, or your own private workers.To lean more, see [Workforces](sms-workforce-management.md). You cannot use the Mechanical Turk workforce for 3D point cloud or video frame labeling jobs. + If you are using a custom labeling workflow, you must save a worker task template in Amazon S3 and provide an Amazon S3 URI for that template. For more information, see [Creating a custom worker task template](sms-custom-templates-step2.md). + (Optional) An Amazon KMS key ARN if you want SageMaker AI to encrypt the output of your labeling job using your own Amazon KMS encryption key instead of the default Amazon S3 service key. + (Optional) Existing labels for the dataset you use for your labeling job. Use this option if you want workers to adjust, or approve and reject labels. + If you want to create an adjustment or verification labeling job, you must have an output manifest file in Amazon S3 that contains the labels you want adjusted or verified. This option is only supported for bounding box and semantic segmentation image labeling jobs and 3D point cloud and video frame labeling jobs. It is recommended that you use the instructions on [Label verification and adjustment](sms-verification-data.md) to create a verification or adjustment labeling job. **Important** Your work team, input manifest file, output bucket, and other resources in Amazon S3 must be in the same Amazon Region you use to create your labeling job. When you create a labeling job using the SageMaker AI console, you add worker instructions and labels to the worker UI that Ground Truth provides. You can preview and interact with the worker UI while creating your labeling job in the console. You can also see a preview of the worker UI on your [built-in task type page](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-task-types.html). **To create a labeling job (console)** 1. Sign in to the SageMaker AI console at [https://console.amazonaws.cn/sagemaker/](https://console.amazonaws.cn/sagemaker/). 1. In the left navigation pane, choose **Labeling jobs**. 1. On the **Labeling jobs** page, choose **Create labeling job**. 1. For **Job name**, enter a name for your labeling job. 1. (Optional) If you want to identify your labels with a key, select **I want to specify a label attribute name different from the labeling job name**. If you do not select this option, the labeling job name you specified in the previous step will be used to identify your labels in your output manifest file. 1. Choose a data setup to create a connection between your input dataset and Ground Truth. + For **Automated data setup**: + Follow the instructions in [Automate data setup for labeling jobs](sms-console-create-manifest-file.md) for image, text, and video clip labeling jobs. + Follow the instructions in [Set up Automated Video Frame Input Data](sms-video-automated-data-setup.md) for video frame labeling jobs. + For **Manual data setup**: + For **Input dataset location**, provide the location in Amazon S3 in which your input manifest file is located. For example, if your input manifest file, manifest.json, is located in **example-bucket**, enter **s3://example-bucket/manifest.json**. + For **Output dataset location**, provide the location in Amazon S3 where you want Ground Truth to store the output data from your labeling job. 1. For **IAM Role**, choose an existing IAM role or create an IAM role with permission to access your resources in Amazon S3, to write to the output Amazon S3 bucket specified above, and with a SageMaker AI execution policy attached. 1. (Optional) For **Additional configuration**, you can specify how much of your dataset you want workers to label, and if you want SageMaker AI to encrypt the output data for your labeling job using an Amazon KMS encryption key. To encrypt your output data, you must have the required Amazon KMS permissions attached to the IAM role you provided in the previous step. For more details, see [Assign IAM Permissions to Use Ground Truth](sms-security-permission.md). 1. In the **Task type** section, under **Task category**, use the dropdown list to select your task category. 1. In **Task selection**, choose your task type. 1. (Optional) Provide tags for your labeling job to make it easier to find in the console later. 1. Choose **Next**. 1. In the **Workers** section, choose the type of workforce you would like to use. For more details about your workforce options see [Workforces](sms-workforce-management.md). 1. (Optional) After you've selected your workforce, specify the **Task timeout**. This is the maximum amount of time a worker has to work on a task. For 3D point cloud annotation tasks, the default task timeout is 3 days. The default timeout for text and image classification and label verification labeling jobs is 5 minutes. The default timeout for all other labeling jobs is 60 minutes. 1. (Optional) For bounding box, semantic segmentation, video frame, and 3D point cloud task types, you can select **Display existing labels** if you want to display labels for your input data set for workers to verify or adjust. For bounding box and semantic segmentation labeling jobs, this will create an adjustment labeling job. For 3D point cloud and video frame labeling jobs: + Select **Adjustment** to create an adjustment labeling job. When you select this option, you can add new labels but you cannot remove or edit existing labels from the previous job. Optionally, you can choose label category attributes and frame attributes that you want workers to edit. To make an attribute editable, select the check box **Allow workers to edit this attribute** for that attribute. Optionally, you can add new label category and frame attributes. + Select **Verification** to create an adjustment labeling job. When you select this option, you cannot add, modify, or remove existing labels from the previous job. Optionally, you can choose label category attributes and frame attributes that you want workers to edit. To make an attribute editable, select the check box **Allow workers to edit this attribute** for that attribute. We recommend that you can add new label category attributes to the labels that you want workers to verify, or add one or more frame attributes to have workers provide information about the entire frame. For more information, see [Label verification and adjustment](sms-verification-data.md). 1. Configure your workers' UI: + If you are using a [built-in task type](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-task-types.html), specify workers instructions and labels. + For image classification and text classification (single and multi-label) you must specify at least two label categories. For all other built-in task types, you must specify at least one label category. + (Optional) If you are creating a 3D point cloud or video frame labeling job, you can specify label category attributes (not supported for 3D point cloud semantic segmentation) and frame attributes. Label category attributes can be assigned to one or more labels. Frame attributes will appear on each point cloud or video frame workers label. To learn more, see [Worker user interface (UI)](sms-point-cloud-general-information.md#sms-point-cloud-worker-task-ui) for 3D point cloud and [Worker user interface (UI)](sms-video-overview.md#sms-video-worker-task-ui) for video frame. + (Optional) Add **Additional instructions** to help your worker complete your task. + If you are creating a custom labeling workflow you must : + Enter a [custom template](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-custom-templates-step2.html) in the code box. Custom templates can be created using a combination of HTML, the Liquid templating language and our pre-built web components. Optionally, you can choose a base-template from the drop-down menu to get started. + Specify pre-annotation and post-annotation lambda functions. To learn how to create these functions, see [Processing data in a custom labeling workflow with Amazon Lambda](sms-custom-templates-step3.md). 1. (Optional) You can select **See preview** to preview your worker instructions, labels, and interact with the worker UI. Make sure the pop-up blocker of the browser is disabled before generating the preview. 1. Choose **Create**. After you've successfully created your labeling job, you are redirected to the **Labeling jobs** page. The status of the labeling job you just created is **In progress**. This status progressively updates as workers complete your tasks. When all tasks are successfully completed, the status changes to **Completed**. If an issue occurs while creating the labeling job, its status changes to **Failed**. To view more details about the job, choose the labeling job name. ## Next Steps After your labeling job status changes to **Completed**, you can view your output data in the Amazon S3 bucket that you specified while creating that labeling job. For details about the format of your output data, see [Labeling job output data](sms-data-output.md). # Create a Labeling Job (API) To create a labeling job using the Amazon SageMaker API, you use the [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html) operation. For specific instructions on creating a labeling job for a built-in task type, see that [task type page](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-task-types.html). To learn how to create a streaming labeling job, which is a labeling job that runs perpetually, see [Create a streaming labeling job](sms-streaming-create-job.md). To use the `CreateLabelingJob` operation, you need the following: + A worker task template (`UiTemplateS3Uri`) or human task UI ARN (`[HumanTaskUiArn](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_UiConfig.html#sagemaker-Type-UiConfig-HumanTaskUiArn)`) in Amazon S3. + For 3D point cloud jobs, video object detection and tracking jobs, and NER jobs, use the ARN listed in `HumanTaskUiArn` for your task type. + If you are using a built-in task type other than 3D point cloud tasks, you can add your worker instructions to one of the pre-built templates and save the template (using a .html or .liquid extension) in your S3 bucket. Find the pre-build templates on your [task type page](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-task-types.html). + If you are using a custom labeling workflow, you can create a custom template and save the template in your S3 bucket. To learn how to built a custom worker template, see [Creating a custom worker task template](sms-custom-templates-step2.md). For custom HTML elements that you can use to customize your template, see [Crowd HTML Elements Reference](sms-ui-template-reference.md). For a repository of demo templates for a variety of labeling tasks, see [Amazon SageMaker Ground Truth Sample Task UIs ](https://github.com/aws-samples/amazon-sagemaker-ground-truth-task-uis). + An input manifest file that specifies your input data in Amazon S3. Specify the location of your input manifest file in `ManifestS3Uri`. For information about creating an input manifest, see [Input data](sms-data-input.md). If you create a streaming labeling job, this is optional. To learn how to create a streaming labeling job, see [Create a streaming labeling job](sms-streaming-create-job.md). + An Amazon S3 bucket to store your output data. You specify this bucket, and optionally, a prefix in `S3OutputPath`. + A label category configuration file. Each label category name must be unique. Specify the location of this file in Amazon S3 using the `LabelCategoryConfigS3Uri` parameter. The format and label categories for this file depend on the task type you use: + For image classification and text classification (single and multi-label) you must specify at least two label categories. For all other task types, the minimum number of label categories required is one. + For named entity recognition tasks, you must provide worker instructions in this file. See [Provide Worker Instructions in a Label Category Configuration File](sms-named-entity-recg.md#worker-instructions-ner) for details and an example. + For 3D point cloud and video frame task type, use the format in [Labeling category configuration file with label category and frame attributes reference](sms-label-cat-config-attributes.md). + For all other built-in task types and custom tasks, your label category configuration file must be a JSON file in the following format. Identify the labels you want to use by replacing `label_1`, `label_2`,`...`,`label_n` with your label categories. ``` { "document-version": "2018-11-28", "labels": [ {"label": "label_1"}, {"label": "label_2"}, ... {"label": "label_n"} ] } ``` + An Amazon Identity and Access Management (IAM) role with the [AmazonSageMakerGroundTruthExecution](https://console.amazonaws.cn/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerGroundTruthExecution) managed IAM policy attached and with permissions to access your S3 buckets. Specify this role in `RoleArn`. To learn more about this policy, see [Use IAM Managed Policies with Ground Truth](sms-security-permissions-get-started.md). If you require more granular permissions, see [Assign IAM Permissions to Use Ground Truth](sms-security-permission.md). If your input or output bucket name does not contain `sagemaker`, you can attach a policy similar to the following to the role that is passed to the `CreateLabelingJob` operation. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws-cn:s3:::my_input_bucket/*" ] }, { "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws-cn:s3:::my_output_bucket/*" ] } ] } ``` ------ + A pre-annotation and post-annotation (or annotation-consolidation) Amazon Lambda function Amazon Resource Name (ARN) to process your input and output data. + Lambda functions are predefined in each Amazon Region for built-in task types. To find the pre-annotation Lambda ARN for your Region, see [PreHumanTaskLambdaArn](https://docs.amazonaws.cn/sagemaker/latest/dg/API_HumanTaskConfig.html#SageMaker-Type-HumanTaskConfig-PreHumanTaskLambdaArn). To find the annotation-consolidation Lambda ARN for your Region, see [AnnotationConsolidationLambdaArn](https://docs.amazonaws.cn/sagemaker/latest/dg/API_AnnotationConsolidationConfig.html#SageMaker-Type-AnnotationConsolidationConfig-AnnotationConsolidationLambdaArn). + For custom labeling workflows, you must provide a custom pre- and post-annotation Lambda ARN. To learn how to create these Lambda functions, see [Processing data in a custom labeling workflow with Amazon Lambda](sms-custom-templates-step3.md). + A work team ARN that you specify in `WorkteamArn`. You receive a work team ARN when you subscribe to a vendor workforce or create a private workteam. If you are creating a labeling job for a video frame or point cloud task type, you cannot use the Amazon Mechanical Turk workforce. For all other task types, to use the Mechanical Turk workforce, use the following ARN. Replace *`region`* with the Amazon Region you are using to create the labeling job. ` arn:aws:sagemaker:region:394669845002:workteam/public-crowd/default` If you use the [Amazon Mechanical Turk workforce](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-workforce-management-public.html), use the `ContentClassifiers` parameter in `DataAttributes` of `InputConfig` to declare that your content is free of personally identifiable information and adult content. Ground Truth *requires* that your input data is free of personally identifiable information (PII) if you use the Mechanical Turk workforce. If you use Mechanical Turk and do not specify that your input data is free of PII using the `FreeOfPersonallyIdentifiableInformation` flag, your labeling job will fail. Use the `FreeOfAdultContent` flag to declare that your input data is free of adult content. SageMaker AI may restrict the Amazon Mechanical Turk workers that can view your task if it contains adult content. To learn more about work teams and workforces, see [Workforces](sms-workforce-management.md). + If you use the Mechanical Turk workforce, you must specify the price you'll pay workers for performing a single task in `PublicWorkforceTaskPrice`. + To configure the task, you must provide a task description and title using `TaskDescription` and `TaskTitle` respectively. Optionally, you can provide time limits that control how long the workers have to work on an individual task (`TaskTimeLimitInSeconds`) and how long tasks remain in the worker portal, available to workers (`TaskAvailabilityLifetimeInSeconds`). + (Optional) For [some task types](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-annotation-consolidation.html), you can have multiple workers label a single data object by inputting a number greater than one for the `NumberOfHumanWorkersPerDataObject` parameter. For more information about annotation consolidation, see [Annotation consolidation](sms-annotation-consolidation.md). + (Optional) To create an automated data labeling job, specify one of the ARNs listed in [LabelingJobAlgorithmSpecificationArn](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_LabelingJobAlgorithmsConfig.html) in `LabelingJobAlgorithmsConfig`. This ARN identifies the algorithm used in the automated data labeling job. The task type associated with this ARN must match the task type of the `PreHumanTaskLambdaArn` and `AnnotationConsolidationLambdaArn` you specify. Automated data labeling is supported for the following task types: image classification, bounding box, semantic segmentation, and text classification. The minimum number of objects allowed for automated data labeling is 1,250, and we strongly suggest providing a minimum of 5,000 objects. To learn more about automated data labeling jobs, see [Automate data labeling](sms-automated-labeling.md). + (Optional) You can provide [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#API_CreateLabelingJob_RequestSyntax](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#API_CreateLabelingJob_RequestSyntax) that cause the labeling job to stop if one the conditions is met. You can use stopping conditions to control the cost of the labeling job. ## Examples The following code examples demonstrate how to create a labeling job using `CreateLabelingJob`. You can also see these example notebooks on GitHub in the [SageMaker AI Examples repository](https://github.com/aws/amazon-sagemaker-examples/tree/master/ground_truth_labeling_jobs). ------ #### [ Amazon SDK for Python (Boto3) ] The following is an example of an [Amazon Python SDK (Boto3) request](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_labeling_job) to create a labeling job for a built-in task type in the US East (N. Virginia) Region using a private workforce. Replace all *red-italized text* with your labeling job resources and specifications. ``` response = client.create_labeling_job( LabelingJobName="example-labeling-job", LabelAttributeName="label", InputConfig={ 'DataSource': { 'S3DataSource': { 'ManifestS3Uri': "s3://bucket/path/manifest-with-input-data.json" } }, 'DataAttributes': { 'ContentClassifiers': [ "FreeOfPersonallyIdentifiableInformation"|"FreeOfAdultContent", ] } }, OutputConfig={ 'S3OutputPath': "s3://bucket/path/file-to-store-output-data", 'KmsKeyId': "string" }, RoleArn="arn:aws:iam::*:role/*", LabelCategoryConfigS3Uri="s3://bucket/path/label-categories.json", StoppingConditions={ 'MaxHumanLabeledObjectCount': 123, 'MaxPercentageOfInputDatasetLabeled': 123 }, HumanTaskConfig={ 'WorkteamArn': "arn:aws:sagemaker:region:*:workteam/private-crowd/*", 'UiConfig': { 'UiTemplateS3Uri': "s3://bucket/path/custom-worker-task-template.html" }, 'PreHumanTaskLambdaArn': "arn:aws:lambda:us-east-1:432418664414:function:PRE-tasktype", 'TaskKeywords': [ "Images", "Classification", "Multi-label" ], 'TaskTitle': "Multi-label image classification task", 'TaskDescription': "Select all labels that apply to the images shown", 'NumberOfHumanWorkersPerDataObject': 1, 'TaskTimeLimitInSeconds': 3600, 'TaskAvailabilityLifetimeInSeconds': 21600, 'MaxConcurrentTaskCount': 1000, 'AnnotationConsolidationConfig': { 'AnnotationConsolidationLambdaArn': "arn:aws:lambda:us-east-1:432418664414:function:ACS-" }, Tags=[ { 'Key': "string", 'Value': "string" }, ] ) ``` ------ #### [ Amazon CLI ] The following is an example of an Amazon CLI request to create a labeling job for a built-in task type in the US East (N. Virginia) Region using the [Amazon Mechanical Turk workforce](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-workforce-management-public.html). For more information, see [start-human-loop](https://docs.amazonaws.cn/cli/latest/reference/sagemaker/create-labeling-job.html) in the *[Amazon CLI Command Reference](https://docs.amazonaws.cn/cli/latest/reference/)*. Replace all *red-italized text* with your labeling job resources and specifications. ``` $ aws --region us-east-1 sagemaker create-labeling-job \ --labeling-job-name "example-labeling-job" \ --label-attribute-name "label" \ --role-arn "arn:aws:iam::account-id:role/role-name" \ --input-config '{ "DataAttributes": { "ContentClassifiers": [ "FreeOfPersonallyIdentifiableInformation", "FreeOfAdultContent" ] }, "DataSource": { "S3DataSource": { "ManifestS3Uri": "s3://bucket/path/manifest-with-input-data.json" } } }' \ --output-config '{ "KmsKeyId": "", "S3OutputPath": "s3://bucket/path/file-to-store-output-data" }' \ --human-task-config '{ "AnnotationConsolidationConfig": { "AnnotationConsolidationLambdaArn": "arn:aws:lambda:us-east-1:432418664414:function:ACS-" }, "TaskAvailabilityLifetimeInSeconds": 21600, "TaskTimeLimitInSeconds": 3600, "NumberOfHumanWorkersPerDataObject": 1, "PreHumanTaskLambdaArn": "arn:aws:lambda:us-east-1:432418664414:function:PRE-tasktype", "WorkteamArn": "arn:aws:sagemaker:us-east-1:394669845002:workteam/public-crowd/default", "PublicWorkforceTaskPrice": { "AmountInUsd": { "Dollars": 0, "TenthFractionsOfACent": 6, "Cents": 3 } }, "TaskDescription": "Select all labels that apply to the images shown", "MaxConcurrentTaskCount": 1000, "TaskTitle": "Multi-label image classification task",, "TaskKeywords": [ "Images", "Classification", "Multi-label" ], "UiConfig": { "UiTemplateS3Uri": "s3://bucket/path/custom-worker-task-template.html" } }' ``` ------ For more information about this operation, see [CreateLabelingJob](https://docs.amazonaws.cn/sagemaker/latest/dg/API_CreateLabelingJob.html). For information about how to use other language-specific SDKs, see [See Also](https://docs.amazonaws.cn/sagemaker/latest/dg/API_CreateLabelingJob.html#API_CreateLabelingJob_SeeAlso) in the `CreateLabelingJobs` topic. # Create a streaming labeling job Streaming labeling jobs enable you to send individual data objects in real time to a perpetually running, streaming labeling job. To create a streaming labeling job, you can specify the Amazon SNS *input topic* ARN, `SnsTopicArn`, in the `InputConfig` parameter when making a [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html) request. Optionally, you can also create an Amazon SNS *output topic* and specify it in `OutputConfig`if you want to receive label data in real time. **Important** If you are a new user of Ground Truth streaming labeling jobs, it is recommended that you review [Ground Truth streaming labeling jobs](sms-streaming-labeling-job.md) before creating a streaming labeling job. Ground Truth streaming labeling jobs are only supported through the SageMaker API. Use the following sections to create the resources that you need and can use to create a streaming labeling job: + Learn how to create SNS topics with the permissions required for Ground Truth streaming labeling jobs by following the steps in [Use Amazon SNS Topics for Data Labeling](sms-create-sns-input-topic.md). Your SNS topics must be created in the same Amazon Region as your labeling job. + See [Subscribe an Endpoint to Your Amazon SNS Output Topic](sms-create-sns-input-topic.md#sms-streaming-subscribe-output-topic) to learn how to set up an endpoint to receive labeling task output data at a specified endpoint each time a labeling task is completed. + To learn how to configure your Amazon S3 bucket to send notifications to your Amazon SNS input topic, see [Creating Amazon S3 based bucket event notifications based of the Amazon SNS defined in your labeling job](sms-streaming-s3-setup.md). + Optionally, add data objects that you want to have labeled as soon as the labeling job starts to your input manifest. For more information, see [Create a Manifest File (Optional)](sms-streaming-manifest.md). + There are other resources required to create a labeling job, such as an IAM role, Amazon S3 bucket, a worker task template and label categories. These are described in the Ground Truth documentation on creating a labeling job. For more information, see [Create a Labeling Job](sms-create-labeling-job.md). **Important** When you create a labeling job you must provide an IAM execution role. Attach the Amazon managed policy **AmazonSageMakerGroundTruthExecution** to this role to ensure it has required permissions to execute your labeling job. When you submit a request to create a streaming labeling job, the state of your labeling job is `Initializing`. Once the labeling job is active, the state changes to `InProgress`. Do not send new data objects to your labeling job or attempt to stop your labeling job while it is in the `Initializing` state. Once the state changes to `InProgress`, you can start sending new data objects using Amazon SNS and the Amazon S3 configuration. **Topics** + [ # Use Amazon SNS Topics for Data Labeling ](sms-create-sns-input-topic.md) + [ # Creating Amazon S3 based bucket event notifications based of the Amazon SNS defined in your labeling job ](sms-streaming-s3-setup.md) + [ # Create a Manifest File (Optional) ](sms-streaming-manifest.md) + [ # Create a Streaming Labeling Job with the SageMaker API ](sms-streaming-create-labeling-job-api.md) + [ # Stop a Streaming Labeling Job ](sms-streaming-stop-labeling-job.md) # Use Amazon SNS Topics for Data Labeling You need to create an Amazon SNS input to create a streaming labeling job. Optionally, you may provide an Amazon SNS output topic. When you create an Amazon SNS topic to use in your streaming labeling job, note down the topic Amazon Resource Name (ARN). The ARN will be the input values for the parameter `SnsTopicArn` in `InputConfig` and `OutputConfig` when you create a labeling job. ## Create an Input Topic Your input topic is used to send new data objects to Ground Truth. To create an input topic, follow the instructions in [Creating an Amazon SNS topic](https://docs.amazonaws.cn/sns/latest/dg/sns-create-topic.html) in the Amazon Simple Notification Service Developer Guide. Note down your input topic ARN and use it as input for the `CreateLabelingJob` parameter `SnsTopicArn` in `InputConfig`. ## Create an Output Topic If you provide an output topic, it is used to send notifications when a data object is labeled. When you create a topic, you have the option to add an encryption key. Use this option to add a Amazon Key Management Service customer managed key to your topic to encrypt the output data of your labeling job before it is published to your output topic. To create an output topic, follow the instructions in [Creating an Amazon SNS topic](https://docs.amazonaws.cn/sns/latest/dg/sns-create-topic.html) in the Amazon Simple Notification Service Developer Guide. If you add encryption, you must attach additional permission to the topic. See [Add Encryption to Your Output Topic (Optional)](#sms-streaming-encryption). for more information. **Important** To add a customer managed key to your output topic while creating a topic in the console, do not use the **(Default) alias/aws/sns** option. Select a customer managed key that you created. Note down your input topic ARN and use it in your `CreateLabelingJob` request in the parameter `SnsTopicArn` in `OutputConfig`. ### Add Encryption to Your Output Topic (Optional) To encrypt messages published to your output topic, you need to provide an Amazon KMS customer managed key to your topic. Modify the following policy and add it to your customer managed key to give Ground Truth permission to encrypt output data before publishing it to your output topic. Replace *``* with the ID of the account that you are using to create your topic. To learn how to find your Amazon account ID, see [Finding Your Amazon Account ID](https://docs.amazonaws.cn/IAM/latest/UserGuide/console_account-alias.html#FindingYourAWSId). ------ #### [ JSON ] **** ``` { "Id": "key-console-policy", "Version":"2012-10-17", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws-cn:iam::111122223333:root" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": { "AWS": "arn:aws-cn:iam::111122223333:role/Admin" }, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "*" } ] } ``` ------ Additionally, you must modify and add the following policy to the execution role that you use to create your labeling job (the input value for `RoleArn`). Replace *``* with the ID of the account that you are using to create your topic. Replace *``* with the Amazon Region you are using to create your labeling job. Replace `` with your customer managed key ID. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "sid1", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": "arn:aws-cn:kms:us-east-1:111122223333:key/your_key_id" } ] } ``` ------ For more information on creating and securing keys, see [Creating Keys](https://docs.amazonaws.cn/kms/latest/developerguide/create-keys.html) and [Using Key Policies](https://docs.amazonaws.cn/kms/latest/developerguide/key-policies.html) in the Amazon Key Management Service Developer Guide. ## Subscribe an Endpoint to Your Amazon SNS Output Topic When a worker completes a labeling job task from a Ground Truth streaming labeling job, Ground Truth uses your output topic to publish output data to one or more endpoints that you specify. To receive notifications when a worker finishes a labeling task, you must subscribe an endpoint to your Amazon SNS output topic. To learn how to add endpoints to your output topic, see [ Subscribing to an Amazon SNS topic](https://docs.amazonaws.cn/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html) in the *Amazon Simple Notification Service Developer Guide*. To learn more about the output data format that is published to these endpoints, see [Labeling job output data](sms-data-output.md). **Important** If you do not subscribe an endpoint to your Amazon SNS output topic, you will not receive notifications when new data objects are labeled. # Creating Amazon S3 based bucket event notifications based of the Amazon SNS defined in your labeling job Labeling job bucket based notifications Changes to your Amazon S3 bucket, event notifications, are enabled either the Amazon S3 console, API, language specific Amazon SDKs, or the Amazon Command Line Interface. Events must use the same Amazon SNS input topic ARN, `SnsTopicArn`, specified in the `InputConfig` parameter as part of your `CreateLabelingJob` request. **Amazon S3 bucket notifications and your input data should not be the same Amazon S3 bucket** When you create event notifications do not use the same Amazon S3 location that you specified as your `S3OutputPath` in the `OutputConfig` parameters. Linking the two buckets may result in unwanted data objects being processed by Ground Truth for labeling. You control the types of events that you want to send to your Amazon SNS topic. Ground Truth creates a labeling job when you send [object creation events](https://docs.amazonaws.cn/AmazonS3/latest/user-guide/enable-event-notifications.html#enable-event-notifications-types). The event structure sent to your Amazon SNS input topic must be a JSON message formatted using the same structure found in [Event message structure](https://docs.amazonaws.cn/AmazonS3/latest/dev/notification-content-structure.html). To see examples of how you can set up an event notification for your Amazon S3 bucket using the Amazon S3 console, Amazon SDK for .NET, and Amazon SDK for Java, follow this walkthrough,[Walkthrough: Configure a bucket for notifications (SNS topic or SQS queue)](https://docs.amazonaws.cn/AmazonS3/latest/dev/ways-to-add-notification-config-to-bucket.html) in the *Amazon Simple Storage Service User Guide*. Amazon EventBridge notifications are not natively supported. To use EventBridge based notification you must update the output format to match the JSON format used in the [Event message structure](https://docs.amazonaws.cn/AmazonS3/latest/dev/notification-content-structure.html). # Create a Manifest File (Optional) When you create a streaming labeling job, you have the one time option to add objects (such as images or text) to an input manifest file that you specify in `ManifestS3Uri` of `CreateLabelingJob`. When the streaming labeling job starts, these objects are sent to workers or added to the Amazon SQS queue if the total number of objects exceed `MaxConcurrentTaskCount`. The results are added to the Amazon S3 path that you specify when creating the labeling job periodically as workers complete labeling tasks. Output data is sent to any endpoint that you subscribe to your output topic. If you want to provide initial objects to be labeled, create a manifest file that identifies these objects and place it in Amazon S3. Specify the S3 URI of this manifest file in `ManifestS3Uri` within `InputConfig`. To learn how to format your manifest file, see [Input data](sms-data-input.md). To use the SageMaker AI console to automatically generate a manifest file (not supported for 3D point cloud task types), see [Automate data setup for labeling jobs](sms-console-create-manifest-file.md). # Create a Streaming Labeling Job with the SageMaker API The following is an example of an [Amazon Python SDK (Boto3) request](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_labeling_job) that you can use to start a streaming labeling job for a built-in task type in the US East (N. Virginia) Region. For more details about each parameter below see [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html). To learn how you can create a labeling job using this API and associated language specific SDKs, see [Create a Labeling Job (API)](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-create-labeling-job-api.html). In this example, note the following parameters: + `SnsDataSource` – This parameter appears in `InputConfig` and `OutputConfig` and is used to identify your input and output Amazon SNS topics respectively. To create a streaming labeling job, you are required to provide an Amazon SNS input topic. Optionally, you can also provide an Amazon SNS output topic. + `S3DataSource` – This parameter is optional. Use this parameter if you want to include an input manifest file of data objects that you want labeled as soon as the labeling job starts. + [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#sagemaker-CreateLabelingJob-request-StoppingConditions](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#sagemaker-CreateLabelingJob-request-StoppingConditions) – This parameter is ignored when you create a streaming labeling job. To learn more about stopping a streaming labeling job, see [Stop a Streaming Labeling Job](sms-streaming-stop-labeling-job.md). + Streaming labeling jobs do not support automated data labeling. Do not include the `LabelingJobAlgorithmsConfig` parameter. ``` response = client.create_labeling_job( LabelingJobName= 'example-labeling-job', LabelAttributeName='label', InputConfig={ 'DataSource': { 'S3DataSource': { 'ManifestS3Uri': 's3://bucket/path/manifest-with-input-data.json' }, 'SnsDataSource': { 'SnsTopicArn': 'arn:aws:sns:us-east-1:123456789012:your-sns-input-topic' } }, 'DataAttributes': { 'ContentClassifiers': [ 'FreeOfPersonallyIdentifiableInformation'|'FreeOfAdultContent', ] } }, OutputConfig={ 'S3OutputPath': 's3://bucket/path/file-to-store-output-data', 'KmsKeyId': 'string', 'SnsTopicArn': 'arn:aws:sns:us-east-1:123456789012:your-sns-output-topic' }, RoleArn='arn:aws:iam::*:role/*', LabelCategoryConfigS3Uri='s3://bucket/path/label-categories.json', HumanTaskConfig={ 'WorkteamArn': 'arn:aws:sagemaker:us-east-1:*:workteam/private-crowd/*', 'UiConfig': { 'UiTemplateS3Uri': 's3://bucket/path/custom-worker-task-template.html' }, 'PreHumanTaskLambdaArn': 'arn:aws:lambda:us-east-1:432418664414:function:PRE-tasktype', 'TaskKeywords': [ 'Example key word', ], 'TaskTitle': 'Multi-label image classification task', 'TaskDescription': 'Select all labels that apply to the images shown', 'NumberOfHumanWorkersPerDataObject': 123, 'TaskTimeLimitInSeconds': 123, 'TaskAvailabilityLifetimeInSeconds': 123, 'MaxConcurrentTaskCount': 123, 'AnnotationConsolidationConfig': { 'AnnotationConsolidationLambdaArn': 'arn:aws:lambda:us-east-1:432418664414:function:ACS-tasktype' } }, Tags=[ { 'Key': 'string', 'Value': 'string' }, ] ) ``` # Stop a Streaming Labeling Job You can manually stop your streaming labeling job using the operation [StopLabelingJob](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_StopLabelingJob.html). If your labeling job remains idle for over 10 days, it is automatically stopped by Ground Truth. In this context, a labeling job is considered *idle* if no objects are sent to the Amazon SNS input topic and no objects remain in your Amazon SQS queue, waiting to be labeled. For example, if no data objects are fed to the Amazon SNS input topic and all the objects fed to the labeling job are already labeled, Ground Truth starts a timer. After the timer starts, if no items are received within a 10 day period, the labeling job is stopped. When a labeling job is stopped, its status is `STOPPING` while Ground Truth cleans up labeling job resources and unsubscribes your Amazon SNS topic from your Amazon SQS queue. The Amazon SQS is *not* deleted by Ground Truth because this queue may contain unprocessed data objects. You should manually delete the queue if you want to avoid incurring additional charges from Amazon SQS. To learn more, see [Amazon SQS pricing ](https://aws.amazon.com/sqs/pricing/). # Labeling category configuration file with label category and frame attributes reference Label category and frame attributes reference When you create a 3D point cloud or video frame labeling job using the Amazon SageMaker API operation `CreateLabelingJob`, you use a label category configuration file to specify your labels and worker instructions. Optionally, you can also provide the following in your label category attribute file: + You can provide *label category attributes* for video frame and 3D point cloud object tracking and object detection task types. Workers can use one or more attributes to give more information about an object. For example, you may want to use the attribute *occluded* to have workers identify when an object is partially obstructed. You can either specify a label category attribute for a single label using the `categoryAttributes` parameter, or for all labels using the `categoryGlobalAttributes` parameter. + You can provide *frame attributes* for video frame and 3D point cloud object tracking and object detection task types using `frameAttributes`. When you create a frame attribute, it appears on each frame or point cloud in the worker task. In video frame labeling jobs, these are attributes that workers assign to an entire video frame. For 3D point cloud labeling jobs, these attributes are applied to a single point cloud. Use frame attributes to have workers provide more information about the scene in a specific frame or point cloud. + For video frame labeling jobs, you use the label category configuration file to specify the task type (bounding box, polyline, polygon, or keypoint) sent to workers. For workers, specifying values for label category attributes and frame attributes will be optional. **Important** You should only provide a label attribute name in `auditLabelAttributeName` if you are running an audit job to verify or adjust labels. Use this parameter to input the [LabelAttributeName](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#sagemaker-CreateLabelingJob-request-LabelAttributeName) used in the labeling job that generated the annotations you want your worker to adjust. When you create a labeling job in the console, if you did not specify a label attribute name, the **Name** of your job is used as the LabelAttributeName. The following topics show examples of a label category configuration file for different kinds of labeling jobs. They also explain the schema and quotas of a category configuration file. **Topics** + [ ## Examples: label category configuration files for 3D point cloud labeling jobs ](#sms-label-cat-config-attributes-3d-pc) + [ ## Examples: label category configuration files for video frame labeling jobs ](#sms-label-cat-config-attributes-vid-frame) + [ ## Label category configuration file schema ](#sms-label-cat-config-attributes-schema) + [ ## Label and label category attribute quotas ](#sms-point-cloud-label-cat-limits) ## Examples: label category configuration files for 3D point cloud labeling jobs The following topics show examples of 3D point cloud label category configuration files for object detection, object tracking, semantic segmentation, adjustment, and verification labeling jobs. **Topics** + [ ### Example: 3D point cloud object tracking and object detection ](#example-3d-point-cloud-object) + [ ### Example: 3D point cloud semantic segmentation ](#example-3d-point-cloud-semantic) + [ ### Example: 3D point cloud adjustment ](#example-3d-point-cloud-adjustment) + [ ### Example: 3D point cloud verification ](#example-3d-point-cloud-verification) ### Example: 3D point cloud object tracking and object detection The following is an example of a label category configuration file that includes label category attributes for a 3D point cloud object detection or object tracking labeling job. This example includes a two frame attributes, which will be added to all point clouds submitted to the labeling job. The `Car` label will include four label category attributes—`X`, `Y`, `Z`, and the global attribute, `W`. ``` { "documentVersion": "2020-03-01", "frameAttributes": [ { "name":"count players", "description":"How many players to you see in the scene?", "type":"number" }, { "name":"select one", "description":"describe the scene", "type":"string", "enum":["clear","blurry"], "isRequired":true }, ], "categoryGlobalAttributes": [ { "name":"W", "description":"label-attributes-for-all-labels", "type":"string", "enum": ["foo", "buzz", "biz"] } ], "labels": [ { "label": "Car", "categoryAttributes": [ { "name":"X", "description":"enter a number", "type":"number", }, { "name":"Y", "description":"select an option", "type":"string", "enum":["y1", "y2"] }, { "name":"Z", "description":"submit a free-form response", "type":"string", } ] }, { "label": "Pedestrian", "categoryAttributes": [...] } ], "instructions": {"shortInstruction":"Draw a tight Cuboid", "fullInstruction":""} } ``` ### Example: 3D point cloud semantic segmentation The following is an example of a label category configuration file for a 3D point cloud semantic segmentation labeling job. Label category attributes are not supported for 3D point cloud semantic segmentation task types. Frame attributes are supported. If you provide label category attributes for a semantic segmentation labeling job, they will be ignored. ``` { "documentVersion": "2020-03-01", "frameAttributes": [ { "name":"count players", "description":"How many players to you see in the scene?", "type":"number" }, { "name":"select one", "description":"describe the scene", "type":"string", "enum":["clear","blurry"] }, ], "labels": [ { "label": "Car", }, { "label": "Pedestrian", }, { "label": "Cyclist", } ], "instructions": {"shortInstruction":"Select the appropriate label and paint all objects in the point cloud that it applies to the same color", "fullInstruction":""} } ``` ### Example: 3D point cloud adjustment The following is an example of a label category configuration file for a 3D point cloud object detection or object tracking adjustment labeling job. For 3D point cloud semantic segmentation adjustment labeling jobs, `categoryGlobalAttributes` and `categoryAttributes` are not supported. You must include `auditLabelAttributeName` to specify the label attribute name of the previous labeling job that you use to create the adjustment labeling job. Optionally, you can use the `editsAllowed` parameter to specify whether or not a label or frame attribute can be edited. ``` { "documentVersion": "2020-03-01", "frameAttributes": [ { "name":"count players", "description":"How many players to you see in the scene?", "type":"number" }, { "name":"select one", "editsAllowed":"none", "description":"describe the scene", "type":"string", "enum":["clear","blurry"] }, ], "categoryGlobalAttributes": [ { "name":"W", "editsAllowed":"any", "description":"label-attributes-for-all-labels", "type":"string", "enum": ["foo", "buzz", "biz"] } ], "labels": [ { "label": "Car", "editsAllowed":"any", "categoryAttributes": [ { "name":"X", "description":"enter a number", "type":"number" }, { "name":"Y", "description":"select an option", "type":"string", "enum":["y1", "y2"], "editsAllowed":"any" }, { "name":"Z", "description":"submit a free-form response", "type":"string", "editsAllowed":"none" } ] }, { "label": "Pedestrian", "categoryAttributes": [...] } ], "instructions": {"shortInstruction":"Draw a tight Cuboid", "fullInstruction":""}, // include auditLabelAttributeName for label adjustment jobs "auditLabelAttributeName": "myPrevJobLabelAttributeName" } ``` ### Example: 3D point cloud verification The following is an example of a label category configuration file you may use for a 3D point cloud object detection or object tracking verification labeling job. For a 3D point cloud semantic segmentation verification labeling job, `categoryGlobalAttributes` and `categoryAttributes` are not supported. You must include `auditLabelAttributeName` to specify the label attribute name of the previous labeling job that you use to create the verification labeling job. Additionally, you must use the `editsAllowed` parameter to specify that no labels can be edited. ``` { "documentVersion": "2020-03-01", "frameAttributes": [ { "name":"count players", "editsAllowed":"any", "description":"How many players to you see in the scene?", "type":"number" }, { "name":"select one", "editsAllowed":"any", "description":"describe the scene", "type":"string", "enum":["clear","blurry"] }, ], "categoryGlobalAttributes": [ { "name":"W", "editsAllowed":"none", "description":"label-attributes-for-all-labels", "type":"string", "enum": ["foo", "buzz", "biz"] } ], "labels": [ { "label": "Car", "editsAllowed":"none", "categoryAttributes": [ { "name":"X", "description":"enter a number", "type":"number", "editsAllowed":"none" }, { "name":"Y", "description":"select an option", "type":"string", "enum":["y1", "y2"], "editsAllowed":"any" }, { "name":"Z", "description":"submit a free-form response", "type":"string", "editsAllowed":"none" } ] }, { "label": "Pedestrian", "editsAllowed":"none", "categoryAttributes": [...] } ], "instructions": {"shortInstruction":"Draw a tight Cuboid", "fullInstruction":""}, // include auditLabelAttributeName for label verification jobs "auditLabelAttributeName": "myPrevJobLabelAttributeName" } ``` ## Examples: label category configuration files for video frame labeling jobs The annotation tools available to your worker and task type used depends on the value you specify for `annotationType`. For example, if you want workers to use key points to track changes in the pose of specific objects across multiple frames, you would specify `Keypoint` for the `annotationType`. If you do not specify an annotation type, `BoundingBox` will be used by default. The following topics show examples of video frame category configuration files. **Topics** + [ ### Example: video frame keypoint ](#example-video-frame-keypoint) + [ ### Example: video frame adjustment ](#example-video-frame-adjustment) + [ ### Example: video frame verification ](#example-video-frame-verification) ### Example: video frame keypoint The following is an example of a video frame keypoint label category configuration file with label category attributes. This example includes two frame attributes, which will be added to all frames submitted to the labeling job. The `Car` label will include four label category attributes—`X`, `Y`, `Z`, and the global attribute, `W`. ``` { "documentVersion": "2020-03-01", "frameAttributes": [ { "name":"count players", "description":"How many players to you see in the scene?", "type":"number" }, { "name":"select one", "description":"describe the scene", "type":"string", "enum":["clear","blurry"] }, ], "categoryGlobalAttributes": [ { "name":"W", "description":"label-attributes-for-all-labels", "type":"string", "enum": ["foo", "buz", "buz2"] } ], "labels": [ { "label": "Car", "categoryAttributes": [ { "name":"X", "description":"enter a number", "type":"number", }, { "name":"Y", "description":"select an option", "type":"string", "enum": ["y1", "y2"] }, { "name":"Z", "description":"submit a free-form response", "type":"string", } ] }, { "label": "Pedestrian", "categoryAttributes": [...] } ], "annotationType":"Keypoint", "instructions": {"shortInstruction":"add example short instructions here", "fullInstruction":""} } ``` ### Example: video frame adjustment The following is an example of a label category configuration file you may use for a video frame adjustment labeling job. You must include `auditLabelAttributeName` to specify the label attribute name of the previous labeling job that you use to create the verification labeling job. Optionally, you can use the `editsAllowed` parameter to specify whether or not labels, label category attributes, or frame attributes can be edited. ``` { "documentVersion": "2020-03-01", "frameAttributes": [ { "name":"count players", "editsAllowed":"none", "description":"How many players to you see in the scene?", "type":"number" }, { "name":"select one", "description":"describe the scene", "type":"string", "enum":["clear","blurry"] }, ], "categoryGlobalAttributes": [ { "name":"W", "editsAllowed":"any", "description":"label-attributes-for-all-labels", "type":"string", "enum": ["foo", "buz", "buz2"] } ], "labels": [ { "label": "Car", "editsAllowed":"any", "categoryAttributes": [ { "name":"X", "description":"enter a number", "type":"number", "editsAllowed":"any" }, { "name":"Y", "description":"select an option", "type":"string", "enum": ["y1", "y2"], "editsAllowed":"any" }, { "name":"Z", "description":"submit a free-form response", "type":"string", "editsAllowed":"none" } ] }, { "label": "Pedestrian", "editsAllowed":"none", "categoryAttributes": [...] } ], "annotationType":"Keypoint", "instructions": {"shortInstruction":"add example short instructions here", "fullInstruction":""}, // include auditLabelAttributeName for label adjustment jobs "auditLabelAttributeName": "myPrevJobLabelAttributeName" } ``` ### Example: video frame verification The following is an example of a label category configuration file for a video frame labeling job. You must include `auditLabelAttributeName` to specify the label attribute name of the previous labeling job that you use to create the verification labeling job. Additionally, you must use the `editsAllowed` parameter to specify that no labels can be edited. ``` { "documentVersion": "2020-03-01", "frameAttributes": [ { "name":"count players", "editsAllowed":"none", "description":"How many players to you see in the scene?", "type":"number" }, { "name":"select one", "editsAllowed":"any", "description":"describe the scene", "type":"string", "enum":["clear","blurry"] }, ], "categoryGlobalAttributes": [ { "name":"W", "editsAllowed":"none", "description":"label-attributes-for-all-labels", "type":"string", "enum": ["foo", "buz", "buz2"] } ], "labels": [ { "label": "Car", "editsAllowed":"none", "categoryAttributes": [ { "name":"X", "description":"enter a number", "type":"number", "editsAllowed":"any" }, { "name":"Y", "description":"select an option", "type":"string", "enum": ["y1", "y2"], "editsAllowed":"any" }, { "name":"Z", "description":"submit a free-form response", "type":"string", "editsAllowed":"none" } ] }, { "label": "Pedestrian", "editsAllowed":"none", "categoryAttributes": [...] } ], "annotationType":"Keypoint", "instructions": {"shortInstruction":"add example short instructions here", "fullInstruction":""}, // include auditLabelAttributeName for label adjustment jobs "auditLabelAttributeName": "myPrevJobLabelAttributeName" } ``` ## Label category configuration file schema The following table lists elements you can and must include in your label category configuration file. **Note** The parameter `annotationType` is only supported for video frame labeling jobs. **** | Parameter | Required | Accepted Values | Description | | --- | --- | --- | --- | | frameAttributes | No | A list of JSON objects. **Required Parameters in each JSON Object:** `name`, `type`, `description` `minimum` and `maximum` are required if `type` is `"number"` **Optional Parameters in each JSON Object:** `enum`, `editsAllowed`, `isRequired` | Use this parameter to create a frame attribute that is applied to all frames or 3D point clouds in your labeling job.See the third table in this section for more information. | | categoryGlobalAttributes | No | A list of JSON objects. **Required Parameters in each JSON Object:** `name`, `type` `minimum` and `maximum` are required if `type` is `"number"` **Optional Parameters in each JSON Object:** `description`, `enum`, `editsAllowed`, `isRequired` | Use this parameter to create label category attributes that are applied to all labels you specify in `labels`. See the third table in this section for more information. | | labels | Yes | A list of up to 30 JSON objects **Required Parameters in each JSON Object:** `label` **Optional Parameters in each JSON Object:** `categoryAttributes`, `editsAllowed` | Use this parameter to specify your labels, or classes. Add one `label` for each class. To add a label category attribute to a label, add `categoryAttributes` to that label. Use `editsAllowed` to specify whether or not a label can be edited in an adjustment labeling job. Set `editsAllowed` to `"none"` for verification labeling jobs. See the following table for more information. | | annotationType (only supported for video frame labeling jobs) | No | String **Accepted Parameters:** `BoundingBox`, `Polyline`, `Polygon`, `Keypoint` **Default:** `BoundingBox` | Use this to specify the task type for your video frame labeling jobs. For example, for a polygon video frame object detection task, choose `Polygon`. If you do not specify an `annotationType` when you create a video frame labeling job, Ground Truth will use `BoundingBox` by default. | | instructions | No | A JSON objectRequired Parameters in each JSON Object:`"shortInstruction"`, `"fullInstruction"` | Use this parameter to add worker instructions to help your workers complete their tasks. For more information about worker instructions, see [Worker instructions](sms-point-cloud-general-information.md#sms-point-cloud-worker-instructions-general). Short instructions must be under 255 characters and long instruction must be under 2,048 characters. For more information, see [Create instruction pages](sms-creating-instruction-pages.md). | | auditLabelAttributeName | Required for adjustment and verification task types | String | Enter the [LabelAttributeName](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#sagemaker-CreateLabelingJob-request-LabelAttributeName) used in the labeling job you want to adjust annotations of. Only use this parameter if you are creating an adjustment job for video frame and 3D point cloud object detection, object tracking, or 3D point cloud semantic segmentation. | ### Labels object schema The following table describes the parameters that you can and must use to create a list of `Labels`. Each parameter should be included in a JSON object. **** | Parameter | Required | Accepted Values | Description | | --- | --- | --- | --- | | label | Yes | String | The name of the label category that is displayed to workers. Each label category name must be unique. | | categoryAttributes | No | A list of JSON objects. **Required Parameters in each JSON Object:** `name`, `type` `minimum` and `maximum` required if `type` is `"number"` **Optional Parameters in each JSON Object:** `description`, `enum`, `editsAllowed`, `isRequired` | Use this parameter to add label category attributes to specific labels you specify in `labels`. To add one or more label category attributes to a label, include the `categoryAttributes` JSON object in the same `labels` JSON object as that `label`.See the following table for more information. | | editsAllowed | No | String **Supported Values**: `"none"`: no modifications are not allowed. or `"any"` (Default): all modifications are allowed. | Specifies whether or not a label can be edited by workers. For video frame or 3D point cloud *adjustment* labeling jobs, add this parameter to one or more JSON objects in the `labels` list to specify whether or not a worker can edit a label. For 3D point cloud and video frame *verification* labeling jobs, add this parameter with the value `"none"` to each JSON object in the `labels` list. This will make all labels uneditable. | ### frameAttributes and categoryGlobalAttributes schema The following table describes the parameters that you can and must use to create a frame attributes using `frameAttributes` and label category attribute using the `categoryGlobalAttributes` and `categoryAttributes` parameters. **** | Parameter | Required | Accepted Values | Description | | --- | --- | --- | --- | | name | Yes | String | Use this parameter to assign a name to your label category or frame attribute. This is the attribute name that workers see. Each label category attribute name in your label category configuration file must be unique. Global label category attributes and label specific label category attributes cannot have the same name. | | type | Yes | String **Required Values**: `"string"` or `"number"` | Use this parameter to define the label category or frame attribute type. If you specify `"string"` for `type` and provide an `enum` value for this attribute, workers will be able to choose from one of the choices you provide. If you specify `"string"` for `type` and do not provide an `enum` value, workers can enter free form text. If you specify `number` for `type`, worker can enter a number between the `minimum` and `maximum` numbers you specify. | | enum | No | List of strings | Use this parameter to define options that workers can choose from for this label category or frame attribute. Workers can choose one value specified in `enum`. For example, if you specify `["foo", "buzz", "bar"`] for `enum`, workers can choose one of `foo`, `buzz`, or `bar`. You must specify `"string"` for `type` to use an `enum` list. | | description | `frameAttributes`: Yes `categoryAttributes` or `categoryGlobalAttributes`: No | String | Use this parameter to add a description of the label category or frame attribute. You can use this field to give workers more information about the attribute. This field is only required for frame attributes. | | minimum and maximum | Required if attribute type is "number" | Integers | Use these parameters to specify minimum and maximum (inclusive) values workers can enter for numeric label category or frame attributes. You must specify `"number"` for `type` to use `minimum` and `maximum`. | | editsAllowed | No | String **Required Values**: `"none"`: no modifications are not allowed. or `"any"` (Default): all modifications are allowed. | Specifies whether or not a label category or frame attribute can be edited by workers. For video frame or 3D point cloud *adjustment* and *verification* labeling jobs, add this parameter to label category and frame attribute JSON objects to specify whether or not a worker can edit an attribute. | | isRequired | No | Boolean | Specifies whether workers are required to annotate an attribute. Workers cannot submit the job until all required attributes are annotated. | ## Label and label category attribute quotas You can specify up to 10 label category attributes per class. This 10-attribute quotas includes global label category attributes. For example, if you create four global label category attributes, and then assign three label category attributes to label `X`, that label will have 4\$13=7 label category attributes in total. For all label category and label category attribute limits, refer to the following table. **** | Type | Min | Max | | --- | --- | --- | | Labels (`Labels`) | 1 | 30 | | Label name character quota | 1 | 16 | | Label category attributes per label (sum of `categoryAttributes` and `categoryGlobalAttributes`) | 0 | 10 | | Free form text entry label category attributes per label (sum of `categoryAttributes` and `categoryGlobalAttributes`). | 0 | 5 | | Frame attributes | 0 | 10 | | Free form text entry attributes in `frameAttributes`. | 0 | 5 | | Attribute name character quota (`name`) | 1 | 16 | | Attribute description character quota (`description`) | 0 | 128 | | Attribute type characters quota (`type`) | 1 | 16 | | Allowed values in the `enum` list for a `string` attribute | 1 | 10 | | Character quota for a value in `enum` list | 1 | 16 | | Maximum characters in free form text response for free form text frameAttributes | 0 | 1000 | | Maximum characters in free form text response for free form text categoryAttributes and categoryGlobalAttributes | 0 | 80 |