AMFOrA (Automated Macroscopic Fabric and Orientation Analysis)
A Python package for automated quantitative analysis of ceramic sherd fabric from flatbed-scanner images — inclusion detection, void analysis, size and orientation measurements, and color characterization.
Built for archaeological and materials-science workflows that need reproducible, DPI-aware measurements across many sherds.
Developed at the University of Washington's Digital Archaeology Research Laboratory (DigAR Lab)
Features
- Inclusion detection — Blob and contour-based detectors with a paste-anchored MAD-scaled pop gate that handles dense clusters, fine grains on uniform paste, and mottled tempers consistently.
- Void analysis — Brightness-gated dark feature detection that separates pores from dark mineral inclusions.
- Watershed cluster recovery — Dense touching grains are split into individual sub-grains rather than being counted as one lumpy contour.
- Size and density metrics — Areas in cm², densities per cm², with the denominator computed over the actually-searched area (not the full sherd) so cross-sherd comparisons stay valid.
- Orientation and color — Per-inclusion orientation distributions and CIELAB color summaries.
- Batch processing — Run a whole folder of sherd scans into a single CSV via
full_analysis.
Installation
pip install amfora
Or, to develop against the latest source:
git clone https://github.com/aleciaco/AMFOrA_public.git
cd AMFOrA_public
pip install -e .
PyPI project page: pypi.org/project/amfora
Dependencies
Python 3.10+, OpenCV, NumPy, pandas, matplotlib, SciPy, scikit-image, Pillow. All pulled in automatically by pip install.
Quickstart
import cv2
import amfora
# Load a raw scanned sherd image (background still present)
image = cv2.imread('sherd.jpg')
# One-call analysis: masking, blob + contour detection, color, orientation
results = amfora.analyze_single_sherd(image, scan_dpi=1200)
print(f"Blob inclusions: {results['blob_inclusion_count']}")
print(f"Contour inclusions: {results['contour_inclusion_count']}")
print(f"Inclusion density: {results['contour_inclusion_density_per_cm2']:.1f} per cm²")
For a batch of sherds in a folder:
df = amfora.full_analysis('path/to/sherd_scans/', scan_dpi=1200)
df.to_csv('results.csv')
See examples/ for working notebooks (and example sherd images) and docs/ for the full user guide.
Documentation
Core entry points
analyze_single_sherd(image, scan_dpi)— Mask + detect + measure a single sherd; returns a dict of metrics.full_analysis(folder_path, scan_dpi)— Runanalyze_single_sherdover a directory; returns a pandas DataFrame and writes CSV.sherd_mask(image, scan_dpi)— GrabCut-based mask isolating the sherd from scanner background.sherd_blobs(masked_image, scan_dpi)— SimpleBlobDetector with adaptive thresholds and paste-anchored pop gating.contour_detection(masked_image, scan_dpi)— Contour-based detection with watershed cluster recovery and multigrain split.
Every function has a NumPy-style docstring with parameter and return-value details.
DPI and units
All measurements are DPI-aware. The default is scan_dpi=1200. Conversion factor is dpcm = scan_dpi * 0.3937; areas are returned in cm². Set scan_dpi to match your scanner.
Scientific applications
Designed for:
- Quantitative petrographic analysis of ceramic fabrics
- Inclusion size and shape distribution studies
- Void analysis (organic burnout, shrinkage cracks)
- Orientation analysis of elongated inclusions
- Color characterization (paste, inclusion populations, core-periphery firing-atmosphere indicators)
Cross-fabric inclusion-density comparisons are limited by optical contrast: grains that share the matrix's color are invisible to scanning regardless of detection parameters. See analyze_single_sherd's docstring for the full discussion and the R08G/R08TC calibration data showing the ~2.3× density gap on bars sharing identical sand temper.
Contributing
Pull requests welcome — see CONTRIBUTING.md for development setup, code style, and PR guidelines. By participating you agree to the Code of Conduct.
Disclosure: use of generative AI tools
Parts of this package have been developed and refined with assistance from generative AI tools (Anthropic Claude, primarily for testing, repackaging in modern Python standards, docstring and documentation drafting, code review, and iterative tuning of detector parameters). All algorithmic design decisions, validation against real sherd data, and final acceptance of changes were performed by the human maintainer. As a solo archaeologist who knows Python, I had a glaring gap in my ability to actually format the github in the modern standard where it would be useful by other researchers, so I turned to Anthropic Claude to help format the documentation, make docstrings make enough sense for other users, write tests, and do linting/CI because I had never learned how to do that. If there are any issues with this content, please reach out or suggest better ways of maintaining it!
License
MIT License — see LICENSE.
Citation
If you use AMFOrA in published work, please cite:
Iacobucci, A. (2026). AMFOrA: Automated Macroscopic Fabric and Orientation Analysis for ceramic sherds (Version 1.0.3) [Computer software]. https://pypi.org/project/amfora/
A DOI / Zenodo archive will be added in a future release.
Support
- Bug reports and feature requests: GitHub issues
- Maintainer: aleciaco@uw.edu
Metadata
Release files for amfora 1.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amfora-1.0.3.tar.gz | 109.6 kB | With provenance | Details for amfora-1.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amfora-1.0.3-py3-none-any.whl | Python 3 | none | any | Details for amfora-1.0.3-py3-none-any.whl |
Total release size: 218.1 kB
Release files / amfora-1.0.3.tar.gz
| Download URL | amfora-1.0.3.tar.gz |
|---|---|
| Size | 109.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0dbb95ea20e409a94455d6f4caf0d977e7eeab9db26bc8ef5c0c0dadfb7d203
|
|
BLAKE2b-256 checksum How to use checksums |
296b47ac63b7584decf74c3f248a9c3cd7631f4f258068cb51862dfa12484d17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 25, 2026.
Transparency logRelease files / amfora-1.0.3-py3-none-any.whl
| Download URL | amfora-1.0.3-py3-none-any.whl |
|---|---|
| Size | 108.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7ffbe14685508bd6b1bbc418ea2766ae873a1bdefc4ca230823ea62b40ea2a08
|
|
BLAKE2b-256 checksum How to use checksums |
e2182fcd2d13642d78384e38cf33e22961a47f3a752dd0f9890b7aecf05a56b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 25, 2026.
Transparency logSecurity for amfora 1.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for amfora-1.0.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.