StartLabelDetection リクエスト GetLabelDetection オペレーションレスポンス GetLabelDetection レスポンスの変換

ビデオ内のラベルの検出

Amazon Rekognition Video では、ビデオ内のラベル (オブジェクトと概念) を検出して、ラベルが検出された時刻を表示できます。SDK のコード例については、「Java または Python を使用した、Amazon S3 バケットに保存されたビデオの分析 (SDK)」を参照してください。 AWS CLI 例については、「」を参照してくださいを使用したビデオの分析 AWS Command Line Interface。

Amazon Rekognition Video のラベル検出は、非同期オペレーションです。ビデオ内のラベルの検出を開始するには、StartLabelDetection を呼び出します。

Amazon Rekognition Video は、ビデオ分析の完了ステータスを Amazon Simple Notification Service トピックに発行します。ビデオ分析が成功したら、GetLabelDetection を呼び出して検出されたラベルを取得します。ビデオ分析の API オペレーションの詳細については、「Amazon Rekognition Video オペレーションを呼び出す」を参照してください。

StartLabelDetection リクエスト

以下に StartLabelDetection オペレーションのリクエストの例を示します。Amazon S3 バケットに保存されたビデオを使用して StartLabelDetection オペレーションを行います。リクエスト JSON の例では、Amazon S3 バケットとビデオ名が MinConfidence、Features、Settings、NotificationChannel と共に指定されています。

MinConfidence は、Amazon Rekognition Video がレスポンスで返すことができるようにするための、検出されたラベル、またはインスタンスの境界ボックス (検出された場合) の精度に対する最小限の信頼度です。

Features では、GENERAL_LABELS をレスポンスの一部として返すように指定できます。

Settings では、GENERAL_LABELS で返されるアイテムをフィルタリングできます。ラベルには、包含フィルターと除外フィルターを使用できます。特定のラベル、個別のラベル、またはラベルカテゴリ別にフィルタリングすることもできます。

LabelInclusionFilters - レスポンスに含めるラベルを指定するために使用します。
LabelExclusionFilters - レスポンスから除外するラベルを指定するために使用します。
LabelCategoryInclusionFilters - レスポンスに含めるラベルカテゴリを指定するために使用します。
LabelCategoryExclusionFilters - レスポンスから除外するラベルカテゴリを指定するために使用します。

また、必要に応じて包含フィルターと除外フィルターを組み合わせて、一部のラベルやカテゴリを除外したり、含めたりすることもできます。

NotificationChannel は、Amazon Rekognition Video がラベル検出オペレーションの完了ステータスを公開する Amazon SNS トピックの ARN です。AmazonRekognitionServiceRole 権限ポリシーを使用している場合、Amazon SNS トピックには、Rekognition で始まるトピック名が必要です。

以下は、フィルターを含む JSON 形式の StartLabelDetection リクエストの例です。


{
    "ClientRequestToken": "5a6e690e-c750-460a-9d59-c992e0ec8638",
    "JobTag": "5a6e690e-c750-460a-9d59-c992e0ec8638",
    "Video": {
        "S3Object": {
            "Bucket": "bucket",
            "Name": "video.mp4" 
         } 
     }, 
     "Features": ["GENERAL_LABELS"],
     "MinConfidence": 75,
     "Settings": {
         "GeneralLabels": {
             "LabelInclusionFilters": ["Cat", "Dog"],
             "LabelExclusionFilters": ["Tiger"],
             "LabelCategoryInclusionFilters": ["Animals and Pets"],
             "LabelCategoryExclusionFilters": ["Popular Landmark"] 
         }
     },
     "NotificationChannel": {
         "RoleArn": "arn:aws:iam::012345678910:role/SNSAccessRole",
         "SNSTopicArn": "arn:aws:sns:us-east-1:012345678910:notification-topic",
     }
}

GetLabelDetection オペレーションレスポンス

GetLabelDetection は、ビデオ内で検出されたラベルに関する情報が含まれた配列 (Labels) を返します。配列は、時間または SortBy パラメータを指定したとき検出されたラベルでソートできます。また、AggregateBy パラメータを使用してレスポンス項目の集計方法を選択することもできます。

次は、GetLabelDetection の JSON レスポンス例です。レスポンスで、以下の点に注意してください。

