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`