Python Functions & Operators

Python Functions & Operators

Earth Volumetric Studio supports Python 3.12 and 3.13. It will use the highest supported system installed version by default, but can be configured in options.

A listing of Python Functions & Operators can be found at python.org. Below are links to relevant pages:

• Functions

• Math Operators

• String Operators

• Date and Time Operators

  • Date & time syntax

Please note: C Tech does not provide Python programming or syntax assistance as a part of Technical Support (included with valid subscriptions). Python scripting and functionality is provided as an advanced feature of Earth Volumetric Studio, but is not required to use the basic functionality.

Below are Earth Volumetric Studio specific functions and classes which provide means to get and set parameters, read field data, and act upon the modules in the libraries and network. All functions below are available through the evs module unless otherwise noted.

Module Properties

These functions read and write property values on modules. For a detailed walkthrough with examples, see Accessing Properties Using Python.

evs.get_module(module, category, property)

Gets a property value from a module within the application.

Returns: The property value.

explode = evs.get_module('explode and scale', 'Properties', 'Explode')

evs.get_module_extended(module, category, property)

Gets an extended property value from a module within the application. Extended values include additional metadata beyond the basic value.

Returns: The extended property value.

evs.set_module(module, category, property, value)

Sets a property value on a module within the application.

evs.set_module('explode and scale', 'Properties', 'Explode', {'Linked': False, 'Value': 1.0})

evs.set_module_interpolated(module, category, property, start_value, end_value, percent, interpolation_method)

Sets a property value by interpolating between two values. Useful for animating properties across sequence states.

The interpolation_method parameter accepts one of the following evs.InterpolationMethod values:

# Interpolate the Explode value from 0.0 to 5.0 at 50%
evs.set_module_interpolated('explode and scale', 'Properties', 'Explode',
    {'Linked': False, 'Value': 0.0},
    {'Linked': False, 'Value': 5.0},
    0.5, evs.InterpolationMethod.Cosine)

Port Properties

These functions read and write property values on module ports.

evs.get_port(module, port, category, property)

Gets a value from a port on a module within the application.

Returns: The port property value.

evs.get_port_extended(module, port, category, property)

Gets an extended value from a port on a module within the application.

Returns: The extended port property value.

evs.set_port(module, port, category, property, value)

Sets a property value on a port in a module within the application.

evs.set_port_interpolated(module, port, category, property, start_value, end_value, percent, interpolation_method)

Sets a port property value by interpolating between two values. Accepts the same evs.InterpolationMethod values as set_module_interpolated.

Reading Field Data

These functions and classes allow Python scripts to read the contents of field data from module ports. This is useful for extracting coordinates, node data, and cell data from computed fields.

evs.get_field_info(module, port)

Gets a FieldInfo object for reading field data from a module port. The returned object should be used within a with statement, or you must call close() manually when finished.

Returns: FieldInfo — a field reader for accessing coordinates and data.

Raises: ValueError if the field reader cannot be created for the specified module and port.

with evs.get_field_info('kriging', 'Output Field') as field:
    print(f"Nodes: {field.number_coordinates}, Cells: {field.number_cells}")
    print(f"Units: {field.coordinate_units}")

    # Read coordinates
    for x, y, z in field.coordinates:
        print(f"  ({x}, {y}, {z})")

    # Read node data
    for i in range(field.number_node_data):
        data = field.get_node_data(i)
        print(f"  {data.name} ({data.units}): {len(data.values)} values")

evs.FieldInfo

Represents a field, providing access to its coordinates, node data, and cell data. Should be used within a with statement to ensure resources are properly released.

Properties:

Methods:

evs.FieldData

Represents one node or cell data component of a field. Returned by FieldInfo.get_node_data() and FieldInfo.get_cell_data().

Properties:

Application and Module Management

evs.get_application_info()

Gets basic information about the current application.

Returns: dict — a dictionary with the following keys:

evs.get_modules()

Gets a list of all module names in the application.

Returns: list of str — module names.

for name in evs.get_modules():
    print(f"{name}: {evs.get_module_type(name)}")

evs.get_module_type(module)

Gets the type of a module given its name.

Returns: str — the module type.

evs.get_module_position(module)

Gets the position of a module in the network editor.

Returns: tuple of (x, y) — the module’s position coordinates.

evs.rename_module(module, suggested_name)

Renames a module and returns the actual new name. The actual name may differ from the suggested name if a module with that name already exists.

Returns: str — the actual new name of the module.

evs.delete_module(module)

Deletes a module from the application.

Returns: bool — True if successful.

evs.instance_module(module, suggested_name, x, y)

