GXF Core Python API

上下文

context_create

context_create()

创建 GXF 上下文。

返回:

已创建上下文的唯一标识符。

返回类型:

int

引发:

ValueError – 如果创建上下文失败。

context_destroy

context_destroy(context)

销毁 GXF 上下文。

参数:

context (int) – 要销毁的上下文的唯一标识符。

引发:

ValueError – 如果销毁上下文失败。

扩展

一个上下文中扩展的最大数量可以是 1024。

load_extensions

load_extensions(

context,

extension_filenames=[],

manifest_filenames=[],

base_directory='',

)

加载 GXF 扩展库。

参数:

• context (int) – 有效的 GXF 上下文。

• extension_filenames (list) – 有效文件名列表。

• manifest_filenames (list) – 有效文件名列表。

• base_directory (str) – 有效目录。

引发:

ValueError – 如果加载扩展失败。

get_extension_list

get_extension_list(context)

获取已加载扩展的列表。

参数:

context (int) – 从中检索扩展列表的上下文。

返回:

表示已加载扩展的 UUID 列表。

返回类型:

list

引发:

ValueError – 如果获取扩展列表失败。

get_extension_info

get_extension_info(context, uuid)

获取有关已加载扩展的信息。

参数:

• context (int) – 加载扩展的上下文。

• uuid (str) – 扩展的 UUID。

返回:

包含有关扩展信息的字典。

返回类型:

dict

引发:

ValueError – 如果获取扩展信息失败。

返回的字典具有以下键

• name (str): 扩展的名称。

• display_name (str): 扩展的显示名称。

• category (str): 扩展的类别。

• brief (str): 扩展的简要描述。

• description (str): 扩展的详细描述。

• version (str): 扩展的版本。

• author (str): 扩展的作者。

• license (str): 扩展的许可证。

图

graph_load_file

graph_load_file(context, filename)

从文件加载图。

参数:

• context (int) – 有效的 GXF 上下文。

• filename (str) – 有效的 YAML 文件名。

引发:

ValueError – 如果加载图文件失败。

set_root_filepath

set_root_filepath(context, filename)

设置图的根文件路径。

参数:

• context (int) – 要为其设置根文件路径的上下文。

• filename (str) – 根路径。

引发:

ValueError – 如果设置根文件路径失败。

_subgraph_load_file

_subgraph_load_file(

context,

filename,

entity_prefix,

parent_eid,

prerequisites,

)

从 YAML 文件加载实体列表。当使用以下项创建共享上下文时，将使用此 API

参数:

• context (int) – 有效的 GXF 上下文。

• filename (str) – 包含子图的文件的路径。

• entity_prefix (str) – 子图中实体的前缀。

• parent_eid (int) – 父实体的唯一标识符。

• prerequisites (str) – 字符串中的 GXF 子图先决条件 YAML 节点。

引发:

ValueError – 如果加载子图文件失败。

graph_activate

graph_activate(context)

激活图。

参数:

context (int) – 包含要激活的图的上下文。

引发:

ValueError – 如果激活图失败。

graph_run

graph_run(context)

运行图。它会阻塞调用者线程，直到图完成。

参数:

context (int) – 包含要运行的图的上下文。

引发:

ValueError – 如果运行图失败。

graph_run_async

graph_run_async(context)

异步运行图，即不阻塞调用者线程。

参数:

context (int) – 包含要异步运行的图的上下文。

引发:

ValueError – 如果异步运行图失败。

graph_interrupt

graph_interrupt(context)

中断图。

参数:

context (int) – 包含要中断的图的上下文。

引发:

ValueError – 如果中断图失败。

graph_wait

graph_wait(context)

等待图完成，即阻塞调用者线程，直到图完成。

参数:

context (int) – 包含要等待的图的上下文。

引发:

ValueError – 如果等待图失败。

graph_save

graph_save(context, filename)

将图保存到文件。

参数:

• context (int) – 包含要保存的图的上下文。

• filename (str) – 将在其中保存图的文件的路径。

引发:

ValueError – 如果保存图失败。

graph_deactivate

graph_deactivate(context)

停用图。

参数:

context (int) – 包含要停用的图的上下文。

引发:

ValueError – 如果停用图失败。

gxf_set_severity

gxf_set_severity(context, severity)

为 GXF_LOG_* 日志宏设置严重级别

参数:

• context (int) – 要为其设置日志记录严重性的上下文。