並べ替え順 – 返されるラベルの配列は時刻別にソートされます。ラベル別に並べ替えるには、GetLabelDetection の SortBy 入力パラメータに NAME を指定します。ビデオ内でラベルが複数回表示されている場合、(LabelDetection) 要素のインスタンスが複数存在しています。既定の並べ替え順序は TIMESTAMP で、副次的な並べ替え順序は NAME です。
ラベル情報 – LabelDetection 配列要素には (ラベル) オブジェクトが含まれ、そこにはラベル名と、Amazon Rekognition が検出したラベルの精度に対する信頼度が含まれています。Label オブジェクトには、ラベルの階層分類と、一般的なラベルの境界ボックス情報も含まれます。Timestamp は、ラベルが検出された時間であり、ビデオの開始時刻からの経過ミリ秒数として定義されます。

ラベルに関連付けられているカテゴリやエイリアスに関する情報も返されます。ビデオ SEGMENTS ごとに集計された結果では、StartTimestampMillis、EndTimestampMillis、DurationMillis 構造が返され、それぞれセグメントの開始時間、終了時間、持続時間を定義します。
集計 — 結果が返されたときの集計方法を指定します。デフォルトでは TIMESTAMPS によって集計されます。また、SEGMENTS による集計を選択することもできます。この方法では、時間枠の結果が集計されます。SEGMENTS による集計の場合、境界ボックス付きの検出されたインスタンスに関する情報は返されません。このセグメント中に検出されたラベルのみが返されます。
ページング情報 – この例では、ラベル検出情報が記載された 1 ページを示しています。GetLabelDetection の MaxResults 入力パラメータには、返す LabelDetection オブジェクトの数を指定できます。結果が MaxResults を超える場合、GetLabelDetection は次のページの結果を取得するためのトークン (NextToken) を返します。詳細については、「Amazon Rekognition Video の分析結果を取得する」を参照してください。
ビデオの情報 – レスポンスには、VideoMetadata から返される情報のページごとにビデオ形式に関する情報 (GetLabelDetection) が含まれます。

以下は、TIMESTAMPS による集計を含む JSON 形式の GetLabelDetection レスポンスのサンプルです。


{  
    "JobStatus": "SUCCEEDED",
    "LabelModelVersion": "3.0",
    "Labels": [
        {
            "Timestamp": 1000,
            "Label": {
                "Name": "Car",
                "Categories": [
                  {
                    "Name": "Vehicles and Automotive"
                  }
                ],
                "Aliases": [
                  {
                    "Name": "Automobile"
                  }
                ],
                "Parents": [
                  {
                    "Name": "Vehicle"
                  }
                ],
                "Confidence": 99.9364013671875, // Classification confidence
                "Instances": [    
                    {        
                        "BoundingBox": {            
                            "Width": 0.26779675483703613,
                            "Height": 0.8562285900115967,
                            "Left": 0.3604024350643158,
                            "Top": 0.09245597571134567         
                        },  
                        "Confidence": 99.9364013671875 // Detection confidence     
                    }    
                ]
            }
        },
        {
            "Timestamp": 1000,
            "Label": {
                "Name": "Cup",
                "Categories": [
                  {
                    "Name": "Kitchen and Dining"
                  }
                ],
                "Aliases": [
                  {
                    "Name": "Mug"
                  }
                ],
                "Parents": [],
                "Confidence": 99.9364013671875, // Classification confidence
                "Instances": [    
                    {        
                        "BoundingBox": {            
                            "Width": 0.26779675483703613,
                            "Height": 0.8562285900115967,
                            "Left": 0.3604024350643158,
                            "Top": 0.09245597571134567         
                        },  
                        "Confidence": 99.9364013671875 // Detection confidence     
                    }    
                ]
            }
        },
        {
            "Timestamp": 2000,
            "Label": {
                "Name": "Kangaroo",
                "Categories": [
                  {
                    "Name": "Animals and Pets"
                  }
                ],
                "Aliases": [
                  {
                    "Name": "Wallaby"
                  }
                ],
                "Parents": [
                  {
                    "Name": "Mammal"
                  }
                ],
                "Confidence": 99.9364013671875,  
                "Instances": [    
                    {        
                        "BoundingBox": {            
                            "Width": 0.26779675483703613,
                            "Height": 0.8562285900115967,
                            "Left": 0.3604024350643158,
                            "Top": 0.09245597571134567,
                        },  
                        "Confidence": 99.9364013671875    
                    }    
                ]
            }
        },
        {
            "Timestamp": 4000,
            "Label": {
                "Name": "Bicycle",
                "Categories": [
                  {
                    "Name": "Hobbies and Interests"
                  }
                ],
                "Aliases": [
                  {
                    "Name": "Bike"
                  }
                ],
                "Parents": [
                  {
                    "Name": "Vehicle"
                  }
                ],
                "Confidence": 99.9364013671875,
                "Instances": [    
                    {        
                        "BoundingBox": {            
                            "Width": 0.26779675483703613,
                            "Height": 0.8562285900115967,
                            "Left": 0.3604024350643158,
                            "Top": 0.09245597571134567         
                        },  
                        "Confidence": 99.9364013671875     
                    }    
                ]
            }
        }
    ],
    "VideoMetadata": {
        "ColorRange": "FULL",
        "DurationMillis": 5000,
        "Format": "MP4",
        "FrameWidth": 1280,
        "FrameHeight": 720,
        "FrameRate": 24
    }
}

