s3dgraphy 1.5.2

3D Stratigraphic Graph Management Library for archaeological and heritage applications

s3dgraphy

3D Stratigraphic Graph Management Library

s3dgraphy is a Python library for creating and managing multitemporal, 3D knowledge graphs, with a focus on archaeological and heritage applications. It provides tools for stratigraphic data management, temporal modeling, and graph-based analysis of archaeological contexts.

Part of the Extended Matrix Framework, s3dgraphy implements the formal language Extended Matrix (EM) for archaeological documentation and 3D reconstruction workflows.

🚀 Installation

# From PyPI (stable releases)
pip install s3dgraphy

# From TestPyPI (development versions)
pip install --index-url https://test.pypi.org/simple/ s3dgraphy

# With optional dependencies
pip install s3dgraphy[visualization]  # For plotting features
pip install s3dgraphy[full]          # All optional dependencies

🔧 Quick Start

import s3dgraphy

# Create a new stratigraphic graph
graph = s3dgraphy.Graph()

# Add stratigraphic units
us1 = graph.add_node("US001", node_type="US", 
                     properties={"period": "Roman", "material": "pottery"})
us2 = graph.add_node("US002", node_type="US", 
                     properties={"period": "Medieval", "material": "stone"})

# Add stratigraphic relationships
graph.add_edge(us1, us2, edge_type="ABOVE", 
               properties={"certainty": "high"})

# Query the graph
print(f"Graph contains {len(graph.nodes)} stratigraphic units")
print(f"Relationships: {len(graph.edges)}")

# Export to different formats
graph.export_graphml("stratigraphy.graphml")
graph.export_json("stratigraphy.json")

📚 Core Features

🏛️ Archaeological Stratigraphic Modeling

• Stratigraphic Units (US): Physical layers and contexts
• Stratigraphic Volumes (USV): 3D spatial representations
• Surfaces (SF): Interface documentation
• Temporal Relationships: Before/after, contemporary, uncertain

🔗 Extended Matrix Integration

• EM Language Support: Full implementation of Extended Matrix formal language
• Visual Rules: JSON-based styling and visualization rules
• CIDOC-CRM Mapping: Semantic web compatibility
• Connection Rules: Automated relationship inference

📊 Graph Operations

• Multitemporal Analysis: Handle complex temporal sequences
• Graph Traversal: Navigate stratigraphic relationships
• Filtering & Querying: Find specific contexts and relationships
• Validation: Check stratigraphic consistency

💾 Data Exchange

• GraphML Import/Export: Industry standard graph format
• JSON/YAML Support: Lightweight data exchange
• Excel Integration: Tabular data import
• 3D Model Integration: GLTF/GLB support for 3D contexts

🎯 Use Cases

Archaeological Projects

• Excavation Documentation: Record stratigraphic sequences
• Site Analysis: Understand temporal relationships
• 3D Reconstruction: Link physical evidence to 3D models
• Publication: Generate stratigraphic matrices and diagrams

Heritage Applications

• Monument Analysis: Document construction phases
• Conservation Planning: Track intervention history
• Virtual Archaeology: Create interactive 3D experiences
• Research Integration: Connect archaeological data with other disciplines

📖 Documentation

• User Guide - Complete documentation
• API Reference - Detailed API docs
• Examples - Code examples and tutorials
• Extended Matrix - Framework overview

🔧 Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/zalmoxes-laran/s3dgraphy.git
cd s3dgraphy

# Install in development mode
pip install -e .[dev]

# Run tests
pytest

# Run linting
black src/
flake8 src/

Release Process

# Bump version and create tag
bump2version patch  # or minor, major

# Push to GitHub
git push --follow-tags

# Create release on GitHub to auto-publish to PyPI

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Areas for Contribution

• New Node Types: Archaeological contexts, dating methods
• Import/Export Formats: Additional data exchange formats
• Visualization: Enhanced 3D layouts and rendering
• Analysis Tools: Statistical analysis, pattern recognition
• Documentation: Examples, tutorials, case studies

🏛️ Extended Matrix Ecosystem

s3dgraphy is part of a larger ecosystem:

• EM-tools for Blender - 3D visualization and modeling
• 3D Survey Collection (3DSC) - 3D model preparation
• ATON Framework - Web-based 3D presentation
• Extended Matrix Documentation - Formal language specification

🏛 Production users & integrations

PyArchInit — first production consumer of s3Dgraphy. PyArchInit is an open-source QGIS plugin for archaeological data management with particular strength in 2D GIS visualization of stratigraphic data, maintained by an active community led by Luca Mandolesi. It is used in production by archaeology teams across Europe, and brings existing PyArchInit projects into the Extended Matrix workflow as an auxiliary data source through s3Dgraphy — referencing records live or baking them into the graph.

The PyArchInit integration drove the design of the LocationNodeGroup in s3Dgraphy 0.1.41 (insight from issue #5 by Enzo Cocca).

To request inclusion in this list, see the Ecosystem page of the Extended Matrix manual.

Open invitation

s3Dgraphy is designed to be consumed by independent tools. Revit, Unreal Engine, Houdini, PostgreSQL/PostGIS, and other domain-specific tools are natural candidates for similar bridges into the Extended Matrix ecosystem. If you maintain such a project and want to explore an integration, open a discussion at github.com/zalmoxes-laran/s3Dgraphy/discussions or look at the PyArchInit integration as a worked example.

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

The GPL-3.0 license ensures that s3dgraphy remains free and open source, promoting transparency and collaboration in archaeological research and heritage preservation.

🏛️ Citation

If you use s3dgraphy in your research, please cite:

@software{s3dgraphy2024,
  title={s3dgraphy: 3D Stratigraphic Graph Management Library},
  author={Demetrescu, Emanuel},
  year={2024},
  url={https://github.com/zalmoxes-laran/s3dgraphy},
  version={0.1.1},
  institution={CNR-ISPC (National Research Council - Institute of Heritage Science)}
}

👥 Credits

Author & Maintainer: Emanuel Demetrescu (CNR-ISPC)

Institution: National Research Council of Italy - Institute of Heritage Science (CNR-ISPC)

Funding: This research has been supported by various archaeological and heritage preservation projects.

🔗 Links

• GitHub Repository: https://github.com/zalmoxes-laran/s3dgraphy
• PyPI Package: https://pypi.org/project/s3dgraphy/
• Documentation: https://docs.extendedmatrix.org/projects/s3dgraphy/
• Extended Matrix Website: https://www.extendedmatrix.org
• Bug Reports: https://github.com/zalmoxes-laran/s3dgraphy/issues

---

s3dgraphy - Bringing archaeological stratigraphy into the digital age 🏛️✨