Запись атрибутов метаданных статистики

В таблице ниже резюмируются доступные статистики захвата IMFAttributes для контейнера атрибутов метаданных MFT0 MFSampleExtension_CaptureMetaData, для предварительного просмотра, видеозаписи и захвата изображений.

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

Имя Тип Пин Описание
MF_CAPTURE_METADATA_FOCUSSTATE UINT32 Предварительный просмотр Этот атрибут содержит текущее состояние фокуса, которое может принимать одно из следующих значений.
MF_CAPTURE_METADATA_SENSORFRAMERATE UINT64 Предварительный просмотр Этот атрибут содержит измеряемую скорость чтения датчика в герце при захвате кадра предварительного просмотра, который состоит из числового значения в верхнем 32-разрядном бите и знаменателя в нижнем 32-разрядном разряде.
MF_CAPTURE_METADATA_FACEROIS Комок Предварительный просмотр, видео Этот атрибут содержит информацию о прямоугольнике области лица, обнаруженном драйвером.
MF_CAPTURE_METADATA_FACEROITIMESTAMPS Комок Предварительный просмотр, видео Этот атрибут содержит сведения о метке времени для ПАРАМЕТРОВ распознавания лиц, определенных в MF_CAPTURE_METADATA_FACEROIS.
MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS Комок Предварительный просмотр, видео Этот атрибут содержит состояние мигания и выражения лица для ПАРАМЕТРОВ распознавания лиц, определенных в MF_CAPTURE_METADATA_FACEROIS
MF_CAPTURE_METADATA_EXPOSURE_TIME UINT64 Предварительный просмотр, по-прежнему Этот атрибут содержит время воздействия, примененное в 100 наносекундах
MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION Комок Предварительный просмотр, стоп-кадр Этот атрибут содержит флаг шага компенсации EV и значение компенсации EV в единицах измерения шага, применённых к драйверу при захвате фотографии.
MF_CAPTURE_METADATA_ISO_SPEED UINT32 Предварительный просмотр, по-прежнему Этот атрибут содержит значение скорости ISO, применяемое как целое число.
MF_CAPTURE_METADATA_LENS_POSITION UINT32 Предварительный просмотр, кадр Этот атрибут содержит логическую позицию объектива при применении фокуса к фотоснимку. Это значение не имеет определённой единицы.
MF_CAPTURE_METADATA_SCENE_MODE UINT64 Ещё Этот атрибут содержит режим сцены, применяемый как флаг UINT64KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX.
MF_CAPTURE_METADATA_FLASH UINT32 (boolean) Предварительный просмотр, статичный кадр Этот атрибут содержит логическое значение, содержащее состояние флэш-памяти. Значение 1 указывает, что вспышка включена, а значение 0 указывает, что вспышка отключена для захваченной фотографии.
MF_CAPTURE_METADATA_FLASH_POWER (Мощность вспышки) UINT32 Всё же [Необязательно] Этот атрибут содержит мощность флэш-памяти, применяемую в процентах от 0 до 100.
MF_CAPTURE_METADATA_WHITEBALANCE UINT32 (Кельвин) Предварительный просмотр, статический Этот атрибут содержит белый баланс, применяемый как значение в Келвине.
MF_CAPTURE_METADATA_ZOOMFACTOR UINT32 (Q16) Всё же Этот атрибут содержит примененное значение масштабирования и является тем же значением, которое можно запрашивать из KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM в вызове GET. Значение должно находиться в Q16.
MF_CAPTURE_METADATA_EXIF Комок Всё ещё [Необязательно] Этот атрибут содержит метаданные EXIF, указанные в разделе определения BLOB-объектов
MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID UINT32 По-прежнему [Необязательно] Этот атрибут содержит идентификатор кадра для соответствующего кадра в переменной последовательности фотографий. Этот атрибут задается только для записи переменной последовательности фотографий.
MF_CAPTURE_METADATA_ISO_GAINS Комок Предварительный просмотр Этот атрибут содержит аналоговые и цифровые усиления, применяемые к сенсору при съёмке кадра на предварительном просмотре. Это без единиц измерения.
MF_CAPTURE_METADATA_WHITEBALANCE_GAINS Комок Предварительный просмотр Этот атрибут содержит усиление баланса белого, примененное к R, G, B датчиком и\или ISP во время захвата кадра предварительного просмотра. Это безукоризненный.
MF_CAPTURE_METADATA_HISTOGRAM Комок Предварительный просмотр Этот атрибут содержит гистограмму при захвате кадра предпросмотра.
MF_CAPTURE_METADATA_FRAME_ILLUMINATION UINT64 Пин-код IR, используемый для Hello Этот атрибут для камер IR указывает, используются ли кадры с активной подсветкой IR и должны применяться в сочетании с FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION.
Любой настраиваемый GUID Любой тип варианта Этот атрибут содержит настраиваемые данные, связанные с настраиваемым GUID.

