人員標記概觀

發行項
06/12/2023

本主題介紹新的 Extensible Metadata Platform (XMP) 架構和 Windows 7 相片屬性 System.Photo.PeopleNames ，可啟用數位相片中個人標記的功能。本主題也會討論如何使用 Windows 映像元件 (WIC) API 來讀取和寫入人員標記所需的中繼資料。

本主題包含下列各節。

先決條件
簡介
人員標記
- 人員名稱
- 人員矩形
架構參考
相關主題

必要條件

若要瞭解本主題，您應該熟悉 WIC 解碼器介面及其相關的元件物件模型 (COM) 元件，如 Windows 映像處理元件概觀中所述。它也有助於熟悉映射中繼資料，特別是 XMP。

簡介

Microsoft 已建立新的 XMP 架構，以標記數位影像內的人員。此架構可讓應用程式將影像中個別的名稱和位置儲存為影像內的中繼資料。除了新的架構之外，Windows 7 還提供新的 photo 屬性 System.Photo.PeopleNames 。這個新屬性可讓應用程式讀取儲存在影像中繼資料中的個別名稱。 WIC 藉由讓應用程式輕鬆地讀取和寫入將元資料標記至數位相片的人員，藉此利用這些新功能。

人員標記

WIC 為應用程式開發人員提供可讀取影像資料和影像中繼資料的 COM 元件。為了讀取和寫入中繼資料，例如新的人員標記功能， WIC 會提供 IWICMetadataQueryReader 和 IWICMetadataQueryWriter 介面。這些介面可讓應用程式使用中繼資料查詢語言，將中繼資料寫入影像的個別畫面。下一節示範如何使用 WIC 查詢讀取器和寫入器，將人員標記中繼資料讀取和寫入影像的中繼資料。

人員名稱

人員標記功能的一部分是只取得影像內標記人員名稱的清單的能力。 System.Photo.PeopleNames和 WIC 的元資料處理程式支援此功能的這個部分。 IWICMetadataQueryReader介面與 System.Photo.PeopleNames 屬性搭配使用，用來讀取影像中識別並儲存在影像中繼資料中的人員名稱。

下列程式碼範例示範從影像框架取得的查詢讀取器，以查詢影像的中繼資料，以取得 System.Photo.PeopleNames 屬性的標記名稱。

// Not shown: image decoding, retrieving an image frame. 
...
PROPVARIANT value;
IWICMetadataQueryReader *pQueryReader = NULL;
...
// Get the query reader.
if (SUCCEEDED(hr))
{
    hr = pFrameDecode->GetMetadataQueryReader(&pQueryReader);
}

// Query for the System.Photo.PeopleNames property.
if (SUCCEEDED(hr))
{
    // Get the property metadata by property name.
    hr = pQueryReader->GetMetadataByName(L"System.Photo.PeopleNames", &value);
}

查詢運算式「System.Photo.PeopleNames」會查詢屬性的框架。如果人員標記中繼資料存在且包含人員的名稱， PROPVARIANT 值將會設定為VT_LPWSTR，而資料值將包含標記的名稱清單。如需讀取影像中繼資料的詳細資訊，請參閱讀取和寫入影像中繼資料的概觀。

只有在影像實際包含人員標記中繼資料時，查詢人員名稱標籤才有用。若要發生此情況，應用程式必須先撰寫它。若要撰寫人員名稱中繼資料，請使用 IWICMetadataQueryWriter 和中繼資料的明確 XMP 路徑。下列程式碼範例示範如何使用查詢寫入器，將名稱寫入查詢路徑。

// Not shown: image encoding, retrieving/creating the image frame,
// creating the IWICImagingFactory 
...
IWICImagingFactory *pFactory = NULL;
IWICMetadataQueryWriter *pQueryWriter = NULL;
...
// Get the query writer from the image frame.
if (SUCCEEDED(hr))
{
    hr = pFrameEncode->GetMetadataQueryWriter(&pQueryWriter);
}

// A query writer specifically for this person's XMP struct
IWICMetadataQueryWriter *pXMPStructQueryWriter = NULL;

// Create a query writer specifically for an XMP Struct
hr = pFactory->CreateQueryWriter(
    GUID_MetadataFormatXMPStruct,
    NULL,
    &pXMPStructQueryWriter
    );

// Create a variant representing the structure created above
PROPVARIANT xmpStruct;
PropVariantInit(&xmpStruct);

