Tag That Photo User Guide - Part 5¶

Metadata Management and Technical Details¶

Understanding Metadata Management¶

What is Metadata?¶

Metadata is "data about data" - information embedded in or alongside your image files describing: - Who is in the photo (face tags) - When it was taken (date/time) - Where it was taken (GPS coordinates, location names) - What it contains (keywords, descriptions) - Technical details (camera settings, dimensions)

TTP's Metadata Philosophy¶

Tag That Photo is built on the principle that you should own your metadata. Your tags and organizational work should:

1. Be portable - not locked in proprietary databases
2. Use industry standards - readable by other applications
3. Travel with your images - embedded in the files themselves
4. Survive software changes - not dependent on any single vendor

This is why TTP writes metadata directly into your images using Adobe XMP format and other industry standards.

ExifTool: TTP's Metadata Engine¶

Tag That Photo uses ExifTool (by Phil Harvey) as its primary engine for reading and writing image metadata. ExifTool is the gold standard for image metadata processing and supports hundreds of metadata formats across thousands of camera and software types.

Key benefits of using ExifTool:

• Broad format support — Reads and writes metadata in JPEG, TIFF, PNG, HEIC, and virtually all RAW formats
• Standards compliant — Fully supports EXIF, IPTC, and XMP standards
• Reliable — Used by professional photographers and researchers worldwide
• Full Unicode support — Handles non-Latin characters in all metadata fields via UTF-8

Family History Metadata Working Group (FHMWG)¶

Tag That Photo supports the recommendations of the Family History Metadata Working Group (FHMWG), a collaborative effort focused on key metadata areas cherished by family historians — names, dates, locations, events, and captions. By embedding metadata directly into image files using existing standards like IPTC, XMP, and EXIF, TTP helps preserve family history information for future generations.

More information: https://savemetadata.org/

Metadata Standards Used by TTP¶

Storage Locations¶

For JPEG Images¶

Metadata is embedded directly within the image file in multiple formats: - EXIF - Camera and technical data - IPTC - Descriptive information (keywords, captions) - XMP - Modern extensible format (includes face regions)

Sidecar reading: TTP will read an .xmp sidecar alongside a JPEG if one is present. This ensures that tags created while TTP was in Non-Embedded mode are always visible, even after switching back to Sync mode.

Sidecar writing: In Sync mode (default), TTP writes metadata directly into the JPEG file. If a sidecar already exists alongside the JPEG, TTP also updates it to stay in sync. TTP does not create a new sidecar for JPEG in Sync mode. To create JPEG sidecars, enable Non-Embedded mode (see Export Settings below).

For TIFF Images¶

Metadata is embedded directly within the TIFF file (EXIF, IPTC, and XMP). TTP also writes a matching XMP sidecar file alongside every TIFF, keeping both in sync automatically. You do not need to manage this — TTP creates the sidecar if one doesn't exist and always updates both on every write.

For PNG and RAW Images¶

Metadata is stored in an XMP sidecar file only: - Same filename as image, with .xmp extension (e.g., photo.cr2.xmp) - Plain text XML format - Typically less than 20KB in size - Human-readable (open in any text editor)

Critical: When moving these images, always move the .xmp file with them!

For HEIC Images¶

TTP reads embedded XMP written into HEIC files by other applications (such as Apple Photos or the iOS camera), and also reads the accompanying .xmp sidecar if one is present.

In Sync mode, TTP now writes metadata to both the embedded XMP inside the .heic file and the .xmp sidecar file, keeping them in sync automatically. (Embedded HEIC write is newly added and requires testing.)

In Non-Embedded mode, TTP writes to the .xmp sidecar only — the original .heic file is never modified.

Critical: When moving HEIC images out of TTP's managed folders, always move the .xmp sidecar file with them.

Sidecar Support Summary¶

† HEIC embedded write is newly added and requires testing.

Face Region Standards¶

TTP supports three face region metadata standards and writes to all three simultaneously for maximum compatibility.

1. Metadata Working Group (MWG)¶

• Industry-wide standard
• Supported by Adobe, Apple, and others
• Broadest application compatibility
• Uses center-point normalized coordinates (0.0–1.0)
• Reference: MWG Guidelines PDF

2. Microsoft Photo Region Info (MPRI)¶

• Used by Microsoft Photo Gallery
• Windows Explorer reads and displays these regions
• Good for Windows ecosystem compatibility
• Uses top-left corner coordinates
• Specification: Microsoft Photo 1.2 Schema

3. IPTC Extension (ImageRegion)¶

• Part of the IPTC Photo Metadata Standard
• Growing adoption in newer photo applications
• Includes both face region coordinates and a simple PersonInImage name list
• Uses center-point normalized coordinates (same as MWG)
• Reference: IPTC Photo Metadata

Recommendation: Enable all three formats in Settings for maximum compatibility.

TTP also normalizes face coordinates using current orientation data to prevent drift on images with non-standard EXIF orientation metadata.

How TTP Reads Metadata¶

