Welcome to the EM Tools Documentation

EM Tools is a Blender extension that creates a connection between the Extended Matrix (.graphml file) and the 3D environment of Blender (proxy files). With EM Tools you can import, manage, visualize, modify, represent and export all the information (geometries, data and paradata) concerning micro and macro scale contexts, single objects or collections of objects.

The extension is developed by E. Demetrescu at CNR-ISPC (Rome, former CNR-ITABC).

First time here?

If this is your very first contact with the Extended Matrix project, the recommended landing page is extendedmatrix.org — it explains what EM is, who it is for, and which of the manuals you should open next. The page you are reading now is the EM Tools manual: the practical guide to the Blender add-on. The complementary language manual is where the formal notation is defined.

Fig. 1 EM Tools at a glance: the five moments your work will move through, from importing the graph and the 3D content to exporting a publishable reconstruction. The panels in the addon follow this order.

Where this manual sits in the EM ecosystem

You are reading the EM Tools manual — the Blender add-on. For the broader Extended Matrix ecosystem (the formal language, the s3dgraphy library, 3DSC, Heriverse), see Where this fits — the Extended Matrix ecosystem at the bottom of this page.

Start here

Pick the entry that fits you best. Each path is short and ends back at the panels reference.

I work with sources, stratigraphy and reconstruction logic

Begin with the formal language at the EM language docs, then come back here for Installation, the Installing EM Tools: yEd and the Blender Add-on walkthrough, and the Creating Your First Extended Matrix exercise. The Stratigraphy Manager is where most of your work will happen.

I build and texture 3D models and want to enrich them with EM data

Go straight to Installation, then follow Installing EM Tools: yEd and the Blender Add-on and Creating Your First Extended Matrix. From there, EM Data Tree, Proxy Box Creator and Visual Manager cover the daily authoring loop. Export options are in Export Guide.

I want to extend EM Tools, integrate it, or contribute code

Read Development Setup and API Reference, then Contributing for the workflow. The s3Dgraphy library — bundled inside the addon — is what you will most often touch; its source lives in the EM-blender-tools repo.

Note

Starting from version 1.5, EM Tools is distributed as a Blender Extension (.zip file) which automatically manages all Python dependencies.

Quick Start

• For users — download the latest release and install via Blender’s preferences. See Installation.

• For developers — clone the repository and follow Development Setup.

• Community — join the Telegram group for support and discussions.

What’s New

Version 1.5 (development snapshot — building toward 1.5.0 stable)

• Landscape mode: manage multiple archaeological graphs simultaneously in a single Blender scene

• CronoFilter: chronological horizons manager for landscape mode with horizon-based filtering and coloring

• Stratigraphy Manager: complete rewrite (formerly US/USV Manager) with containment filters, instance chain tracking, and associated documents

• Anastylosis Manager (RMSF): link 3D objects to SpecialFind nodes with LOD management

• 3D Document Manager: spatial-temporal document management with camera and image plane support

• Graph Editor: node-based graph visualization in the Node Editor

• Proxy Box Creator: 7-point measurement tool with optional paradata enrichment

• Conservation Workflow / TSU: Transformation Stratigraphic Units for documenting decay, restoration and thematic surveys (see Conservation Workflow (TSU))

• Tapestry Integration: AI-powered photorealistic reconstruction (experimental)

• Blender Extension format with automatic dependency management

• Heriverse export functionality

• See full Changelog for details

Development tracking

• Visit dev.extendedmatrix.org for progress and feature requests

• See the Roadmap for future plans

Documentation status

This documentation describes EM Tools 1.5 (development snapshot) and is rebuilt continuously from the main branch. The downloadable PDF carries the same release string on its cover (Extended Matrix tool 1.5.0-dev). If you land on a page whose header says 1.4 you are reading the previous stable release; switch the version selector at the bottom-left of the page to the version you actually need. Issues and suggestions: please open them on GitHub issues.

Contents

The TOC below is organised by intent (Diátaxis-flavoured): Get started is where to land if this is your first time; Daily use is the task-oriented how-to walkthroughs you reach for during a project; Reference is the lookup material you keep open in a second tab while working; Workflows & concepts is the explanatory material that tells you why the system is shaped the way it is. The s3dgraphy and ExtendedMatrix-doc manuals follow the same grouping — same shape across the ecosystem.

Get started

• Installation
  • Quick install (recommended)
  • System requirements
  • Offline / manual install
  • Updating EM Tools
  • Importing the EM palette in yEd
  • Development setup
• Usage Examples (text under review)
  • Basic Workflow
  • Archaeological Workflow
  • Reconstruction Workflow
  • Data Export
  • Visualization Techniques
  • Statistical Analysis
  • Advanced Features
  • Tips and Best Practices

