# s3dgraphy
[](https://badge.fury.io/py/s3dgraphy)
[](https://pypi.org/project/s3dgraphy/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://pepy.tech/project/s3dgraphy)
[](https://github.com/zalmoxes-laran/s3dgraphy/actions/workflows/publish.yml)
## 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](https://www.extendedmatrix.org), s3dgraphy implements the formal language Extended Matrix (EM) for archaeological documentation and 3D reconstruction workflows.
## 🚀 Installation
```bash
# 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
```python
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](https://docs.extendedmatrix.org/projects/s3dgraphy/)** - Complete documentation
- **[API Reference](https://docs.extendedmatrix.org/projects/s3dgraphy/api.html)** - Detailed API docs
- **[Examples](https://github.com/zalmoxes-laran/s3dgraphy/tree/main/examples)** - Code examples and tutorials
- **[Extended Matrix](https://www.extendedmatrix.org)** - Framework overview
## 🔧 Development
### Setting up Development Environment
```bash
# 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
```bash
# 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](CONTRIBUTING.md) 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](https://github.com/zalmoxes-laran/EM-blender-tools)** - 3D visualization and modeling
- **[3D Survey Collection (3DSC)](https://docs.extendedmatrix.org/projects/3DSC/)** - 3D model preparation
- **[ATON Framework](https://www.aton3d.org)** - Web-based 3D presentation
- **[Extended Matrix Documentation](https://github.com/zalmoxes-laran/ExtendedMatrix)** - Formal language specification
## 📄 License
This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](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:
```bibtex
@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](https://github.com/zalmoxes-laran) (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* 🏛️✨
Raw data
{
"_id": null,
"home_page": null,
"name": "s3dgraphy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Emanuel Demetrescu <emanuel.demetrescu@cnr.it>",
"keywords": "archaeology, stratigraphy, graph, 3d, heritage, temporal-modeling, knowledge-graph, extended-matrix",
"author": null,
"author_email": "Emanuel Demetrescu <emanuel.demetrescu@cnr.it>",
"download_url": "https://files.pythonhosted.org/packages/91/8a/775af366f04d2f95d919c5f7a069c3c9760bc6aa93ae9e0bea6aae74f30f/s3dgraphy-0.1.15.tar.gz",
"platform": null,
"description": "# s3dgraphy\n\n[](https://badge.fury.io/py/s3dgraphy)\n[](https://pypi.org/project/s3dgraphy/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://pepy.tech/project/s3dgraphy)\n[](https://github.com/zalmoxes-laran/s3dgraphy/actions/workflows/publish.yml)\n\n## 3D Stratigraphic Graph Management Library\n\ns3dgraphy 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.\n\nPart of the [Extended Matrix Framework](https://www.extendedmatrix.org), s3dgraphy implements the formal language Extended Matrix (EM) for archaeological documentation and 3D reconstruction workflows.\n\n## \ud83d\ude80 Installation\n\n```bash\n# From PyPI (stable releases)\npip install s3dgraphy\n\n# From TestPyPI (development versions)\npip install --index-url https://test.pypi.org/simple/ s3dgraphy\n\n# With optional dependencies\npip install s3dgraphy[visualization] # For plotting features\npip install s3dgraphy[full] # All optional dependencies\n```\n\n## \ud83d\udd27 Quick Start\n\n```python\nimport s3dgraphy\n\n# Create a new stratigraphic graph\ngraph = s3dgraphy.Graph()\n\n# Add stratigraphic units\nus1 = graph.add_node(\"US001\", node_type=\"US\", \n properties={\"period\": \"Roman\", \"material\": \"pottery\"})\nus2 = graph.add_node(\"US002\", node_type=\"US\", \n properties={\"period\": \"Medieval\", \"material\": \"stone\"})\n\n# Add stratigraphic relationships\ngraph.add_edge(us1, us2, edge_type=\"ABOVE\", \n properties={\"certainty\": \"high\"})\n\n# Query the graph\nprint(f\"Graph contains {len(graph.nodes)} stratigraphic units\")\nprint(f\"Relationships: {len(graph.edges)}\")\n\n# Export to different formats\ngraph.export_graphml(\"stratigraphy.graphml\")\ngraph.export_json(\"stratigraphy.json\")\n```\n\n## \ud83d\udcda Core Features\n\n### \ud83c\udfdb\ufe0f Archaeological Stratigraphic Modeling\n- **Stratigraphic Units (US)**: Physical layers and contexts\n- **Stratigraphic Volumes (USV)**: 3D spatial representations\n- **Surfaces (SF)**: Interface documentation\n- **Temporal Relationships**: Before/after, contemporary, uncertain\n\n### \ud83d\udd17 Extended Matrix Integration\n- **EM Language Support**: Full implementation of Extended Matrix formal language\n- **Visual Rules**: JSON-based styling and visualization rules\n- **CIDOC-CRM Mapping**: Semantic web compatibility\n- **Connection Rules**: Automated relationship inference\n\n### \ud83d\udcca Graph Operations\n- **Multitemporal Analysis**: Handle complex temporal sequences\n- **Graph Traversal**: Navigate stratigraphic relationships\n- **Filtering & Querying**: Find specific contexts and relationships\n- **Validation**: Check stratigraphic consistency\n\n### \ud83d\udcbe Data Exchange\n- **GraphML Import/Export**: Industry standard graph format\n- **JSON/YAML Support**: Lightweight data exchange\n- **Excel Integration**: Tabular data import\n- **3D Model Integration**: GLTF/GLB support for 3D contexts\n\n## \ud83c\udfaf Use Cases\n\n### Archaeological Projects\n- **Excavation Documentation**: Record stratigraphic sequences\n- **Site Analysis**: Understand temporal relationships\n- **3D Reconstruction**: Link physical evidence to 3D models\n- **Publication**: Generate stratigraphic matrices and diagrams\n\n### Heritage Applications\n- **Monument Analysis**: Document construction phases\n- **Conservation Planning**: Track intervention history\n- **Virtual Archaeology**: Create interactive 3D experiences\n- **Research Integration**: Connect archaeological data with other disciplines\n\n## \ud83d\udcd6 Documentation\n\n- **[User Guide](https://docs.extendedmatrix.org/projects/s3dgraphy/)** - Complete documentation\n- **[API Reference](https://docs.extendedmatrix.org/projects/s3dgraphy/api.html)** - Detailed API docs\n- **[Examples](https://github.com/zalmoxes-laran/s3dgraphy/tree/main/examples)** - Code examples and tutorials\n- **[Extended Matrix](https://www.extendedmatrix.org)** - Framework overview\n\n## \ud83d\udd27 Development\n\n### Setting up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/zalmoxes-laran/s3dgraphy.git\ncd s3dgraphy\n\n# Install in development mode\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run linting\nblack src/\nflake8 src/\n```\n\n### Release Process\n\n```bash\n# Bump version and create tag\nbump2version patch # or minor, major\n\n# Push to GitHub\ngit push --follow-tags\n\n# Create release on GitHub to auto-publish to PyPI\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Areas for Contribution\n- **New Node Types**: Archaeological contexts, dating methods\n- **Import/Export Formats**: Additional data exchange formats \n- **Visualization**: Enhanced 3D layouts and rendering\n- **Analysis Tools**: Statistical analysis, pattern recognition\n- **Documentation**: Examples, tutorials, case studies\n\n## \ud83c\udfdb\ufe0f Extended Matrix Ecosystem\n\ns3dgraphy is part of a larger ecosystem:\n\n- **[EM-tools for Blender](https://github.com/zalmoxes-laran/EM-blender-tools)** - 3D visualization and modeling\n- **[3D Survey Collection (3DSC)](https://docs.extendedmatrix.org/projects/3DSC/)** - 3D model preparation\n- **[ATON Framework](https://www.aton3d.org)** - Web-based 3D presentation\n- **[Extended Matrix Documentation](https://github.com/zalmoxes-laran/ExtendedMatrix)** - Formal language specification\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.\n\nThe GPL-3.0 license ensures that s3dgraphy remains free and open source, promoting transparency and collaboration in archaeological research and heritage preservation.\n\n## \ud83c\udfdb\ufe0f Citation\n\nIf you use s3dgraphy in your research, please cite:\n\n```bibtex\n@software{s3dgraphy2024,\n title={s3dgraphy: 3D Stratigraphic Graph Management Library},\n author={Demetrescu, Emanuel},\n year={2024},\n url={https://github.com/zalmoxes-laran/s3dgraphy},\n version={0.1.1},\n institution={CNR-ISPC (National Research Council - Institute of Heritage Science)}\n}\n```\n\n## \ud83d\udc65 Credits\n\n**Author & Maintainer**: [Emanuel Demetrescu](https://github.com/zalmoxes-laran) (CNR-ISPC)\n\n**Institution**: National Research Council of Italy - Institute of Heritage Science (CNR-ISPC)\n\n**Funding**: This research has been supported by various archaeological and heritage preservation projects.\n\n## \ud83d\udd17 Links\n\n- **GitHub Repository**: https://github.com/zalmoxes-laran/s3dgraphy\n- **PyPI Package**: https://pypi.org/project/s3dgraphy/\n- **Documentation**: https://docs.extendedmatrix.org/projects/s3dgraphy/\n- **Extended Matrix Website**: https://www.extendedmatrix.org\n- **Bug Reports**: https://github.com/zalmoxes-laran/s3dgraphy/issues\n\n---\n\n*s3dgraphy - Bringing archaeological stratigraphy into the digital age* \ud83c\udfdb\ufe0f\u2728\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "3D Stratigraphic Graph Management Library for archaeological and heritage applications",
"version": "0.1.15",
"project_urls": {
"Bug Reports": "https://github.com/zalmoxes-laran/s3dgraphy/issues",
"Changelog": "https://github.com/zalmoxes-laran/s3dgraphy/blob/main/CHANGELOG.md",
"Documentation": "https://docs.extendedmatrix.org/projects/s3dgraphy/",
"Extended Matrix": "https://www.extendedmatrix.org",
"Homepage": "https://github.com/zalmoxes-laran/s3dgraphy",
"Repository": "https://github.com/zalmoxes-laran/s3dgraphy.git",
"Source Code": "https://github.com/zalmoxes-laran/s3dgraphy"
},
"split_keywords": [
"archaeology",
" stratigraphy",
" graph",
" 3d",
" heritage",
" temporal-modeling",
" knowledge-graph",
" extended-matrix"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d1c3590e1747c7929d302dab267f520379c7902a9e4ce809330bc82c652ea2c0",
"md5": "4556cb75e0dfc4467ec8f8203815900d",
"sha256": "c85e62b1815740632064a2d566364cd893b782c1a7778afcaaac1d1d22826e19"
},
"downloads": -1,
"filename": "s3dgraphy-0.1.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4556cb75e0dfc4467ec8f8203815900d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 482309,
"upload_time": "2025-10-26T06:27:35",
"upload_time_iso_8601": "2025-10-26T06:27:35.119843Z",
"url": "https://files.pythonhosted.org/packages/d1/c3/590e1747c7929d302dab267f520379c7902a9e4ce809330bc82c652ea2c0/s3dgraphy-0.1.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "918a775af366f04d2f95d919c5f7a069c3c9760bc6aa93ae9e0bea6aae74f30f",
"md5": "61657c57318f6db13cc0566c161502c9",
"sha256": "adcbea3c397ed66bad7e5de2a42cffbcb3e4f1b325d6e345684a47ec666c7a5b"
},
"downloads": -1,
"filename": "s3dgraphy-0.1.15.tar.gz",
"has_sig": false,
"md5_digest": "61657c57318f6db13cc0566c161502c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 454508,
"upload_time": "2025-10-26T06:27:36",
"upload_time_iso_8601": "2025-10-26T06:27:36.826101Z",
"url": "https://files.pythonhosted.org/packages/91/8a/775af366f04d2f95d919c5f7a069c3c9760bc6aa93ae9e0bea6aae74f30f/s3dgraphy-0.1.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 06:27:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zalmoxes-laran",
"github_project": "s3dgraphy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "s3dgraphy"
}
JSON