// VT_UNKNOWN indicates that we're setting a COM object, in this case a XMPStruct
// which will hold the name and rectangle
xmpStruct.vt = VT_UNKNOWN; 
xmpStruct.punkVal = pXMPStructQueryWriter;

if(SUCCEEDED(hr))
{
    // WIC will automatically create the xmp base, the RegionInfo struct, and the Regions
    // bag (an unordered array) but structs within that bag need to be explicitly created.
    // The {ulong=0} in the query means to insert the new struct at the start of the bag,
    // {} could also be used to insert at the end of the bag.
    hr = pQueryWriter->SetMetadataByName(
        L"/xmp/<xmpstruct>MP:RegionInfo/<xmpbag>MPRI:Regions/{ulong=0}",
        &xmpStruct
        );
}

// Set up the PROPVARIANT with the name information
PROPVARIANT personName;
PropVariantInit(&personName);
personName.vt = VT_LPWSTR;
personName.pwszVal = L"John Doe";

if(SUCCEEDED(hr))
{
    // Set the name metadata
    hr = pQueryWriter->SetMetadataByName(
        L"/xmp/MP:RegionInfo/MPRI:Regions/{ulong=0}/MPReg:PersonDisplayName",
        &personName
        );  
}

請注意建構 XMP 結構的步驟，並在下 MPRI:Regions/{ulong=0} 設定它。如果沒有此步驟，WIC 就無法識別稍後要放置 PersonDisplayName 的位置。另請注意，系統會使用明確的查詢路徑，而不是 System.Photo.PeopleNames，其中繼資料原則不支援寫入中繼資料。

人員矩形

不過，人員的名稱只是人員標記功能的一部分。除了將人員的名稱儲存在中繼資料中，架構也支援區域資訊，以識別特定區域 (矩形) 該人員顯示在影像中。

矩形資訊是以四個逗號分隔的十進位值來表示，例如「0.25、0.25、0.25、0.25」。前兩個值指定左上方座標;最後兩個指定矩形的高度和寬度。為了定義人員矩形的目的影像維度會標準化為 1，這表示在「0.25， 0.25， 0.25， 0.25」範例中，矩形會從頂端開始 1/4 的距離，而影像左邊距離的 1/4。矩形的高度和寬度都是其各自的影像維度大小的 1/4。

識別個人的矩形資訊是以相同結構內人員名稱寫入的相同方式寫入。若要寫入矩形中繼資料，請使用 IWICMetadataQueryWriter 和中繼資料的明確 XMP 路徑。下列程式碼範例會繼續上述範例，並將代表 'John Doe' 的矩形新增至影像的中繼資料。請注意，它會使用相同的 {ulong=0} 索引將此矩形與 'John Doe' 產生關聯。

// Set up the PROPVARIANT with the rectangle information
PROPVARIANT rectangle;
PropVariantInit(&rectangle);
rectangle.vt = VT_LPWSTR;
rectangle.pwszVal = L"0.0,0.0,0.25,0.25";

if(SUCCEEDED(hr))
{
    // Set the rectangle metadata
    hr = pQueryWriter->SetMetadataByName(
        L"/xmp/MP:RegionInfo/MPRI:Regions/{ulong=0}/MPReg:Rectangle",
        &rectangle
        );
}

結構描述參考

用於標記人員的 Microsoft XMP 架構會定義一組屬性，以標記數位相片中的個人。

下列各節提供人員標記所需的架構定義。可能的話，架構定義會使用 Adobe 可延伸中繼資料平臺所提供的慣例， (XMP) 規格。本主題中的架構定義會顯示 XML 命名空間統一資源識別項 (URI) ，可識別架構和慣用的架構命名空間前置詞，後面接著列出針對架構定義的所有屬性的資料表。每個資料表都有下列資料行：

Property - 屬性 的名稱，包括慣用的命名空間前置詞。
實值型別 - 屬性的實值型別。人員標記支援架構會盡可能使用 XMP 實數值型別，包括日期和文字。陣列類型前面會加上容器類型： alt 、 bag 或 seq 。
類別 - 架構屬性為內部或外部：
- 內部中繼資料必須由應用程式設定。
- 外部中繼資料必須由使用者設定，而且與檔的內容無關。
描述 - 屬性的描述。

Microsoft Photo 1.2 架構

Microsoft Photo 1.2 架構提供一組影像區域的屬性。