Daily use (how-to)

• Tutorials
  • 3D Survey Collection: Level of Detail in Blender
  • Site-Scale LOD and Data Preparation
  • Installing EM Tools: yEd and the Blender Add-on
  • Creating Your First Extended Matrix
  • Build the stratigraphic proxies in Blender
  • Building an Extended Matrix Manually, Unit by Unit
  • Linking EM to Your 2D and 3D Documentation
  • Managing Sources, Paradata and Metadata
  • End-to-End: A Complete Site Workflow
  • Placing 2D Drawings as 3D References
  • Linking Photos as Auxiliary Files
  • Multi-Temporal 3D Visualization Demo
  • Auxiliary Resources: pyArchInit and External Data Connections
  • Bulk Import via the Excel Mapping Tool
  • Paradata Manager and Graph Visualization
  • Creating Proxies and Exporting Your Dataset

Reference

• EMtools Structure
  • EM tab — core
  • EM Annotator tab — spatial authoring
  • EM Bridge tab — export & integrations
  • Reference
  • Experimental
• API Reference
  • Architecture Overview
  • Graph Access
  • Import Operators
  • Export Operators
  • Property Groups
  • Panels Reference
  • Module Structure
  • Further Reading

Workflows & concepts

• Workflows
  • 1. From an existing GraphML to a navigable 3D scene
  • 2. Authoring an EM graph from a 3D survey
  • 3. Multi-temporal reconstruction (epochs and hypotheses)
  • 4. Conservation survey (TSU)
  • 5. Export and publication
• Creating an Extended Matrix from Different Sources
  • The Knowledge Tree
  • Overview
  • From GraphML (yEd)
  • From em_data.xlsx (Unified schema)
  • From Existing Databases
  • Legacy two-file workflow (deprecated)
• Export Guide

Developer setup

• Development Setup
• Contributing

Project information

• Roadmap
  • Current Development (v1.5)
  • Next Release (v1.6)
  • Future Development
  • Tracking Progress
  • Suggesting New Features
• Changelog
  • Version History
  • Semantic Versioning
  • Version Support
• License

Community & support

• Support
• FAQ
• Showcase

Additional Resources

• GitHub Repository: EM-blender-tools

• Extended Matrix website: extendedmatrix.org

• EM language docs: docs.extendedmatrix.org

• 3DSC docs: 3D-survey-collection

• Heriverse docs: Heritage Science Metaverse

• ATON Framework: phoenixbf/aton on GitHub

• Video tutorials: YouTube Channel

Indices and tables

• Index

• Module Index

• Search Page

Where this fits — the Extended Matrix ecosystem

Note

Extended Matrix is the name of the broader project — a formal language, an open-source tool family and a community. Each individual component below has its own name and its own manual. When you see Extended Matrix (or EM) without a qualifier, the surrounding context normally tells you whether the reference is to the project as a whole or to the formal language specifically. The table below disambiguates the components.

Name	What it is	Where to learn it
EM language	The formal language (the notation itself) used to document stratigraphy and reconstruction processes. Drawn in yEd (with the EM palette) or produced from an em_data.xlsx worksheet. This is what the EM language manual on docs.extendedmatrix.org documents — node types, connectors, paradata, canvas conventions, formal semantics.	EM language manual
EM Tools	The Blender add-on that connects an EM graph to 3D content — proxies, representation models, exports.	EM Tools manual
s3dgraphy	The Python library that powers EM Tools — graph data structures, GraphML / XLSX / SQLite import/export, JSON for web platforms. Usable standalone outside Blender.	s3dgraphy manual
3DSC	A complementary Blender add-on for high-quality 3D survey processing (photogrammetry, LOD, Cesium tilesets) that feeds EM Tools.	3DSC manual
Heriverse	The Heritage Science Metaverse — web-based publication and collaborative VR for EM-aware scenes. The natural endpoint of what you author in EM Tools.	Heriverse manual

If you are unsure which one you need: start from the EM language if you have evidence to organize; come to EM Tools if you have 3D content to annotate; reach for 3DSC if you have raw survey data to clean and align; open Heriverse when your work is ready to be published on the web. The Extended Matrix site at extendedmatrix.org is the discovery and orchestration layer above all the manuals — start there if you are not sure which manual to open first. For methodological end-to-end paths that cross multiple tools (a photogrammetric pipeline, an anastylosis workflow, a web publication), see the Workflows collection on the site.

Note

This map is identical in every Extended Matrix manual (EM language, EM Tools, s3dgraphy, 3DSC, Heriverse). Wherever you land, you can orient yourself in the broader ecosystem from this table.