xmp: XMP metadata object

Description

xmp() creates an XMP metadata object. Such objects can be used with set_xmp() to edit XMP medata for a variety of media formats and such objects are returned by get_xmp().

Usage

xmp(
  ...,
  alt_text = NULL,
  attribution_name = NULL,
  attribution_url = NULL,
  create_date = NULL,
  creator = NULL,
  creator_tool = NULL,
  credit = NULL,
  date_created = NULL,
  description = NULL,
  ext_description = NULL,
  headline = NULL,
  keywords = NULL,
  license = NULL,
  marked = NULL,
  modify_date = NULL,
  more_permissions = NULL,
  producer = NULL,
  rights = NULL,
  subject = NULL,
  title = NULL,
  usage_terms = NULL,
  web_statement = NULL,
  auto_xmp = c("cc:attributionName", "cc:license", "dc:rights", "dc:subject",
    "photoshop:Credit", "xmpRights:Marked", "xmpRights:UsageTerms",
    "xmpRights:WebStatement"),
  spdx_id = NULL
)

Value

An xmp object as can be used with set_xmp(). Basically a named list whose names are the (optional) xmp namespace and tag names separated by ":" and the values are the xmp values. Datetimes should be a datetime object such as POSIXlt().

Arguments

...: Entries of xmp metadata. The names are either the xmp tag names or alternatively the xmp namespace and tag names separated by ":". The values are the xmp values.
alt_text: Brief textual description that can be used as its "alt text" (XMP tag Iptc4xmpCore:AltTextAccessibility). Will be coerced by as_lang_alt(). Core IPTC photo metadata.
attribution_name: The name to be used when attributing the work (XMP tag cc:attributionName). Recommended by Creative Commons. If missing and "cc:attributionName" in auto_xmp and and photoshop:Credit non-missing will use that else if dc:creator non-missing then will automatically use stringi::stri_join(creator, collapse = " and ").
attribution_url: The URL to be used when attributing the work (XMP tag cc:attributionURL). Recommended by Creative Commons.
create_date: The date the digital document was created (XMP tag xmp:CreateDate). Will be coerced by datetimeoffset::as_datetimeoffset(). Related pdf documentation info key is CreationDate. Not to be confused with photoshop:DateCreated which is the date the intellectual content was created.
creator: The document's author(s) (XMP tag dc:creator). Related pdf documentation info key is Author. Core IPTC photo metadata used by Google Photos. If credit is missing and "photoshop:Credit" in auto_xmp then we'll also use this for the photoshop:Credit XMP tag.
creator_tool: The name of the application that originally created the document (XMP tag xmp:CreatorTool). Related pdf documentation info key is Creator.
credit: Credit line field (XMP tag photoshop:Credit). Core IPTC photo metadata used by Google Photos. If missing and "photoshop:Credit" in auto_xmp and dc:creator non-missing then will automatically use stringi::stri_join(creator, collapse = " and ").
date_created: The date the intellectual content was created (XMP tag photoshop:DateCreated). Will be coerced by datetimeoffset::as_datetimeoffset(). Core IPTC photo metadata. Not to be confused with xmp:CreateDate for when the digital document was created.
description: The document's subject (XMP tag dc:description). Will be coerced by as_lang_alt(). Core IPTC photo metadata. Related pdf documentation info key is Subject.
ext_description: An extended description (for accessibility) if the "alt text" is insufficient (XMP tag Iptc4xmpCore:ExtDescrAccessibility). Will be coerced by as_lang_alt(). Core IPTC photo metadata.
headline: A short synopsis of the document (XMP tag photoshop:Headline). Core IPTC photo metadata.
keywords: Character vector of keywords for this document (for cross-document searching). Related pdf documentation info key is pdf:Keywords. Will be coerced into a string by stringi::stri_join(keywords, collapse = ", ").
license: The URL of (open source) license terms (XMP tag cc:license). Recommended by Creative Commons. Note xmpRights:WebStatement set in web_statement is a more popular XMP tag (e.g. used by Google Images) that can also hold the URL of license terms or a verifying web statement. If cc:license in auto_xmp and spdx_id is not NULL then we'll automatically use an URL from spdx_licenses corresponding to that license.
marked: Whether the document is a rights-managed resource (XMP tag xmpRights:Marked). Use TRUE if rights-managed, FALSE if public domain, and NULL if unknown. Creative Commons recommends setting this. If xmpRights:Marked in auto_xmp and spdx_id is not NULL then we can automatically set this for a subset of SPDX licenses (including all Creative Commons licenses).
modify_date: The date the document was last modified (XMP tag xmp:ModifyDate). Will be coerced by datetimeoffset::as_datetimeoffset(). Related pdf documentation info key is ModDate.
more_permissions: A URL for additional permissions beyond the license (XMP tag cc:morePermissions). Recommended by Creative Commons. Contrast with the LicensorURL property of plus:Licensor XMP tag.
producer: The name of the application that converted the document to pdf (XMP tag pdf:Producer). Related pdf documentation info key is Producer.
rights: (copy)right information about the document (XMP tag dc:rights). Will be coerced by as_lang_alt(). Core IPTC photo metadata used by Google Photos that Creative Commons also recommends setting. If dc:rights in auto_xmp and creator and date_created are not NULL then we can automatically generate a basic copyright statement with the help of spdx_id.
subject: List of description phrases, keywords, classification codes (XMP tag dc:subject). Core IPTC photo metadata. A character vector. Similar but less popular to the XMP tag pdf:Keywords which is a string. If dc:subject in auto_xmp and keywords is not NULL then we can automatically extract the keywords from it using strsplit(keywords, ", ")[[1]].
title: The document's title (XMP tag dc:title). Will be coerced by as_lang_alt(). Related pdf documentation info key is Title.
usage_terms: A string describing legal terms of use for the document (XMP tag xmpRights:UsageTerms). Will be coerced by as_lang_alt(). Core IPTC photo metadata and recommended by Creative Commons. If xmpRights:UsageTerms in auto_xmp and spdx_id is not NULL then we can automatically set this with that license's name and URL.
web_statement: Web Statement of Rights (XMP tag xmpRights:WebStatement): a string of a full URL with license information about the page. If xmpRights:WebStatement in auto_xmp and spdx_id is not NULL then we'll automatically use an URL from spdx_licenses corresponding to that license. Core IPTC photo metadata used by Google Photos. Also recommended by Creative Commons (who also recommends using a "verifying" web statement).
auto_xmp: Character vector of XMP metadata we should try to automatically determine if missing from other XMP metadata and spdx_id.
spdx_id: The id of a license in the SPDX license list. See spdx_licenses.