架構命名空間 URI 為 https://ns.microsoft.com/photo/1.2/ 。
慣用的架構命名空間前置詞是 MP 。

屬性	值類型	類別	描述
MP：RegionInfo	RegionInfo	內部	必要：儲存人員標記中繼資料的根目錄。請參閱下列的 Microsoft Photo RegionInfo 架構一節。

Microsoft Photo RegionInfo 架構

Microsoft Photo RegionInfo 1.2 架構提供一組區域資訊的屬性。

架構命名空間 URI 為 https://ns.microsoft.com/photo/1.2/t/RegionInfo# 。
慣用的架構命名空間前置詞是 MPRI 。

屬性	值類型	類別	描述
MPRI：DateRegionsValid	Date	外部	選擇性：上次建立區域的日期。
MPRI：Regions	包區域	外部	必要：儲存標記區域的人員。請參閱下列 Microsoft 相片區域架構一節。

Microsoft 相片區域架構

Microsoft Photo Region 1.2 架構提供一組影像區域的屬性。

架構命名空間 URI 為 https://ns.microsoft.com/photo/1.2/t/Region# 。
慣用的架構命名空間前置詞為 MPReg 。

MPReg：Property	值類型	類別	描述
MPReg：PersonDisplayName	Text	外部	必要：將人員的名稱儲存在指定的矩形中。
MPReg：Rectangle	Text	外部	選擇性：儲存矩形，以識別相片內的人員。矩形會儲存為四個逗號分隔的十進位值。前兩個值指定左上方座標;最後兩個指定矩形的高度和寬度。十進位值必須正規化為 1。
MPReg：PersonEmailDigest	Text	外部	選用：儲存人員即時電子郵件地址的 SHA-1 加密郵件雜湊。
MPReg：PersonLiveIdCID	Text	外部	選擇性：儲存人員 Live CID 的帶正負號十進位標記法，這是一個公開識別 Live 身分識別的 64 位整數。

範例中繼資料

以下是人員標記的 XMP 中繼資料標記法。

<rdf:Description rdf:about="" xmlns:MP="https://ns.microsoft.com/photo/1.2/">
<MP:RegionInfo> 
<rdf:Description xmlns:MPRI="https://ns.microsoft.com/photo/1.2/t/RegionInfo#">
   <MPRI:Regions> 
       <rdf:Bag> 
          <rdf:li> 
       <rdf:Description xmlns:MPReg="https://ns.microsoft.com/photo/1.2/t/Region#"> 
           <MPReg:Rectangle>0.790650, 0.441734, 0.209350, 0.279133
           </MPReg:Rectangle>
           <MPReg:PersonDisplayName>John Doe</MPReg:PersonDisplayName> 
           <MPReg:PersonEmailDigest>2FD4E1C67A2D28FCED849EE1BB76E7391B93EB13</MPReg:PersonEmailDigest> 
           <MPReg:PersonLiveIdCID>1234567890123456789</MPReg:PersonLiveIdCID> 
       </rdf:Description> 
         </rdf:li> 
         <rdf:li>
             <rdf:Description xmlns:MPReg="https://ns.microsoft.com/photo/1.2/t/Region#">
                  <MPReg:Rectangle>0.222656, 0.302083, 0.378906, 0.505208</MPReg:Rectangle> 
                  <MPReg:PersonDisplayName>Jane Doe</MPReg:PersonDisplayName> 
              </rdf:Description> 
         </rdf:li> 
<!-- Addition Regions --> ... 
<rdf:li>...
</rdf:li> 
</rdf:Bag> 
</MPRI:Regions> </rdf:Description> </MP:RegionInfo> </rdf:Description>

概念
Windows 映像元件概觀
WIC 中繼資料概觀
讀取和寫入影像中繼資料的概觀
中繼資料查詢語言概觀

Share via

人員標記概觀

必要條件

簡介

人員標記

人員名稱

人員矩形

結構描述參考

Microsoft Photo 1.2 架構

Microsoft Photo RegionInfo 架構

Microsoft 相片區域架構

範例中繼資料

意見反應

意見反應

其他資源

Share via

人員標記概觀

必要條件

簡介

人員標記

人員名稱

人員矩形

結構描述參考

Microsoft Photo 1.2 架構

Microsoft Photo RegionInfo 架構

Microsoft 相片區域架構

範例中繼資料

相關主題

意見反應

意見反應

其他資源