evo-data-converters-common 0.4.0

Seequent Developer Portal • Seequent Community • Seequent website

Evo

Evo is a unified platform for geoscience teams. It enables access, connection, computation, and management of subsurface data. This empowers better decision-making, simplified collaboration, and accelerated innovation. Evo is built on open APIs, allowing developers to build custom integrations and applications. Our open schemas, code examples, and SDK are available for the community to use and extend.

Evo is powered by Seequent, a Bentley organisation.

Pre-requisites

• Python 3.10, 3.11, or 3.12

Installation

pip install evo-data-converters-common

Data converters

This package provides a framework for Evo-specific data converters.

When running a converter, data is imported from a supported file format, converted into geoscience objects, and then published to the Seequent Evo API.

This framework (evo.data_converters.common) can be used to build custom data converters for any type of geoscience data.

For an existing set of supported data converters, see:

• DUF
• GOCAD
• Image
• OBJ
• OMF
• RESQML
• SHP
• UBC
• VTK
• XYZ

Data converters can be optionally both an importer and an exporter.

• The importer will load data into Seequent Evo.
• The exporter will export data from Seequent Evo into the designated file format.

There are examples of both in the OMF converter.

Each converter will support a subset of Evo geoscience objects.

Existing converters can be extended to support additional geoscience objects depending on your data requirements.

New converters can be created to support additional data file types. The easiest way to start one is with the create-converter CLI, which scaffolds a new converter package for you.

Developing converters

Working on data converters

To work on your local version of the data converters module, first follow the directions in Setting up your environment.

Each converter package is installed independently. Change into the package you want to work on and run:

cd packages/<converter>
uv sync

Developer tasks (uv run)

Common developer tasks are exposed as scripts on the evo-data-converters-common package. Run lint and test commands from the converter package you want to check; run create-converter from packages/common:

cd packages/<converter>

uv run lint            # ruff check + format --check for this package
uv run lint-fix        # ruff check --fix + format for this package
uv run test            # sync and run the tests for this package
uv run test-<type>     # sync and run the tests for a named package, e.g. test-xyz

cd ../common

uv run create-converter  # scaffold a new converter (see below)

Creating a new converter with the CLI

The quickest way to start a new converter is with the create-converter CLI. It scaffolds a complete, ready-to-build converter package from a template so you can focus on the format-specific conversion logic rather than boilerplate.

From within packages/common run:

uv run create-converter

This runs the CLI (../../scripts/create_converter.py) from within packages/common, where its copier dependency lives (in the dev dependency group).

You will be prompted for:

• Converter type – a short name for the file format, e.g. obj, shp, xyz. This is used for the package name (evo-data-converters-<type>), module paths, and the convert_<type> / export_<type> function names.
• Export support – whether the converter is Import only or Import and Export. Choose Import and Export to also scaffold an exporter.

The CLI then:

• Creates a new package under packages/<type>/ with the standard importer/ (and exporter/, if selected) layout, code samples, and tests.
• Registers the package by adding a test-<type> script to packages/common/pyproject.toml and updating README.md.

The generated convert_<type> and export_<type> functions follow the conventions described below, with the format-specific parts left as TODO comments that raise NotImplementedError. These are the places where you add your own file parsing and geoscience object conversion. See Structure of a converter for what to implement in each file.

After generating a converter:

# Install the new package (run from packages/<type>)
uv sync

# Run the generated tests for your converter (run from packages/common)
uv run test-<type>

General converter architecture

Within packages/common the directory structure for converters comprises a top level common directory, containing common modules that are usable across all converters. In the other packages folders are various supported data converter packages that build on the "common" library:

.
├── common/
├── omf/
├── resqml/
├── vtk/
└── README.md

Expanding this out, each converter type contains an importer directory, an exporter directory (if supported), and any other utility modules specific to this converter type:

.
├── common/src/evo/data_converters/common/
│   ├── __init__.py
│   └── blockmodel_client.py
│   └── evo_client.py
│   └── exceptions.py
│   └── generate_paths.py
│   └── publish.py
│   └── utils.py
│   └── (and more common modules)
├── omf/code-samples/
├── omf/src/evo/data_converters/omf/
│   ├── exporter/
│   │   └── __init__.py
│   │   └── evo_to_omf.py
│   │   └── (and more modules specific to omf/exporter)
│   ├── importer/
│   │   └── __init__.py
│   │   └── omf_to_evo.py
│   │   └── (and more modules specific to omf/importer)
│   ├── __init__.py
│   ├── utils.py
│   └── (and more common modules for omf)
├── resqml/code-samples/
├── resqml/src/evo/data_converters/resqml/
│   ├── importer/
│   │   └── __init__.py
│   │   └── resqml_to_evo.py
│   │   └── (and more modules specific to resqml/importer)
│   ├── __init__.py
│   ├── utils.py
│   └── (and more common modules for resqml)
├── vtk/src/evo/data_converters/vtk/
│   ├── importer/
│   │   └── __init__.py
│   │   └── vtk_to_evo.py
│   │   └── (and more modules specific to vtk/importer)
│   ├── __init__.py
└── README.md