<code>xmp</code> R6 Class Methods

fig_process(..., auto = c("fig.alt", "fig.cap", "fig.scap")): Returns a function to embed XMP metadata suitable for use with {knitr}'s fig.process chunk option. ... are local XMP metadata changes for this function. auto are which chunk options should be used to further update metadata values.
get_item(key): Get XMP metadata value for key key. Can also use the relevant active bindings to get more common values.
print(mode = c("null_omit", "google_images", "creative_commons", "all"), xmp_only = FALSE): Print out XMP metadata values. If mode is "null_omit" print out which metadata would be embedded. If mode is "google images" print out values for the five fields Google Images uses. If mode is creative_commons print out the values for the fields Creative Commons recommends be set when using their licenses. If mode is all print out values for all XMP metadata that we provide active bindings for (even if NULL). If xmp_only is TRUE then don't print out spdx_id and auto_xmp values.
set_item(key, value): Set XMP metadata key key with value value. Can also use the relevant active bindings to set XMP metadata values.
update(x): Update XMP metadata entries using non-NULL entries in x coerced by as_xmp().

<code>xmp</code> R6 Active Bindings

alt_text: The image's alt text (accessibility).
attribution_name: The name to attribute the document.
attribution_url: The URL to attribute the document.
create_date: The date the document was created.
creator: The document's author.
creator_tool: The name of the application that originally created the document.
credit: Credit line.
date_created: The date the document's intellectual content was created
description: The document's description.
ext_description: An extended description for accessibility.
headline: A short synopsis of document.
keywords: String of keywords for this document (less popular than subject)).
license: URL of (open-source) license terms the document is licensed under.
marked: Boolean of whether this is a rights-managed document.
modify_date: The date the document was last modified.
more_permissions: URL for acquiring additional permissions beyond license.
producer: The name of the application that converted the document (to pdf).
rights: The document's copy(right) information.
subject: Vector of key phrases/words/codes for this document (more popular than keywords)).
title: The document's title.
usage_terms: The document's rights usage terms.
web_statement: A URL string for the web statement of rights for the document.
spdx_id: The id of a license in the SPDX license list. See spdx_licenses.
auto_xmp: Character vector of XMP metadata we should try to automatically determine if missing from other XMP metadata and spdx_id.

XMP tag recommendations

https://exiftool.org/TagNames/XMP.html recommends "dc", "xmp", "Iptc4xmpCore", and "Iptc4xmpExt" schemas if possible
https://github.com/adobe/xmp-docs/tree/master/XMPNamespaces are descriptions of some common XMP tags
https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata#xmp-namespaces-and-identifiers is popular for photos
https://developers.google.com/search/docs/appearance/structured-data/image-license-metadata#iptc-photo-metadata are the subset of IPTC photo metadata which Google Photos uses (if no structured data on web page)
https://wiki.creativecommons.org/wiki/XMP are Creative Commons license recommendations

Examples

Run this code

  x <- xmp(attribution_url = "https://example.com/attribution",
           creator = "John Doe",
           description = "An image caption",
           date_created = Sys.Date(),
           spdx_id = "CC-BY-4.0")
  print(x)
  print(x, mode = "google_images", xmp_only = TRUE)
  print(x, mode = "creative_commons", xmp_only = TRUE)

  if (supports_set_xmp() &&
      supports_get_xmp() &&
      capabilities("png") &&
      requireNamespace("grid", quietly = TRUE)) {

    f <- tempfile(fileext = ".png")
    png(f)
    grid::grid.text("This is an image!")
    invisible(dev.off())
    set_xmp(x, f)
    print(get_xmp(f)[[1]])
  }

Run the code above in your browser using DataLab