Welcome to PyLithics¶

Archaeological Lithic Analysis with Computer Vision¶

PyLithics is an open-source Python package that applies advanced computer vision techniques to extract quantitative morphological data from 2D line drawings of prehistoric stone artifacts. PyLithics processes scanned 2D illustrations of stone tools (lithics) from archaeological publications, automatically identifying and measuring key technological and morphological features. The tool has been optimized for feature extraction using cutting-edge computer vision techniques including:

Pixel intensity thresholding
Edge detection and contour finding
Custom template matching
Advanced geometric analysis
Machine learning-based feature recognition

Key Features¶

Accurate Surface Identification¶

Automatically identifies dorsal, ventral, platform, and lateral surfaces
Recognizes individual flake scars with high precision
Detect cortex areas
Configurable detection parameters for different drawing styles

Comprehensive Measurements¶

Complete size and shape metrics for whole flakes and individual scars
Technical dimensions (length, width, thickness)
Geometric properties (area, perimeter, aspect ratios)
Symmetry analysis (vertical and horizontal)
Scar complexity and adjacency relationships

Advanced Analysis¶

Flaking direction detection through arrow recognition
Voronoi diagram generation for spatial analysis
Convex hull calculations
Lateral edge convexity analysis
Configurable analysis modules that can be enabled/disabled

Configuration and Customization¶

PyLithics offers extensive configuration options through both YAML configuration files and command-line arguments:

Adjust thresholding methods (simple, Otsu, adaptive)
Enable/disable specific analysis modules
Fine-tune detection parameters
Customize output formats

Research-Ready Output¶

Structured CSV data output with hierarchical organization
Annotated visualization images for validation
Comprehensive logging for reproducibility
Compatible with standard statistical analysis software

Why PyLithics?¶

For Researchers¶

Time-Saving: Automate hours of manual measurement
Consistency: Eliminate inter-observer variability
Scale: Process entire assemblages efficiently
Reproducibility: Ensure consistent, replicable results

For Archaeological Science¶

Quantitative Analysis: Move beyond qualitative descriptions
Pattern Recognition: Identify subtle technological variations
Big Data: Enable large-scale comparative studies
Open Science: Free, open-source tool for the community

Getting Started¶

Installation Guide - Set up PyLithics on your system
User Guide - Learn how to use PyLithics effectively
Image Requirements - Prepare your lithic illustrations
Basic Usage - Run your first analysis

See the CLI Commands Reference for complete configuration options.

Support and Contributing¶

PyLithics is actively developed and maintained. We welcome contributions from the archaeological and computer science communities.