Structure of a converter

The converters are designed to follow a consistent coding pattern to encourage reusability and commonality. Within this pattern there is much room for flexibility, although this is expected to come at the lower level when addressing the needs of specific data sources.

When you scaffold a converter with the create-converter CLI, the files described below are generated for you with the format-specific logic left as TODO stubs to implement.

Importer

An importer takes geoscience data from a specific file type, converts it to Evo geoscience objects and uploads these objects to Evo.

As observable in the example Jupyter notebook for converting an OMF file the main interface to a convertor is the convert_* function. This function will be in a module in the root directory of the named yourfiletype_to_evo.py.

Within this function the following tasks must be completed:

• Read the passed data file
• Extract supported geoscience objects from the file
• Convert source geoscience objects into Evo geoscience objects
• Publish the geoscience objects to the Geoscience Object API

By convention the convert function should return a list, and the items in the list are either instances of the BaseSpatialDataProperties_V1_0_1 class or the ObjectMetadata class.

The return items will be BaseSpatialDataProperties_V1_0_1 class if returning geoscience objects directly. The purpose of this option is if you wish to use the converter to transform data into Evo geoscience objects but not publish directly to the Geoscience Object API.

The return items will be ObjectMetadata class if returning the output of the upload to the Geoscience Object API.

Example importer

The following pseudocode shows the bare basics of a new converter for yourfiletype importing point set data, based of the existing OMF importer.

# Import common objects for working with the Geoscience Object API
from evo.data_converters.common import (
    EvoWorkspaceMetadata,
    create_evo_object_service_and_data_client,
    publish_geoscience_objects,
)

# Import file parsing modules required - this is pure pseudocode and will vary
# depending on the type of file
from yourfileparsermodule import yourfileparser


# Define the main async convert function
async def convert_yourfiletype(
    filepath: str,
    epsg_code: int,
    evo_workspace_metadata: Optional[EvoWorkspaceMetadata] = None,
    service_manager_widget: Optional["ServiceManagerWidget"] = None,
    upload_path: str = "",
    overwrite_existing_objects: bool = False,
) -> list[ObjectMetadata]:
    geoscience_objects = []

    # create a service and data clients to handle upload to the Seequent Evo API
    object_service_client, data_client = await create_evo_object_service_and_data_client(
        evo_workspace_metadata=evo_workspace_metadata, service_manager_widget=service_manager_widget
    )

    # Read your specific file type to an object ready for conversion (pseudocode only here)
    reader = yourfileparser(filepath)

    # Loop through the elements found in the file - converting any point set elements into to
    # Evo geoscience objects
    for element in reader.elements():
        geoscience_object = None
        if element.type == "pointset":
            # Call the specific pointset converter here
            geoscience_object = _convert_pointset(element, reader, data_client, epsg_code)

        if geoscience_object:
            geoscience_objects.append(geoscience_object)

    # Publish the found geoscience objects to Evo
    objects_metadata = await publish_geoscience_objects(
        geoscience_objects, object_service_client, data_client, upload_path, overwrite_existing_objects
    )

    # Return the publishing response
    return objects_metadata

Note: this example only returns the ObjectMetadata, and will publish immediately. Refer to the existing converter examples to see usage for the optional return of BaseSpatialDataProperties_V1_0_1.

Parameters

The following parameters are passed into the async convert function. By convention these are the typical minimum parameters a convert function should have, however additional ones can be added as needed for specific usage needs.

File parsing

Both the OMF and RESQML converters use external libraries for parsing the file into usable Python objects by the converter function. This will vary for different file types and in some cases file parsers may need to be developed from scratch. Refer to OMF and RESQML converters for existing examples of this (omf2 and resqpy respectively).

Conversion to geoscience objects

As observable in the example above, the top level convert function will then use specific conversion functions for each type of geoscience data. As with file parsing, the specific method for conversion will vary depending on the data source. All these functions should return an Evo supported geoscience object type ready for upload to Evo. For the point set example, this will be Pointset_V1_2_0.

Exporter

An exporter takes specified geoscience objects from Evo and converts them to a specified file format on disk.

Reversing the pattern of the importer, the main interface of an exporter is the export_* function that takes a specified list of Evo objects and a filepath to create the file.

Example exporter

Refer to evo_to_omf.py for an example of the export_omf function.

Parameters

Code of conduct

We rely on an open, friendly, inclusive environment. To help us ensure this remains possible, please familiarise yourself with our code of conduct.

License

Evo data converters are open source and licensed under the Apache 2.0 license.

Copyright © 2026 Bentley Systems, Incorporated.

Licensed under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.