MF_CAPTURE_METADATA_FOCUSSTATE

MF_CAPTURE_METADATA_FOCUSSTATE атрибут содержит текущее состояние фокуса, которое может принимать одно из следующих значений.

typedef enum
{
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_UNINITIALIZED = 0,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_LOST,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_SEARCHING,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FOCUSED,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FAILED,
} KSCAMERA_EXTENDEDPROP_FOCUSSTATE;

MF_CAPTURE_METADATA_SENSORFRAMERATE

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

MF_CAPTURE_METADATA_FACEROIS

Атрибут MF_CAPTURE_METADATA_FACEROIS содержит информацию о прямоугольнике лица, обнаруженную драйвером. По умолчанию driver\MFT0 должен предоставлять сведения о лицах в потоке предварительной версии. Если драйвер объявляет возможность в других потоках, драйвер\MFT должен предоставить сведения о лицах в соответствующих потоках, если приложение включает обнаружение лиц в этих потоках. Если для драйвера включена стабилизация видео, сведения о лицах должны быть предоставлены после стабилизации видео. Структуры данных, приведённые ниже, описывают формат BLOB для MF_CAPTURE_METADATA_FACEROIS. Доминирующее лицо должно быть первым FaceRectInfo в группе данных.

typedef struct tagFaceRectInfoBlobHeader
{
    ULONG Size;             // Size of this header + all FaceRectInfo following
    ULONG Count;            // Number of FaceRectInfo’s in the blob
} FaceRectInfoBlobHeader;

typedef struct tagFaceRectInfo
{
    RECT Region;            // Relative coordinates on the frame that face detection is running (Q31 format)
    LONG ConfidenceLevel;   // Confidence level of the region being a face ([0, 100])
} FaceRectInfo;

Обратите внимание, что структуры FaceRectinfoBlobHeader и FaceRectInfo описывают только формат BLOB-объектов для атрибута MF_CAPTURE_METADATA_FACEROIS. Структура элементов метаданных для областей интереса лиц (KSCAMERA_METADATA_ITEMHEADER + полезные данные метаданных для лиц) определяется драйвером и должна быть выровнена по 8-байтовому границу.

По задумке, если поток настроен с включенным обнаружением лиц, и рассматриваемая сцена не содержит лиц во время захвата, драйвер все равно должен присоединить условный атрибут MF_CAPTURE_METADATA_FACEROIS к каждому образцу, который не имеет связанной с ним информации о лицах. (Атрибут ROI для лица "фиктивный" имеет поле Count структуры FaceRectInfoBlobHeader, равное нулю.)

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

атрибут MF_CAPTURE_METADATA_FACEROITIMESTAMPS содержит сведения о метке времени для ПАРАМЕТРОВ распознавания лиц, определенных в MF_CAPTURE_METADATA_FACEROIS. Для устройства, которое не может предоставить метку времени для областей интереса лиц (ROI), этот атрибут должен быть опущен.

Структура данных ниже описывает формат BLOB для MF_CAPTURE_METADATA_FACEROITIMESTAMPS.

typedef struct tagMetadataTimeStamps
{
    ULONG Flags;            // Bitwise OR of MF_METADATATIMESTAMPS_XXX flags
    LONGLONG Device;        // QPC time for the sample where the face rect is derived from (in 100ns)
    LONGLONG Presentation;  // PTS for the sample where the face rect is derived from (in 100ns)
} MetadataTimeStamps;

