人員標記概觀

發行項
03/18/2025

本主題介紹新的可延伸元數據平臺（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相片 1.2 架構

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

架構命名空間的 URI 是 https://ns.microsoft.com/photo/1.2/。
慣用的架構命名空間首碼是 MP。

財產	實值類型	類別	描述
MP：區域資訊	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	日期	外部	選擇性：上次建立區域的日期。
MPRI：地區	包袋區域	外部	必要：儲存人物標記的區域。請參閱下列Microsoft相片區域架構一節。

Microsoft相片區域架構

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

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

MPReg：Property	實值類型	類別	描述
MPReg：人物顯示名稱	文字	外部	必須：將人員的名稱儲存在指定的矩形中。
MPReg：矩形	文字	外部	選擇性：儲存識別相片內人員的矩形。矩形會儲存為四個逗號分隔的十進位值。前兩個值指定左上方座標;最後兩個指定矩形的高度和寬度。十進位值必須正規化為 1。
MPReg：使用者電子郵件摘要	文字	外部	選擇性：儲存個人 Live 電子郵件地址的 SHA-1 加密訊息雜湊值。
MPReg：PersonLiveIdCID	文本	外部	選擇性：儲存人員 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 元數據概觀
讀取和寫入影像元數據的概觀
元數據查詢語言概觀

共用方式為

人員標記概觀

先決條件

介紹

人員標記

人員名稱

人員矩形

架構參考

Microsoft相片 1.2 架構

Microsoft Photo RegionInfo 架構

Microsoft相片區域架構

範例元數據

意見反應

其他資源

共用方式為

人員標記概觀

先決條件

介紹

人員標記

人員名稱

人員矩形

架構參考

Microsoft相片 1.2 架構

Microsoft Photo RegionInfo 架構

Microsoft相片區域架構

範例元數據

相關主題

意見反應

其他資源