RubyGems - mini_exiftool_vendored - Versions diffs - 8.9.7.v2 → 9.2.7.v1 - Mend

mini_exiftool_vendored 8.9.7.v2 → 9.2.7.v1

Files changed (1023) hide show

data/vendor/Image-ExifTool-9.27/html/overview.png ADDED

Binary file

data/vendor/Image-ExifTool-9.27/html/standards.html ADDED

@@ -0,0 +1,277 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
+<html>
+<head>
+  <title>Problems with current Metadata Standards</title>
+<link rel=stylesheet type='text/css' href='style.css' title='Style'>
+<style type="text/css">
+<!--
+a.ref   { text-decoration: none; font-size: x-small;
+          font-weight: normal; vertical-align: super; }
+-->
+</style>
+</head>
+<body>
+<div class='index'>
+<a href="#TIFF">TIFF 6.0</a>
+<br><a href="#DNG">DNG 1.3</a>
+<br><a href="#EXIF">EXIF 2.3</a>
+<br><a href="#PhotoInfo">OffsetSchema</a>
+<br><a href="#JPEG">JPEG</a>
+<br><a href="#MPF">MPF</a>
+<br><a href="#refs">References</a>
+</div>
+<h1 class=up>Problems with current Metadata Standards</h1>
+<p>It seems that all metadata standards have their own unique problems. This
+page documents some significant structural problems found in some current
+metadata and file format specifications, and gives possible solutions to these
+problems.  <i>[Also see my <a href="commentary.html">Commentary on Meta
+Information Formats</a>.]</i></p>
+<a name="TIFF"></a>
+<h3>TIFF 6.0 <a class=ref href="#ref1">[1]</a></h3>
+<p>A significant problem of the 1992 TIFF 6.0 specification is that there is no
+way to distinguish an IFD (image file directory) offset from a simple integer
+value.  As a result, new IFD's may not be created without risking corruption of
+the files by unaware software.  This is not only a problem for proprietary maker
+notes which commonly use a TIFF IFD structure, but is also a problem for
+extensibility of TIFF-based RAW image formats (as demonstrated by the DNG 1.3
+specification -- see below).</p>
+<p><b>A simple solution:</b></p>
+<p>Use a TIFF field type of 13 (IFD) instead of 4 (LONG) for IFD offsets.
+This was first proposed in 1995 by Adobe in their PageMaker
+6.0 TIFF Technical Notes<a class=ref href="#ref2">[2]</a>,
+but unfortunately it never found its way into the TIFF specification.  Even so,
+Olympus Optical Co. has shown some intelligence and is using this field type in
+the maker notes of their recent digital cameras.
+</p>
+<p><b>Another useful addition:</b> <i>(added 2009/09/27)</i></p>
+<p>A number of camera and cell phone manufacturers (Concord, Kodak, Motorola,
+Nokia, Olympus, Pentax, Ricoh, Samsung and Sony) leave blank IFD entries in the
+maker notes of images from some models. Presumably this simplifies the embedded
+software by allowing the output file structure to be kept constant even when the
+number of maker note IFD entries changes.  It could be useful if this feature
+was added explicitly to the offical TIFF specification by defining a field type
+of 0 as a "free IFD entry" to be ignored.  (Note that this ability already
+exists implicitly at a certain level in the specification, which states:
+<i>"Readers should skip over fields containing an unexpected field
+type"</i>.)</p>
+<a name="DNG"></a>
+<h3>DNG 1.3 <a class=ref href="#ref3">[3]</a></h3>
+<p>With the DNG 1.3 specification of June 2009, Adobe added a new Camera Profile
+IFD referenced by an offset using the standard (and unfortunate) TIFF LONG field
+type.  This means that the new Profile IFD will be lost if the file is rewritten
+by any software which does not have explicit knowledge of the 1.3 specification.
+But to make things worse, Adobe didn't even use a standard IFD format for the
+data. Instead, the IFD begins with a TIFF-style header and uses relative instead
+of absolute offsets.  This would have been a good idea if the IFD was stored as
+the value of an UNDEFINED tag rather than referenced from a LONG offset. (If
+done this way, the new information would have been preserved if the file was
+rewritten by unaware software.) But as implemented it just adds to the pain of
+parsing the file by requiring even more specialized code to be written in
+support of the DNG 1.3 format.</p>
+<p><b>A simple solution:</b></p>
+<p>Sack the Adobe developers who were responsible for this, and use field type
+13 (as recommended above for TIFF 6.0) and a standard TIFF IFD structure when
+adding new IFD's in the future.</p>
+<a name="EXIF"></a>
+<h3>EXIF 2.3 <a class=ref href="#ref4">[4]</a></h3>
+<p>The EXIF specification has been the standard for digital camera metadata for
+many years, and while the digital camera technology has advanced significantly
+in these years, the EXIF specification has not.  There are a number of
+significant problems with the EXIF specification which have never been
+addressed.</p>
+<p>Some current problems with the EXIF specification are:</p>
+<ol>
+<li>Maker note data structure has no restrictions and is easily invalidated when
+editing EXIF.</li>
+<li>No facility for storing the time zone for date/time values.</li>
+<li>Very limited support for alternate character sets (essentially only the
+UserComment tag has this feature).</li>
+<li>No alternate language support.</li>
+<li>Byte ordering for "Unicode" text strings, and the meaning of "Unicode"
+itself is not clearly specified.</li>
+<li>Mandatory tags are unnecessary and painful to implement.</li>
+<li>ApertureValue and MaxApertureValue are stored as unsigned RATIONAL, which
+means that lenses with F numbers faster than 1.0 (with equivalent APEX values of
+less than zero) can not be represented.</li>
+<li>MaxApertureValue is defined as "The smallest F number of the lens".  This
+definition is unclear in the case of zoom lenses where the maximum aperture
+varies across the zoom range.  Some manufacturers (Canon, Nikon, Sony) store the
+maximum aperture at the specific focal length, but others (Olympus, Pentax)
+store the absolute maximum aperture of the lens.</li>
+</ol>
+<p><b>Simple solutions:</b></p>
+<ol>
+<li>Specify that maker note data must be self-contained (ie. must not exceed the
+bounds of the maker note value data), and must be relocatable (ie. must not use
+absolute offsets).  <i>[I would have suggested defining a new maker note tag
+with field type 13 (IFD) which references a standard format IFD, but I am afraid
+that no camera maker would ever jump on board with this suggestion now that they
+have already been seduced by the dark side.]</i></li>
+<li>Change the specification to allow an optional time zone of the format
+"-05:00" to be appended to the date/time string values.</li>
+<li>Change the specification to allow UTF-8 in ASCII-type values as recommended
+by the MWG<a class=ref href="#ref5">[5]</a>.</li>
+<li>No simple solution for this.  XMP<a class=ref href="#ref6">[6]</a>
+is the only reasonable alternative if alternate language support is
+required.</li>
+<li>Specify that the Unicode byte order must be the same as the EXIF byte
+ordering. (This is the only reasonable choice, but for some reason both
+Microsoft and Apple seem to write Unicode using the native processor byte
+ordering. regardless of the EXIF byte order.)  Also, it should be made clear
+that by "Unicode" the EXIF specification actually means UCS-2, although updating
+this to allow UTF-16 surrogate pairs may be a good idea.</li>
+<li>Define reasonable fallback values for required tags which are missing.</li>
+<li>Allow ApertureValue and MaxApertureValue to be stored as signed SRATIONAL.</li>
+<li>Define whether MaxApertureValue is taken at the current focal length of
+a zoom lens, or over the entire zoom range.</li>
+</ol>
+<a name="PhotoInfo"></a>
+<h3>Microsoft "OffsetSchema" Tag <a class=ref href="#ref7">[7]</a></h3>
+<p>In February 2007 Microsoft proposed a new PhotoInfo tag called "OffsetSchema"
+(hex. 0xEA1D, dec. 59933) in an attempt to patch a deficiency in the EXIF maker
+note specification (see point 1 in EXIF 2.2 section above).  This tag represents
+the offset difference between the original maker note location in the EXIF and
+the new location after editing, and is designed to allow the maker note tag
+values to be accessed after the location of the maker notes is changed by
+editing the EXIF. <i>[Bless their little hearts for trying to improve this
+situation, but while the idea is good the implementation is flawed and
+ultimately unworkable.]</i></p>
+<p>There are two main problems with the implementation, and the second is a show
+stopper:</p>
+<blockquote>1. For this new tag to be available to a single-pass metadata reader, it
+must come <i>before</i> the maker note data (hex. 0x927C, dec. 37500).  But
+since the EXIF/TIFF format specifies that tags must be stored in numerical
+order, the maker note tag (hex. 0x927C) comes before the OffsetSchema tag
+(hex. 0xEA1D).</blockquote>
+<blockquote>2. The OffsetSchema tag will be invalidated by any software that
+rewrites the EXIF and moves the maker notes without properly updating the tag.
+In an ideal world all application developers would release an updated version
+of their software which treats the OffsetSchema properly, and all users would
+update to this new version.  But since this is the real world it just won't
+happen, which makes the value of OffsetSchema unreliable.  Too bad, because this
+wouldn't have been a problem if Microsoft had specified that the new tag
+represented the original offset of the maker notes instead of the difference
+from the original position. With this change, the tag wouldn't need updating
+when the EXIF is edited, and the information would be much more reliable.  The
+only problem here would be editing software that explicitly changes the maker
+note offsets.  However, software with this ability is rare, and it is more
+reasonable to ask that the OffsetSchema tag simply be deleted by any software
+that updates the maker note offsets.  (Software must be fairly advanced in the
+first place if it parses the proprietary maker note data structures and changes
+these offsets.)</blockquote>
+<p><b>A simple solution:</b></p>
+<p>Create a new tag which comes before the maker notes (hex. 0x927B, dec. 37499
+would be good) and represents the original offset of the maker notes.</p>
+<a name="JPEG"></a>
+<h3>JPEG File Interchange Format <a class=ref href="#ref8">[8]</a></h3>
+<p>The JPEG File Interchange Format version 1.02 was released in 1992.  The
+biggest structural problem with this standard is that metadata in these files in
+is stored in segments which have a maximum size of 65533 bytes.  This limit has
+necessitated a number of creative solutions, each creating complications and
+problems of their own.  <i>[See my comments on the <a
+href="writing.html#Preview">PreviewImage problem</a> for example.]</i></p>
+<p><b>A simple solution:</b></p>
+<p>Since the value of the segment size word includes the 2 bytes of the segment
+size word itself, a value of 0 or 1 is not allowed by the current JPEG standard.
+The standard could be enhanced so a value of 1 indicates an extended JPEG
+segment where the 2-byte size word (with value 0x0001) is followed immediately
+by a 4-byte integer giving the size of the extended JPEG segment.  This would
+allow segment sizes of up to 4294967291 bytes (assuming the size includes these
+4 bytes). Further, a value of 0 could be defined for an 8-byte integer if one
+really wanted to support huge metadata segments.  Either change to an existing
+JPEG would break all current JPEG reader/writers, but the change is trivial and
+could easily be implemented.</p>
+<p><b>An alternative solution:</b></p>
+<p>Define a new application marker segment which uses a 4-byte size word.  This
+technique is already used for the extended JPEG2000 codestream MCT, MCC and MIC
+marker segments.</p>
+<a name="MPF"></a>
+<h3>Multi-Picture Format (MPF) <a class=ref href="#ref9">[9]</a></h3>
+<p>In February 2009 CIPA<a class=ref href="#ref10">[10]</a> released a
+"Multi-Picture Format" standard for storing large images in JPEG files.  This
+format is yet another attempt to bypass the JPEG segment-size limit (see above)
+to store large preview images.  But again, there is a significant problem with
+this standard:  Pointers in the new APP2 MPF segment use offsets relative to the
+start of the MPF header in this segment to reference image data after the JPEG
+EOI.  Unfortunately, these offsets are quickly broken if any data after the MPF
+segment changes length.  This problem could have been avoided if offsets had
+been specified relative to the end of file, but it is too late for this now that
+the specification is public.  However, another problem is that information after
+the JPEG EOI is often discarded by software when the file is edited.</p>
+<p><b>A possible work-around:</b></p>
+<p>Enforce the rule that the MPF APP2 segment must come after all other APP
+segments.  (It would have been smart if this was specified in the CIPA standard,
+but sadly this wasn't the case.)  If this is done, then metadata in the remaining
+APP segments (EXIF, IPTC, XMP, etc) can safely be edited without breaking the
+MPF offsets.  I suggest that all metadata editors employ this strategy,
+regardless of the segment order specified in the standard (which says that the
+MPF APP2 segment must come immediately after the EXIF APP1 segment).</p>
+<p>Unfortunately this work-around has the same problems as the Microsoft
+OffsetSchema tag because the MPF information may easily be invalidated by an
+unaware editor, and it doesn't address the problem of losing data stored after
+the JPEG EOI.</p>
+<p><b>A simple solution:</b></p>
+<p>Change the JPEG specification to allow larger segments (as mentioned above in
+the JPEG section), and change the MPF specification to store all information
+inside a JPEG segment.</p>
+<a name="refs"></a>
+<h3>References</h3>
+<ol>
+<li><a name="ref1" href="http://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf">http://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf</a></li>
+<li><a name="ref2" href="http://partners.adobe.com/public/developer/en/tiff/TIFFPM6.pdf">http://partners.adobe.com/public/developer/en/tiff/TIFFPM6.pdf</a></li>
+<li><a name="ref3" href="http://www.adobe.com/products/dng/pdfs/dng_spec_1_3_0_0.pdf">http://www.adobe.com/products/dng/pdfs/dng_spec_1_3_0_0.pdf</a></li>
+<li><a name="ref4" href="http://www.cipa.jp/english/hyoujunka/kikaku/pdf/DC-008-2010_E.pdf">http://www.cipa.jp/english/hyoujunka/kikaku/pdf/DC-008-2010_E.pdf</a></li>
+<li><a name="ref5" href="http://www.metadataworkinggroup.org/pdf/mwg_guidance.pdf">http://www.metadataworkinggroup.org/pdf/mwg_guidance.pdf</a></li>
+<li><a name="ref6" href="http://www.adobe.com/devnet/xmp/">http://www.adobe.com/devnet/xmp/</a></li>
+<li><a name="ref7" href="http://support.microsoft.com/kb/927527">http://support.microsoft.com/kb/927527</a></li>
+<li><a name="ref8" href="http://www.jpeg.org/public/jfif.pdf">http://www.jpeg.org/public/jfif.pdf</a></li>
+<li><a name="ref9" href="http://www.cipa.jp/english/hyoujunka/kikaku/pdf/DC-X007-KEY_E.pdf">http://www.cipa.jp/english/hyoujunka/kikaku/pdf/DC-X007-KEY_E.pdf</a></li>
+<li><a name="ref10" href="http://www.cipa.jp/english/hyoujunka/kikaku/cipa_e_kikaku_list.html">http://www.cipa.jp/english/hyoujunka/kikaku/cipa_e_kikaku_list.html</a></li>
+</ol>
+<hr>
+<i>Created Sep 17, 2009</i><br>
+<i>Last revised Jan 8, 2013</i>
+<p class='lf'><a href="index.html">&lt;-- Back to ExifTool home page</a></p>
+</body>
+</html>

data/vendor/Image-ExifTool-9.27/html/struct.html ADDED

@@ -0,0 +1,342 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
+<html>
+<head>
+  <title>Structured Information</title>
+<link rel=stylesheet type='text/css' href='style.css' title='Style'>
+<style type="text/css">
+<!--
+pre  { padding: 0; margin: 0px 2px }
+spc  { margin-top: 5em }
+li   { margin-top: .5em }
+li.c { margin-top: 0 }
+-->
+</style>
+</head>
+<body>
+<div class='index'>
+<a href="#Reading">Reading</a>
+<br><a href="#Writing">Writing</a>
+<br><a href="#Copying">Copying</a>
+<br><a href="#Deleting">Deleting</a>
+<br><a href="#Fields">Field Names</a>
+<br><a href="#Serialize">Serialization</a>
+<br><a href="#User">User-Defined</a>
+</div>
+<h1 class='up'>Structured Information</h1>
+<p>ExifTool has the ability to read and write XMP structures through the use of
+either <b>structured or flattened tags</b>.  The ability to write via structured
+input was added in ExifTool version 8.44; older versions wrote using flattened
+tags only.</p>
+<p>To illustrate the concept of a flattened tag, the <code>XMP-exif:Flash</code>
+structure contains <code>Fired</code> and <code>Mode</code> fields (among
+others).  The flattened tags corresponding to these structure fields are
+<code>XMP-exif:FlashFired</code> and <code>XMP-exif:FlashMode</code>.  In the
+<a href="TagNames/XMP.html">XMP Tags documentation</a>, flattened tags are
+indicated by an underline (<code>_</code>) after the Writable type.</p>
+<p>This page describes various techniques used to read and write XMP structures
+using both structured and flattened tags.</p>
+<a name='Reading'></a>
+<h2>Reading</h2>
+<p>When reading, structures are <b>flattened by default</b>, and ExifTool
+returns one "flattened" tag for each field in the structure:</p>
+<blockquote><table class='box'><tr><td>
+<pre>&gt; <span class=code>exiftool -xmp:all a.xmp</span>
+XMP Toolkit                     : Image::ExifTool 8.44
+Flash Fired                     : True
+Flash Mode                      : On
+Flash Return                    : Return not detected</pre>
+</td></tr></table></blockquote>
+<p>But the <code>-struct</code> option may be used to give <b>structured
+output</b>.  In this mode structures are returned instead of separate
+"flattened" tags:</p>
+<blockquote><table class='box'><tr><td>
+<pre>&gt; <span class=code>exiftool -struct -xmp:all a.xmp</span>
+XMP Toolkit                     : Image::ExifTool 8.44
+Flash                           : {Fired=True,Mode=On,Return=Return not detected}</pre>
+</td></tr></table></blockquote>
+<p class=lt>(Note: As illustrated in the example above, structures are
+<a href='#Serialize'>serialized</a> for console output by the ExifTool
+application. However, via the API with the <code>Struct</code> option,
+they are returned as Perl HASH references.)</p>
+<p>The <code>-struct</code> option may also be combined with the JSON
+(<code>-j</code>), PHP (<code>-php</code>) or XML (<code>-X</code>) output
+formats to provide a structured format which may be more compatible with other
+applications.</p>
+<a name='Writing'></a>
+<h2>Writing</h2>
+<p>When writing, <b>flattened tags and structures may be used interchangeably</b>.
+For example, the following commands all have the same effect.</p>
+<blockquote><table class='box'><tr><td>
+<pre class=code>exiftool -flashmode=on -flashreturn=not -flashfired=true a.xmp
+exiftool -xmp:flash="{mode=on,fired=true}" -flashreturn=not a.xmp
+exiftool -xmp:flash="{mode=on,fired=true,return=not}" a.xmp</pre>
+</td></tr></table></blockquote>
+<p class=lt>(Note:  Structures must be <a href='#Serialize'>serialized</a> when
+writing via the command-line application, in the same format as when reading with
+the <code>-struct</code> option.)</p>
+<p>An advantage of writing in structured form is that it can be easier to
+achieve the desired hierarchy with complex structures or when there are multiple
+structures in a list.  For example, this command adds a new hierarchical keyword
+to the XMP-mwg-kw:HierarchicalKeywords list:</p>
+<blockquote><table class='box'><tr><td>
+<pre class=code>exiftool -hierarchicalkeywords+="{keyword=cat,children={keyword=Siamese}}" a.jpg</pre>
+</td></tr></table></blockquote>
+<p>But the flattened tags may be more convenient for <b>adding or replacing a
+single field</b> in an existing structure because writing as a structure would
+requires that entire structure be replaced.  For example, the following command
+adds a new second-level keyword to an existing HierarchicalKeywords structure:</p>
+<blockquote><table class='box'><tr><td>
+<pre class=code>exiftool -hierarchicalkeywords2+="Persian" a.jpg</pre>
+</td></tr></table></blockquote>
+<p><b>Tricky:</b> There is one drawback when using this technique to add new
+fields to existing structures in lists:  New fields are added to the first
+structure which doesn't already contain the corresponding field.  So before
+adding a new field to a arbitrary structure, dummy fields must first be added to
+all earlier structures in the list which are missing this field.  However, the
+alternative of adding a new field by writing structured information also has its
+drawbacks. Here, although a specific structure in a list can easily be targeted
+through any unique combination of field values, the drawback is that the entire
+structure must be replaced (see <a href="#Deleting">Deleting / Replacing</a>
+below).</p>
+<p>The flattened tag names may also be used to <b>write structures at any level
+in a complex hierarchy</b>.  The following example writes a third-level
+structure inside a HierarchicalKeywords structure:</p>
+<blockquote><table class='box'><tr><td>
+<pre class=code>exiftool -hierarchicalkeywords2Children='{Keyword=Tabby,Applied=true}' a.jpg</pre>
+</td></tr></table></blockquote>
+<p class=lt>(Note: Containing structures are created as necessary.  In this
+case, the HierarchicalKeywords and top-level KeywordInfo structures would be
+created if they didn't already exist.)</p>
+<p>The <b>order of structure fields is not significant</b>, so they may be read
+in a different order then written, unlike arrays which maintain the same order.
+To give a predictable output, fields in structured information are <b>sorted in
+alphabetical order</b> of field name by ExifTool when reading and writing.</p>
+<p>If there are <b>errors converting some fields</b> of the input structure,
+other fields are still written and a warning is issued (but only one warning per
+structure is reported).  This also applies when copying structured information
+except that the <code>-v3</code> option must be used to see the warnings when
+copying.</p>
+<p><b>Programmers:</b> Structured information is written and read as Perl HASH
+references via the ExifTool API, but it may also be written as a serialized
+string.  The following two techniques are equivalent:</p>
+<blockquote><table class='box'><tr><td>
+<pre># as a HASH reference
+<span class=code>$exifTool-&gt;SetNewValue('XMP:Flash' =&gt; { mode=>'on', fired=>'true', return=>'not' });
+</span>
+# as a serialized string
+<span class=code>$exifTool-&gt;SetNewValue('XMP:Flash' =&gt; '{mode=on,fired=true,return=not}');</span></pre>
+</td></tr></table></blockquote>
+<a name='Copying'></a>
+<h2>Copying</h2>
+<p>By default, tags are <b>copied as structures</b>, but flattened tag names
+may still be copied by specifying them explicitly.  Copying as structures
+allows the hierarchy of complex structures to be preserved.</p>
+<blockquote><table class='box'><tr><td>
+<pre># this copies all XMP information as structures
+# (flattened tags are not copied by default...)
+<span class=code>exiftool -tagsfromfile src.jpg -xmp:all dst.jpg
+</span>
+# ... but flattened tags may be copied individually.  Here the
+# first level hierarchical keywords are copied to the Subject tag
+# (this may be done in the same command as one that copies structures)
+<span class=code>exiftool -tagsfromfile src.jpg "-subject&lt;hierarchicalkeywords1" dst.jpg</span></pre>
+</td></tr></table></blockquote>
+<p>Note that when copying a specific structure, only the top-level structures
+may be specified:</p>
+<blockquote><table class='box'><tr><td>
+<pre># this copies the complete keyword hierarchy
+<span class=code>exiftool -tagsfromfile src.jpg -keywordinfo dst.jpg
+</span>
+# WRONG because HierarchicalKeywords is NOT a top-level structure!
+<span class=code>exiftool -tagsfromfile src.jpg -hierarchicalkeywords dst.jpg</span></pre>
+</td></tr></table></blockquote>
+<p>The copy-as-structure feature may be disabled with <code>--struct</code> on
+the command line, or by setting the <a href="ExifTool.html#Struct">Struct option</a>
+to 0 via the API.  When this is done, only flattened tags are copied, and
+structures may not be specified. Conversely, if the structure option is enabled
+(by setting the <a href="ExifTool.html#Struct">Struct option</a> to 1 via the API,
+or with <code>-struct</code> on the command line), only structures are copied,
+and flattened tags may not be specified.</p>
+<p class=lt>(Note: This method of copying as flattened tags was the default
+behaviour with ExifTool 8.43 and earlier.  Copying as structures has been the
+default since the ability to write structured information was introduced in
+version 8.44, but an enhancement in version 8.82 allowed flattened tags to be
+copied explicitly without the need to disable the Struct option.)</p>
+<a name='Deleting'></a>
+<h2>Deleting / Replacing</h2>
+<p>A <b>complete structure is deleted</b> by specifying one or more matching
+fields. For example, the following command deletes all HierarchicalKeywords
+structures which have the Keyword "<code>Terrier</code>" at the second level:</p>
+<blockquote><table class='box'><tr><td>
+<pre class=code>exiftool -hierarchicalkeywords-="{Children={Keyword=Terrier}}" a.jpg</pre>
+</td></tr></table></blockquote>
+<p>Structure <b>fields may also be deleted individually</b> using the flattened
+tag names. The following command deletes only the matching fields from the
+second-level of all HierarchicalKeywords structures:</p>
+<blockquote><table class='box'><tr><td>
+<pre class=code>exiftool -hierarchicalkeywords2-="Terrier" a.jpg</pre>
+</td></tr></table></blockquote>
+<p>When deleting and adding back items in lists in the same command, new items
+are inserted at the point in the list where the first item was removed, or at
+the end of the list if no items were deleted.  This applies to lists of
+structures as well as simple lists of string values, and provides a mechanism to
+replace a specific structure or field.</p>
+<a name='Fields'></a>
+<h2>Field Names</h2>
+<p>Structure field names use a format <b>very similar to tag names</b> in
+ExifTool.  The following table lists some similarities and differences
+between tag names and structure field names:</p>
+<blockquote><table border=1 cellspacing=0 cellpadding=4 width='100%'>
+<tr><th>Feature</th><th>Example</th><th>Tag Names</th><th>Field Names</th></tr>
+<tr align=center><td align=left>Case Insensitivity</td><td>Title, title, TITLE</td>
+<td class=grn>Yes</td><td class=grn>Yes</td></tr>
+<tr align=center><td align=left>Alternate Language Suffix</td><td>Title-de</td>
+<td class=grn>Yes</td><td class=grn>Yes</td></tr>
+<tr align=center><td align=left>Numerical Value Suffix</td><td>Mode#</td>
+<td class=grn>Yes</td><td class=grn>Yes</td></tr>
+<tr align=center><td align=left>Group Name Prefix</td><td>XMP-dc:Title</td>
+<td class=grn>Yes</td><td class=red>No<sup>&dagger;</sup></td></tr>
+</table>
+<sup class=red>&dagger;</sup> Except that group name prefixes are
+allowed in structures which support arbitrary XMP fields (ie.
+<a href='TagNames/MWG.html#Extensions'>Region Extensions</a>)
+</blockquote>
+<a name='Serialize'></a>
+<h2>Serialization</h2>
+Structures are <b>serialized when reading or writing from the command line</b>.
+However, serialization is not done when reading via the API, and is optional when
+writing via the API.  The serialization algorithm is as follows:
+<ol>
+<li>Escape the following characters in string values (structure field values and
+list items) by adding a leading pipe symbol (<code>|</code>):
+<ul>
+<li class=c>pipe symbols (<code>|</code>) and commas (<code>,</code>) anywhere in the string</li>
+<li class=c>closing curly brackets (<code>}</code>) anywhere in structure field values</li>
+<li class=c>closing square brackets (<code>]</code>) anywhere in list items</li>
+<li class=c>an opening curly (<code>{</code>) or square (<code>[</code>)
+bracket, or whitespace character (SPACE, TAB, CR or LF) if it appears at the
+beginning of the string</li>
+</ul>
+<span class=lt>(Note: Any other character may be escaped by adding
+a leading pipe symbol without effect.)</span></li>
+<li>Enclose structures in curly brackets.  Use an equal sign (<code>=</code>)
+to separate field names from their corresponding values, and a comma between
+structure fields.</li>
+<li>Enclose lists in square brackets, with a comma between list items.</li>
+<li>Optional whitespace padding may be added anywhere except inside a structure
+field name, or inside or after a string value, and an optional comma may be
+added after the last field in a structure.</li>
+</ol>
+<p>For example, with a command like this:</p>
+<blockquote><table class='box'><tr><td>
+<pre class=code>exiftool "-RegionInfo&lt;=INFILE" a.xmp</pre>
+</td></tr></table></blockquote>
+<p>the INFILE below may be used to write structured information to
+XMP:RegionInfo.</p>
+<blockquote><table class='box'><tr><td>
+<pre>{
+  AppliedToDimensions =
+  {
+     W = 4288,
+     H = 2848,
+     Unit = pixel,
+  },
+  RegionList =
+  [
+    {
+      Area =
+      {
+        W = 0.15, H = 0.17, X = 0.3, Y = 0.4,
+        Unit = normalized,
+      },
+      Description = A Physics Icon {relatively speaking|},
+      Name = Albert Einstein,
+      Type = Face,
+      Extensions = {
+        XMP-xmpRights:UsageTerms = copyright Phil Harvey,
+        XMP-xmpRights:UsageTerms-fr = droit d'auteur Phil Harvey,
+      },
+      SeeAlso = dc:subject,
+    },
+    {
+      Area =
+      {
+        W = 0.06, H = 0.09, X = 0.5, Y = 0.6,
+        Unit = normalized,
+      },
+      Description = this is a test|, what did you expect?,
+      Type = Focus,
+      FocusUsage = EvaluatedUsed,
+    }
+  ],
+}</pre>
+</td></tr></table></blockquote>
+<p>In this example, white space has been added in all allowed locations for
+demonstration purposes and to improve readability.  Also, optional commas have
+been added after the last field of each structure.  (Note that a comma may NOT
+be added after the last item in a list because this would be interpreted as an
+additional list item of a zero-length string.)</p>
+<a name='User'></a>
+<h2>User-Defined Structures</h2>
+<p>User-defined XMP structure tags may be created via the ExifTool config file.
+See the NewXMPxxxStruct tag definition in the <a href="config.html#xmp-xxx">XMP-xxx
+examples of the sample config file</a> for more details.</p>
+<hr>
+<i>Last revised Mar. 10, 2012</i>
+<p class='lf'><a href="index.html">&lt;-- Back to ExifTool home page</a></p>
+</body>
+</html>