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#
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#
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:
- 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 passedlength – 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.
Function Name |
data_type |
---|---|
|
|
|
|
|
|
|
|
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 thewidth
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.
Function Name |
data_type |
---|---|
|
|
|
|
|
|
|
|
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.
Function Name |
data_type |
---|---|
|
|
|
|
|
|
|
|
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
orwidth
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.
Function Name |
data_type |
---|---|
|
|
|
|
|
|
|
|