Skip to content

🏷️ 图像获取能力

tongsim.entity.ability.impl.camera

CameraAbility

Bases: Protocol

相机能力接口定义，包括: - 相机挂载 - 内参配置 - 图像数据采集（当前帧、历史帧、流） - 可见物体检测结果访问等。

Source code in src\tongsim\entity\ability\impl\camera.py 
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
class CameraAbility(Protocol):
    """
    相机能力接口定义，包括:
    - 相机挂载
    - 内参配置
    - 图像数据采集（当前帧、历史帧、流）
    - 可见物体检测结果访问等。
    """

    def attach_to_target_socket(self, target_id: str, socket_name: str) -> bool:
        """
        将当前相机挂载到目标 Entity 的指定 socket 上。

        Args:
            target_id (str): 目标实体 ID
            socket_name (str): 目标 socket 名称。常用socket:["MidCameraSocket","LeftCameraSocket","RightCameraSocket"]

        Returns:
            bool: 是否成功挂载。
        """

    def set_intrinsic_params(self, fov: float, width: int, height: int) -> bool:
        """
        设置相机的内参，包括视场角、分辨率等。

        Args:
            fov (float): 相机的视场角（Field of View）。
            width (int): 图像宽度（单位: 像素）。
            height (int): 图像高度（单位: 像素）。

        Returns:
            bool: 是否设置成功。
        """

    def get_intrinsic_params(self) -> CameraIntrinsic:
        """
        获取当前相机的内参配置。

        Returns:
            CameraIntrinsic: 包含 fov、width 和 height 的内参信息。
        """

    def start_imagedata_streaming(
        self,
        rgb: bool = True,
        depth: bool = False,
        segmentation: bool = False,
        mirror_segmentation: bool = False,
        visible_object_list: bool = False,
    ) -> None:
        """
        启动图像数据流接收任务。

        启动后，将持续接收来自服务器的图像帧数据，并缓存最近一帧。

        Args:
            rgb (bool): 是否接收 RGB 图像数据。
            depth (bool): 是否接收深度图像。
            segmentation (bool): 是否接收分割图像。
            mirror_segmentation (bool): 是否接收镜子中的分割图像。
            visible_object_list (bool): 是否接收可见物体列表。
        """

    def stop_imagedata_streaming(self) -> bool:
        """
        停止图像数据流接收任务（暂未实现）。

        Returns:
            bool: 停止是否成功。
        """

    def fetch_image_data_from_streaming(self) -> CameraImageWrapper | None:
        """
        从图像数据流中获取最近一帧的完整图像数据封装。

        返回:
            CameraImageWrapper | None: 图像数据封装对象，包含 RGB、深度、分割、可见物体信息等；
                                    若当前尚未接收到任何图像帧，则返回 None。
        """

    def fetch_rgb_from_streaming(
        self, deep_copy: bool = False
    ) -> memoryview | bytes | None:
        """
        从图像数据流中获取最近接收到的 RGB 图像帧。

        Args:
            deep_copy (bool): 是否返回深拷贝副本。

        Returns:
            memoryview | bytes | None: RGB 图像数据（如果存在）。
        """

    def fetch_depth_from_streaming(
        self, deep_copy: bool = False
    ) -> memoryview | bytes | None:
        """
        从图像数据流中获取最近接收到的深度图像帧。

        Args:
            deep_copy (bool): 是否返回深拷贝副本。

        Returns:
            memoryview | bytes | None: 深度图像数据（如果存在）。
        """

    def fetch_segmentation_from_streaming(
        self, deep_copy: bool = False
    ) -> memoryview | bytes | None:
        """
        从图像数据流中获取最近接收到的分割图像帧。

        Args:
            deep_copy (bool): 是否返回深拷贝副本。

        Returns:
            memoryview | bytes | None: 分割图像数据（如果存在）。
        """

    def fetch_mirror_segmentation_from_streaming(
        self, deep_copy: bool = False
    ) -> memoryview | bytes | None:
        """
        从图像数据流中获取最近接收到的镜子中的分割图像帧。

        Args:
            deep_copy (bool): 是否返回深拷贝副本。

        Returns:
            memoryview | bytes | None: 镜子中的分割图像数据（如果存在）。
        """

    def fetch_visible_object_list_from_streaming(
        self,
    ) -> list[VisibleObjectInfo] | None:
        """
        从图像数据流中获取最近一帧图像数据中检测到的可见物体信息列表。

        Returns:
            list[VisibleObjectInfo] | None: 可见物体信息列表，若尚未接收或未启用则为 None。
        """

    def get_current_imageshot(
        self,
        rgb: bool = True,
        depth: bool = False,
        segmentation: bool = False,
        mirror_segmentation: bool = False,
        visible_object_list: bool = False,
    ) -> CameraImageWrapper | None:
        """
        以同步方式请求当前图像帧（一次性抓拍）。

        Args:
            rgb (bool): 是否获取 RGB 图像。
            depth (bool): 是否获取深度图像。
            segmentation (bool): 是否获取语义分割图像。
            mirror_segmentation (bool): 是否获取镜像分割图像。
            visible_object_list (bool): 是否包含可见物体列表。

        Returns:
            CameraImageWrapper | None: 包含图像内容的封装对象，若失败则为 None。
        """

    async def async_get_current_imageshot(
        self,
        rgb: bool = True,
        depth: bool = False,
        segmentation: bool = False,
        mirror_segmentation: bool = False,
        visible_object_list: bool = False,
    ) -> CameraImageWrapper | None:
        """
        以异步方式请求当前图像帧（一次性抓拍）。

        Args:
            rgb (bool): 是否获取 RGB 图像。
            depth (bool): 是否获取深度图像。
            segmentation (bool): 是否获取语义分割图像。
            mirror_segmentation (bool): 是否获取镜像分割图像。
            visible_object_list (bool): 是否包含可见物体列表。

        Returns:
            CameraImageWrapper | None: 包含图像内容的封装对象，若失败则为 None。
        """

    async def async_subscribe_imagedata(
        self,
        rgb: bool = True,
        depth: bool = False,
        segmentation: bool = False,
        mirror_segmentation: bool = False,
        visible_object_list: bool = False,
    ) -> AsyncIterator[CameraImageWrapper]:
        """
        异步订阅图像数据流，返回一个异步迭代器，逐帧返回图像。

        Args:
            rgb (bool): 是否订阅 RGB 图像。
            depth (bool): 是否订阅深度图像。
            segmentation (bool): 是否订阅语义分割图像。
            mirror_segmentation (bool): 是否订阅镜像分割图像。
            visible_object_list (bool): 是否订阅可见物体列表。

        Returns:
            AsyncIterator[CameraImageWrapper]: 图像帧异步迭代器。
        """