以下は、SEGMENTS による集計を含む JSON 形式の GetLabelDetection レスポンスのサンプルです。


{  
    "JobStatus": "SUCCEEDED",
    "LabelModelVersion": "3.0",
    "Labels": [ 
        {
            "StartTimestampMillis": 225,
            "EndTimestampMillis": 3578,
            "DurationMillis": 3353,
            "Label": {
                "Name": "Car",
                "Categories": [
                  {
                    "Name": "Vehicles and Automotive"
                  }
                ],
                "Aliases": [
                  {
                    "Name": "Automobile"
                  }
                ],
                "Parents": [
                  {
                    "Name": "Vehicle"
                  }
                ],
                "Confidence": 99.9364013671875 // Maximum confidence score for Segment mode
            }
        },
        {
            "StartTimestampMillis": 7578,
            "EndTimestampMillis": 12371,
            "DurationMillis": 4793,
            "Label": {
                "Name": "Kangaroo",
                "Categories": [
                  {
                    "Name": "Animals and Pets"
                  }
                ],
                "Aliases": [
                  {
                    "Name": "Wallaby"
                  }
                ],
                "Parents": [
                  {
                    "Name": "Mammal"
                  }
                ],
                "Confidence": 99.9364013671875
            }
        },
        {
            "StartTimestampMillis": 22225,
            "EndTimestampMillis": 22578,
            "DurationMillis": 2353,
            "Label": {
                "Name": "Bicycle",
                "Categories": [
                  {
                    "Name": "Hobbies and Interests"
                  }
                ],
                "Aliases": [
                  {
                    "Name": "Bike"
                  }
                ],
                "Parents": [
                  {
                    "Name": "Vehicle"
                  }
                ],
                "Confidence": 99.9364013671875
            }
        }
    ],
    "VideoMetadata": {
        "ColorRange": "FULL",
        "DurationMillis": 5000,
        "Format": "MP4",
        "FrameWidth": 1280,
        "FrameHeight": 720,
        "FrameRate": 24
    }
}

GetLabelDetection レスポンスの変換

GetLabelDetection API オペレーションを実行して結果を取得する場合、プライマリラベルとエイリアスの両方が同じリストに含まれていた古い API レスポンス構造を模倣したレスポンス構造が必要になることがあります。

前のセクションにある JSON レスポンスの例には、GetLabelDetection からの API レスポンスの現在の形式が表示されています。

次の例は、GetLabelDetection API からのレスポンスを示しています。


