arMetadataExtractionPlugin for AtoM 2.9

Automatic EXIF, IPTC, and XMP Metadata Extraction for Access to Memory (AtoM)

---

📛 Status & Compatibility

---

📦 Overview

The arMetadataExtractionPlugin is a Symfony 1.4 plugin for AtoM 2.9 that automatically extracts and applies embedded metadata (EXIF, IPTC, XMP) from digital objects uploaded to AtoM.

It enhances AtoM’s digital object ingest workflow by:

• Improving description quality
• Reducing manual metadata entry
• Creating actors, events, access points, and notes automatically
• Populating ISAD(G), RAD, and DACS fields intelligently

---

🚀 Features

🔍 Automatic Metadata Extraction

Reads metadata using ExifTool, including:

• Camera data (EXIF)
• Captions, by-lines, keywords (IPTC)
• XMP descriptions, subjects, rights (XMP)
• GPS coordinates
• Technical metadata (exposure, aperture, ISO)

🧠 Intelligent Metadata Mapping

Metadata Source	AtoM Field	Notes
XMP Title / IPTC Headline	Title	Configurable overwrite
IPTC Caption / XMP Description	Scope & Content	Optional overwrite
Creator fields	Actor + Event	Auto-creates actors
EXIF DateTimeOriginal	Event Date	Parsed as YYYY-MM-DD
XMP/Keyword arrays	Access Points	Creates subject terms
GPS Lat/Long	Digital Object Geolocation	Stored in object
Camera ISO, lens, shutter	Physical Characteristics	Optional append
Copyright statement	Conditions of Access	Only if empty

🧬 Auto-Generated Keywords

Based on camera type and settings:

• "Canon Photography"
• "Mobile Photography"
• "Telephoto Photography"
• "Wide Angle Photography"
• "High ISO Photography"
• "Digital Photography"

⚙ Fully Configurable Admin Settings

Available in:

Admin → Settings → EXIF/IPTC/XMP

Options include:

• Enable/disable extraction
• EXIF / IPTC / XMP toggle
• Overwrite vs only fill empty fields
• Auto-generate keywords
• Append technical metadata
• Extract GPS coordinates
• Select ISAD field to store technical metadata

---

📸 Example Output

Below is an example of how the plugin automatically extracts and applies metadata:

📋 Requirements

• AtoM 2.9.x
• PHP 8.3+
• exiftool
• Ubuntu Server 22.04 / 24.04 recommended
• Nginx + PHP-FPM
• AtoM’s built-in arEmbeddedMetadataParser

---

🛠 Installation

1. Copy the Plugin

cd /usr/share/nginx/atom_psis/plugins/
sudo cp -r /path/to/arMetadataExtractionPlugin ./
sudo chown -R www-data:www-data arMetadataExtractionPlugin/
sudo chmod -R 755 arMetadataExtractionPlugin/
2. Override AtoM's Digital Object Upload Action
Option A — Core File Replacement (quick testing)
bash
Copy code
sudo cp /usr/share/nginx/atom_psis/apps/qubit/modules/object/actions/addDigitalObjectAction.class.php \
    /usr/share/nginx/atom_psis/apps/qubit/modules/object/actions/addDigitalObjectAction.class.php.backup

sudo cp arMetadataExtractionPlugin/modules/object/actions/addDigitalObjectAction.class.php \
    /usr/share/nginx/atom_psis/apps/qubit/modules/object/actions/
Option B — Local Override (production-safe)
bash
Copy code
sudo mkdir -p /usr/share/nginx/atom_psis/apps/qubit/modules/object/actions/
sudo cp arMetadataExtractionPlugin/modules/object/actions/addDigitalObjectAction.class.php \
    /usr/share/nginx/atom_psis/apps/qubit/modules/object/actions/
3. Clear Symfony Cache
bash
Copy code
cd /usr/share/nginx/atom_psis/
sudo -u www-data php symfony cc
4. Optional: Rebuild Doctrine Classes
bash
Copy code
sudo -u www-data php symfony doctrine:build --all-classes
5. Verify Installation
Login as admin

Navigate to Admin → Settings → EXIF/IPTC/XMP

Confirm the settings page loads

Upload a digital object to test extraction

⚙ Plugin Configuration
Accessible at:

Admin → Settings → EXIF/IPTC/XMP

Settings Include:
Metadata Types
Extract EXIF

Extract IPTC

Extract XMP

Field Behavior
Overwrite titles

Overwrite descriptions

Advanced
Auto-generate keywords

Add technical metadata to chosen field

Extract GPS coordinates

Enable/disable entire plugin

📂 Plugin Structure
vbnet
Copy code
arMetadataExtractionPlugin/
├── config/
│   └── arMetadataExtractionPluginConfiguration.class.php
├── lib/
│   └── arMetadataExtractor.class.php
├── modules/
│   ├── object/
│   │   └── actions/
│   │       └── addDigitalObjectAction.class.php
│   └── settings/
│       ├── actions/
│       │   └── metadataExtractionAction.class.php
│       └── templates/
│           └── metadataExtractionSuccess.php
└── README.md
🧪 Usage
Go to any Information Object

Upload a digital object

Metadata is automatically extracted on save

Mapped metadata is applied to the description

Events, actors, subjects, and notes are created automatically

🐛 Troubleshooting
Check if exiftool is installed
bash
Copy code
which exiftool
Check plugin permissions
bash
Copy code
ls -la /usr/share/nginx/atom_psis/plugins/arMetadataExtractionPlugin/
View AtoM logs
bash
Copy code
tail -f /usr/share/nginx/atom_psis/log/frontend_*.log
Clear cache
bash
Copy code
php symfony cc
Check GPS metadata
bash
Copy code
exiftool -GPS* photo.jpg
🧹 Uninstallation
Restore original upload action
bash
Copy code
sudo mv /usr/share/nginx/atom_psis/apps/qubit/modules/object/actions/addDigitalObjectAction.class.php.backup \
    /usr/share/nginx/atom_psis/apps/qubit/modules/object/actions/addDigitalObjectAction.class.php
Remove plugin
bash
Copy code
sudo rm -rf /usr/share/nginx/atom_psis/plugins/arMetadataExtractionPlugin/
Clear cache
bash
Copy code
php symfony cc
👨‍💻 Development
Extend extraction logic
Modify:

vbnet
Copy code
lib/arMetadataExtractor.class.php
Key functions:

extractMetadata()

normalizeMetadata()

applyMetadata()

Events used:
digital_object.post_create

🤝 Contributing
Fork the repository

Create a feature branch

Ensure compatibility with AtoM 2.9

Submit a PR

Contributions are welcome!

📄 License
Distributed under the GNU AGPLv3, identical to AtoM’s license.

👤 Author
Johan Pieterse
The African Heritage Group Archives
📧 pieterse.johan3@gmail.com