GXF Python APIs

Context

Create context

context_create()

Creates a new GXF context

A GXF context is required for all almost all GXF operations. The context must be destroyed with ‘GxfContextDestroy’. Multiple contexts can be created in the same process, however they can not communicate with each other.

returns: A unique interger representing context.

Destroy context

context_destroy(context)

Destroys a GXF context

Every GXF context must be destroyed by calling this function. The context must have been previously created with ‘GxfContextCreate’. This will also destroy all entities and components which were created as part of the context.

parameter: context A unique integer representing context

returns: None. Throws one of the GXF errors in not successful

Extensions

Maximum number of extensions in a context can be 1024.

Load Extensions from a file

load_extensions(context, extension_filenames, manifest_filenames, base_directory)

Loads extension in the given context from file.

parameter: context A valid GXF context

parameter: extension_filenames A list of valid filename.

parameter: manifest_filenames A list of valid filename.

parameter: base_directory Valid directory.

returns: None. Throws one of the GXF errors in not successful.

Graph

Loads a list of entities from YAML file

graph_load_file(context, filename)

parameter: context A valid GXF context

parameter: filename A valid YAML filename.

returns: None. Throws one of the GXF errors in not successful.

Activate all system components

graph_activate(context)

parameter: context A valid GXF context

returns: None. Throws one of the GXF errors in not successful.

Deactivate all System components

graph_deactivate(context)

parameter: context A valid GXF context

returns: None. Throws one of the GXF errors in not successful.

Starts the execution of the graph asynchronously

graph_run_async(context)

parameter: context A valid GXF context

returns: None. Throws one of the GXF errors in not successful.

Waits for the graph to complete execution

graph_wait(context)

parameter: context A valid GXF context

returns: None. Throws one of the GXF errors in not successful.

Runs all System components and waits for their completion

graph_run(context)

parameter: context A valid GXF context

returns: None. Throws one of the GXF errors in not successful.

Entities

Find an entity

entity_find(context, entity_name)

Finds an entity by its name

parameter: context A valid GXF context

parameter: entitiy_name A C string with the name of the entity. Ownership is not transferred.

returns: A unique entity identifier if successful else throws one of the GXF errors in not successful.

Get status of an entity

entity_get_status(context, eid)

Gets the status of the entity.

parameter: context A valid GXF context

parameter: eid The UID of a valid entity

returns: Returns entity status integer if successful else throws one of the GXF errors in not successful.

Components

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

Find a component in an entity

component_find(context, eid, tid, component_name)

Finds a component 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.

parameter: context A valid GXF context

parameter: eid The unique object ID (UID) of the entity which is searched.

parameter: tid The component type ID (TID) of the component to find (optional)

parameter: component_name The component name of the component to find (optional). Ownership not transferred.

returns: List of cids if successful else throws one of the GXF errors in not successful.

Primitive Parameters

64-bit floating point

Set

parameter_set_float64(context, eid, key, value)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value a double value

returns: None. Throws one of the GXF errors in not successful.

Get

parameter_get_float64(context, eid, key)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the GXF errors in not successful.

64-bit signed integer

Set

parameter_set_int64(context, eid, key, value)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value 64-bit integer value to set.

returns: None. Throws one of the GXF errors in not successful.

Get

parameter_get_int64(context, eid, key)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the GXF errors in not successful.

64-bit unsigned integer

Set

parameter_set_uint64(context, eid, key, value)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value unsigned 64-bit integet value to set.

returns: None. Throws one of the GXF errors in not successful.

Get

parameter_get_uint64(context, eid, key)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the GXF errors in not successful.

32-bit signed integer

Set

parameter_set_int32(context, eid, key, value)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value 32-bit integer value to set.

returns: None. Throws one of the GXF errors in not successful.

Get

parameter_get_int32(context, eid, key)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the GXF errors in not successful.

String parameter

Set

parameter_set_str(context, eid, key, value)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value A char array containing value to set.

returns: None. Throws one of the GXF errors in not successful.

Get

parameter_get_str(context, eid, key)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the GXF errors in not successful.

Boolean

Set

parameter_set_bool(context, eid, key, value)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value A boolean value to set.

returns: None. Throws one of the GXF errors in not successful.

Get

parameter_get_bool(context, eid, key)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the GXF errors in not successful.

Handle

Set

parameter_set_handle(context, eid, key, value)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value Unique identifier to set.

returns: None. Throws one of the GXF errors in not successful.

Get

parameter_get_handle(context, eid, key)

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the GXF errors in not successful.

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

Users can call parameter_set_1d_'data_type'_vector(context, eid, key, value, length)

value should be a list of the data to be set. The size of the stored array should match the length argument passed.

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

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: value The value to set of the parameter

parameter: length The length of the vector parameter

returns: None. Throws one of the GXF errors in not successful.

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

Users can call parameter_set_2d_'data_type'_vector(context, eid, key, value, height, width)

value 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.

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

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: value The value to set of the parameter

parameter: height The height of the 2-D vector parameter

parameter: width The width of the 2-D vector parameter

returns: None. Throws one of the GXF errors in not successful.

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

Users can call parameter_get_1d_'data_type'_vector(context, eid, key, length) to get the value of a 1-D vector.

If the length 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.

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

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: length The length of the stored 1-D vector parameter.

returns: A list containing the values.

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

Users can call parameter_get_2d_'data_type'_vector(context, eid, key, height, width) to get the value of a 2D vector.

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.

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

parameter: context A valid GXF context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: height The height of the stored 2-D vector parameter.

parameter: width The width of the stored 2-D vector parameter.

returns: A list of list containing the values.

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`