GXF Core Python APIs

Context

context_create

context_create()

Create a GXF context.

Returns: The unique identifier of the created context.
Return type: int
Raises: ValueError – If creating the context fails.

context_destroy

context_destroy(context)

Destroy a GXF context.

Parameters: context (int) – The unique identifier of the context to destroy.
Raises: ValueError – If destroying the context fails.

Extensions

Maximum number of extensions in a context can be 1024.

load_extensions

load_extensions(context, extension_filenames=[], manifest_filenames=[], base_directory='')

Load GXF extension libraries.

Parameters

context (int) – A valid GXF context.
extension_filenames (list) – A list of valid filename.
manifest_filenames (list) – A list of valid filename.
base_directory (str) – Valid directory.

Raises

ValueError – If loading the extensions fails.

get_extension_list

get_extension_list(context)

Get a list of loaded extensions.

Parameters: context (int) – The context from which to retrieve the extension list.
Returns: A list of UUIDs representing the loaded extensions.
Return type: list
Raises: ValueError – If getting the extension list fails.

get_extension_info

get_extension_info(context, uuid)

Get information about a loaded extension.

Parameters

context (int) – The context in which the extension is loaded.
uuid (str) – The UUID of the extension.

Returns

A dictionary containing information about the extension.

Return type

dict

Raises

ValueError – If getting the extension information fails.

The returned dictionary has the following keys:

name (str): The name of the extension.
display_name (str): The display name of the extension.
category (str): The category of the extension.
brief (str): A brief description of the extension.
description (str): A detailed description of the extension.
version (str): The version of the extension.
author (str): The author of the extension.
license (str): The license of the extension.

Graph

graph_load_file

graph_load_file(context, filename)

Load a graph from a file.

Parameters

context (int) – A valid GXF context.
filename (str) – A valid YAML filename.

Raises

ValueError – If loading the graph file fails.

set_root_filepath

set_root_filepath(context, filename)

Set the root file path for the graph.

Parameters

context (int) – The context for which to set the root file path.
filename (str) – The root path.

Raises

ValueError – If setting the root file path fails.

_subgraph_load_file

_subgraph_load_file(context, filename, entity_prefix, parent_eid, prerequisites)

Loads a list of entities from a YAML file. This API is used when shared context is created using

Parameters

context (int) – A valid GXF context.
filename (str) – The path to the file containing the subgraph.
entity_prefix (str) – The prefix for entities in the subgraph.
parent_eid (int) – The unique identifier of the parent entity.
prerequisites (str) – GXF subgraph prerequisites YAML node in str.

Raises

ValueError – If loading the subgraph file fails.

graph_activate

graph_activate(context)

Activate the graph.

Parameters: context (int) – The context containing the graph to activate.
Raises: ValueError – If activating the graph fails.

graph_run

graph_run(context)

Run the graph. It blocks the caller thread until graph completes.

Parameters: context (int) – The context containing the graph to run.
Raises: ValueError – If running the graph fails.

graph_run_async

graph_run_async(context)

Run the graph asynchronously, i.e. without blocking the caller thread.

Parameters: context (int) – The context containing the graph to run asynchronously.
Raises: ValueError – If running the graph asynchronously fails.

graph_interrupt

graph_interrupt(context)

Interrupt the graph.

Parameters: context (int) – The context containing the graph to interrupt.
Raises: ValueError – If interrupting the graph fails.

graph_wait

graph_wait(context)

Wait for the graph to complete, i.e. blocks caller thread until graph completes.

Parameters: context (int) – The context containing the graph to wait for.
Raises: ValueError – If waiting for the graph fails.

graph_save

graph_save(context, filename)

Save the graph to a file.

Parameters

context (int) – The context containing the graph to save.
filename (str) – The path to the file where the graph will be saved.

Raises

ValueError – If saving the graph fails.

graph_deactivate

graph_deactivate(context)

Deactivate the graph.

Parameters: context (int) – The context containing the graph to deactivate.
Raises: ValueError – If deactivating the graph fails.

gxf_set_severity

gxf_set_severity(context, severity)

Set severity levels for GXF_LOG_* logging macros

Parameters

context (int) – The context for which to set the logging severity.
severity (int) – The severity level to set. - 0: GXF_SEVERITY_NONE, - 1: GXF_SEVERITY_ERROR, - 2: GXF_SEVERITY_WARNING, - 3: GXF_SEVERITY_INFO, - 4: GXF_SEVERITY_DEBUG, - 5: GXF_SEVERITY_VERBOSE

Raises

ValueError – If setting the logging severity fails.

Entities

gxf_entity_create_info

class gxf_entity_create_info

entity_name: str: The name of the entity.

flags: int: 1 for system entity, 0 for non system entity

entity_create

entity_create(context, info)

Create an entity with info

Parameters