Для поля "Флаги" мы определим следующие битовые флаги, чтобы указать, какая метка времени действительна. MFT0 должен задать флаги для MF_METADATATIEMSTAMPS_DEVICE и соответствующее время QPC для устройства, если драйвер предоставляет метаданные метки времени для лицевой роли.

#define MF_METADATATIMESTAMPS_DEVICE 0x00000001

#define MF_METADATATIMESTAMPS_PRESENTATION 0x00000002

Обратите внимание, что структуру MetadataTimeStamps описывает только формат BLOB-объектов для атрибута MF_CAPTURE_METADATA_FACEROITIMESTAMPS. Структура элемента метаданных для метки времени (KSCAMERA_METADATA_ITEMHEADER + полезные данные метаданных метки времени) определяется драйвером и должно быть выровнено по 8 байт.

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS

Атрибут MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS содержит состояние мигания и/или выражения лица для областей лица, определенных в MF_CAPTURE_METADATA_FACEROIS.  Для устройства, которое не поддерживает обнаружение мигающих и\или лицевых выражений, этот атрибут должен быть опущен.

Структура данных ниже описывает формат BLOB для MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS.

Обратите внимание, что структуры FaceCharacterizationBlobHeader и FaceCharacterization описывают только формат BLOB для параметра MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS. Структура элементов метаданных для распознавания лиц (KSCAMERA_METADATA_ITEMHEADER + данные метаданных для распознавания лиц) определяется драйвером и должна быть выровнена по 8 байтам.

typedef struct tagFaceCharacterizationBlobHeader
{
    ULONG Size;     // Size of this header + all FaceCharacterization following
    ULONG Count;    // Number of FaceCharacterization’s in the blob. Must match the number of FaceRectInfo’s in FaceRectInfoBlobHeader
} FaceCharacterizationBlobHeader;

typedef struct tagFaceCharacterization
{
    ULONG BlinkScoreLeft;   // [0, 100]. 0 indicates no blink for the left eye. 100 indicates definite blink for the left eye
    ULONG BlinkScoreRight;  // [0, 100]. 0 indicates no blink for the right eye. 100 indicates definite blink for the right eye
    ULONG FacialExpression; // Any one of the MF_METADATAFACIALEXPRESSION_XXX defined
    ULONG FacialExpressionScore; // [0, 100]. 0 indicates no such facial expression as identified. 100 indicates definite such facial expression as defined
} FaceCharacterization;

Ниже определено возможное выражение лица, которое можно обнаружить.  

#define MF_METADATAFACIALEXPRESSION_SMILE             0x00000001

Если атрибут MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS представлен, число и порядок записей FaceCharacterization в большом двоичном объекте должны соответствовать числу и порядку записей FaceRectInfo в большом двоичном объекте MF_CAPTURE_METADATA_FACEROIS.   Каждая запись FaceCharacterization отражает состояние мигания и/или выражения лица в соответствующей записи FaceRectInfo на том же индексе.

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

MF_CAPTURE_METADATA_EXPOSURE_TIME

MF_CAPTURE_METADATA_EXPOSURE_TIME атрибут содержит время экспозиции, примененное к датчику при предварительном просмотре и/или фотокадре, которая является UINT64 и измеряется в 100 наносекундах.

МЕТАДАННЫЕ_ЗАХВАТА_КОМПЕНСАЦИЯ_ЭКСПОЗИЦИИ

Атрибут MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION содержит флаг шага компенсации экспозиции (EV) и значение компенсации EV, выраженное в единицах шага, которые применяются к датчику во время захвата кадра предварительного просмотра и/или фотографии.

Структура данных ниже описывает формат BLOB для MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION.

typedef struct tagCapturedMetadataExposureCompensation
{
    UINT64 Flags;   // KSCAMERA_EXTENDEDPROP_EVCOMP_XXX step flag
    INT32 Value;    // EV Compensation value in units of the step
} CapturedMetadataExposureCompensation;

Обратите внимание, что структура CapturedMetadataExposureCompensation описывает только бинарный формат для атрибута MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION. Структура элементов метаданных для компенсации EV (KSCAMERA_METADATA_ITEMHEADER + полезные данные метаданных компенсации EV) определяется драйвером и должна быть выровнена по 8 байтам.

