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.

_images/EM_workflow_blender.svg

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.

EM, EM Tools, 3DSC: who is who

A new user often meets three names at once. The distinction matters because each one solves a different problem:

Name

What it is

Where to learn it

Extended Matrix (EM)

The formal language used to document stratigraphy and reconstruction processes. Drawn in yEd or produced from em_data.xlsx.

extendedmatrix.org docs

EM Tools

The Blender add-on that connects an EM graph to 3D content (this manual).

You are here.

3DSC

A complementary Blender environment for high-quality 3D survey processing that can feed EM Tools.

3D-survey-collection docs

Heriverse

The Heritage Science Metaverse — web-based publication and collaborative VR for EM-aware scenes. The natural endpoint of what you author here.

Heriverse docs

If you are unsure which one you need: start from EM (the 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.

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 and Development, 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 and Development, 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

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

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

Getting Started

User Guide

Developer Guide

Project Information

Community

Tutorials

Additional Resources

Indices and tables