Processing of photo metadata in compliance with the IPTC Photo Metadata Standard
npm install iptc-photometadata-enginesh
$ npm install --save iptc-photometadata-engine
`
Require / Import
For importing the module the systems CommonJS and ES2020 are supported.
`javascript
const ipmde = require('iptc-photometadata-engine');
`
or
`javascript
import * as ipmde from 'iptc-photometadata-engine'
`
API Documentation
Table of Contents
* Use of ExifTool and its requirements
* Object IPTC Photo Metadata
* Class IpmdChecker
* Method checkIpmdStd
* Object ipmdCheckerResult
* Object Any-Other-Metadata-Reference
* Method compareIpmdCheckerResults
* Class CompareOptions
* Class CompareResultRow
* Class IpmdSetter
* Method generateExiftoolJson
* Class GenerateEtJsonOptions
* Construct Tree of Property Nodes
* Function ipmdChkResultToPropNodes
* Class OutputDesignOptions
* Object PropNode
* Class PropNodesArraysSet1
* Examples of generated PropNodes
* More functions transforming data of this Engine
* Function ipmdChkResultToTabledata1
* Function tabledata1ToCsvdata1
* Function tabledata1ToCsvstring1
* Function ipmdChkResultToIpmd
* Class Row1Fields
* Class Csv1Options
* Utility functions
* Function loadFromJson
* Function writeAsJson
* Function xmpIsoDatetime2etDatetime
* Function objectIsEmpty
* Function arraysEqual
* generateIpmdChkResultsStateTemplate
* Class FixedStructureData
* Method getFsData
* Method setFsd
* Available constants
* Auxiliary Files folder
Use of ExifTool and its requirements
The IPTC Photo Metadata Engine builds on the software ExifTool as the worker reading metadata from an image file or writing - aka embedding - metadata into an image file.
ExifTool is not integrated into this module but if npmjs.org is searched for the term "exiftool" more than a dozen of modules making ExifTool usable with node.js are available. Be aware that some of the modules only support reading metadata from an image file.
For enabling metadata being read by ExifTool to be processed by this Engine and for enabling ExifTool to embed metadata generated by this Engine some requirements must be met.
Requirements for reading metadata from an image file
The data generated by ExifTool ...
* ... must be an object and not a list/array of properties.
For this purpose the ExifTool argument "-j" MUST be used.
* ... must be a structured object: IPTC properties like the Location Created don't have only a single plain text value but a structure of sub-properties as value. Such a hierarchy of superior properties and sub-properties must be generated.
For this purpose the ExifTool argument "-struct" MUST be used.
* ... must have XMP property identifiers with the namespace alias. Example: for the XMP property of the IPTC property _Creator_ the identifier "XMP-dc:Creator" must be used, "XMP:Creator" is not sufficient!
For this purpose the ExifTool argument "-G1" MUST be used.
* ... should use "native" codes for properties with an enumeration of values.
Example: the IPTC property Model Release Status must hold a predefined value. For the value with the human description _Unlimited Model Releases_ the "native" code _MR-UMR_ should be used and not the text _Unlimited Model Releases_ as the use of a code supports user interfaces in different languages. (The to be used codes are defined on ExifTool tag pages, e.g. for this property on this page).
For this purpose the ExifTool argument "-n" SHOULD be used.
Requirements for embedding metadata into an image file
The object generated by this Engine for ExifTool ...
* ... is an object and not a list/array of properties.
For this purpose the ExifTool argument "-j" must be used.
* ... is a structured object: IPTC properties like the Location Created don't have only a single plain text value but a structure of sub-properties as value. Such a hierarchy of superior properties and sub-properties is generated.
* ... should use "native" codes for properties with an enumeration of values.
Example: the IPTC property Model Release Status must hold a predefined value. For the value with the human description _Unlimited Model Releases_ the "native" code _MR-UMR_ should be used and not the text _Unlimited Model Releases_ as the use of a code supports user interfaces in different languages. (The to be used codes are defined on ExifTool tag pages, e.g. for this property on this page.)
For this purpose the ExifTool argument "-n" SHOULD be used.
> Be aware 1: the party creating photo metadata values must adopt this rule, this requirement cannot be fulfilled by the Engine or ExifTool.
Be aware 2: it is also possible to use the human-readable variant of such property values, their text is defined on a corresponding tag page of the ExifTool documentation. In this case the ExifTool argument "-n" must not be used!
* ... should support deleting existing properties. For deleting a property two requirements must be met:
* the value of this property MUST be "-"
* the ExifTool argument "-f" MUST be used
For the exchange of metadata to and from ExifTool its JSON format must be used:
* A serialized object using the JSON format.
* The object holds a hierarchy of metadata properties (and NOT a flat list of all properties!). The properties defined by the IPTC Photo Metadata Standard are at the top level of this object, if a property defines a structure as its value an object is used as value of the superior property.
* The names of the top level properties must follow the "-G1" (Group 1) format: use of group names and for the XMP metadata also a namespace alias is used as prefix separated by a colon from the ExifTool tag (aka property identifier).
> Be aware: properties at lower levels of the hierarchy don't use such a prefix, onl the ExifTool tag.
* The values are in most cases a string or number as embedded, for some properties with predefined values (an enumeration, a controlled vocabulary) a special term as defined by ExifTool has to be used. Please check the Tag Names pages of ExifTool.
Object IPTC Photo Metadata
Object holding IPTC Photo Metadata properties as defined by the IPTC standard. The name of each property of this object MUST be the JSON identifier of an IPTC Photo Metadata property. (See the "JSON specs" row of the tables defining each property.)
The object may be hierarchical if IPTC properties with a structured value are used.
Typically, an instance of this object includes only IPTC properties with a value.
This object holds only a single value for properties which can be embedded using the XMP and the IIM format. As the IPTC Standard defines that the values of these formats must be the same (they must be "in sync") this is sufficient.
Instances of this object are used as input to and returned output of methods of classes or of generic functions described below.
Class IpmdChecker
This class checks photo metadata read from an image against the IPTC Photo Metadata Standard and returns an object with data about the state and optionally the value(s) of each property.
$3
* Parameter iptcPmdTechRefDocFp:
Path to a local copy of the IPTC Photo Metadata TechReference JSON file. IPTC makes these files available on this page, download the latest JSON variant. A TechReference file holds information about each property defined by the IPTC standard.
* Parameter ipmdCheckerResultTemplateFp:
Path to a local copy of the IPTC Photo Metadata Checker Result template file. This file is available at TBD!!!
$3
Checks the photo metadata of an image file based on the properties defined by the IPTC Photo Metadata Standard. Returns an instance of the IpmdCheckerResult.
* Parameter imgEtPmdInput: object with photo metadata as read from an image file with ExifTool (see the ExifTool requirements)).
* Parameter compareValues (boolean): "true" = if XMP and IIM values of an IPTC property exist they are compared and the INSYNC property of the IpmdCheckerResult is set accordingly.
* Parameter anyOtherDataRef: Any-Other-Metadata-Reference object setting properties of any non-IPTC (meta)data in the ExifTool object.
Returns an ipmdCheckerResult object
#### Object ipmdCheckerResult
An instance of this object is created by the checkIpmdStd method of the IpmdChecker class.
Its structure:
* procstate: holds a value from this enumeration:
* OK: the processing of the called method was and the result is OK
* PROCERR: the processing of the called method was not OK, see the errormsgs
* PMDERR: the processing of the photo metadata is not OK, see the errormsgs
* state: object of data about each property defined by the IPTC Photo Metadata Standard. This object reflects the state of the occurrence of values and if multiple values for the same IPTC property are in sync. It has this structure:
* {a JSON property name}: object of data about a specific IPTC PMD property. The property name is the identifier of this property as defined by the JSON Specs row in the specification table of a property in the IPTC Photo Metadata Standard and used by the IPTC TechReference. The object has this structure:
* data: object with details about the plain (not-structured) value(s) of this IPTC property. The object has this structure:
* XMP: shows if a value in the XMP format exists, 0 = no, 1 = yes
* XMPVALOCCUR: occurs only if the IPTC property may hold multiple values (XMP Bag). In this case it shows the number of found values.
* IIM: occurs only if the IIM format is defined for this IPTC property. Shows if a value in the IIM format exists, 0 = no, 1 = yes
* INSYNC: occurs only if both the XMP and the IIM format are defined for this IPTC property. Shows if the values of both formats are synchronized: 0 = no, 1 = yes
* EXIF: occurs only if this IPTC property is mapped to an Exif tag. Shows if a value in the Exif format exists, 0 = no, 1 = yes
* MAPINSYNC: occurs only if this IPTC property is mapped to an Exif tag. Shows if the values of the IPTC formats (XMP and optionally IIM) are synchronized with the Exif tag value: 0 = no, 1 = yes
* struct: object with data about the IPTC Photo Metadata structure used as value of the IPTC property. The object has this structure:
* {a property name}: object of data about a specific IPTC Photo Metadata property of this structure. All properties of this object are the same as for an {a JSON property name}-property at the superior level.
* value: object holding the values of IPTC properties found in this image file. The object has this structure:
* {a JSON property name}: object with values of a specific IPTC PMD property. The property name is the identifier of this property as defined by the JSON Specs row in the specification table of a property in the IPTC Photo Metadata Standard and used by the IPTC TechReference. The object has this structure:
* XMP: found value(s) of the XMP format
* IIM: found value(s) of the IIM format
* EXIF: found value of the Exif format
* struct: object with data aboute the IPTC Photo Metadata structure used as value of the IPTC property. The object has this structure:
* {a JSON property name}: object with values a specific IPTC Photo Metadata property of this structure. All properties of this object are the same as for an {a JSON property name}-property at the superior level.
* errormsgs: an array of objects providing details about an error occurring while processing the called method. The objects have this structure:
* propId: the identifier of the property involved in the error - as defined by the IPTC Photo Metadata Standard as identifier of the JSON property, also used by the IPTC Photo Metadata Standard TechReference files and document. If not property was involved "NA" is the value.
* propName: the name of the property as defined by the IPTC Photo Metadata Standard. If not property is identified an empty string is the value.
* msg: A free text message about the error.
#### Object Any-Other-Metadata-Reference
This object holds reference data about non-IPTC Photo Metadata Standard properties.
The properties:
* {a JSON property name}: object with values of a specific non-IPTC
metadata property. The JSON property name can be any string value.
* label': the label of the metadata property
sortorder: Sort order value, should fit into the sort order values of IPTC properties
datatype: "plain"
dataformat: "string" or "number"
etTag: ExifTool tag used for this metadata property
JSON
{
"exiftoolVersion": {
"label": "ExifTool version used by this system",
"sortorder": "aod0010",
"datatype": "plain",
"dataformat": "string",
"etTag": "ExifTool:ExifToolVersion"
},
"xmpToolkit": {
"label": "XMP Toolkit version used for writing XMP",
"sortorder": "aod0020",
"datatype": "plain",
"dataformat": "string",
"etTag": "XMP-x:XMPToolkit"
}
}
`
$3
Compares an IPTC Photo Metadata Checker Result of a test image file against the IPTC Photo Metadata Checker Result of a reference image, this is usually the IPTC reference image of a Photo Metadata Standard version. Returns and array of CompareResultRow objects.
* Parameter resultRef: instance of IpmdCheckerResult holding the data of the image being the reference.
* Parameter resultTest: instance of IpmdCheckerResult holding the data of image being the to-be-compared-against-the-reference image.
* Parameter ipmdIdFilter: an array of identifiers of IPTC properties which should be uses for comparing. IPTC properties not included are ignored. If the array is empty all IPTC properties are compared.
* Parameter compareOptions: an instance of the compareOptions
Returns an array of instances of the CompareResultRow class.
#### Class CompareOptions
The properties of this class act as options for comparing IpmdCheckerResults with the method compareIpmdCheckerResults of the class IpmdChecker.
* option mergeXmpIimRows (boolean): controls if result rows reflecting the XMP and the IIM value of a property should be merged into a single row. Default = false
#### Class CompareResultRow
Instances of this class are generated as results of the method compareIpmdCheckerResults of the class IpmdChecker for each compared IPTC property. They help to generate a table of comparison results.
Properties of this class:
* result: a string from this enumeration:
* valueCHANGED: the value of the property of the test image has changed compared to value of the reference image.
* valueMISSING: the value of the property of the test image is missing - but not the property as such - compared to value of the reference image
* valueNOTARRAY: the value of the property of the test image is not na array as the value of the reference image.
* propMISSING: the property of the test image is missing compared to value of the reference image.
* message: short human-readable message in English reflecting the result.
* comparedNamePath: sequence of IPTC Photo Metadata property names from the top level of the metadata structure down to this property - separated by / (slash)
* comparedIpmdIdPath: sequence of IPTC Photo Metadata property identifiers from the top level of the metadata structure down to this property - separated by / (slash)
* comparedValueFormat: a string from this enumeration: 'XMP' or 'IIM'
* refValue: the value of the IPTC property in the reference image
* testValue: the value of the IPTC property in the test image
* dispparam1, dispparam2, dispparam3: parameters for displaying the results, can be used for displaying the results in e.g. an HTML page.
Class IpmdSetter
Covers the embedding of IPTC photo metadata into image files.
$3
* Parameter iptcPmdTechRefDocFp:
Path to a local copy of the IPTC Photo Metadata TechReference JSON file. IPTC makes these files available on this page, download the latest JSON variant. A TechReference file holds information about each property defined by the IPTC standard.
$3
Generates from an IPTC Photo Metadata object an ExifTool object which can be used for embedding IPTC photo metadata into an image file.
* Parameter ipmdData: object holding the IPTC Photo Metadata properties which should be embedded - an instance of the object IPTC Photo Metadata.
* Parameter genOptions: options for generating the ExifTool object. An instance of the class GenerateEtJsonOptions.
Returns an object of ExifTool JSON data.
#### Class GenerateEtJsonOptions
The properties of this class act as options for the method generateExiftoolJson of the class IpmdSetter.
* disabledPrintConv: boolean = false. Should be set to "true" if -f parameter of ExifTool will be used
Construct Tree of Property Nodes
This construct is a helper for creating a tree-like display of the hierarchical IPTC Photo Metadata properties in a user interface like an HTML document.
The basic design is:
* a Tree of Property Nodes is an object
* each JavaScript property of the object represents an IPTC Photo Metadata property by a PropNode object
* if an IPTC property has a structured value of sub-properties the corresponding PropNode has sub-PropNodes as value.
$3
Transforms an instance of the object IpmdCheckerResult to a hierarchical structure of PropNodes.
* Parameter ipmdChkResult: an instance of the to-be-converted IPTC Photo Metadata Checker Result
* Parameter opdOpt: an instance of OutputDesignOptions for controlling the generation of output data corresponding to the design option.
* Parameter labeltype: a code from this enumeration selects the applied label: ipmd (= IPTC Photo Metadata Standard labels), valuefmt (= labels used by XMP, IPTC IIM or Exif), et (= labels used by ExifTool)
* Parameter noValueText: a string acting as default text applied if no embedded value was found, e.g. "[no value found]"
* Parameter ipmdIdFilter: array of IPTC Photo Metadata property identifiers. If this array is not empty only these IPTC properties are used for generating output data.
* Parameter ipmdTechRef: an object of the IPTC TechReference data.
* Parameter anyOtherDataRef: Any-Other-Metadata-Reference object setting properties of any non-IPTC (meta)data in the ExifTool object.
Returns an instance of PropNodesArraysSet1.
#### Class OutputDesignOptions
The properties of this class act as options for setting the appropriate data for a specific design of the Tree of Property Nodes
All properties are of boolean data type:
* ipmdfull: if "true", a full set IPTC Photo Metadata properties in alphabetical order of the property names
* topics: if "true", sets of IPTC Photo Metadata properties grouped by User Guide topics
* fstds: if "true", sets of IPTC Photo Metadata properties grouped by the formats used for embedding the properties (XMP, IPTC IIM and Exif)
* isearch1: if "true", a set IPTC Photo Metadata properties which are relevant for search engines
* wvalonly: if "true", only properties with value are selected (and returned)
One property of ipmdfull through isearch1 must be set to true.
$3
This object represents an IPTC Photo Metadata property.
> Be aware: multiple objects about the same IPTC property may exist, this depends on the Output Design. For "fstds" instances exist for the XMP, the IIM and the Exif value. For "ipmdfull" multiple instances may exist if the XMP and the IIM values (and Exif value) are different.
The properties of this JavaScript object and if their occurrence is mandatory or optional:
* ptype (mandatory): has one of these values:
* "plain": this property has plain value(s), may be an array
* "struct": this property has structured value(s), may be an array
* plabel (mandatory): label of the IPTC Photo Metadata property
* psort (optional): sortorder value of the IPTC Photo Metadata property (of an alphabetical sortorder of the property labels in English)
* pspecidx (mandatory): fragment identifer of the specification of this IPTC property in the IPTC Photo Metadata Standard specification document. This fragment identifier may be appended to the URL https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata for linking.
* pvalue (mandatory): the IPTC Photo Metadata property's plain value or its data structure value expressed as PropNode.
* pinsync (mandatory): a numeric value indicating if values of this IPTC property in different embedded formats are in sync: 0 = a value of only one format was found, 1 = XMP and IIM value are in sync, 2 = XMP/IIM and further Exif values are in sync, -1 = should be 1 but is not in sync, -2 = should be 2 but is not in sync.
* pembformat (optional): a comma separated sequence of these codes: "XMP", "IIM", "Exif". It shows from which format the pvalue was taken. This property is only set for top level properties as sub-properties in a structure can only be from the XMP format.
* hasValue (mandatory): boolean value, is "true" if a value exists, else "false"
$3
Class of properties holding arrays of PropNodes for different Output Designs, can be used for rendering HTML.
The properties of this JavaScript object:
* Used for the 'full IPTC Photo Metadata' design option
* ipmdFullPna1: array of PropNodes
* Used for the 'format standards' design option
* xmpPna: array of PropNodes of embedded XMP properties
* iimPna: array of PropNodes of embedded IIM properties
* exifPna: array of PropNodes of embedded IIM properties
* Used for a specific IPTC Photo Metadata User Guide topic with the 'topic' design option
* gimgcontPna: array of PropNodes of the General Image Content topic
* personPna: array of PropNodes of the Persons topic
* locationPna: array of PropNodes of the Locations topic
* othingsPna: array of PropNodes of the Other Things topic
* rightsPna: array of PropNodes of the Asserting Rights topic
* licPna: array of PropNodes of the Licensing Usage topic
* adminPna: array of PropNodes of the Administration and Commissioning topic
* imgregPna: array of PropNodes of the Image Region topic
* anyPnaTopic: array of PropNodes assigned to any topic
* noTopicPna: array of PropNodes assigned to any topic
* Used for other purposes:
* schemaorgPna: container of schema.org metadata (property name/value pair objects)
* Used for any other kind of data than the IPTC Photo Metadata
* anyOtherDataPna: array of PropNodes
$3
A property with a singular plain value
`JSON
{
"ptype": "plain",
"plabel": "Copyright Notice",
"psort": "tp150",
"pspecidx": "#copyright-notice",
"pvalue": "Copyright 2022 Michael Kreatoris",
"pinsync": 2,
"pembformat": "XMP,IIM,Exif",
"hasValue": true
}
`
A property with multiple plain values
`JSON
{
"ptype": "plain",
"plabel": "Keywords",
"psort": "tp450",
"pspecidx": "#keywords",
"pvalue": "[1] sports, [2] soccer,",
"pinsync": 1,
"pembformat": "XMP,IIM",
"hasValue": true
}
`
A property with a structured value
`JSON
{
"ptype": "struct",
"plabel": "Licensor",
"psort": "tp460",
"pspecidx": "#licensor",
"pvalue": [
{
"ptype": "plain",
"plabel": "[1] Licensor ID",
"psort": "s3101",
"pspecidx": "#licensor-id",
"pvalue": "https://m.kreatoris.example.com",
"pinsync": 0,
"pembformat": "",
"hasValue": true
},
{
"ptype": "plain",
"plabel": "[1] Licensor Name",
"psort": "s3102",
"pspecidx": "#licensor-name",
"pvalue": "Michael Kreatoris",
"pinsync": 0,
"pembformat": "",
"hasValue": true
},{
"ptype": "plain",
"plabel": "[1] Licensor URL",
"psort": "s3114",
"pspecidx": "#licensor-url",
"pvalue": "https://m.kreatoris.example.com/imageshop/id13423423",
"pinsync": 0,
"pembformat": "",
"hasValue": true
}]
}
`
More functions transforming data of this Engine
$3
Transforms an IPTC Photo Metadata Checker result to an object with properties for building a visual table (in HTML). These properties reflect a state of the IPTC properties: was it found, are XMP and IIM values in sync.
* Parameter ipmdChkResult: an instance of the to-be-converted IPTC Photo Metadata Checker Result
* Parameter ipmdIdFilter: array of IPTC Photo Metadata property identifiers. If this array is not empty only these IPTC properties are used for generating output data.
* Parameter ipmdTechRef: an object of the IPTC TechReference data.
Returns an array of instances of Row1Fields.
#### Class Row1Fields
Object holding basic data about the state of an IPTC Photo Metadata property in an image file which can be used for building a row of a visual table (e.g. in HTML)
The properties:
* topic: identifier of the selected Output Design Options
* sortorder: a string value setting the sort order of this row
* nameL1: name of the IPTC property at the top level = Level 1
* nameL2: name of a sub-property of the IPTC property at Level 1
* nameL3: name of a sub-property of the IPTC property at Level 2
* nameL4: name of a sub-property of the IPTC property at Level 3
* nameL5: name of a sub-property of the IPTC property at Level 4
* xmpprop: state of finding the XMP property of the IPTC property: "found" or "MISSING".
* iimprop: state of finding the IIM property of the IPTC property: "found" or "MISSING" or "not spec" if for the IPTC property no IIM property is in the IPTC Photo Metadata Standard specification
* valuesinsync: state of checking if the XMP and the IIM values are in sync: "in sync" or "NOT in sync"
* comments: any comments to be shown in the table.
$3
Transforms an array of Row1Fields to CSV data.
* Parameter tableRows: array of Row1Fields as generated by e.g. the function ipmdChkResultToTabledata1
* Parameter csv1Options: an instance of Csv1Options
Returns an array of strings, each one is a CSV line.
$3
Transforms an array of Row1Fields to a single string with CSV data.
* Parameter tableRows: array of Row1Fields as generated by e.g. the function ipmdChkResultToTabledata1
* Parameter csv1Options: an instance of Csv1Options
Returns none to many CSV line strings seperated by a New Line/Line Feed code 0x000A
$3
Transforms an IPTC Photo Metadata Checker Result to an IPTC Photo Metadata object.
* Parameter ipmdChkResult: the to-be-transformed IPTC Photo Metadata Checker Result
* Parameter embFormatPref: code for creating the single value of an IPTC Photo Metadata property from the embedded XMP and IIM format values: "XMP" or "IIM"
* Parameter thisEmbFormatOnly: if "true", only values of the XMP or IIM format selected by embFormatPref are used. In fact this overrules any "which format should be preferred" processing.
Returns an IPTC Photo Metadata object.
$3
The properties of this class act as options for generating CSV data.
The property:
* fieldsep: character acting as separator of the fields in a CSV line
Utility functions
$3
Loads a local JSON file and tries to create a Javascript object from it.
* Parameter jsonFp: local path to the JSON file
$3
Writes a Javascript object as JSON file.
* Parameter dataObject: the Javascript object
* Parameter jsonFp: local path to the JSON file
$3
Transforms a ISO Date/Time format value - as used by XMP - to a Date-Time string as used by ExifTool.
* Parameter xmpIsoDt: ISO Date/Time format value
$3
Checks if a Javascript object is empty = it has no keys except optional Javascript prototype keys. Returns "true" if this is the case.
* Parameter obj: the to be tested object
$3
Compares two arrays: if all their members are the same regardless of the sequence of members "true" is returned.
* Parameters a and b: two to-be-compared arrays
$3
Generates an IPTC Photo Metadata Checker Result template from an IPTC TechReference object.
It returns the template data as object. This object could be saved to a local file with the writeAsJson function.
IPTC makes IPTC TechRef files available on this page, download the latest JSON variant. A TechReference file holds information about each property defined by the IPTC standard.
The latest file is also available in the Auxiliary Files folder of this project.
* Parameter ipmdTechRefData: an object with IPTC TechReference data, can be obtained by the loadFromJson function applied to a local copy of the TechRef file.
Class FixedStructureData
A helper for reading from and writing to a fixed structure of data. It supports the use of hierarchical paths from the top level of the structure down to any deeper level. "Fixed structure" means that the data structure loaded into an instance of this class is not changed during reading (and optionally writing) values of its properties.
In the IPTC Photo Metadata Engine it is used for the structured data of IPTC properties.
$3
* Parameter fsData: object of fixed structure data, it may have a hierarchical structure.
* Parameter readAndWrite: if false: date can be read only, if true: data can be written too.
$3
Reads value(s) from a property in the fixed structure of data with a path of property names as selector.
The method returns this object:
* Property state with one of these values
* "FOUND" = the addressed property was found
* "ERROR" = value occured, see property "msg"
* Property msg (only with "state": "ERROR"): a human readable message about any error
* Property value (only with "state": "FOUND"): the value(s) of the addressed property as it is:
* a single string or number
* an array of strings or numbers
* an object being the structured value
* an array of objects being the structured values
* Note: a returned string or object may be an empty value
The parameters:
* Parameter selectpath: a sequence of property names of the structure. The property names are separated by the parameter levelsep (see below) and the top level property is the first one. If multiple values of a property may occur a zero-based index can address a specific item of this array.
* Parameter levelsep (optional): a character separating property names of the hierarchical structure in the selectpath. Default value: "/"
* Parameter indexsep (optional): a character separating the property identifier from the index number of a to-be-read value in an array of values in the selectpath. Default value: "#"
Returns an object of this structure:
* Property state with one of these values
* "SET" = the value of the addressed property was set
* "ERROR" = value occured, see property "msg"
* Property msg: in case of "state" = "ERROR", a human readable message about any error
* Property value: in case of "state" = "FOUND", the value of the found property.
Examples of selectpath:
* "copyrightNotice": addresses the IPTC property with the identifier "copyrightNotice" at the top level of the hierarchy
* "keywords": addresses the IPTC property with the identifier "keywords" at the top level of the hierarchy. As this property has an array of strings as data type an array with none, one or many strings is returned.
* "locationCreated/countryCode": addresses the top level IPTC property with the identifier "locationCreated" and in its structured value the sub-property with the identifier "countryCode"
* "locationShown#2/city": addresses the top level IPTC property with the identifier "locationShown" and as its value is an array the item with index 2. In this item the sub-property with the identifier "city" is addressed.
$3
Writes value(s) to a property in the fixed structure of data with a path of property names as selector.
The parameters:
* Parameter setvalue: a string or a number or an object or an array thereof to be set as value of the property addressed by the selectpath.
* Parameter selectpath: a sequence of property names of the structure. The property names are separated by the parameter levelsep (see below) and the top level property is the first one. If multiple values of a property may occur a zero-based index can address a specific item of this array.
* Parameter levelsep (optional): a character separating property names of the hierarchical structure in the selectpath. Default value: "/"
* Parameter indexsep (optional): a character separating the property identifier from the index number of a to-be-read value in an array of values in the selectpath. Default value: "#"
The method returns an object of this structure:
* Property state with one of these values
* "SET" = the value of the addressed property was set
* "ERROR" = value occured, see property "msg"
* Property msg (only with "state": "ERROR"): a human readable message about any error
See the Examples of the method getFsData they apply to using the selectpath for this method in the same way.
Available constants
The Engine provides a set of constant values used with the IPTC TechReference, the ipmdCheckerResult, and other documented objects.
All constants can be used with the namespace "icc", e.g. as ipmde.icc.itgSortorder
`javascript
// constant property names of an IPTC PMD Checker Result (ipmdcr) object
const ipmdcrState: string = 'state';
// ... property names inside the top level "state" property
const ipmdcrSData: string = 'data';
// ... property names inside sub-property "data" of the top level "state"
const ipmdcrSDxmp: string = 'XMP';
const ipmdcrSDiim: string = 'IIM';
const ipmdcrSDexif: string = 'EXIF';
const ipmdcrSDinsync: string = 'INSYNC';
const ipmdcrSDmapinsync: string = 'MAPINSYNC';
const ipmdcrSDvaloccur: string = 'XMPVALOCCUR';
const ipmdcrSStruct: string = 'struct';
// ... property names inside the top level "value" property
const ipmdcrValue: string = 'value';
const ipmdcrVxmp: string = 'XMP';
const ipmdcrViim: string = 'IIM';
const ipmdcrVexif: string = 'EXIF';
const ipmdcrVet: string ='EXIFTOOL';
const ipmdcrVaodPrefix: string = 'AOD__';
// constant values of compareIpmdCheckerResults object's "result" property
const cmpRCvchngd: string = 'valueCHANGED';
const cmpRCvmisg: string = 'valueMISSING';
const cmpRCvnotarr: string = 'valueNOTARRAY';
const cmpRCpmisg: string = 'propMISSING';
// constant values of the Property Node (pnode)
const pnodeTypePlain: string = 'plain';
const pnodeTypeStruct: string = 'struct';
// constant values of the FixedStructureData class
// top level property names of a processing result object
const fsdResState: string = 'state';
const fsdResValue: string = 'value';
// values of the fsdResState property
const fsdStFound: string = 'FOUND';
const fsdStErr: string = 'ERROR';
const fsdStSearch: string = 'SEARCHING';
const fsdStRO: string = 'READONLY';
// any other relevant constant values
const anyPlusBaseUrl: string = 'http://ns.useplus.org/ldf/vocab/';
`
Auxiliary Files folder
The folder /auxiliary-files holds files helping to use the IPTC Photo Metadata Engine:
* iptc-pmd-techreference_{standard version}--{date}.json: the IPTC Photo Metadata TechReference file providing the data of the IPTC Photo Metadata Standard specification document in a machine readable format.
The latest {standard version} is "2021.1". The {date} shows when this file was created. This may be later than the publication date of the standard as minor errata can be fixed.
This file can be downloaded from this page of the IPTC site, download the latest JSON variant.
* iptc-pmd-checkerresults-template_{standard version}--{date}.json: the template file for results generated by the IpmdChecker class. {standard version} and {date} are used as defined for the iptc-pmd-techreference_....json file above.
It can be generated by the function generateIpmdChkResultsStateTemplate, it is included to the auxiliary files for your convenience.
* iptc-pmd-props-asJSON_{standard version}--{date}.json: a JSON object holding one or more example values of each IPTC Photo Metadata property. (See Object IPTC Photo Metadata above.)
Such an object has to be used for setting photo metadata with the class IpmdSetter or it is generated by the function ipmdChkResultToIpmd as output. {standard version} and {date} are used as defined for the iptc-pmd-techreference_....json file above.
* any-other-data-reference--example1.json: a file holding what the section Object Any-Other-Metadata-Reference explains.
Sub folder examples`