context (int) – A unique interger representing GXF context.
info (gxf_entity_create_info) – The entity creation information.

Returns

A unique entity identifier.

Return type

int

Raises

ValueError – If not successful.

entity_activate

entity_activate(context, eid)

Activate an entity

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Raises

ValueError – If not successful.

entity_deactivate

entity_deactivate(context, eid)

Deactivate an entity

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Raises

ValueError – If not successful.

entity_destroy

entity_destroy(context, eid)

Destroy an entity

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Raises

ValueError – If not successful.

entity_find

entity_find(context, entity_name)

Finds an entity by its name

Parameters

context (int) – A unique interger representing GXF context.
entity_name (str) – A C string with the name of the entity. Ownership is not transferred.

Returns

A unique entity identifier.

Return type

int

Raises

ValueError – If not successful.

entity_find_all

entity_find_all(context)

Get all the entities of the given context

Parameters: context (int) – A unique interger representing GXF context.
Returns: A list of unique identifiers for the entities in the context.
Return type: list
Raises: ValueError – If not successful.

entity_ref_count_inc

entity_ref_count_inc(context, eid)

Increase reference count of an entity

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Raises

ValueError – If not successful.

entity_ref_count_dec

entity_ref_count_dec(context, eid)

Decrease reference count of an entity

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Raises

ValueError – If not successful.

entity_get_state

entity_get_state(context, eid)

Get state of an entity

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Returns

The state of the entity.

Return type

int

Raises

ValueError – If not successful.

The returned state has following values:

0: GXF_BEHAVIOR_INIT,
1: GXF_BEHAVIOR_SUCCESS,
2: GXF_BEHAVIOR_RUNNING,
3: GXF_BEHAVIOR_FAILURE,
4: GXF_BEHAVIOR_UNKNOWN

entity_event_notify

entity_event_notify(context, eid)

Notify entity on an event

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Raises

ValueError – If not successful.

entity_notify_event_type

entity_notify_event_type(context, eid)

Notify entity on an event

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Raises

ValueError – If not successful.

entity_get_status

entity_get_status(context, eid)

Gets the status of the entity

Parameters

context (int) – A unique interger representing GXF context.
eid (int) – The UID of a valid entity.

Returns

The status of the entity.

Return type

int

Raises

ValueError – If not successful.

The returned status has following values:

0: GXF_ENTITY_STATUS_NOT_STARTED,
1: GXF_ENTITY_STATUS_START_PENDING,
2: GXF_ENTITY_STATUS_STARTED,
3: GXF_ENTITY_STATUS_TICK_PENDING,
4: GXF_ENTITY_STATUS_TICKING,
5: GXF_ENTITY_STATUS_IDLE,
6: GXF_ENTITY_STATUS_STOP_PENDING,
7: GXF_ENTITY_MAX

EntityGroup

entity_group_create

entity_group_create(context, name)

Create an entity group with name

Parameters

context (int) – A unique interger representing GXF context.
name (str) – entity group name.

Returns

A unique entity group identifier.

Return type

int

Raises

ValueError – If not successful.

entity_group_add

entity_group_add(context, gid, eid)

Add an entity to an entity group

Parameters

context (int) – A unique interger representing GXF context.
gid (int) – The UID of a valid entity group.
eid (int) – The UID of a valid entity.

Returns

The entity group ID used to add this entity.

Return type

int

Raises

ValueError – If not successful.

Components

Maximum number of components in an entity or an extension can be upto 1024.

gxf_tid_t

class gxf_tid_t

hash1: int

hash2: int

gxf_uid_t

class gxf_uid_t

Type: int

get_component_list

get_component_list(context, uuid)

Get list of components of an extension

Parameters

context (int) – A unique interger representing GXF context.
uuid (str) – GXF extension UUID. The length has to be 36, in format 8-4-4-4-12. Eg, 85f64c84-8236-4035-9b9a-3843a6a2026f

Returns

A list of comonent type UUID.

Return type

list

Raises

ValueError – If not successful.

get_component_info

get_component_info(context, uuid)

intro

Parameters

context (int) – A unique interger representing GXF context.
uuid (str) – GXF component type UUID. The length has to be 36, in format 8-4-4-4-12. Eg, 85f64c84-8236-4035-9b9a-3843a6a2026f

Returns

A dictionary containing information about the component.

Return type

dict

Raises

ValueError – If not successful.

The returned dictionary has the following keys:

typename (str): The fully qualified C++ type name of the component name.
display_name (str): The display name of the component.
brief (str): A brief description of the component.
description (str): A detailed description of the component.
base_typename (str): The fully qualified C++ type name of the base class, or an empty string if it is not inherited.
is_abstract (bool): Whether the component is abstract or not.

get_param_list

get_param_list(context, uuid)

Get parameter list of a component

Parameters