{
    "Labels": [
        {
            "Timestamp": 0,
            "Label": {
                "Instances": [],
                "Confidence": 60.51791763305664,
                "Parents": [],
                "Name": "Leaf"
            }
        },
        {
            "Timestamp": 0,
            "Label": {
                "Instances": [],
                "Confidence": 99.53411102294922,
                "Parents": [],
                "Name": "Human"
            }
        },
        {
            "Timestamp": 0,
            "Label": {
                "Instances": [
                    {
                        "BoundingBox": {
                            "Width": 0.11109819263219833,
                            "Top": 0.08098889887332916,
                            "Left": 0.8881205320358276,
                            "Height": 0.9073750972747803
                        },
                        "Confidence": 99.5831298828125
                    },
                    {
                        "BoundingBox": {
                            "Width": 0.1268676072359085,
                            "Top": 0.14018426835536957,
                            "Left": 0.0003282368124928324,
                            "Height": 0.7993982434272766
                        },
                        "Confidence": 99.46029663085938
                    }
                ],
                "Confidence": 99.63411102294922,
                "Parents": [],
                "Name": "Person"
            }
        },
        .
        .   
        .

        {
            "Timestamp": 166,
            "Label": {
                "Instances": [],
                "Confidence": 73.6471176147461,
                "Parents": [
                    {
                        "Name": "Clothing"
                    }
                ],
                "Name": "Sleeve"
            }
        }
        
    ],
    "LabelModelVersion": "2.0",
    "JobStatus": "SUCCEEDED",
    "VideoMetadata": {
        "Format": "QuickTime / MOV",
        "FrameRate": 23.976024627685547,
        "Codec": "h264",
        "DurationMillis": 5005,
        "FrameHeight": 674,
        "FrameWidth": 1280
    }
}

必要に応じて、現在のレスポンスを古いレスポンスの形式に従うように変換できます。次のサンプルコードを使用して、最新の API レスポンスを以前の API レスポンス構造に変換できます。


from copy import deepcopy

VIDEO_LABEL_KEY = "Labels"
LABEL_KEY = "Label"
ALIASES_KEY = "Aliases"
INSTANCE_KEY = "Instances"
NAME_KEY = "Name"

#Latest API response sample for AggregatedBy SEGMENTS
EXAMPLE_SEGMENT_OUTPUT = {
    "Labels": [
        {
            "Timestamp": 0,
            "Label":{
                "Name": "Person",
                "Confidence": 97.530106,
                "Parents": [],
                "Aliases": [
                    {
                        "Name": "Human"
                    },
                ],
                "Categories": [
                    {
                        "Name": "Person Description"
                    }
                ],
            },
            "StartTimestampMillis": 0,
            "EndTimestampMillis": 500666,
            "DurationMillis": 500666
        },
        {
            "Timestamp": 6400,
            "Label": {
                "Name": "Leaf",
                "Confidence": 89.77790069580078,
                "Parents": [
                    {
                        "Name": "Plant"
                    }
                ],
                "Aliases": [],
                "Categories": [
                    {
                        "Name": "Plants and Flowers"
                    }
                ],

            },
            "StartTimestampMillis": 6400,
            "EndTimestampMillis": 8200,
            "DurationMillis": 1800
        },
    ]
}

#Output example after the transformation for AggregatedBy SEGMENTS
EXPECTED_EXPANDED_SEGMENT_OUTPUT = {
    "Labels": [
        {
            "Timestamp": 0,
            "Label":{
                "Name": "Person",
                "Confidence": 97.530106,
                "Parents": [],
                "Aliases": [
                    {
                        "Name": "Human"
                    },
                ],
                "Categories": [
                    {
                        "Name": "Person Description"
                    }
                ],
            },
            "StartTimestampMillis": 0,
            "EndTimestampMillis": 500666,
            "DurationMillis": 500666
        },
        {
            "Timestamp": 6400,
            "Label": {
                "Name": "Leaf",
                "Confidence": 89.77790069580078,
                "Parents": [
                    {
                        "Name": "Plant"
                    }
                ],
                "Aliases": [],
                "Categories": [
                    {
                        "Name": "Plants and Flowers"
                    }
                ],

            },
            "StartTimestampMillis": 6400,
            "EndTimestampMillis": 8200,
            "DurationMillis": 1800
        },
        {
            "Timestamp": 0,
            "Label":{
                "Name": "Human",
                "Confidence": 97.530106,
                "Parents": [],
                "Categories": [
                    {
                        "Name": "Person Description"
                    }
                ],
            },
            "StartTimestampMillis": 0,
            "EndTimestampMillis": 500666,
            "DurationMillis": 500666
        },
    ]
}