MF_CAPTURE_METADATA_ISO_SPEED

Атрибуты MF_CAPTURE_METADATA_ISO_SPEED содержат значение ISO-скорости, примененное к датчику во время предварительного просмотра и/или съемки фото. Это безукоризненный.

MF_CAPTURE_METADATA_ISO_GAINS

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

Структура данных ниже описывает формат BLOB для MF_CAPTURE_METADATA_ISO_GAINS.

typedef struct tagCapturedMetadataISOGains
{
    FLOAT AnalogGain;
    FLOAT DigitalGain;
} CapturedMetadataISOGains;

Обратите внимание, что структура CapturedMetadataISOGains описывает только формат BLOB для атрибута MF_CAPTURE_METADATA_ISO_GAINS. Структура элемента метаданных для усиления ISO (KSCAMERA_METADATA_ITEMHEADER + нагрузка метаданных усиления ISO) определяется драйвером и должна быть выровнена на границу 8 байт.

MF_CAPTURE_METADATA_LENS_POSITION

Атрибут MF_CAPTURE_METADATA_LENS_POSITION содержит логическую позицию объектива при захвате кадра предварительного просмотра и/или фотоснимка, которая является безразмерной. Это то же значение, которое можно запрашивать из KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS в вызове GET.

MF_CAPTURE_METADATA_SCENE_MODE

атрибут MF_CAPTURE_METADATA_SCENE_MODE содержит режим сцены, примененный к фотографии, что представляет собой 64-разрядный флаг KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX.

MF_CAPTURE_METADATA_FLASH

Атрибут MF_CAPTURE_METADATA_FLASH содержит логическое значение при захвате кадра в режиме предварительного просмотра и\или фотографирования, где 1 означает, что вспышка включена, а 0 означает, что вспышка выключена.

МФ_ЗАХВАТ_МЕТАДАННЫХ_МОЩНОСТЬ_ВСПЫШКИ

Атрибут MF_CAPTURE_METADATA_FLASH_POWER содержит мощность вспышки, применяемую к захваченной фотографии, что выражается в значении от 0 до 100. Этот атрибут должен быть опущен, если драйвер не поддерживает настраиваемую мощность для флэш-памяти.

MF_CAPTURE_METADATA_WHITEBALANCE

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

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS

Атрибут MF_CAPTURE_METADATA_WHITEBALANCE_GAINS содержит коэффициенты баланса белого, примененные к R, G, B сенсором и\или ISP при захвате кадра предварительного просмотра. Это безукоризненный.

Структура данных ниже описывает формат BLOB для MF_CAPTURE_METADATA_WHITEBALANCE_GAINS.

typedef struct tagCapturedMetadataWhiteBalanceGains
{
    FLOAT R;
    FLOAT G;
    FLOAT B;
} CapturedMetadataWhiteBalanceGains;

Обратите внимание, что структуру CapturedMetadataWhiteBalanceGains описывает только формат BLOB-объектов для атрибута MF_CAPTURE_METADATA_WHITEBALANCE_GAINS. Структура элементов метаданных для усиления баланса белого (KSCAMERA_METADATA_ITEMHEADER + полезная нагрузка метаданных для усиления баланса белого) определяется драйвером и должна быть выровнена по 8 байт.

MF_CAPTURE_METADATA_ZOOMFACTOR

Атрибут MF_CAPTURE_METADATA_ZOOMFACTOR содержит масштаб, примененный к фотографии; это та же величина, которую можно запросить из KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM при вызове GET. Это должно быть в Q16.

MF_CAPTURE_METADATA_EXIF

MF_CAPTURE_METADATA_EXIF содержит метаданные EXIF, указанные в разделе 3.1 (определение BLOB-объектов). MFT0 должен извлекать необработанные метаданные EXIF, которые определяются как пользовательский элемент метаданных (MetadataId >= MetadataId_Custom_Start), из буфера MF_CAPTURE_METADATA_FRAME_RAWSTREAM, предоставленного драйвером. Затем MFT0 преобразует необработанные данные в атрибут MF_CAPTURE_METADATA_EXIF.

Определение BLOB-объектов