context (int) – A unique interger representing GXF context.
uuid (str) – GXF component type UUID. The length has to be 36, in format 8-4-4-4-12. Eg, 85f64c84-8236-4035-9b9a-3843a6a2026f.

Returns

A list of parameter key of this component.

Return type

list

Raises

ValueError – If not successful.

get_param_info

get_param_info(context, uuid, key)

Get information about a parameter of a component.

Parameters

context (int) – The context in which the component exists.
uuid (str) – GXF component type UUID. The length has to be 36, in format 8-4-4-4-12. Eg, 85f64c84-8236-4035-9b9a-3843a6a2026f.
key (str) – The key of the parameter.

Returns

A dictionary containing information about the parameter.

Return type

dict

Raises

ValueError – If not successful.

The returned dictionary has the following keys:

key (str): The key of the parameter.
headline (str): The headline or short description of the parameter.
description (str): A detailed description of the parameter.
gxf_parameter_type (str): The type of the parameter, as a string representation.
rank (int): The rank or number of dimensions of the parameter.
shape (list): A list representing the shape of the parameter.
flags (str): The flags associated with the parameter, as a string representation.
handle_type (str): The fully qualified C++ type name of the handle component, or “N/A” if not applicable.
default (varies): The default value of the parameter, or “N/A” if not applicable.
max_value (varies): The maximum value of the parameter, if applicable.
min_value (varies): The minimum value of the parameter, if applicable.
step_value (varies): The step value of the parameter, if applicable.

component_add

component_add(context, eid, tid, name)

Add a component of the specified type to an entity.

Parameters

context (int) – The context in which to create the component.
eid (int) – The unique identifier of the entity to contain the component.
tid (gxf_tid_t) – The type identifier of the component type to create.
name (str) – The name of the component.

Returns

The unique identifier of the added component.

Return type

int

Raises

ValueError – If adding the component fails.

component_find

component_find(context, eid, tid, component_name)

Find components of a specific type in an entity.

Searches components in an entity which satisfy certain criteria: component type, component name, and component min index. All three criteria are optional; in case no criteria is given the first component is returned. The main use case for “component min index” is a repeated search which continues at the index which was returned by a previous search.

In case no entity with the given criteria was found GXF_ENTITY_NOT_FOUND is thrown.

Parameters

context (int) – The context in which the entity and components exist.
eid (int) – The unique identifier of the entity.
tid (gxf_tid_t) – The type identifier of the components to find. If not provided, all components will be searched.
component_name (str) – The name of the component to find. If not provided, all components of the specified type will be returned.

Returns

A list of unique identifiers for the found components.

Return type

list

Raises

ValueError – If finding the components fails.

component_type_id

component_type_id(context, component_name)

Get the type identifier for a component type.

Parameters

context (int) – The context in which the component type exists.
component_name (str) – The fully qualified C++ type name of the component.

Returns

The type identifier for the specified component type.

Return type

gxf_tid_t

Raises

ValueError – If getting the type identifier fails.

component_type_name

component_type_name(context, tid)

Get the fully qualified C++ type name from its type identifier.

Parameters

context (int) – The context in which the component type exists.
tid (gxf_tid_t) – The type identifier of the component type.

Returns

The fully qualified C++ type name.

Return type

str

Raises

ValueError – If getting the type name fails.

component_add_to_interface

component_add_to_interface(context, eid, cid, name)

Adds the component to the alias map

Parameters

context (int) – The context in which the entity and component exist.
eid (int) – The unique identifier of the entity.
cid (int) – The unique identifier of the component to add to the interface.
name (str) – The name of the component in the interface.

Raises

ValueError – If adding the component to the interface fails.

Primitive Parameters

64-bit floating point (double)

set

parameter_set_float64(context, eid, key, value)

Set a float64 (double) parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (double) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

get

parameter_get_float64(context, eid, key)

Get a float64 (double) parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

double

Raises

ValueError – If getting the parameter fails.

32-bit floating point

set

parameter_set_float32(context, eid, key, value)

Set a float32 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (float) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

get

parameter_get_float32(context, eid, key)

Get a float32 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

float

Raises

ValueError – If getting the parameter fails.

64-bit signed integer

set

parameter_set_int64(context, eid, key, value)

Set an int64 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (int) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

get

parameter_get_int64(context, eid, key)

Get an int64 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

int

Raises

ValueError – If getting the parameter fails.

64-bit unsigned integer

set

parameter_set_uint64(context, eid, key, value)

Set a uint64 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (int) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

get

parameter_get_uint64(context, eid, key)

Get a uint64 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

int

Raises

ValueError – If getting the parameter fails.

32-bit signed integer

set

parameter_set_int32(context, eid, key, value)

Set an int32 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (int) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

get

parameter_get_int32(context, eid, key)

Get an int32 parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

int

Raises

ValueError – If getting the parameter fails.

parameter_set_str

