поиск-лиц-по-изображению

Описание

Для заданного входного изображения сначала определяется самое большое лицо на изображении, а затем в указанной коллекции ищутся совпадающие лица. Операция сравнивает характеристики лица на входе с лицами в указанной коллекции.

Примечание

Чтобы найти все лица на входном изображении, можно сначала вызвать операцию IndexFaces, а затем использовать идентификаторы лиц, возвращенные в последующих вызовах операции SearchFaces.

Также можно вызвать операцию DetectFaces и использовать прямоугольники на изображении в ответе для создания обрезков лица, которые затем можно передать в операцию SearchFacesByImage.

Вы передаете входное изображение в виде байтов изображения в формате base64 или ссылкой на изображение в ведре Amazon S3. Если вы используете AWS CLI для вызова операций Amazon Rekognition, передача байтов изображения не поддерживается. Изображение должно быть в формате PNG или JPEG.

Ответ возвращает массив совпадающих лиц, упорядоченный по баллам сходства, начиная с самого высокого. Более конкретно, это массив метаданных для каждого найденного совпадения лица. Вместе с метаданными ответ также включает similarity, указывающий, насколько лицо похоже на входное лицо. В ответе операция также возвращает прямоугольник (и уровень уверенности в том, что прямоугольник содержит лицо) лица, которое Amazon Rekognition использовал для входного изображения.

Если на входном изображении не обнаружено ни одного лица, SearchFacesByImage возвращает ошибку InvalidParameterException.

Для примера см. «Поиск лица по изображению» в руководстве разработчика Amazon Rekognition.

Вводной параметр QualityFilter позволяет фильтровать обнаруженные лица, которые не соответствуют требуемому качеству. Критерий качества основан на различных распространенных случаях использования. Используйте QualityFilter, чтобы установить критерий качества для фильтрации, указав LOW, MEDIUM или HIGH. Если вы не хотите фильтровать обнаруженные лица, укажите NONE. Значение по умолчанию — NONE.

Примечание

Для использования фильтрации по качеству вам нужна коллекция, связанная с моделью лица версии 3 или выше. Чтобы узнать версию модели лица, связанную с коллекцией, вызовите DescribeCollection .

Для этой операции необходимы разрешения на выполнение действия rekognition:SearchFacesByImage.

См. также: Документация API AWS

Синтаксис

  search-faces-by-image
--collection-id <value>
[--image <value>]
[--max-faces <value>]
[--face-match-threshold <value>]
[--quality-filter <value>]
[--image-bytes <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]

Параметры

--collection-id (строка)

Идентификатор коллекции для поиска.

--image (структура)

Входное изображение в формате base64 или объект S3. Если вы используете AWS CLI для вызова операций Amazon Rekognition, передача изображений в формате base64 не поддерживается.

Если вы используете AWS SDK для вызова операций Amazon Rekognition, возможно, вам не нужно будет кодировать изображение в base64, передаваемое через поле Bytes. Дополнительную информацию см. в разделе Изображения в руководстве разработчика Amazon Rekognition.

Для указания локального файла используйте --image-bytes вместо этого.

Bytes -> (бинарный блок)

Бинарный блок байтов изображения до 5 МБ. Обратите внимание, что максимальный размер изображения, который вы можете передать в DetectCustomLabels, составляет 4 МБ.

S3Object -> (структура)

Идентифицирует объект S3 как источник изображения.

Bucket -> (строка)

Имя ведра S3.

Name -> (строка)

Имя ключа объекта S3.

Version -> (строка)

Если в ведре включена версия, вы можете указать версию объекта.

Сокращенный синтаксис:

Bytes=blob,S3Object={Bucket=string,Name=string,Version=string}

Синтаксис JSON:

{
  "Bytes": blob,
  "S3Object": {
    "Bucket": "string",
    "Name": "string",
    "Version": "string"
  }
}

--max-faces (целое число)

Максимальное количество лиц для возврата. Операция возвращает максимальное количество лиц с самой высокой уверенностью в совпадении.

--face-match-threshold (вещественное число)

(Необязательно) Устанавливает минимальную уверенность в совпадении лица для возврата. Например, не возвращать совпадения, где уверенность в совпадениях меньше 70%. Значение по умолчанию — 80%.

--quality-filter (строка)

