capa-sdk 1.2.0

CAPA - Craniofacial Analysis & Prediction Architecture SDK

CAPA SDK

Craniofacial Analysis & Prediction Architecture

A Python SDK for advanced craniofacial analysis based on 12+ peer-reviewed scientific papers.

Features

• WD Analysis: Bizygomatic width measurement and classification
• Forehead Analysis: Frontal inclination angle measurement
• Morphology Analysis: Face shape classification and facial proportions
• Neoclassical Canons: Classical facial proportion analysis
• Multi-Angle Support: Combine results from multiple images
• Quality Control: Adaptive quality assessment and validation

🎯 Interactive Demo

Try the Reflex Web Demo to explore all features with a modern UI!

cd demo_reflex
./start.sh

Visit http://localhost:3000 to use the interactive demo with:

• ✅ All SDK features accessible via web UI
• ✅ Visual results and metrics
• ✅ Multiple analysis modes
• ✅ Export functionality
• ✅ Professional interface

→ See Demo Documentation

Installation

pip install capa-sdk

Or install from source:

git clone https://github.com/yarel2l/capa-sdk.git
cd capa-sdk
pip install -e .

Dependencies

• Python 3.9+
• OpenCV
• dlib
• MediaPipe
• face-recognition
• scikit-learn
• scipy
• numpy
• Pillow
• matplotlib

Model Files

CAPA does not bundle large model files in the PyPI package. They are resolved automatically at runtime:

Model	Used by	How it is obtained
face_landmarker.task (MediaPipe)	Landmark detection	Auto-downloaded on first use to ~/.capa/models/
shape_predictor_68_face_landmarks.dat (dlib)	dlib fallback detector, canons	Provided by the face_recognition_models dependency, or place it in the working directory
buffalo_l (InsightFace / ArcFace)	KYC & continuous-auth verticals	Auto-managed by insightface on first use

No manual setup is required for a standard install. If you prefer to provide the dlib model yourself (e.g. offline environments), download it and place it in your working directory:

wget http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2
bzip2 -d shape_predictor_68_face_landmarks.dat.bz2

The repo's local models/ directory and *.dat files are git-ignored and are not part of the distributed package.

Quick Start

from capa import CoreAnalyzer

# Initialize analyzer
analyzer = CoreAnalyzer()

# Analyze an image
result = analyzer.analyze_image("photo.jpg")

# Access results
if result.wd_result:
    print(f"WD Value: {result.wd_result.wd_value:.3f}")
    print(f"Classification: {result.wd_result.primary_classification.value}")

if result.forehead_result:
    print(f"Forehead Angle: {result.forehead_result.forehead_geometry.slant_angle_degrees:.1f}")

if result.morphology_result:
    print(f"Face Shape: {result.morphology_result.shape_classification.primary_shape.value}")

# Always shutdown when done
analyzer.shutdown()

Analysis Modes

from capa import CoreAnalyzer, AnalysisConfiguration, AnalysisMode

config = AnalysisConfiguration(
    mode=AnalysisMode.STANDARD,  # FAST, STANDARD, THOROUGH, SCIENTIFIC
    enable_wd_analysis=True,
    enable_forehead_analysis=True,
    enable_morphology_analysis=True,
)

analyzer = CoreAnalyzer(config=config)

Multi-Angle Analysis

from capa import MultiAngleAnalyzer, AngleSpecification

analyzer = MultiAngleAnalyzer()

angle_specs = [
    AngleSpecification(angle_type='frontal', image_path='front.jpg'),
    AngleSpecification(angle_type='profile', image_path='side.jpg'),
]

result = analyzer.analyze_multiple_angles(
    angle_specs=angle_specs,
    subject_id="subject_001"
)

print(f"Combined Confidence: {result.combined_confidence*100:.1f}%")
analyzer.shutdown()

Using Individual Modules

from capa.modules import WDAnalyzer, ForeheadAnalyzer, MorphologyAnalyzer
import cv2

image = cv2.imread("photo.jpg")

# WD Analysis only
wd_analyzer = WDAnalyzer()
wd_result = wd_analyzer.analyze(image)