• severity (int) – 要设置的严重级别。 - 0: GXF_SEVERITY_NONE, - 1: GXF_SEVERITY_ERROR, - 2: GXF_SEVERITY_WARNING, - 3: GXF_SEVERITY_INFO, - 4: GXF_SEVERITY_DEBUG, - 5: GXF_SEVERITY_VERBOSE

引发:

ValueError – 如果设置日志记录严重性失败。

实体

gxf_entity_create_info

class gxf_entity_create_info

entity_name: str

实体的名称。

flags: int

系统实体为 1，非系统实体为 0

entity_create

entity_create(context, info)

使用信息创建实体

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• info (gxf_entity_create_info) – 实体创建信息。

返回:

唯一的实体标识符。

返回类型:

int

引发:

ValueError – 如果不成功。

entity_activate

entity_activate(context, eid)

激活实体

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

引发:

ValueError – 如果不成功。

entity_deactivate

entity_deactivate(context, eid)

停用实体

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

引发:

ValueError – 如果不成功。

entity_destroy

entity_destroy(context, eid)

销毁实体

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

引发:

ValueError – 如果不成功。

entity_find

entity_find(context, entity_name)

按名称查找实体

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• entity_name (str) – 带有实体名称的 C 字符串。所有权不转移。

返回:

唯一的实体标识符。

返回类型:

int

引发:

ValueError – 如果不成功。

entity_find_all

entity_find_all(context)

获取给定上下文的所有实体

参数:

context (int) – 表示 GXF 上下文的唯一整数。

返回:

上下文中实体的唯一标识符列表。

返回类型:

list

引发:

ValueError – 如果不成功。

entity_ref_count_inc

entity_ref_count_inc(context, eid)

增加实体的引用计数

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

引发:

ValueError – 如果不成功。

entity_ref_count_dec

entity_ref_count_dec(context, eid)

减少实体的引用计数

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

引发:

ValueError – 如果不成功。

entity_get_state

entity_get_state(context, eid)

获取实体的状态

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

返回:

实体的状态。

返回类型:

int

引发:

ValueError – 如果不成功。

返回的状态具有以下值

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

在事件时通知实体

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

引发:

ValueError – 如果不成功。

entity_notify_event_type

entity_notify_event_type(context, eid)

在事件时通知实体

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

引发:

ValueError – 如果不成功。

entity_get_status

entity_get_status(context, eid)

获取实体的状态

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• eid (int) – 有效实体的 UID。

返回:

实体的状态。

返回类型:

int

引发:

ValueError – 如果不成功。

返回的状态具有以下值

• 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

实体组

entity_group_create

entity_group_create(context, name)

使用名称创建实体组

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• name (str) – 实体组名称。

返回:

唯一的实体组标识符。

返回类型:

int

引发:

ValueError – 如果不成功。

entity_group_add

entity_group_add(context, gid, eid)

将实体添加到实体组

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• gid (int) – 有效实体组的 UID。

• eid (int) – 有效实体的 UID。

返回:

用于添加此实体的实体组 ID。

返回类型:

int

引发:

ValueError – 如果不成功。

组件

实体或扩展中的组件最大数量可以达到 1024。

gxf_tid_t

class gxf_tid_t

hash1: int

hash2: int

gxf_uid_t

class gxf_uid_t

类型:

int

get_component_list

get_component_list(context, uuid)

获取扩展的组件列表

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• uuid (str) – GXF 扩展 UUID。长度必须为 36，格式为 8-4-4-4-12。例如，85f64c84-8236-4035-9b9a-3843a6a2026f

返回:

组件类型 UUID 列表。

返回类型:

list

引发:

ValueError – 如果不成功。

get_component_info

get_component_info(context, uuid)

介绍

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• uuid (str) – GXF 组件类型 UUID。长度必须为 36，格式为 8-4-4-4-12。例如，85f64c84-8236-4035-9b9a-3843a6a2026f

返回:

包含有关组件信息的字典。

返回类型:

dict

引发:

ValueError – 如果不成功。

返回的字典具有以下键

• typename (str): 组件名称的完全限定 C++ 类型名称。

• display_name (str): 组件的显示名称。

• brief (str): 组件的简要描述。

• description (str): 组件的详细描述。

• base_typename (str): 基类的完全限定 C++ 类型名称，如果未继承，则为空字符串。

• is_abstract (bool): 组件是否为抽象组件。

get_param_list

get_param_list(context, uuid)

获取组件的参数列表

