Skip to main content

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

AMFOrA Docs -- GitHub Docs

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) — Run analyze_single_sherd over 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

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)

Source distribution for amfora 1.0.3
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)

Table of built distributions (wheels) for amfora 1.0.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page