# Forehead Analysis only
forehead_analyzer = ForeheadAnalyzer()
forehead_result = forehead_analyzer.analyze(image)

# Morphology Analysis only
morphology_analyzer = MorphologyAnalyzer()
morphology_result = morphology_analyzer.analyze(image)

Scientific Foundation

CAPA is built on 12+ peer-reviewed scientific papers. All referenced papers are included in the data/ folder for easy access.

WD Analysis (Bizygomatic Width)

Paper	Local PDF
Bizygomatic Width and Personality Traits of the Relational Field	View PDF
Bizygomatic Width and its Association with Social and Personality Traits in Males	View PDF
Association between self-reported impulsiveness and gray matter volume	View PDF

Forehead Analysis (Frontal Inclination)

Paper	Local PDF
The Slant of the Forehead as a Craniofacial Feature of Impulsiveness	View PDF
Correlation between Impulsiveness, Cortical Thickness and Slant of The Forehead	View PDF
La impulsividad y su asociacion con la inclinacion de la frente	View PDF
Frontonasal dysmorphology in bipolar disorder by 3D laser surface imaging	View PDF

Morphology Analysis (Face Shape)

Paper	Local PDF
The validity of eight neoclassical facial canons in the Turkish adults	View PDF
Evaluation of Face Shape in Turkish Individuals	View PDF
Accuracy and precision of a 3D anthropometric facial analysis	View PDF
Determinacion del Indice Facial Total y Cono Facial	View PDF

Neoclassical Canons

Paper	Local PDF
Assessing Facial Beauty of Sabah Ethnic Groups Using Farkas Principles	View PDF

Additional Morphology Papers

Paper	Local PDF
Morphology Studies	View PDF 1 / View PDF 2

External References

• Farkas, L.G. (1994). Anthropometry of the Head and Face. Raven Press, New York.
• Gonzalez-Jose, R. et al. (2005). Functional-craniology approach to the influence of economic strategy on skull morphology. American Journal of Physical Anthropology.
• Kolar, J.C. & Salter, E.M. (1997). Craniofacial Anthropometry: Practical Measurement of the Head and Face for Clinical, Surgical, and Research Use. Charles C Thomas Publisher.

Documentation

Full documentation is available in the docs/ directory:

Document	Description
Getting Started	Installation and basic usage
Configuration	Analysis modes and settings
API Reference	Complete API documentation
Scientific Foundation	Research papers and methodology
Examples	Code examples and use cases

API Reference

Main Classes

Class	Description
CoreAnalyzer	Main orchestrator for comprehensive analysis
MultiAngleAnalyzer	Multi-angle analysis coordinator
ResultsIntegrator	Combines results from multiple sources

Scientific Modules

Module	Description
WDAnalyzer	Bizygomatic width analysis
ForeheadAnalyzer	Frontal inclination analysis
MorphologyAnalyzer	Face shape classification
NeoclassicalCanonsAnalyzer	Classical proportion analysis

Result Types

Type	Description
ComprehensiveAnalysisResult	Complete analysis result
WDResult	WD analysis result
ForeheadResult	Forehead analysis result
MorphologyResult	Morphology analysis result

Examples

See the examples/ directory for complete usage examples:

• basic_analysis.py - Simple single-image analysis
• multi_angle_analysis.py - Multi-angle analysis
• individual_modules.py - Using modules directly

License

Dual License - See LICENSE for full terms

Use Type	License	Cost
Personal projects	Non-Commercial License	Free
Academic research	Non-Commercial License	Free
Educational use	Non-Commercial License	Free
Non-profit internal use	Non-Commercial License	Free
Commercial use	Commercial License Required	Contact us

Patent Notice

This software implements methods covered by US Patent 10,885,309: "System and method for evaluating personality using anthropometric measurement of a person's face"

The Non-Commercial License includes a limited patent license for non-commercial use only. Commercial use without a Commercial License may constitute patent infringement.

Commercial Licensing

For commercial licensing inquiries, contact:

• Email: [e-mail]
• GitHub: Open an issue

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Disclaimer

This SDK provides measurements and classifications based on peer-reviewed scientific research. Results should be interpreted by qualified professionals and should not be used as the sole basis for any clinical, psychological, or employment decisions.