R3XA_API Documentation

Environment assumption

Documentation commands assume a local virtual environment exists at .venv (project root).

Create it once from the project root:

python -m venv .venv

Activate it:

# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Then upgrade pip:

python -m pip install --upgrade pip

Once the environment is activated, the documented python ... commands are the same across Linux, macOS, and Windows.

Bootstrap the full contributor environment with one command:

python scripts/dev.py setup-dev

This installs the editable contributor stack (dev, docs, typed, web, notebook, graph_nx) and regenerates the schema-derived artifacts tracked in the repository.

R3XA: Toward a metadata standard for experimental (photo)mechanics datasets - Jean-Charles Passieux et al. PM-IDICS 2024

Credits and origin

Initial implementation by E. Roubin, based on a shared specification led by J‑C. Passieux.
Original upstream repository: https://gitlab.com/photomecanics/r3xa
Current public repository: https://github.com/jeffwitz/R3XA_API

Installation profiles

Choose one profile from the project root, inside .venv:

Install everything — all optional Python features in one command:
```
pip install -e ".[dev,docs,typed,web,notebook,graph_nx]"
```
Warning

This installs all Python extras, but it does not install the Graphviz executable dot. If you want SVG graph generation in the web UI or notebook, install Graphviz at system level too:
- Linux: sudo apt-get install graphviz
- macOS: brew install graphviz
- Windows: install from https://graphviz.org/download/ and make sure dot is in PATH
Core SDK — create and validate JSON files:
```
pip install -e .
```
Typed SDK — add IDE autocompletion with generated Pydantic models:
```
pip install -e ".[typed]"
```

Web UI — run the FastAPI editor and validator:

pip install -e ".[web]"
python scripts/dev.py run-web --port 8002

Notebook — run the Marimo notebook example:

pip install -e ".[notebook]"
python scripts/dev.py notebook-dic

Static graph fallback — enable the optional NetworkX/Matplotlib renderer:
```
pip install -e ".[graph_nx]"
```
Contributor setup — install the full local stack:
```
python scripts/dev.py setup-dev
```
If you only want the dependencies without regeneration, the equivalent install is:
```
pip install -e ".[dev,docs,typed,web,notebook,graph_nx]"
```

Warning

SVG graph generation depends on the Graphviz executable dot. The Python package graphviz alone is not sufficient. See Web UI (R3XA_API) and Tutorial — Interactive DIC notebook (Marimo) for details.

Web UI

The optional web interface is documented here: Web UI (R3XA_API).

Quick links

Tutorials: Tutorial — Interactive DIC notebook (Marimo), Tutorial — Qi Hu case study (IR Lagrangian thermography)
How-to guides: Examples and recipes — from scratch vs registry, Registry Web Editor, Deploy on Railway
Explanation: R3XA_API — Overview and rationale, Engineering Contract — user and developer requirements
Reference: R3XA_API — API Reference, R3XA Specification, Validation — concepts and best practices, MATLAB binding reference (minimal), Web UI (R3XA_API), Developer workflow

Common workflows

If you do not want to read the whole documentation, start from one of these three workflows:

Learn the library interactively — start with Tutorial — Interactive DIC notebook (Marimo).
Study a full worked case — continue with Tutorial — Qi Hu case study (IR Lagrangian thermography).
Create a new R3XA file — use R3XAFile with the guided helpers documented in R3XA_API — API Reference.
Load, edit, and save an existing file — see R3XA_API — API Reference and examples/python/load_edit_save.py.
Reuse or create registry items — use Registry and RegistryItem, documented in R3XA_API — API Reference and demonstrated in examples/python/create_registry_camera.py and examples/python/registry_discovery.py.

Tutorials

Explanation

Reference