Creates a new instance of a module in the application at the specified position.

Returns: str — the actual name of the instanced module.

name = evs.instance_module('Estimation.kriging', 'my kriging', 100, 200)
print(f"Created module: {name}")

Module Connections

evs.connect(starting_module, starting_port, ending_module, ending_port)

Connects a port on one module to a port on another module.

Returns: bool — True if successful.

evs.connect('kriging', 'Output Field', 'cut', 'Input Field')

evs.disconnect(starting_module, starting_port, ending_module, ending_port)

Disconnects two previously connected module ports.

Returns: bool — True if successful.

Execution Control

evs.check_cancel()

Checks whether the user has requested to cancel the script. If a cancellation has been requested, the script will stop at that point. Insert this in loops that may run for a long time so that canceling the script remains possible.

for i in range(10000):
    evs.check_cancel()
    # ... do work ...

evs.suspend()

Suspends the execution of the application until resume() is called. Use this when making multiple property changes to prevent the application from updating between each change.

evs.resume()

Resumes the execution of the application, causing any operations that were suspended to run.

evs.suspend()
evs.set_module('kriging', 'Properties', 'Allow Run', True)
evs.set_module('kriging', 'Properties', 'Variogram Range', 500.0)
evs.resume()

evs.refresh()

Refreshes the viewer and processes all mouse and keyboard actions in the application.

evs.is_module_executed()

Returns whether the script is being executed by a module (such as trigger script) as opposed to being run directly by the user.

Returns: bool — True if executed by a module, False when the user executes directly (e.g., hitting play in the script window).

Number Formatting

evs.sigfig(number, digits)

Rounds a number to a specified number of significant figures.

Returns: float — the rounded value.

evs.sigfig(123456.789, 4)  # Returns 123500.0

evs.fn(number, digits, include_thousands_separators, preserve_trailing_zeros)

Formats a number as a string using a specified number of significant figures. Also available as evs.format_number().

Returns: str — the formatted number.

evs.fn(1234567.89)           # "1,234,570"
evs.fn(1234567.89, 3)        # "1,230,000"
evs.fn(1234567.89, 6, False) # "1234570"

evs.fn_a(number, adapt_size, digits, include_thousands_separators, preserve_trailing_zeros)

Formats a number as a string, adapting the precision to the magnitude of a second number. This is useful when formatting a value relative to a step size or range. Also available as evs.format_number_adaptive().

Returns: str — the formatted number.

Export Scripting

The export scripting API allows Python scripts to respond to events during a web scene export. When the export web scene module writes a CTWS file, it triggers the attached Python script at each stage of the process. Use get_export_stage() to determine the current stage and respond accordingly.

evs.get_export_stage()

Gets the current export stage and related information.

Returns: ExportStage — an object describing the current stage of the export process.

stage = evs.get_export_stage()

# Run initialization code at the start of an export
stage.handle_init(lambda: print("Export starting"))

# Handle a specific module being exported
stage.handle_module('kriging', lambda: print("Kriging exported"))

# Handle sequence states with state number and name
stage.handle_sequence('scripted sequence', lambda num, name: print(f"State {num}: {name}"))

# Run finalization code at the end of an export
stage.handle_finalize(lambda: print("Export complete"))

evs.ExportStage

Represents the current export stage and provides handler methods for responding to specific stages. Constructed by get_export_stage().

Properties:

Stages:

Handler Methods:

Python Assets

evs.import_asset(name)

Imports a Python module included in the Python Assets section of the Application Properties. This is used instead of a standard import statement when working with EVS presentation files or packaged data, since Python assets are embedded within the application rather than stored as separate files on disk.

Returns: module — the imported Python module.

Raises: ModuleNotFoundError if no Python asset exists with the given name.

helpers = evs.import_asset('my_utilities')
helpers.do_something()

Date Conversions (evs_util)

The evs_util module provides functions for converting between three date representations used in EVS:

Each function converts from one format to another. The naming convention is {source}_to_{target}:

import evs_util
import datetime

# Convert an EVS date string to a Python datetime
dt = evs_util.evsdate_to_datetime("2024-06-15T14:30:00")

# Convert to an Excel date number
excel_num = evs_util.datetime_to_excel(dt)

# Convert back to an EVS date string
evs_date = evs_util.excel_to_evsdate(excel_num)

Testing

evs.test(assertion, error_on_fail)

Asserts that a condition is true. If the assertion is false, the specified error message is printed as an error.

value = evs.get_module('kriging', 'Properties', 'Allow Run')
evs.test(value == True, "Expected Allow Run to be enabled")