Фильтр, определяющий уровень качества для определения лиц. Отфильтрованные лица не ищутся в коллекции. Если вы укажете AUTO, Amazon Rekognition выберет уровень качества. Если вы укажете LOW, MEDIUM или HIGH, фильтрация удалит все лица, которые не соответствуют выбранному уровню качества. Критерий качества основан на различных распространенных случаях использования. Низкое качество обнаружения может возникать по ряду причин. Некоторые примеры — объект, ошибочно идентифицированный как лицо, лицо, которое слишком размыто, или лицо с слишком экстремальной позой для использования. Если вы укажете NONE, фильтрация не выполняется. Значение по умолчанию — NONE.

Для использования фильтрации по качеству используемая коллекция должна быть связана с моделью лица версии 3 или выше.

Возможные значения:

NONE
AUTO
LOW
MEDIUM
HIGH

--image-bytes (бинарный блок)

Содержимое изображения для загрузки. Для указания содержимого локального файла используйте префикс fileb://. Пример: fileb://image.png

--cli-input-json | --cli-input-yaml (строка) Считывает аргументы из предоставленной строки JSON. Строка JSON соответствует формату, предоставленному --generate-cli-skeleton. Если другие аргументы указаны в командной строке, эти значения переопределят значения, предоставленные в JSON. Невозможно передавать произвольные двоичные значения с помощью предоставленного значения JSON, так как строка будет взята буквально. Это может не быть указано вместе с --cli-input-yaml.

--generate-cli-skeleton (строка) Выводит каркас JSON в стандартный вывод без отправки запроса API. Если указано без значения или со значением input, выводит пример входного JSON, который можно использовать в качестве аргумента для --cli-input-json. Аналогично, если указано yaml-input, выведет пример входного YAML, который можно использовать с --cli-input-yaml. Если указано значение output, он проверит входные данные команды и вернет пример выходного JSON для этой команды. Сгенерированный каркас JSON не является стабильным между версиями AWS CLI, и нет гарантий обратной совместимости в сгенерированном каркасе JSON.

Глобальные параметры

--debug (логическое значение)

Включить отладочную запись журнала.

--endpoint-url (строка)

Переопределить URL по умолчанию команды на указанный URL.

--no-verify-ssl (логическое значение)

По умолчанию AWS CLI использует SSL при общении с AWS-сервисами. Для каждого SSL-соединения AWS CLI проверит SSL-сертификаты. Этот параметр переопределяет поведение по умолчанию проверки SSL-сертификатов.

--no-paginate (логическое значение)

Отключить автоматическую постраничную навигацию. Если автоматическая постраничная навигация отключена, AWS CLI выполнит только один вызов для первой страницы результатов.

--output (строка)

Стиль форматирования для вывода команды.

json
text
table
yaml
yaml-stream

--query (строка)

Запрос JMESPath для фильтрации данных ответа.

--profile (строка)

Использовать определенный профиль из файла учетных данных.

--region (строка)

Регион для использования. Переопределяет настройки конфигурации/среды.

--version (строка)

Отобразить версию этого инструмента.

--color (строка)

Включить/отключить цветной вывод.

on
off
auto

--no-sign-request (логическое значение)

Не подписывать запросы. Учетные данные не будут загружаться, если этот аргумент указан.

--ca-bundle (строка)

Файл с пакетом сертификатов CA для проверки SSL-сертификатов. Переопределяет настройки конфигурации/среды.

--cli-read-timeout (целое число)

Максимальное время чтения сокета в секундах. Если значение установлено в 0, чтение сокета будет блокирующим и не будет иметь таймаута. Значение по умолчанию — 60 секунд.

--cli-connect-timeout (целое число)

Максимальное время подключения к сокету в секундах. Если значение установлено в 0, подключение к сокету будет блокирующим и не будет иметь таймаута. Значение по умолчанию — 60 секунд.

--cli-binary-format (строка)

Стиль форматирования, используемый для двоичных блоков. По умолчанию используется формат base64. Формат base64 ожидает, что двоичные блоки будут предоставлены как закодированная строка base64. Формат raw-in-base64-out сохраняет совместимость с поведением AWS CLI V1, и двоичные значения должны быть переданы буквально. При предоставлении содержимого из файла, отображающего двоичный блок fileb://, всегда будет обрабатываться как двоичный и будет использовать содержимое файла непосредственно независимо от параметра cli-binary-format. При использовании file:// содержимое файла должно быть правильно отформатировано для настроенного cli-binary-format.

