# 📘 How-to: Custom fields and custom vectors (openep-py Python library)

**URL:** <https://openep.discourse.group/t/how-to-custom-fields-and-custom-vectors-openep-py-python-library/172>\
**Category:** Uncategorized\
**Created:** [2 February 2026 16:12 UTC](https://openep.discourse.group/t/how-to-custom-fields-and-custom-vectors-openep-py-python-library/172 "2026-02-02T16:12:49Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![vk\_vinush](https://avatars.discourse-cdn.com/v4/letter/v/90ced4/32.png) [@vk\_vinush](https://openep.discourse.group/u/vk_vinush)\
**Post date:** [2 February 2026 16:12 UTC](https://openep.discourse.group/t/how-to-custom-fields-and-custom-vectors-openep-py-python-library/172/1 "2026-02-02T16:12:49Z")

</div>

# 📘 How to add custom fields and custom vectors to OpenEP Case objects - Python

This guide explains how to add **custom scalar fields** and **custom vectors** to OpenEP case objects using the **OpenEP Python library**.

## Contents

1. **Who is this for?**
2. **Prerequisites**
3. **Adding a custom field** (scalar field on a mesh)
  - Step 1: Load a case
  - Step 2: Create field data with the correct shape
  - Step 3: Assign the new field
  - Step 4: Access the field
  - Step 5: Export and view in EP Workbench

4. **Adding a custom vector field/data** (vector data associated with the Case)
5. **How are custom fields and vectors stored in `openep.mat`? (MATLAB Data Viewer)**

* * *

## 1. Who is this for?

This documentation is relevant for users who are:

- Using the **OpenEP Python library (`openep-py`)** directly, or
- Working with OpenEP data through **WIP functionality in EP Workbench**

This is particularly useful if you want to:

- Attach custom analysis results to a case
- Visualise new scalar fields in EP Workbench
- Store additional surface vectors (or vector data) alongside existing OpenEP data

* * *

## 2. Prerequisites

Make sure you have the following installed:

```auto
pip install openep pyvista numpy

```

* * *

## 3. Adding a custom **field** (scalar field on a mesh)

A **field** in OpenEP is a scalar value defined at each mesh point or cell (e.g. voltage, activation time, custom metrics).

For more information on mesh, points and cells see: [What is a Mesh? — PyVista 0.46.3 documentation](https://docs.pyvista.org/user-guide/what-is-a-mesh)

#### Step 1: Load a case

```auto
import openep

case = openep.load_openep_mat("path/to/openep.mat")

```

#### Step 2: Create field data with the correct shape

Use the mesh points or mesh cells to obtain the correct shape:

```auto
mesh = case.create_mesh()
test_data = 100 * np.random.rand(mesh.n_points)

```

#### Step 3: Assign the new field (this should be a `snake_case` string)

```auto
case.fields["new_field"] = test_data

```

#### Step 4: Access the field

Once added, the field is accessible as an attribute:

```auto
case.fields.new_field

```

#### Step 5: Export and view in EP Workbench

```auto
from pathlib import Path

temp_file_name = Path(tmpdir) / "new_openep_dataset"

openep.export_openep_mat(
    case=case,
    filename=str(temp_file_name)
)

```

After loading this file in **EP Workbench** , you can find the field under:

```auto
3D Viewer Menu > Fields (Dropdown) > Custom > "new_field"

```

> **Note** : You can also view the mesh in your Python environment using PyVista simply create a Plotter object then add `mesh` and add scalars as `case.fields.new_field`.

* * *

## 4. Adding a custom **vector**

A **vector** in OpenEP is a ND array of values associated with the case (but not directly mapped to the mesh).

### Example: Adding a custom vector

```auto
import numpy as np

reference_vector = 100 * np.random.rand(294)
case.vectors["dummy_vector"] = reference_vector

```

You can now access it via:

```auto
case.vectors.dummy_vector

```

Just like fields, vectors will be preserved when exporting the case.

* * *

## 5. How are custom fields and vectors stored in `openep.mat`? (MATLAB Data Viewer)

For the full OpenEP data structure, see the official reference:  
👉 [Data Reference | OpenEP](http://openep.io/data/)

From a **MATLAB** perspective, both custom fields and custom vectors are stored in the **`SignalMaps`** section of the OpenEP `.mat` file.

You can inspect this visually using MATLAB’s **Variable Editor / Data Viewer** :

1. Open the `.mat` file in MATLAB
2. Expand the top-level `userdata` struct
3. Navigate to:

```auto
userdata → surface → signalMaps

```

1. Each entry in `signalMaps` corresponds to a field or vector

* * *

#### How to tell fields and vectors apart

Each `signalMaps` entry contains metadata that identifies its type:

- **Custom fields**
  - Stored as signal maps with:

```auto
propSettings.type = "field"

```

- Values represent scalar data defined on the surface mesh
- **Custom vectors**
  - Stored as signal maps with:

```auto
propSettings.type = "vector"

```

The **`name`** field of each entry matches the field or vector name you added in Python, and this is exactly what EP Workbench uses when displaying custom data.

* * *

This means any custom field or vector added via OpenEP Python can always be located in MATLAB under:

```auto
userdata.surface.signalMaps

```

and identified by its `name` and `propSettings.type`.