When TTP scans an image, it reads from multiple tag locations using a priority-based fallback system. The first non-empty value found in the priority list is used.

How TTP Detects Metadata Changes¶

TTP marks a file for metadata re-read when one or more of these signals is detected during scan:

1. The image file's last-write timestamp changed
2. The .xmp sidecar was newly created or its timestamp changed
3. The image's XMP:MetadataDate differs from the canonical metadata date stored in TTP

If a metadata-triggered re-read changes effective canonical values (for example keywords, location, title fields), the corresponding sections are marked dirty so the reconciled DB state can be exported back to files.

Additional workflow behavior:

• Pending metadata changes are shown only when values actually differ
• Newly scanned files are queued for export only when your metadata settings require it
• After folder scans, TTP can prompt you to apply pending metadata updates immediately

Reading Priority¶

Title¶

Read from (in priority order):

1. XMP-dc:Title / XMP:Title
2. IPTC:Headline

Description (Caption)¶

Read from (in priority order):

1. XMP-dc:Description / XMP:Description
2. IPTC:Caption-Abstract

Keywords¶

Read from (in priority order, all sources merged):

1. XMP-dc:Subject
2. XMP:Subject
3. IPTC:Keywords

Logic: All keyword lists are merged into a single deduplicated list. Keywords that match person names are stored as people (not keywords) unless "Export Names as Keywords" is also enabled.

Date Taken¶

Read from (in priority order):

1. XMP-photoshop:DateCreated
2. XMP:DateCreated
3. EXIF:DateTimeOriginal
4. EXIF:CreateDate

Date precision options now support:

• Full date + time
• Date-only
• Year-only (helpful for historical archives)

GPS Coordinates¶

Read from (in priority order):

1. EXIF:GPSLatitude, EXIF:GPSLongitude (with Ref tags)
2. XMP:GPSLatitude, XMP:GPSLongitude

Supported GPS formats:

• DMS: 39 deg 46' 54.12" N
• Compact: 39,46,54.12N
• Decimal Degrees: 39.7817 or -89.6501

Both latitude AND longitude must be present to constitute a valid GPS entry. Altitude is optional.

Location (Address)¶

Read from (in priority order):

1. Structured IPTC Extension LocationShown object — extracts City, State/Province, Country, Sublocation, and free-form venue name (LocationName) as a single unit
2. Flat XMP/IPTC tags as fallback: XMP-photoshop:City, IPTC:City, XMP-photoshop:State, IPTC:Province-State, IPTC:Country-PrimaryLocationName, etc.

Face Regions¶

Read from (in priority order — only ONE source used to avoid duplicates):

1. MWG (XMP-mwg-rs:RegionInfo)
2. Microsoft MP (XMP-MP:RegionInfoMP)
3. IPTC Extension (XMP-iptcExt:ImageRegion)

Logic: Regions are read from the highest-priority source that contains regions. This prevents duplicate faces from appearing when a file already contains regions in multiple formats.

Author / Creator¶

Read from (in priority order):

1. XMP-dc:Creator / XMP:Creator
2. EXIF:Artist

Copyright¶

Read from (in priority order):

1. XMP-dc:Rights / XMP:Rights
2. EXIF:Copyright

How TTP Writes Metadata¶

When metadata writing is enabled, TTP uses ExifTool to write your tags to standard locations in the image file (or its XMP sidecar).

Metadata Write Locations¶

Structured Location Writing¶

TTP writes all location information — city, state/province, country, sublocation (venue address), and free-form location name — as a single structured IPTC Extension LocationShown object. This is more standardized than writing each field to a separate tag and provides better compatibility with IPTC-compliant applications.

Example of what TTP writes:

LocationShown[0].City             = Springfield
LocationShown[0].ProvinceState    = Illinois
LocationShown[0].CountryName      = United States
LocationShown[0].Sublocation      = Lincoln Home
LocationShown[0].LocationName     = Abraham Lincoln's House

The Sublocation field holds the specific address or venue name, while LocationName holds a free-form descriptive name for the location.

Location editing improvements now make it easier to maintain both structured address data and user-friendly location titles together.

Metadata Writing Process¶

Writing happens as a background process:

1. You tag faces or add keywords in TTP
2. Changes are saved to the TTP database immediately
3. A background service queues the image for a metadata update
4. When the system is idle, metadata is written to the image files
5. The XMP metadata date is updated to track the modification

Priority: User actions always have priority over background metadata writing.

For large batches, TTP now keeps a shared ExifTool session active across the write queue, which significantly reduces per-file overhead during bulk metadata operations.

Metadata Merge and Reconciliation¶

When TTP reads metadata from an image during import or a re-scan, it merges the file's metadata with what is already stored in its database. The goal is to never lose your tagging work, while still picking up new information from the image files.

Canonical Model for Duplicate Physical Files¶

When multiple physical files have the same pixel hash and orientation, TTP treats them as one logical image (TtpImage) with multiple attached ImageFiles.

