File Writers

Genesis 提供文件写入器，用于将仿真数据导出到各种格式。

可用的 Writers

Writer	Format	Description
CSVFileWriter	.csv	表格数据导出
NPZFileWriter	.npz	NumPy 压缩数组
VideoFileWriter	.mp4	来自相机/视窗的视频

CSVFile

将数据导出为逗号分隔值：

import genesis as gs

gs.init()
scene = gs.Scene()
robot = scene.add_entity(gs.morphs.URDF(file="robot.urdf"))
scene.build()

# Record joint positions to CSV
scene.start_recording(
    data_func=lambda: {
        "q0": robot.get_qpos()[0],
        "q1": robot.get_qpos()[1],
        "q2": robot.get_qpos()[2],
    },
    rec_options=gs.recorders.CSVFile(
        filepath="joint_data.csv",
        hz=100,
    ),
)

for i in range(1000):
    scene.step()
scene.stop_recording()

NPZFile

将数据导出为 NumPy 压缩归档：

scene.start_recording(
    data_func=lambda: {
        "pos": robot.get_pos(),
        "qpos": robot.get_qpos(),
        "qvel": robot.get_qvel(),
    },
    rec_options=gs.recorders.NPZFile(
        filepath="trajectory.npz",
        hz=50,
    ),
)

# ... simulation ...
scene.stop_recording()

# Load recorded data
import numpy as np
data = np.load("trajectory.npz")
positions = data["pos"]

VideoFile

从相机或视窗录制视频：

cam = scene.add_camera(
    res=(1280, 720),
    pos=(3, 0, 2),
    lookat=(0, 0, 0.5),
)

scene.start_recording(
    data_func=lambda: cam.render(rgb=True),
    rec_options=gs.recorders.VideoFile(
        filepath="simulation.mp4",
    ),
)

for i in range(300):
    scene.step()
scene.stop_recording()

配置选项

通用选项

Option	Type	Default	Description
filepath	str	Required	输出文件路径
hz	float	None	录制频率
async_mode	bool	False	后台处理

VideoFileWriter 选项

Option	Type	Default	Description
fps	int	30	视频帧率
codec	str	“libx264”	视频编解码器

API 参考

class genesis.recorders.file_writers.BaseFileWriter(manager: RecorderManager, options: RecorderOptions, data_func: Callable[[], T])

Bases: Recorder

Base class for file writers.

Handles filename counter when save_on_reset is True.

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

reset(envs_idx=None)

Reset the recorder, e.g. by flushing stored data.

This method is called when the scene is reset by scene.reset().

Parameters:

envs_idx (array_like, optional) – The indices of the environments to reset. If None, all environments are reset.

class genesis.recorders.file_writers.VideoFileWriter(manager: RecorderManager, options: RecorderOptions, data_func: Callable[[], T])

Bases: BaseFileWriter

video_container: av.container.OutputContainer | None

video_stream: av.video.stream.VideoStream | None

video_frame: av.video.frame.VideoFrame | None

video_buffer: np.ndarray | None

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

process(data, cur_time)

Process each incoming data sample.

Parameters:

• data (Any) – The data to be processed.

• cur_time (float) – The current time of the simulation.

cleanup()

Cleanup all resources, e.g. by closing widgets or files.

This method is called when recording is stopped by scene.stop_recording().

property run_in_thread: bool

Whether to run the recorder in a background thread.

Running in a background thread allows for processing data without blocking the main thread, so this is encouraged for most recorders (simply return True), but implementers should check that the recorder is thread-safe on all devices (threading on macOS tends to be less supported).

class genesis.recorders.file_writers.CSVFileWriter(manager: RecorderManager, options: RecorderOptions, data_func: Callable[[], T])

Bases: BaseFileWriter

process(data, cur_time)

Process each incoming data sample.

Parameters:

• data (Any) – The data to be processed.

• cur_time (float) – The current time of the simulation.

cleanup()

Cleanup all resources, e.g. by closing widgets or files.

This method is called when recording is stopped by scene.stop_recording().

property run_in_thread: bool

Whether to run the recorder in a background thread.

Running in a background thread allows for processing data without blocking the main thread, so this is encouraged for most recorders (simply return True), but implementers should check that the recorder is thread-safe on all devices (threading on macOS tends to be less supported).

class genesis.recorders.file_writers.NPZFileWriter(manager: RecorderManager, options: RecorderOptions, data_func: Callable[[], T])

Bases: BaseFileWriter

build()

Build the recorder, e.g. by initializing variables and creating widgets or file handles.

process(data, cur_time)

Process each incoming data sample.

Parameters:

• data (Any) – The data to be processed.

• cur_time (float) – The current time of the simulation.

cleanup()

Cleanup all resources, e.g. by closing widgets or files.

This method is called when recording is stopped by scene.stop_recording().

property run_in_thread: bool

Whether to run the recorder in a background thread.

Running in a background thread allows for processing data without blocking the main thread, so this is encouraged for most recorders (simply return True), but implementers should check that the recorder is thread-safe on all devices (threading on macOS tends to be less supported).

另请参阅

• 记录与回放 - 录制概述

• Plotters - 实时可视化