attach_to_target_socket 

attach_to_target_socket(
    target_id: str, socket_name: str
) -> bool

将当前相机挂载到目标 Entity 的指定 socket 上。

Parameters:

Name Type Description Default
target_id str

目标实体 ID

 required
socket_name str

目标 socket 名称。常用socket:["MidCameraSocket","LeftCameraSocket","RightCameraSocket"]

 required

Returns:

Name Type Description
bool bool

是否成功挂载。
Source code in src\tongsim\entity\ability\impl\camera.py 
30
31
32
33
34
35
36
37
38
39
40
def attach_to_target_socket(self, target_id: str, socket_name: str) -> bool:
    """
    将当前相机挂载到目标 Entity 的指定 socket 上。

    Args:
        target_id (str): 目标实体 ID
        socket_name (str): 目标 socket 名称。常用socket:["MidCameraSocket","LeftCameraSocket","RightCameraSocket"]

    Returns:
        bool: 是否成功挂载。
    """

set_intrinsic_params 

set_intrinsic_params(
    fov: float, width: int, height: int
) -> bool

设置相机的内参，包括视场角、分辨率等。

Parameters:

Name Type Description Default
fov float

相机的视场角（Field of View）。

 required
width int

图像宽度（单位: 像素）。

 required
height int

图像高度（单位: 像素）。

 required

