herzfeld 0.1.0-alpha.1

# HERZFELD (Core)
**High‑fidelity Epigraphic Rendering for Zonated Feature Extraction and Labelled Datasets**
**HERZFELD** is the high-performance numerical engine of the broader [HERZFELD Python Suite](https://pypi.org/project/herzfeld/). It is a specialised library written in **Rust** designed to process large-scale synthetic datasets for the Optical Character Recognition (OCR) of ancient inscriptions, specifically **Middle Persian** and **Inscriptional Pahlavi**.

## 🦀 Why Rust for Epigraphy?
While the synthetic data is generated within Blender, the post-processing of multi-layered high-dynamic-range (HDR) tensors requires significant computational throughput. The Rust core provides:
- **Memory Safety**: Guaranteed safety when parsing complex OpenEXR byte streams.
- **SIMD Acceleration**: Optimised topographic normalisation and relief calculations.
- **Parallelism**: Utilises `Rayon` to process thousands of “takes” (render outputs) across all CPU cores.
- **PyO3 Integration**: Seamlessly exposed as a high-level Python module for researchers.

## ✨ Key Capabilities
- **Adaptive Topographic Normalisation**: Automatically scales Z-buffer data to the micron-level relief of a specific inscription (e.g. isolating a 176.7mm relief from a 1.6m camera distance).
- **Multi-Layered EXR Parsing**: Efficient extraction of Depth, Normal, and Semantic Mask channels from 32-bit float OpenEXR files.
- **Zero-Copy Interoperability**: Uses `numpy-rust` to share memory between the Rust engine and Python’s ML ecosystem (PyTorch/TensorFlow) without overhead.

## ⚙️ The Pipeline Architecture
HERZFELD operates as a hybrid engine:
1. **Generation (Blender Core)**: A procedural simulation environment using Geometry Nodes to synthesise 3D geometry.
2. **Extraction (Rust Backend)**: This crate. A dedicated high-throughput suite that performs adaptive depth normalisation and automated semantic mask generation.

## 🛠 Usage
### For Rust Developers
Add this to your `Cargo.toml`:
```toml
[dependencies]
herzfeld = "0.1.0"
```

### For Python Researchers (Recommended)
This crate is primarily intended to be consumed via the `herzfeld` Python package. To install the pre-compiled binaries:
```bash
pip install herzfeld
```

## 📌 Status & Roadmap
This project is currently in **active early-stage development (Alpha)**.
- [x] **Core Bridge**: Initial PyO3 implementation and project stubs.
- [ ] **Topographic Engine**: Migration of adaptive Z-scaling logic from Python to Rust.
- [ ] **Parallel Processing**: Multi-threaded batch processing for the Paikuli corpus.
- [ ] **OCR Pre-processing**: Surface normal re-mapping for synthetic raking-light augmentation.

## 📜 Project Identity & IP
HERZFELD is developed by **Andrea Marruzzo**, Research Fellow at **Sapienza University of Rome**, as part of the study of the Middle Persian and Parthian **Paikuli Inscription**.

The choice of Rust for the core engine serves a dual purpose: providing the performance required for modern ML pipelines while protecting the intellectual property and algorithmic integrity of the research within a competitive academic environment.

## ⚖️ Citation
If you use the HERZFELD suite or the Rust core in your research, please cite it as:

**APA:**
Marruzzo, A. (2026). _HERZFELD (Suite): High‑fidelity Epigraphic Rendering (Version 0.1.0)_ [Software]. PyPI. https://pypi.org/project/herzfeld/

**BibTeX:**
```bibtex
@software{marruzzo_herzfeld_suite_2026,
  author = {Marruzzo, Andrea},
  title = {HERZFELD (Suite): High‑fidelity Epigraphic Rendering},
  version = {0.1.0},
  year = {2026},
  month = {1},
  publisher = {PyPI},
  url = {https://crates.io/crates/herzfeld},
  note = {Reserved namespace for HERZFELD rendering suite}
}
```