Большой двоичный объект должен состоять из полного заголовка TIFF, "0th IFD" и "EXIF sub-IFD", как определено спецификациями EXIF 2.3 и TIFF 6.0. Блоб не должен содержать никаких данных до заголовка TIFF. BLOB не должен содержать данные после окончания 0-го IFD. Например, недопустимо включить IFD, содержащий данные эскизов.

На следующей схеме, скопированной из спецификации TIFF, показан ожидаемый макет памяти:

определение EXIF BLOB-объекта.

Ниже приведены требования, которые соответствуют спецификациям EXIF и TIFF, но приведены для акцентирования внимания:

  • Порядок байтов должен быть либо little endian ("II"), либо big endian ("MM").
  • Указатели ("смещения байтов" в спецификации TIFF) должны соответствовать началу заголовка TIFF.

Ниже приведены требования, которые являются более строгими, чем спецификации EXIF и TIFF:

  • Смещение к следующему IFD должно иметь значение 0, т. е. дополнительные IFD не указываются.
  • Заголовок TIFF и 0th IFD должны быть смежными, т. е. смещение к 0-му IFD, хранящееся в байтах 4-7, должно быть 0x8.

Обязательные метаданные EXIF

В разделе ниже описаны метаданные EXIF, которые должны быть включены в MF_CAPTURE_METADATA_EXIF.

Имя Тег EXIF Описание
Ориентация 274 Ориентация изображения, просматриваемая с точки зрения строк и столбцов. Полный описание см. в спецификации EXIF
Сделать 271 Производитель оборудования записи
Модель 272 Имя модели или номер модели устройства
XResolution 282 Число пикселей на единицу разрешения в направлении ImageWidth
Разрешение по оси Y 283 Число пикселей на единицу разрешения в направлении ImageLength
ResolutionUnit 296 Единица измерения XResolution и YResolution
Программное обеспечение. 305 Имя и версия встроенного ПО
Цветовое пространство 40961 Сведения о цветовом пространстве, обычно sRGB
SubsSecTimeOriginal 37521 Записывает доли секунд, связанные с тегом DateTimeOriginal
SubSecTimeDigitized 37522 Записывает доли секунд, связанные с тегом DateTimeDigitized
Время выдержки 33434 Время экспозиции в секундах (точность до 0,001s)
FNumber 33437 Номер F, используемый для записи
ISOSpeedRatings 34855 Значение скорости ISO, определенное в ISO 12322, на основе насыщенности
ИсходнаяДатаВремя 36867 Дата и время создания исходных данных изображения
DateTimeDIgitized 36868 Дата и время, когда изображение сохранено как цифровые данные
Shutter SpeedValue 37377 Скорость затвора в единицах аддитивной системы фотографической экспозиции (APEX)
Значение диафрагмы 37378 Диафрагма объектива в единицах APEX
Значение смещения экспозиции 37380 Значение предвзятости экспозиции в единицах APEX
Режим замера 37383 Режим измерения AE (см. спецификацию EXIF)
LightSource 37384 Тип источника света (см. спецификацию EXIF)
Вспышка 37385 Состояние флэш-памяти во время захвата изображения
Фокусное расстояние 37386 Фактическая фокусная длина объектива
Режим экспозиции 41986 Режим экспозиции во время записи
WhiteBalance 41987 Режим балансировки белого баланса во время записи
DigitalZoomRatio 41988 Коэффициент цифрового масштабирования во время захвата изображений
Фокусное расстояние в 35-мм эквиваленте 41989 Эквивалентная фокусная длина 35 мм
Тип захвата сцены 41990 Тип сцены, которая была снята

Необязательные/OEM-определяемые метаданные

Драйвер камеры может содержать любые дополнительные метаданные в виде пользовательских тегов EXIF, если он соответствует спецификации EXIF и хранится в 0-м TIFF IFD или EXIF sub-IFD.

Требования к MakerNote и структура двоичных данных

Драйвер камеры может включать в себя собственные сведения производителя в виде заметки производителя (тег 37500). Примечание создателя не должно содержать указателей на данные, которые находятся за пределами самой заметки производителя, включая начало файла и положение заголовка TIFF. Кроме того, он не должен делать предположения о конце файла, как указано в заголовке TIFF.

