The Python Script Editor is the integrated environment within Earth Volumetric Studio for writing, editing, and running Python scripts. It provides a full-featured text editor with syntax highlighting, code formatting tools, and direct access to execution and debugging functions, making it the central hub for all your scripting activities.

Accessing the Python Script Editor

You can open the editor through the Python Scripting button located in the Main Toolbar.

The dropdown menu provides three main options:

Once a script is created or opened, the Python Script Editor window will appear.

Editor Toolbar Reference

The toolbar at the top of the editor provides a wide range of tools for managing and editing your code.

File and Edit Operations

Execution and Recording

Code Formatting and Navigation

Additional Menus

On the far right of the toolbar are two dropdown menus for additional functionality.

Information Menu

This menu provides access to related information and output windows.

Editor Options Menu

This menu (gear icon) controls the visual display of the text editor itself.

The Python Interactive window provides a real-time environment to execute Python statements and expressions. This tool allows you to test code snippets, perform quick calculations, and inspect data without needing to run a full script.

Window Components

The interface is divided into three primary sections:

To get started with the Python Interactive window, follow these steps:

1. Enter Code: Click into the input field at the bottom of the window.
2. Evaluate: Type a mathematical expression (e.g., 42 * 29.29) or a Python command.
3. Submit: Click the play icon on the right or press your execution hotkey.
4. Review: Check the Output Area for the result or any potential error messages.

While useful as a general tool (such as using as a calculator, as shown above), the window is typically used for interacting with the EVS API directly.

This is particularly useful when writing scripts, as you can interactively inspect the structure of the EVS API calls, and modify as needed.

For example, you can see the values in a dictionary returned by the API directly:

Clicking on the grey text in the Output Area will re-select it and enter it into the Input Box, which can then be edited. Using the above, this allows us to click on the previous code (evs.get_module_exte….), and then add the entry for SelectedOption to test and make sure we are fetching the results we would expect (the name of the analyte):

This shows us the results of the entered code, which could then be reused in a Python script (such as fetching the current analyte name above for use in a title).

You can programmatically read and set the properties of any module using Python Scripting. This is a powerful feature for automating workflows and creating complex interactions between modules. The scripting engine provides programmatic access to the same underlying properties that are exposed as controls in the Properties window. This allows scripts to read, evaluate, and update values, mirroring manual user interaction. The easiest way to script a property is to copy the required syntax directly from the Properties window.

Getting a Property’s Value

To get the current value of a property and assign it to a Python variable:

1. Open the Properties window for the module you want to control.
2. Right-click on the property you want to read.
3. Select Get Value or Get Extended Value from the context menu.

This action copies a line of Python code to your clipboard. You can then paste this code into the Python Script Editor.

Reading Value Example

Right-clicking on the Explode property of the explode and scale module and selecting Get Value will copy the following syntax:

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

After executing this line, the explode variable in your script will hold the current value of the Explode property. Note that the Python API call has three arguments: the module name, the category name, then the property name.

Difference between Get Value and Get Extended Value

The context menu provides two options for getting a value. The Get Value option will use the evs.get_value API call, which fetches the value that is used when saving an application, and contains whatever is required to set the property. This is the value that should be used if using evs.set_value.

The extended option will use evs.get_extended_value, which typically results in a dictionary with the original value, as well as other metadata. For example, a drop down with a list of analytes will typically just return the selected item by index in get_value, but the extended option will include other information, such as the list of options, the selected value by name and index, and more.

Setting a Property’s Value

To set the value of a property:

1. In the Properties window, right-click on the property you want to modify.
2. Select Set Value from the context menu.

This copies the Python syntax for setting the property to your clipboard. Paste the code into the Python Script Editor or the Python Interactive Window and utilize the value as needed.

Updating Value Example

For example, using the same Explode property, the copied syntax would be:

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

You can change 0.0 to any valid value for that property, such as:

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

When dealing with a Linked Property, you should disable the link to manually when setting its value. This is done by setting the corresponding Linked boolean property to false. If you attempt to set the value while it is still linked, your change may be overridden as the value is determined automatically.

Executing this command in the Python Script Editor or the Python Interactive Window will update the property in the module, and the change will be immediately visible in the Properties window.

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")