base64
raw-in-base64-out

--no-cli-pager (логическое значение)

Отключить вывод страницы CLI.

--cli-auto-prompt (логическое значение)

Автоматически запрашивать параметры входных данных CLI.

--no-cli-auto-prompt (логическое значение)

Отключить автоматическое запрос параметров входных данных CLI.

Примеры

Примечание

Чтобы использовать следующие примеры, необходимо установить и настроить AWS CLI. Дополнительную информацию см. в руководстве «Начало работы» в руководстве пользователя AWS CLI.

Если не указано иное, во всех примерах используются правила цитирования, аналогичные правилам Unix. Эти примеры необходимо адаптировать к правилам цитирования вашей оболочки терминала. См. «Использование кавычек со строками» в руководстве пользователя AWS CLI.

Для поиска лиц в коллекции, соответствующих самому большому лицу на изображении.

Следующая команда search-faces-by-image выполняет поиск лиц в коллекции, соответствующих самому большому лицу на указанном изображении:

aws rekognition search-faces-by-image \
    --image '{"S3Object":{"Bucket":"MyImageS3Bucket","Name":"ExamplePerson.jpg"}}' \
    --collection-id MyFaceImageCollection

{
    "SearchedFaceBoundingBox": {
        "Width": 0.18562500178813934,
        "Top": 0.1618015021085739,
        "Left": 0.5575000047683716,
        "Height": 0.24770642817020416
    },
    "SearchedFaceConfidence": 99.993408203125,
    "FaceMatches": [
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.18562500178813934,
                    "Top": 0.1618019938468933,
                    "Left": 0.5575000047683716,
                    "Height": 0.24770599603652954
                },
                "FaceId": "ce7ed422-2132-4a11-ab14-06c5c410f29f",
                "ExternalImageId": "example-image.jpg",
                "Confidence": 99.99340057373047,
                "ImageId": "8d67061e-90d2-598f-9fbd-29c8497039c0"
            },
            "Similarity": 99.97913360595703
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.18562500178813934,
                    "Top": 0.1618019938468933,
                    "Left": 0.5575000047683716,
                    "Height": 0.24770599603652954
                },
                "FaceId": "13692fe4-990a-4679-b14a-5ac23d135eab",
                "ExternalImageId": "image3.jpg",
                "Confidence": 99.99340057373047,
                "ImageId": "8df18239-9ad1-5acd-a46a-6581ff98f51b"
            },
            "Similarity": 99.97913360595703
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.41499999165534973,
                    "Top": 0.09187500178813934,
                    "Left": 0.28083300590515137,
                    "Height": 0.3112500011920929
                },
                "FaceId": "8d3cfc70-4ba8-4b36-9644-90fba29c2dac",
                "ExternalImageId": "image2.jpg",
                "Confidence": 99.99769592285156,
                "ImageId": "a294da46-2cb1-5cc4-9045-61d7ca567662"
            },
            "Similarity": 99.18069458007812
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.48166701197624207,
                    "Top": 0.20999999344348907,
                    "Left": 0.21250000596046448,
                    "Height": 0.36125001311302185
                },
                "FaceId": "bd4ceb4d-9acc-4ab7-8ef8-1c2d2ba0a66a",
                "ExternalImageId": "image1.jpg",
                "Confidence": 99.99949645996094,
                "ImageId": "5e1a7588-e5a0-5ee3-bd00-c642518dfe3a"
            },
            "Similarity": 98.66607666015625
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.5349419713020325,
                    "Top": 0.29124999046325684,
                    "Left": 0.16389399766921997,
                    "Height": 0.40187498927116394
                },
                "FaceId": "745f7509-b1fa-44e0-8b95-367b1359638a",
                "ExternalImageId": "image9.jpg",
                "Confidence": 99.99979400634766,
                "ImageId": "67a34327-48d1-5179-b042-01e52ccfeada"
            },
            "Similarity": 98.24278259277344
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.5307819843292236,
                    "Top": 0.2862499952316284,
                    "Left": 0.1564060002565384,
                    "Height": 0.3987500071525574
                },
                "FaceId": "2eb5f3fd-e2a9-4b1c-a89f-afa0a518fe06",
                "ExternalImageId": "image10.jpg",
                "Confidence": 99.99970245361328,
                "ImageId": "3c314792-197d-528d-bbb6-798ed012c150"
            },
            "Similarity": 98.10665893554688
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.5074880123138428,
                    "Top": 0.3774999976158142,
                    "Left": 0.18302799761295319,
                    "Height": 0.3812499940395355
                },
                "FaceId": "086261e8-6deb-4bc0-ac73-ab22323cc38d",
                "ExternalImageId": "image6.jpg",
                "Confidence": 99.99930572509766,
                "ImageId": "ae1593b0-a8f6-5e24-a306-abf529e276fa"
            },
            "Similarity": 98.10526275634766
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.5574039816856384,
                    "Top": 0.37187498807907104,
                    "Left": 0.14559100568294525,
                    "Height": 0.4181250035762787
                },
                "FaceId": "11c4bd3c-19c5-4eb8-aecc-24feb93a26e1",
                "ExternalImageId": "image5.jpg",
                "Confidence": 99.99960327148438,
                "ImageId": "80739b4d-883f-5b78-97cf-5124038e26b9"
            },
            "Similarity": 97.94659423828125
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.5773710012435913,
                    "Top": 0.34437501430511475,
                    "Left": 0.12396000325679779,
                    "Height": 0.4337500035762787
                },
                "FaceId": "57189455-42b0-4839-a86c-abda48b13174",
                "ExternalImageId": "image8.jpg",
                "Confidence": 100.0,
                "ImageId": "0aff2f37-e7a2-5dbc-a3a3-4ef6ec18eaa0"
            },
            "Similarity": 97.93476867675781
        }
    ],
    "FaceModelVersion": "3.0"
}