Как правило, операционная система не гарантирует, что двоичная структура метаданных сохраняется при записи в выходной JPEG-поток. Это гарантирует, что метаданные записываются в соответствии со спецификацией EXIF. Например, это гарантирует, что заметка производителя копируется как непрерывный блок и определяется правильным тегом IFD, типом и смещением.

Использование с кодировщиком JPEG WIC

Предполагается, что MF_CAPTURE_METADATA_EXIF будет использоваться с кодировщиком JPEG, предоставляемым операционной системой компонентом обработки изображений Windows (WIC). Конвейер камеры Windows использует JPEG-кодировщик Windows WIC для обработки метаданных EXIF, полученных из MF_CAPTURE_METADATA_EXIF, и объединяет их с данными пикселей изображения в JPEG-файл. Это происходит в случаях, когда приложение не захватывает JPEG напрямую с камеры, а настраивает конвейер на захват форматов NV12/YUY2, которые затем кодируются операционной системой.

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID атрибут содержит идентификатор кадра для соответствующего кадра в переменной последовательности фотографий. Этот атрибут задается только для записи переменной последовательности фотографий.

MF_CAPTURE_METADATA_FRAME_ILLUMINATION

Атрибут MF_CAPTURE_METADATA_FRAME_ILLUMINATION для ИК-камер указывает, используется ли активная ИК-подсветка для кадров и должен применяться в сочетании с FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION. Он используется только для примеров IR и не должен присутствовать на rgb-кадрах, если камера поддерживает как ir, так и цветовые образцы.

Значение должно быть установлено как 0xXXXXXXXXXXXXXXX1, если кадр был захвачен при активном освещении, и установлено как 0xXXXXXXXXXXXXXXX0, если при захвате кадра не было освещения.

MF_CAPTURE_METADATA_HISTOGRAM

Атрибут MF_CAPTURE_METADATA_HISTOGRAM содержит гистограмму при захвате кадра предварительного просмотра.

Структуры данных, приведённые ниже, описывают формат BLOB для MF_CAPTURE_METADATA_HISTOGRAM.

typedef struct tagHistogramGrid
{
    ULONG Width;    // Width of the sensor output that histogram is collected from
    ULONG Height;   // Height of the sensor output that histogram is collected from
    RECT Region;    // Absolute coordinates of the region on the sensor output that the histogram is collected for
} HistogramGrid;

typedef struct tagHistogramBlobHeader
{
    ULONG Size;         // Size of the entire histogram blob in bytes
    ULONG Histograms;   // Number of histograms in the blob. Each histogram is identified by a HistogramHeader
} HistogramBlobHeader;

typedef struct tagHistogramHeader
{
    ULONG Size;         // Size of this header + (HistogramDataHeader + histogram data following) * number of channels available
    ULONG Bins;         // Number of bins in the histogram
    ULONG FourCC;       // Color space that the histogram is collected from
    ULONG ChannelMasks; // Masks of the color channels that the histogram is collected for
    HistogramGrid Grid; // Grid that the histogram is collected from
} HistogramHeader;

typedef struct tagHistogramDataHeader
{
    ULONG Size;         // Size in bytes of this header + histogram data following
    ULONG ChannelMask;  // Mask of the color channel for the histogram data
    ULONG Linear;       // 1, if linear; 0 nonlinear
} HistogramDataHeader;

Для поля ChannelMasks мы определим следующие битовые маски, чтобы указать доступные каналы в гистограмме.

#define MF_HISTOGRAM_CHANNEL_Y  0x00000001
#define MF_HISTOGRAM_CHANNEL_R  0x00000002
#define MF_HISTOGRAM_CHANNEL_G  0x00000004
#define MF_HISTOGRAM_CHANNEL_B  0x00000008
#define MF_HISTOGRAM_CHANNEL_Cb 0x00000010
#define MF_HISTOGRAM_CHANNEL_Cr 0x00000020