参数:

• context (int) – 表示 GXF 上下文的唯一整数。

• uuid (str) – GXF 组件类型 UUID。长度必须为 36，格式为 8-4-4-4-12。例如，85f64c84-8236-4035-9b9a-3843a6a2026f。

返回:

此组件的参数键列表。

返回类型:

list

引发:

ValueError – 如果不成功。

get_param_info

get_param_info(context, uuid, key)

获取组件参数的信息。

参数:

• context (int) – 组件存在的上下文。

• uuid (str) – GXF 组件类型 UUID。长度必须为 36，格式为 8-4-4-4-12。例如，85f64c84-8236-4035-9b9a-3843a6a2026f。

• key (str) – 参数的键。

返回:

包含参数信息的字典。

返回类型:

dict

引发:

ValueError – 如果不成功。

返回的字典具有以下键

• key (str): 参数的键。

• headline (str): 参数的标题或简短描述。

• description (str): 参数的详细描述。

• gxf_parameter_type (str): 参数的类型，以字符串形式表示。

• rank (int): 参数的秩或维度数。

• shape (list): 表示参数形状的列表。

• flags (str): 与参数关联的标志，以字符串形式表示。

• handle_type (str): handle 组件的完全限定 C++ 类型名称，如果不可应用，则为 “N/A”。

• default (varies): 参数的默认值，如果不可应用，则为 “N/A”。

• max_value (varies): 参数的最大值（如果适用）。

• min_value (varies): 参数的最小值（如果适用）。

• step_value (varies): 参数的步长值（如果适用）。

component_add

component_add(context, eid, tid, name)

向实体添加指定类型的组件。

参数:

• context (int) – 在其中创建组件的上下文。

• eid (int) – 包含组件的实体的唯一标识符。

• tid (gxf_tid_t) – 要创建的组件类型的类型标识符。

• name (str) – 组件的名称。

返回:

添加的组件的唯一标识符。

返回类型:

int

引发:

ValueError – 如果添加组件失败。

component_find

component_find(context, eid, tid, component_name)

在实体中查找特定类型的组件。

搜索实体中满足特定条件的组件：组件类型、组件名称和组件最小索引。所有三个条件都是可选的；如果未给出任何条件，则返回第一个组件。“组件最小索引”的主要用例是重复搜索，该搜索在先前搜索返回的索引处继续。

如果未找到符合给定条件的实体，则会抛出 GXF_ENTITY_NOT_FOUND。

参数:

• context (int) – 实体和组件存在的上下文。

• eid (int) – 实体的唯一标识符。

• tid (gxf_tid_t) – 要查找的组件的类型标识符。如果未提供，将搜索所有组件。

• component_name (str) – 要查找的组件的名称。如果未提供，将返回指定类型的所有组件。

返回:

找到的组件的唯一标识符列表。

返回类型:

list

引发:

ValueError – 如果查找组件失败。

component_type_id

component_type_id(context, component_name)

获取组件类型的类型标识符。

参数:

• context (int) – 组件类型存在的上下文。

• component_name (str) – 组件的完全限定 C++ 类型名称。

返回:

指定组件类型的类型标识符。

返回类型:

gxf_tid_t

引发:

ValueError – 如果获取类型标识符失败。

component_type_name

component_type_name(context, tid)

从类型标识符获取完全限定的 C++ 类型名称。

参数:

• context (int) – 组件类型存在的上下文。

• tid (gxf_tid_t) – 组件类型的类型标识符。

返回:

完全限定的 C++ 类型名称。

返回类型:

str

引发:

ValueError – 如果获取类型名称失败。

component_add_to_interface

component_add_to_interface(context, eid, cid, name)

将组件添加到别名映射

参数:

• context (int) – 实体和组件存在的上下文。

• eid (int) – 实体的唯一标识符。

• cid (int) – 要添加到接口的组件的唯一标识符。

• name (str) – 接口中组件的名称。

引发:

ValueError – 如果将组件添加到接口失败。

原始参数

64 位浮点数 (double)

设置

parameter_set_float64(context, eid, key, value)

设置 float64 (double) 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (double) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

获取

parameter_get_float64(context, eid, key)

获取 float64 (double) 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

double

引发:

ValueError – 如果获取参数失败。

32 位浮点数

设置

parameter_set_float32(context, eid, key, value)

设置 float32 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (float) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

获取

parameter_get_float32(context, eid, key)

获取 float32 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

float