Returns:

Name Type Description
bool bool

是否设置成功。
Source code in src\tongsim\entity\ability\impl\camera.py 
42
43
44
45
46
47
48
49
50
51
52
53
def set_intrinsic_params(self, fov: float, width: int, height: int) -> bool:
    """
    设置相机的内参，包括视场角、分辨率等。

    Args:
        fov (float): 相机的视场角（Field of View）。
        width (int): 图像宽度（单位: 像素）。
        height (int): 图像高度（单位: 像素）。

    Returns:
        bool: 是否设置成功。
    """

get_intrinsic_params 

get_intrinsic_params() -> CameraIntrinsic

获取当前相机的内参配置。

Returns:

Name Type Description
CameraIntrinsic CameraIntrinsic

包含 fov、width 和 height 的内参信息。
Source code in src\tongsim\entity\ability\impl\camera.py 
55
56
57
58
59
60
61
def get_intrinsic_params(self) -> CameraIntrinsic:
    """
    获取当前相机的内参配置。

    Returns:
        CameraIntrinsic: 包含 fov、width 和 height 的内参信息。
    """

start_imagedata_streaming 

start_imagedata_streaming(
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> None

启动图像数据流接收任务。

启动后，将持续接收来自服务器的图像帧数据，并缓存最近一帧。

Parameters:

Name Type Description Default
rgb bool

是否接收 RGB 图像数据。

 True
depth bool

是否接收深度图像。

 False
segmentation bool

是否接收分割图像。

 False
mirror_segmentation bool

是否接收镜子中的分割图像。

 False
visible_object_list bool

是否接收可见物体列表。

 False
Source code in src\tongsim\entity\ability\impl\camera.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def start_imagedata_streaming(
    self,
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> None:
    """
    启动图像数据流接收任务。

    启动后，将持续接收来自服务器的图像帧数据，并缓存最近一帧。

    Args:
        rgb (bool): 是否接收 RGB 图像数据。
        depth (bool): 是否接收深度图像。
        segmentation (bool): 是否接收分割图像。
        mirror_segmentation (bool): 是否接收镜子中的分割图像。
        visible_object_list (bool): 是否接收可见物体列表。
    """

stop_imagedata_streaming 

stop_imagedata_streaming() -> bool

停止图像数据流接收任务（暂未实现）。

Returns:

Name Type Description
bool bool

停止是否成功。
Source code in src\tongsim\entity\ability\impl\camera.py 
84
85
86
87
88
89
90
def stop_imagedata_streaming(self) -> bool:
    """
    停止图像数据流接收任务（暂未实现）。

    Returns:
        bool: 停止是否成功。
    """

fetch_image_data_from_streaming 

fetch_image_data_from_streaming() -> (
    CameraImageWrapper | None
)

从图像数据流中获取最近一帧的完整图像数据封装。

返回

CameraImageWrapper | None: 图像数据封装对象，包含 RGB、深度、分割、可见物体信息等； 若当前尚未接收到任何图像帧，则返回 None。

Source code in src\tongsim\entity\ability\impl\camera.py 
92
93
94
95
96
97
98
99
def fetch_image_data_from_streaming(self) -> CameraImageWrapper | None:
    """
    从图像数据流中获取最近一帧的完整图像数据封装。

    返回:
        CameraImageWrapper | None: 图像数据封装对象，包含 RGB、深度、分割、可见物体信息等；
                                若当前尚未接收到任何图像帧，则返回 None。
    """

fetch_rgb_from_streaming 

fetch_rgb_from_streaming(
    deep_copy: bool = False,
) -> memoryview | bytes | None

从图像数据流中获取最近接收到的 RGB 图像帧。

Parameters:

Name Type Description Default
deep_copy bool

是否返回深拷贝副本。

 False

Returns:

Type Description
memoryview | bytes | None

memoryview | bytes | None: RGB 图像数据（如果存在）。
Source code in src\tongsim\entity\ability\impl\camera.py 
101
102
103
104
105
106
107
108
109
110
111
112
def fetch_rgb_from_streaming(
    self, deep_copy: bool = False
) -> memoryview | bytes | None:
    """
    从图像数据流中获取最近接收到的 RGB 图像帧。

    Args:
        deep_copy (bool): 是否返回深拷贝副本。

    Returns:
        memoryview | bytes | None: RGB 图像数据（如果存在）。
    """

fetch_depth_from_streaming 

fetch_depth_from_streaming(
    deep_copy: bool = False,
) -> memoryview | bytes | None

从图像数据流中获取最近接收到的深度图像帧。

Parameters:

Name Type Description Default
deep_copy bool

是否返回深拷贝副本。

 False

Returns:

Type Description
memoryview | bytes | None

memoryview | bytes | None: 深度图像数据（如果存在）。
Source code in src\tongsim\entity\ability\impl\camera.py 
114
115
116
117
118
119
120
121
122
123
124
125
def fetch_depth_from_streaming(
    self, deep_copy: bool = False
) -> memoryview | bytes | None:
    """
    从图像数据流中获取最近接收到的深度图像帧。

    Args:
        deep_copy (bool): 是否返回深拷贝副本。

    Returns:
        memoryview | bytes | None: 深度图像数据（如果存在）。
    """

fetch_segmentation_from_streaming 

fetch_segmentation_from_streaming(
    deep_copy: bool = False,
) -> memoryview | bytes | None

从图像数据流中获取最近接收到的分割图像帧。

Parameters:

Name Type Description Default
deep_copy bool

是否返回深拷贝副本。

 False

Returns:

Type Description
memoryview | bytes | None

memoryview | bytes | None: 分割图像数据（如果存在）。
Source code in src\tongsim\entity\ability\impl\camera.py 
127
128
129
130
131
132
133
134
135
136
137
138
def fetch_segmentation_from_streaming(
    self, deep_copy: bool = False
) -> memoryview | bytes | None:
    """
    从图像数据流中获取最近接收到的分割图像帧。

    Args:
        deep_copy (bool): 是否返回深拷贝副本。

    Returns:
        memoryview | bytes | None: 分割图像数据（如果存在）。
    """

fetch_mirror_segmentation_from_streaming 

fetch_mirror_segmentation_from_streaming(
    deep_copy: bool = False,
) -> memoryview | bytes | None

从图像数据流中获取最近接收到的镜子中的分割图像帧。

Parameters:

Name Type Description Default
deep_copy bool

是否返回深拷贝副本。

 False

Returns:

Type Description
memoryview | bytes | None

memoryview | bytes | None: 镜子中的分割图像数据（如果存在）。
Source code in src\tongsim\entity\ability\impl\camera.py 
140
141
142
143
144
145
146
147
148
149
150
151
def fetch_mirror_segmentation_from_streaming(
    self, deep_copy: bool = False
) -> memoryview | bytes | None:
    """
    从图像数据流中获取最近接收到的镜子中的分割图像帧。

    Args:
        deep_copy (bool): 是否返回深拷贝副本。

    Returns:
        memoryview | bytes | None: 镜子中的分割图像数据（如果存在）。
    """

fetch_visible_object_list_from_streaming 

fetch_visible_object_list_from_streaming() -> (
    list[VisibleObjectInfo] | None
)

从图像数据流中获取最近一帧图像数据中检测到的可见物体信息列表。

Returns:

Type Description
list[VisibleObjectInfo] | None

list[VisibleObjectInfo] | None: 可见物体信息列表，若尚未接收或未启用则为 None。
Source code in src\tongsim\entity\ability\impl\camera.py 
153
154
155
156
157
158
159
160
161
def fetch_visible_object_list_from_streaming(
    self,
) -> list[VisibleObjectInfo] | None:
    """
    从图像数据流中获取最近一帧图像数据中检测到的可见物体信息列表。

    Returns:
        list[VisibleObjectInfo] | None: 可见物体信息列表，若尚未接收或未启用则为 None。
    """

get_current_imageshot 

get_current_imageshot(
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> CameraImageWrapper | None

以同步方式请求当前图像帧（一次性抓拍）。

Parameters:

Name Type Description Default
rgb bool

是否获取 RGB 图像。

 True
depth bool

是否获取深度图像。

 False
segmentation bool

是否获取语义分割图像。

 False
mirror_segmentation bool

是否获取镜像分割图像。

 False
visible_object_list bool

是否包含可见物体列表。

 False

Returns:

Type Description
CameraImageWrapper | None

CameraImageWrapper | None: 包含图像内容的封装对象，若失败则为 None。
Source code in src\tongsim\entity\ability\impl\camera.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def get_current_imageshot(
    self,
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> CameraImageWrapper | None:
    """
    以同步方式请求当前图像帧（一次性抓拍）。

    Args:
        rgb (bool): 是否获取 RGB 图像。
        depth (bool): 是否获取深度图像。
        segmentation (bool): 是否获取语义分割图像。
        mirror_segmentation (bool): 是否获取镜像分割图像。
        visible_object_list (bool): 是否包含可见物体列表。

    Returns:
        CameraImageWrapper | None: 包含图像内容的封装对象，若失败则为 None。
    """

async_get_current_imageshot async 

async_get_current_imageshot(
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> CameraImageWrapper | None

以异步方式请求当前图像帧（一次性抓拍）。

Parameters:

Name Type Description Default
rgb bool

是否获取 RGB 图像。

 True
depth bool

是否获取深度图像。

 False
segmentation bool

是否获取语义分割图像。

 False
mirror_segmentation bool

是否获取镜像分割图像。

 False
visible_object_list bool

是否包含可见物体列表。

 False

Returns:

Type Description
CameraImageWrapper | None

CameraImageWrapper | None: 包含图像内容的封装对象，若失败则为 None。
Source code in src\tongsim\entity\ability\impl\camera.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
async def async_get_current_imageshot(
    self,
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> CameraImageWrapper | None:
    """
    以异步方式请求当前图像帧（一次性抓拍）。

    Args:
        rgb (bool): 是否获取 RGB 图像。
        depth (bool): 是否获取深度图像。
        segmentation (bool): 是否获取语义分割图像。
        mirror_segmentation (bool): 是否获取镜像分割图像。
        visible_object_list (bool): 是否包含可见物体列表。

    Returns:
        CameraImageWrapper | None: 包含图像内容的封装对象，若失败则为 None。
    """

async_subscribe_imagedata async 

async_subscribe_imagedata(
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> AsyncIterator[CameraImageWrapper]

异步订阅图像数据流，返回一个异步迭代器，逐帧返回图像。

Parameters:

Name Type Description Default
rgb bool

是否订阅 RGB 图像。

 True
depth bool

是否订阅深度图像。

 False
segmentation bool

是否订阅语义分割图像。

 False
mirror_segmentation bool

是否订阅镜像分割图像。

 False
visible_object_list bool

是否订阅可见物体列表。

 False

Returns:

Type Description
AsyncIterator[CameraImageWrapper]

AsyncIterator[CameraImageWrapper]: 图像帧异步迭代器。
Source code in src\tongsim\entity\ability\impl\camera.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
async def async_subscribe_imagedata(
    self,
    rgb: bool = True,
    depth: bool = False,
    segmentation: bool = False,
    mirror_segmentation: bool = False,
    visible_object_list: bool = False,
) -> AsyncIterator[CameraImageWrapper]:
    """
    异步订阅图像数据流，返回一个异步迭代器，逐帧返回图像。

    Args:
        rgb (bool): 是否订阅 RGB 图像。
        depth (bool): 是否订阅深度图像。
        segmentation (bool): 是否订阅语义分割图像。
        mirror_segmentation (bool): 是否订阅镜像分割图像。
        visible_object_list (bool): 是否订阅可见物体列表。

    Returns:
        AsyncIterator[CameraImageWrapper]: 图像帧异步迭代器。
    """