parameter_set_str(context, eid, key, value)

Set a string parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (str) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

parameter_get_str

parameter_get_str(context, eid, key)

Get a string parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

str

Raises

ValueError – If getting the parameter fails.

parameter_set_handle

parameter_set_handle(context, eid, key, value)

Set a handle parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (gxf_uid_t) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

parameter_get_handle

parameter_get_handle(context, eid, key)

Get a handle parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

int

Raises

ValueError – If getting the parameter fails.

parameter_set_bool

parameter_set_bool(context, eid, key, value)

Set a boolean parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (bool) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

parameter_get_bool

parameter_get_bool(context, eid, key)

Get a boolean parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.

Returns

The value of the parameter.

Return type

bool

Raises

ValueError – If getting the parameter fails.

parameter_set_path

parameter_set_path(context, eid, key, value)

Set a string parameter.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
value (str) – The value to set for the parameter.

Raises

ValueError – If setting the parameter fails.

parameter_set_from_yaml_node

parameter_set_from_yaml_node(context, eid, key, input)

Set parameters using a YAML string.

Parameters

context (int) – The context in which the entity and parameter exist.
eid (int) – The unique identifier of the entity.
key (str) – The key of the parameter to set.
input (str) – The YAML string containing the parameter values.

Raises

ValueError – If setting the parameter fails.

Vector Parameters

To set/get the vector parameters of a component, users can use the following python-APIs for various data types:

Set 1-D Vetor Parameters

parameter_set_1d_<data_type>_vector(context, eid, key, value, length)

Parameters

context – A valid GXF context.
eid – A valid component identifier.
key – The name of the parameter
value – The value to set of the parameter. should be a list of the data to be set. The size of the stored array should match the length argument passed
length – The length of the vector parameter

Raises

ValueError – If setting the parameter fails.

See the table below for all the supported data types and their corresponding function signatures.

Supported Data Types to Set 1D Vector Parameters
Function Name	data_type
`parameter_set_1d_float64_vector(...)`	`double`
`parameter_set_1d_int64_vector(...)`	`int64_t`
`parameter_set_1d_uint64_vector(...)`	`uint64_t`
`parameter_set_1d_int32_vector(...)`	`int32_t`

Set 2-D Vetor Parameters

parameter_set_2d_<data_type>_vector(context, eid, key, value, height, width)

Parameters

context – A valid GXF context.
eid – A valid component identifier.
key – The name of the parameter
value – The value to set of the parameter. Should point to a list of list of the data to be set. The length of the first dimension of the list should match the height argument passed and similarly the length of the second dimension of the list should match the width passed.
height – The height of the 2-D vector parameter
width – The width of the 2-D vector parameter

Raises

ValueError – If setting the parameter fails.

See the table below for all the supported data types and their corresponding function signatures.

Supported Data Types to Set 2D Vector Parameters
Function Name	data_type
`parameter_set_2d_float64_vector(...)`	`double`
`parameter_set_2d_int64_vector(...)`	`int64_t`
`parameter_set_2d_uint64_vector(...)`	`uint64_t`
`parameter_set_2d_int32_vector(...)`	`int32_t`

Get 1-D Vetor Parameters

parameter_get_1d_<data_type>_vector(context, eid, key, length)

Parameters

context – A valid GXF context.
eid – A valid component identifier.
key – The name of the parameter
length – The length of the stored 1-D vector parameter. Should match the length of the parameter. If it is less than the parameter length then error is thrown. If it is greater than the length a larger list with the values set is retured.

Returns

A list containing the values.

See the table below for all the supported data types and their corresponding function signatures.

Supported Data Types to Get the Value of 1D Vector Parameters
Function Name	data_type
`parameter_get_1d_float64_vector(...)`	`double`
`parameter_get_1d_int64_vector(...)`	`int64_t`
`parameter_get_1d_uint64_vector(...)`	`uint64_t`
`parameter_get_1d_int32_vector(...)`	`int32_t`

Get 2-D Vetor Parameters

parameter_get_2d_'data_type'_vector(context, eid, key, height, width)

Parameters

context – A valid GXF context.
eid – A valid component identifier.
key – The name of the parameter
height – The height of the stored 2-D vector parameter.
width – The width of the stored 2-D vector parameter. The height or width should match the height and width of the stored vector. If they are smaller than the stored values then error is thrown. If greater than the stored values then larger lists will be returned with values set.

Returns

A list of list containing the values.

See the table below for all the supported data types and their corresponding function signatures.

Supported Data Types to Get the Value of 2D Vector Parameters
Function Name	data_type
`parameter_get_2d_float64_vector(...)`	`double`
`parameter_get_2d_int64_vector(...)`	`int64_t`
`parameter_get_2d_uint64_vector(...)`	`uint64_t`
`parameter_get_2d_int32_vector(...)`	`int32_t`