#Latest API response sample for AggregatedBy TIMESTAMPS
EXAMPLE_TIMESTAMP_OUTPUT = {
    "Labels": [
        {
            "Timestamp": 0,
            "Label": {
                "Name": "Person",
                "Confidence": 97.530106,
                "Instances": [
                    {
                        "BoundingBox": {
                            "Height": 0.1549897,
                            "Width": 0.07747964,
                            "Top": 0.50858885,
                            "Left": 0.00018205095
                        },
                        "Confidence": 97.530106
                    },
                ],
                "Parents": [],
                "Aliases": [
                    {
                        "Name": "Human"
                    },
                ],
                "Categories": [
                    {
                        "Name": "Person Description"
                    }
                ],
            },
        },
        {
            "Timestamp": 6400,
            "Label": {
                "Name": "Leaf",
                "Confidence": 89.77790069580078,
                "Instances": [],
                "Parents": [
                    {
                        "Name": "Plant"
                    }
                ],
                "Aliases": [],
                "Categories": [
                    {
                        "Name": "Plants and Flowers"
                    }
                ],
            },
        },
    ]
}

#Output example after the transformation for AggregatedBy TIMESTAMPS
EXPECTED_EXPANDED_TIMESTAMP_OUTPUT = {
    "Labels": [
        {
            "Timestamp": 0,
            "Label": {
                "Name": "Person",
                "Confidence": 97.530106,
                "Instances": [
                    {
                        "BoundingBox": {
                            "Height": 0.1549897,
                            "Width": 0.07747964,
                            "Top": 0.50858885,
                            "Left": 0.00018205095
                        },
                        "Confidence": 97.530106
                    },
                ],
                "Parents": [],
                "Aliases": [
                    {
                        "Name": "Human"
                    },
                ],
                "Categories": [
                    {
                        "Name": "Person Description"
                    }
                ],
            },
        },
        {
            "Timestamp": 6400,
            "Label": {
                "Name": "Leaf",
                "Confidence": 89.77790069580078,
                "Instances": [],
                "Parents": [
                    {
                        "Name": "Plant"
                    }
                ],
                "Aliases": [],
                "Categories": [
                    {
                        "Name": "Plants and Flowers"
                    }
                ],
            },
        },
        {
            "Timestamp": 0,
            "Label": {
                "Name": "Human",
                "Confidence": 97.530106,
                "Parents": [],
                "Categories": [
                    {
                        "Name": "Person Description"
                    }
                ],
            },
        },
    ]
}

def expand_aliases(inferenceOutputsWithAliases):

    if VIDEO_LABEL_KEY in inferenceOutputsWithAliases:
        expandInferenceOutputs = []
        for segmentLabelDict in inferenceOutputsWithAliases[VIDEO_LABEL_KEY]:
            primaryLabelDict = segmentLabelDict[LABEL_KEY]
            if ALIASES_KEY in primaryLabelDict:
                for alias in primaryLabelDict[ALIASES_KEY]:
                    aliasLabelDict = deepcopy(segmentLabelDict)
                    aliasLabelDict[LABEL_KEY][NAME_KEY] = alias[NAME_KEY]
                    del aliasLabelDict[LABEL_KEY][ALIASES_KEY]
                    if INSTANCE_KEY in aliasLabelDict[LABEL_KEY]:
                        del aliasLabelDict[LABEL_KEY][INSTANCE_KEY]
                    expandInferenceOutputs.append(aliasLabelDict)

        inferenceOutputsWithAliases[VIDEO_LABEL_KEY].extend(expandInferenceOutputs)

    return inferenceOutputsWithAliases


if __name__ == "__main__":

    segmentOutputWithExpandAliases = expand_aliases(EXAMPLE_SEGMENT_OUTPUT)
    assert segmentOutputWithExpandAliases == EXPECTED_EXPANDED_SEGMENT_OUTPUT

    timestampOutputWithExpandAliases = expand_aliases(EXAMPLE_TIMESTAMP_OUTPUT)
    assert timestampOutputWithExpandAliases == EXPECTED_EXPANDED_TIMESTAMP_OUTPUT

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

イメージ内のラベルの検出

ストリーミングビデオイベント内のラベルの検出