• Metadata is reconciled into one canonical DB record
• If re-import detects metadata-driven changes, dirty sections are flagged on that canonical record
• When metadata export runs, TTP writes the reconciled canonical state back to all physical copies linked to that logical image

General Merge Rules¶

Handling Date Discrepancies¶

If TTP finds a different date in the image file than what is stored in the database, it:

1. Keeps the existing database date as the canonical (displayed) date
2. Records the alternate date for user review
3. Displays a discrepancy indicator in the UI so you can resolve the conflict

Year-Only Dates (Historical Photos)¶

Some applications — including Adobe Photoshop — store year-only dates for historical photos, writing just "1922" rather than a full date and time. TTP handles this gracefully:

• A year-only value like "1922" is interpreted as January 1^st at midnight of that year internally
• For discrepancy detection, January 1^st at midnight and January 1^st at noon of the same year are treated as equivalent — no conflict is reported
• This prevents false discrepancy warnings when different applications normalize the same historical year-only date in slightly different ways

Example:

Photoshop writes:  "1922"              → interpreted as 1922-01-01 00:00
Another app has:   1922:01:01 12:00:00 → interpreted as 1922-01-01 12:00

Result: No discrepancy reported (year-only equivalence rule applied)

In the UI: When the date is January 1^st at midnight, TTP can display it simply as 1922 rather than "January 1, 1922 12:00 AM," giving a cleaner look for historical photos.

Fuzzy Name Matching During Import¶

When reading person names from image metadata (face region tags, PersonInImage, or keywords), TTP uses fuzzy name matching to link names to existing people in the database:

• Similarity threshold: 0.90 (90% match required)
• Handles minor name variations such as slight misspellings or alternate forms
• Applies special handling for generational suffixes (Sr, Jr, I, II, III, etc.) — these are treated as identity-critical and will never be matched across different suffixes even when the base names are identical
• If no match is found at the threshold, a new person record is created automatically

Export Settings (What Gets Written)¶

You can control exactly which metadata fields TTP writes when exporting. These settings are found in Settings > Metadata.

Tip: Enable Export Names as Keywords for compatibility with Adobe Lightroom, Apple Photos, and other applications that read people's names from the keyword list rather than from face region tags.

Metadata Write Mode: Sync vs Non-Embedded¶

TTP supports two metadata write modes, controlled by the Non-Embedded Metadata Mode setting.

These modes only apply when Export Image Metadata is ON. If Export Image Metadata is OFF, TTP does not write metadata in either mode.

Sync Mode (Default — Non-Embedded Off)¶

TTP writes metadata directly into the original image file. Where TTP supports both embedded and sidecar formats, it keeps them in sync automatically.

Best for: Users who want GPS and date metadata visible in Windows Explorer, mobile apps, and other software that reads EXIF directly.

Non-Embedded Mode (Non-Embedded On)¶

TTP never modifies the original image file. All metadata is written to a .xmp sidecar file only.

• Embedded EXIF and embedded XMP writes are completely skipped.
• A .xmp sidecar is created automatically alongside each image if one does not exist.
• Works for all formats, including JPEG.

Best for: Users with archival or original-preservation requirements, or workflows where modifying original files is not acceptable.

GPS and date trade-off: In Non-Embedded mode, GPS coordinates and date-taken are stored in the sidecar only. Applications that read only EXIF (Windows Explorer, most mobile apps) will not display GPS location or date information.

Switching modes: Switching from Sync to Non-Embedded does not retroactively remove embedded data from files that TTP has already written. Future writes go to sidecar only.

Future-Proofing Your Tags¶

Why Standards Matter¶

By writing face tags using MWG, Microsoft, and IPTC standards, your tags:

• Survive vendor changes - not locked to TTP
• Work in other applications - see compatibility chart below
• Remain accessible - XML text format, not binary
• Follow industry direction - MWG widely adopted; IPTC Extension growing rapidly

Verifying Your Metadata¶

You can inspect metadata using free tools:

ExifTool (Command Line)¶

Free utility by Phil Harvey for reading/writing metadata — the same tool TTP uses internally.

Uses: - View all metadata in an image - Export metadata to CSV - Repair corrupted metadata - Batch metadata operations

Download: https://exiftool.org/

Quick check command:

exiftool -j -struct filename.jpg

XnViewMP (Graphical Interface)¶

Free image viewer with excellent metadata display.

Features: - Visual metadata browser - Handles XMP sidecars - Can strip metadata if needed - Supports batch operations

Download: www.xnview.com

Data Quality Checks¶

The Stats tab includes a Data Quality section that runs multiple checks each time you open the Stats page:

After completing a folder scan, TTP can prompt you to review the Stats > Data Quality section and resolve detected issues immediately.

Cross-Application Compatibility¶

Applications That Read TTP Tags¶

Note: The PersonInImage tag — a simple list of person names that TTP writes to every image — provides a useful fallback for applications that don't support full face region coordinate standards. Those applications can still display who is in the photo.

End of Part 5: Metadata & Technical Details

Continue to Part 6: Troubleshooting & Appendix...