MATLAB binding reference (minimal)

This page is mostly reference documentation for the MATLAB binding. Use it when you need the exact supported scope and MATLAB call patterns.

This binding focuses only on generating R3XA JSON from MATLAB.
No graph generation, no GUI dependencies, and no Python packages required inside MATLAB.

Install (MATLAB path)

Add the matlab/ folder to your MATLAB path:

addpath(genpath('path/to/R3XA_API/matlab'));

Quick start

import r3xa.*

r3xa_file = R3XAFile( ...
    "title", "Hello World", ...
    "description", "Minimal R3XA file", ...
    "authors", "JC Passieux", ...
    "date", "2024-10-30" ...
);

specimen = r3xa_file.add_specimen_setting( ...
    "Openhole sample", ...
    "Glass-epoxy specimen", ...
    "sizes", {unit("width", 30.0, "mm", 1.0)} ...
);

camera = r3xa_file.add_camera_source( ...
    "CCD Camera", ...
    "Encoding: 8-bit", ...
    1, ...
    "surface", ...
    {unit("graylevel", 1.0, "gl", 1.0)}, ...
    "Allied Vision Technologies (AVT)", ...
    "Dolphin F-145B", ...
    {unit("width", 1392, "px", 1.0), unit("height", 1040, "px", 1.0)}, ...
    "field_of_view", {unit("width", 120.0, "mm", 1.0), unit("height", 90.0, "mm", 1.0)}, ...
    "focal_length", unit("focal_length", 25.0, "mm", 1.0), ...
    "standoff_distance", unit("standoff", 0.5, "m", 1.0), ...
    "lens", "50mm prime", ...
    "aperture", "f/8", ...
    "exposure", unit("exposure", 2.0, "ms", 1.0) ...
);

images = r3xa_file.add_list_data_set( ...
    "graylevel images", ...
    "images taken by the CCD camera", ...
    "image/tiff", ...
    {camera.id}, ...
    unit("time_reference", 0.0, "s", 1.0), ...
    [0.0, 1.0], ...
    {"zoom-0050_1.tif", "zoom-0070_1.tif"}, ...
    "path", "images/" ...
);

r3xa_file.save("hello-world.json");

MATLAB vs Python helper signatures

The MATLAB binding currently keeps a small handwritten helper layer. It is intentionally close to the Python API, but not identical.

General rule:

• schema-required fields are positional in MATLAB helpers

• optional fields go through trailing name/value arguments (varargin)

• low-level methods remain available for every kind:

  • add_setting(kind, ...)

  • add_data_source(kind, ...)

  • add_data_set(kind, ...)

In particular, add_camera_source(...) is stricter in MATLAB:

• Python guided helper:

  • add_camera_source(title, output_components, output_dimension, output_units, image_size, **extra)

• MATLAB helper:

  • add_camera_source(title, description, output_components, output_dimension, output_units, manufacturer, model, image_size, ...)

So description, manufacturer, and model are positional in MATLAB, while they stay optional schema fields passed through **extra in Python.

When switching from Python to MATLAB, use the MATLAB examples in this page as the reference call signature.

unit() signature difference

Python unit() requires only the unit keyword:

unit(unit="mm")
unit(title="width", value=30.0, unit="mm")

MATLAB unit() keeps title, value, and unit_name as positional parameters:

r3xa.unit("width", 30.0, "mm")
r3xa.unit("width", 30.0, "mm", 1.0)

This divergence is intentional. MATLAB does not support keyword-only arguments, and changing the existing signature would break current MATLAB scripts.

What is implemented

• r3xa.R3XAFile constructor, header editing, JSON serialization, and save

• Low-level item builders:

  • add_setting(kind, ...)

  • add_data_source(kind, ...)

  • add_data_set(kind, ...)

• Guided settings helpers:

  • add_generic_setting(...)

  • add_specimen_setting(...)

  • add_stereorig_setting(...)

  • add_testing_machine_setting(...)

• Guided data source helpers:

  • add_camera_source(...)

  • add_dic_measurement_source(...)

  • add_generic_source(...)

  • add_identification_source(...)

  • add_infrared_source(...)

  • add_load_cell_source(...)

  • add_mechanical_analysis_source(...)

  • add_point_temperature_source(...)

  • add_strain_computation_source(...)

  • add_strain_gauge_source(...)

  • add_tomograph_source(...)

• Guided data set helpers:

  • add_file_data_set(...)

  • add_generic_data_set(...)

  • add_list_data_set(...)

• Legacy MATLAB aliases:

  • add_image_set_list(...)

  • add_image_set_file(...)

• Core helper functions:

  • r3xa.new_item

  • r3xa.unit

  • r3xa.data_set_file

  • r3xa.ensure_data_set_file

• r3xa.schema_version (reads r3xa_api/resources/schema.json)

Legacy aliases

The canonical data set helper names now match the Python API:

• add_list_data_set(...)

• add_file_data_set(...)

For backward compatibility, the legacy MATLAB names remain available:

• add_image_set_list(...)

• add_image_set_file(...)

add_image_set_list(...) keeps the historical positional path argument. Use it only when you need to preserve existing MATLAB scripts unchanged.

What is intentionally omitted

• Graph generation backends

• JSON schema validation

• Registry tooling

• JSON loading / from_dict()