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

1

:blue_book: 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:

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

Step 1: Load a case

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:

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)

case.fields["new_field"] = test_data

Step 4: Access the field

Once added, the field is accessible as an attribute:

case.fields.new_field

Step 5: Export and view in EP Workbench

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:

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

import numpy as np

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

You can now access it via:

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:
:backhand_index_pointing_right: Data Reference | OpenEP

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:
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:
propSettings.type = "field"
  • Values represent scalar data defined on the surface mesh
  • Custom vectors
    • Stored as signal maps with:
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:

userdata.surface.signalMaps

and identified by its name and propSettings.type.