xmp: XMP metadata object
In xmpdf: Edit 'XMP' Metadata and 'PDF' Bookmarks and Documentation Info

View source: R/xmp.R

xmp	R Documentation

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
)

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.

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().

`xmp` 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().

`xmp` 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

  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]])
  }

xmpdf documentation built on July 4, 2024, 9:08 a.m.