Дополнительную информацию см. в разделе «Поиск лица по изображению» в руководстве разработчика Amazon Rekognition.

Вывод

SearchedFaceBoundingBox -> (структура)

Прямоугольник вокруг лица на входном изображении, используемый Amazon Rekognition для поиска.

Ширина -> (вещественное число)

Ширина прямоугольника как отношение к ширине всего изображения.

Высота -> (вещественное число)

Высота прямоугольника как отношение к высоте всего изображения.

Левый край -> (вещественное число)

Координата левого края прямоугольника как отношение к ширине всего изображения.

Верхний край -> (вещественное число)

Координата верхнего края прямоугольника как отношение к высоте всего изображения.

SearchedFaceConfidence -> (вещественное число)

Уровень уверенности в том, что searchedFaceBoundingBox содержит лицо.

FaceMatches -> (список)

Массив лиц, соответствующих входному лицу, вместе с уверенностью в соответствии.

(структура)

Предоставляет метаданные о лице. Кроме того, предоставляет уровень уверенности в соответствии этого лица с входным лицом.

Сходство -> (вещественное число)

Уверенность в соответствии этого лица с входным лицом.

Лицо -> (структура)

Описывает свойства лица, такие как прямоугольник, идентификатор лица, идентификатор изображения исходного изображения и внешний идентификатор изображения, который вы назначили.

FaceId -> (строка)

Уникальный идентификатор, присвоенный Amazon Rekognition лицу.

BoundingBox -> (структура)

Прямоугольник лица.

Ширина -> (вещественное число)

Ширина прямоугольника как отношение к ширине всего изображения.

Высота -> (вещественное число)

Высота прямоугольника как отношение к высоте всего изображения.

Левый край -> (вещественное число)

Координата левого края прямоугольника как отношение к ширине всего изображения.

Верхний край -> (вещественное число)

Координата верхнего края прямоугольника как отношение к высоте всего изображения.

ImageId -> (строка)

Уникальный идентификатор, присвоенный Amazon Rekognition входному изображению.

ExternalImageId -> (строка)

Идентификатор, который вы назначаете всем лицам на входном изображении.

Уверенность -> (вещественное число)

Уровень уверенности в том, что прямоугольник содержит лицо (а не другой объект, например, дерево).

IndexFacesModelVersion -> (строка)

Версия модели распознавания и хранения лиц, которая использовалась при индексировании вектора лица.

UserId -> (строка)

Уникальный идентификатор, присвоенный пользователю.

FaceModelVersion -> (строка)

Номер версии модели распознавания лиц, связанной с входным набором (CollectionId).