# MATLAB Data Types Supported by the `matlab_to_python` Conversion Function

> Discover which MATLAB data types the matlab_to_python conversion function supports and which it doesn't. Understand supported types and Python fallback options.

- Repository: [Jigar Bhoye/matlabmcp](https://github.com/jigarbhoye04/matlabmcp)
- Tags: api-reference
- Published: 2026-03-04

---

**The `matlab_to_python` function in jigarbhoye04/matlabmcp actively converts only `matlab.double`, `matlab.logical`, and `matlab.char` into native Python objects, while all other MATLAB types fall back to string representation or error placeholders.**

The matlabmcp repository bridges MATLAB and Python using the MATLAB Engine API. Understanding which MATLAB data types the `matlab_to_python` conversion function handles is essential for building reliable data pipelines. This analysis examines the implementation in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) to identify exactly which types become JSON-serializable Python objects and which require manual intervention.

## Supported MATLAB Data Types

The conversion logic resides in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) between lines 53 and 77. It explicitly handles four data categories through cascading `isinstance` checks, ensuring JSON-compatible outputs.

### Numeric Arrays (`matlab.double`)

At line 59, the function detects `matlab.double` instances using `isinstance(data, matlab.double)`. The conversion wraps the value in a NumPy array, applies `squeeze()` to remove singleton dimensions, and then:

- Returns a Python `float` if the result is a scalar
- Returns a nested Python `list` of numbers for multidimensional arrays

### Boolean Arrays (`matlab.logical`)

Line 63 checks for `matlab.logical` types using `isinstance(data, matlab.logical)`. The processing mirrors numeric arrays:

- Scalar values become Python `bool` objects
- Arrays convert to nested `list` structures containing `True` or `False` values

### Character Arrays (`matlab.char`)

Detected at line 67 via `isinstance(data, matlab.char)`, MATLAB character arrays convert directly to Python strings using `str(data)`. This handles string literals and row vectors from the MATLAB workspace.

### Python Native Primitives

Line 57 passes through existing Python primitives—including `str`, `int`, `float`, `bool`, and `None`—unchanged. This ensures idempotent behavior when data originates from Python contexts or has already been converted.

## Unsupported MATLAB Types and Fallback Behavior

Any MATLAB type not explicitly handled above—including **structs, cell arrays, tables, sparse matrices, function handles, and MATLAB objects**—falls into the `else` block at line 70.

For these unsupported types, the function:

1. Logs a warning message indicating the type is unserializable
2. Attempts conversion via `str(data)`
3. Returns a descriptive placeholder string `"Unserializable MATLAB Type: <type>"` if stringification fails

This fallback preserves runtime stability but loses structural data, potentially breaking JSON serialization for complex objects that require nested dictionaries or lists.

## Implementation Details in main.py

The `matlab_to_python` function uses a defensive type-checking pattern to handle MATLAB Engine return values:

```python
def matlab_to_python(data):
    if isinstance(data, (str, int, float, bool, type(None))):
        return data
    elif isinstance(data, matlab.double):
        # NumPy conversion, squeeze, scalar check

        arr = np.array(data)
        arr = np.squeeze(arr)
        if arr.ndim == 0:
            return float(arr)
        return arr.tolist()
    elif isinstance(data, matlab.logical):
        # Similar logic yielding bool for scalars

    elif isinstance(data, matlab.char):
        return str(data)
    else:
        # Warning and string fallback (line 70)

        logging.warning(f"Unserializable MATLAB Type: {type(data)}")
        try:
            return str(data)
        except:
            return f"Unserializable MATLAB Type: {type(data)}"

```

This structure prioritizes common numerical and text data while providing a safe fallback for MATLAB-specific complex objects.

## Practical Conversion Examples

### Converting MATLAB Double Matrices

```python
import matlab.engine
from main import matlab_to_python

eng = matlab.engine.start_matlab()
matlab_mat = eng.eval('reshape(1:6, 2, 3)', nargout=1)
py_val = matlab_to_python(matlab_mat)
print(py_val)  

# Output: [[1.0, 3.0, 5.0], [2.0, 4.0, 6.0]]

```

### Handling Logical Scalars

```python
log = eng.eval('true', nargout=1)
result = matlab_to_python(log)
print(result, type(result))  

# Output: True <class 'bool'>

```

### Character Array Conversion

```python
txt = eng.eval("'Hello MATLAB'", nargout=1)
print(matlab_to_python(txt))  

# Output: Hello MATLAB

```

### Unsupported Struct Types

```python
eng.eval("s = struct('a', 1, 'b', 2);", nargout=0)
struct_val = eng.workspace['s']
print(matlab_to_python(struct_val))

# Output: "Unserializable MATLAB Type: <class 'matlab.engine.matlabobject'>"

```

## Summary

- **Actively supported**: `matlab.double` (converts to `float` or nested `list`), `matlab.logical` (converts to `bool` or nested `list`), and `matlab.char` (converts to `str`)
- **Pass-through types**: Python primitives (`str`, `int`, `float`, `bool`, `None`) returned unchanged at line 57 of [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py)
- **Unsupported types**: Structs, cell arrays, tables, sparse matrices, and MATLAB objects fall back to string representation via the `else` block at line 70
- **Critical limitation**: Only three MATLAB native types receive structured conversion; complex data structures require manual preprocessing before calling `matlab_to_python`

## Frequently Asked Questions

### Does `matlab_to_python` support MATLAB tables and timetables?

No. According to the source code in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py), MATLAB tables and timetables are not explicitly handled. They fall into the `else` block at line 70 and return a string representation or "Unserializable MATLAB Type" placeholder, effectively losing the tabular structure and column metadata required for DataFrame conversion.

### How does the function handle multidimensional MATLAB arrays?

The function converts multidimensional `matlab.double` and `matlab.logical` arrays by first wrapping them in NumPy arrays, squeezing singleton dimensions with `np.squeeze()`, then converting to nested Python lists using `.tolist()`. This preserves numerical values but represents the data as standard Python lists rather than preserving MATLAB's matrix structure.

### Can I modify `matlab_to_python` to support MATLAB structs?

Yes. The current implementation uses explicit type checking at lines 59, 63, and 67. You would need to add an `elif isinstance(data, matlab.struct)` branch before the final `else` block at line 70 to recursively convert struct fields into Python dictionaries. Without this modification, structs only receive string representation, making their field data inaccessible programmatically.

### What happens to complex numbers from MATLAB?

Complex numbers are not explicitly handled in the type checks. If MATLAB returns a complex value as `matlab.double`, the NumPy conversion may preserve the complex dtype, but scalar conversion to `float` will raise a TypeError. The function lacks specific handling for complex numbers, meaning they may either cast incorrectly or fall back to the string representation depending on the NumPy array state.