引发:

ValueError – 如果获取参数失败。

64 位有符号整数

设置

parameter_set_int64(context, eid, key, value)

设置 int64 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (int) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

获取

parameter_get_int64(context, eid, key)

获取 int64 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

int

引发:

ValueError – 如果获取参数失败。

64 位无符号整数

设置

parameter_set_uint64(context, eid, key, value)

设置 uint64 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (int) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

获取

parameter_get_uint64(context, eid, key)

获取 uint64 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

int

引发:

ValueError – 如果获取参数失败。

32 位有符号整数

设置

parameter_set_int32(context, eid, key, value)

设置 int32 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (int) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

获取

parameter_get_int32(context, eid, key)

获取 int32 参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

int

引发:

ValueError – 如果获取参数失败。

parameter_set_str

parameter_set_str(context, eid, key, value)

设置字符串参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (str) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

parameter_get_str

parameter_get_str(context, eid, key)

获取字符串参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

str

引发:

ValueError – 如果获取参数失败。

parameter_set_handle

parameter_set_handle(context, eid, key, value)

设置句柄参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (gxf_uid_t) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

parameter_get_handle

parameter_get_handle(context, eid, key)

获取句柄参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

int

引发:

ValueError – 如果获取参数失败。

parameter_set_bool

parameter_set_bool(context, eid, key, value)

设置布尔参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (bool) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

parameter_get_bool

parameter_get_bool(context, eid, key)

获取布尔参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

返回:

参数的值。

返回类型:

bool

引发:

ValueError – 如果获取参数失败。

parameter_set_path

parameter_set_path(context, eid, key, value)

设置字符串参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• value (str) – 要为参数设置的值。

引发:

ValueError – 如果设置参数失败。

parameter_set_from_yaml_node

parameter_set_from_yaml_node(context, eid, key, input)

使用 YAML 字符串设置参数。

参数:

• context (int) – 实体和参数存在的上下文。

• eid (int) – 实体的唯一标识符。

• key (str) – 要设置的参数的键。

• input (str) – 包含参数值的 YAML 字符串。

引发:

ValueError – 如果设置参数失败。

向量参数

要设置/获取组件的向量参数，用户可以使用以下 python-API 用于各种数据类型

设置 1-D 向量参数

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

参数:

• context – 有效的 GXF 上下文。

• eid – 有效的组件标识符。

• key – 参数的名称

• value – 要设置的参数的值。应为要设置的数据列表。存储数组的大小应与传递的 length 参数匹配

• length – 向量参数的长度

引发:

ValueError – 如果设置参数失败。

请参阅下表，了解所有支持的数据类型及其对应的函数签名。

用于设置 1D 向量参数的支持数据类型

函数名称	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

设置 2-D 向量参数

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

参数:

• context – 有效的 GXF 上下文。

• eid – 有效的组件标识符。

• key – 参数的名称

• value – 要设置的参数的值。应指向要设置的数据列表的列表。列表第一维的长度应与传递的 height 参数匹配，类似地，列表第二维的长度应与传递的 width 匹配。

• height – 2-D 向量参数的高度

• width – 2-D 向量参数的宽度

引发:

ValueError – 如果设置参数失败。

请参阅下表，了解所有支持的数据类型及其对应的函数签名。

用于设置 2D 向量参数的支持数据类型

函数名称	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

获取 1-D 向量参数

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

参数:

• context – 有效的 GXF 上下文。

• eid – 有效的组件标识符。

• key – 参数的名称

• length – 存储的 1-D 向量参数的长度。应与参数的长度匹配。如果小于参数长度，则会抛出错误。如果大于长度，则返回包含设置值的较大列表。

返回:

包含值的列表。

请参阅下表，了解所有支持的数据类型及其对应的函数签名。

用于获取 1D 向量参数值的支持数据类型

函数名称	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

获取 2-D 向量参数

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

参数:

• context – 有效的 GXF 上下文。

• eid – 有效的组件标识符。

• key – 参数的名称

• height – 存储的 2-D 向量参数的高度。

• width – 存储的 2-D 向量参数的宽度。height 或 width 应与存储向量的高度和宽度匹配。如果它们小于存储的值，则会抛出错误。如果大于存储的值，则将返回包含设置值的较大列表。

返回:

包含值的列表的列表。

请参阅下表，了解所有支持的数据类型及其对应的函数签名。

用于获取 2D 向量参数值的支持数据类型

函数名称	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