Примечания:

  1. Каждый объект может содержать несколько гистограмм, собранных из разных областей или разных цветовых пространств одного кадра.
  2. Каждая гистограмма в большом двоичном объекте идентифицируется своим собственным заголовком гистограммы.
  3. Каждая гистограмма имеет свой собственный регион и размер выходных данных датчика. Для гистограммы полного кадра область будет соответствовать размеру выходных данных датчика, указанному в HistogramGrid.
  4. Данные гистограммы для всех доступных каналов группируются под одной гистограммой. Данные гистограммы для каждого канала определяются заголовком HistogramDataHeader, находящимся непосредственно перед данными. ChannelMasks указывают, сколько и какие каналы содержат данные гистограммы, представляя собой результат побитовой операции ИЛИ поддерживаемых битовых масок MF_HISTOGRAM_CHANNEL_XXX, как определено выше. ChannelMask указывает, какой канал предназначен для данных, который определяется любым из MF_HISTOGRAM_CHANNEL_XXX битовых маск, определенных выше.

На иллюстрации ниже показан макет гистограммы в формате 'blob' с полной гистограммой, содержащей только компонент Y.

Данные гистограммы — это массив ULONG, где каждая запись представляет количество пикселей, попадающих под определённый набор тонов, классифицированных по корзине. Данные в массиве должны начинаться с bin 0 до bin N-1, где N — это количество ячеек в гистограмме, т. е. HistogramBlobHeader.Bins.

На рисунке ниже показан макет раздела данных гистограммы.

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

На рисунке ниже показано расположение блока гистограммы с гистограммой по компоненте Y, за которой следует гистограмма RGB с тремя каналами.

Для Threshold необходимо предоставить как минимум полную гистограмму с Y-каналом, которая должна быть первой в массиве гистограмм, если поддерживается KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM.

Обратите внимание, что HistogramBlobHeader, HistogramHeader, HistogramDataHeader и данные гистограммы описывают только формат BLOB для атрибута MF_CAPTURE_METADATA_HISTOGRAM. Структура элемента метаданных для гистограммы (KSCAMERA_METADATA_ITEMHEADER + все полезные данные метаданных гистограммы) определяется драйвером и должна быть выровнена по границе 8 байт.

Контроль метаданных гистограммы

KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM — это идентификатор свойства, который будет использоваться для управления метаданными гистограммы, созданными драйвером. Это элемент управления уровнем пина только для предварительного просмотра, и он представлен следующим образом:

typedef enum {
    …
#if (NTDDI_VERSION >= NTDDI_WIN8)
    KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM
#endif
} KSPROPERTY_CAMERACONTROL_EXTENDED_PROPERTY;

Для KSCAMERA_EXTENDEDPROP_HEADER мы определим следующие битовые флаги для управления метаданными гистограммы в драйвере. Значение по умолчанию — OFF.

#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_OFF 0x0000000000000000
#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_ON  0x0000000000000001

Этот элемент управления необходимо использовать перед элементом управления KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA, чтобы обеспечить выделение буфера, подходящего для размера метаданных.

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

Если задано значение HISTOGRAM_ON, драйвер должен передавать метаданные гистограммы на выводе предварительного просмотра. Драйвер должен учитывать размер метаданных гистограммы в требовании размера буфера метаданных.

Если драйвер не имеет возможности создавать метаданные гистограммы, драйвер не должен реализовать этот элемент управления. Если драйвер поддерживает данное управление, он также должен поддерживать управление KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA.

Вызов SET этого элемента управления не оказывает эффекта, если пин предварительного просмотра находится в любом состоянии выше, чем состояние KSSTATE_STOP. Драйвер должен отклонить вызов SET, полученный, если предварительная версия не находится в состоянии остановки и возвращает STATUS_INVALID_DEVICE_STATE. В вызове GET драйвер должен возвращать текущие параметры в поле "Флаги".

Это синхронный элемент управления. Для этого элемента управления не определены возможности.

KSCAMERA_EXTENDEDPROP_HEADER

Версия

Должно быть 1.

PinId

Должен быть идентификатором пин-кода, связанным с пин-кодом предварительного просмотра.

Размер

Должен содержать значение sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VALUE).

Результат

Указывает результаты ошибок последней операции SET. Если операция SET не выполнена, это должно быть 0.

Способность

Должно быть 0.

Флаги

Это поле чтения и записи. Это может быть любой из флагов KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX, определенных выше.

KSCAMERA_EXTENDEDPROP_VALUE

Не используется