Scene#

The Scene is the top-level container for a simulation: add entities to it, build it, then step it. It is assembled from a bundle of options passed to gs.Scene(...), each documented with the component it configures: sim_options (the Simulator), the per-solver options (with each solver), coupler_options (the coupler), viewer_options and vis_options (the viewer), renderer (the renderer), and profiling_options below. Every option a scene is created with is held as one SceneOptions object, reachable as scene.options and documented below. For a worked example, see Hello, Genesis World.

Bases: RBC

A genesis.Scene object wraps all components in a simulation environment, including a simulator (containing multiple physics solvers), entities, and a visualizer (controlling both the viewer and all the cameras). Basically, everything happens inside a scene.

Parameters:

sim_options (gs.options.SimOptions) – The options configuring the overarching simulator, which in turn manages all the solvers.
tool_options (gs.options.ToolOptions) – The options configuring the tool_solver (scene.sim.ToolSolver).
rigid_options (gs.options.RigidOptions) – The options configuring the rigid_solver (scene.sim.RigidSolver).
mpm_options (gs.options.MPMOptions) – The options configuring the mpm_solver (scene.sim.MPMSolver).
sph_options (gs.options.SPHOptions) – The options configuring the sph_solver (scene.sim.SPHSolver).
fem_options (gs.options.FEMOptions) – The options configuring the fem_solver (scene.sim.FEMSolver).
sf_options (gs.options.SFOptions) – The options configuring the sf_solver (scene.sim.SFSolver).
pbd_options (gs.options.PBDOptions) – The options configuring the pbd_solver (scene.sim.PBDSolver).
coupler_options (gs.options.CouplerOptions) – The options configuring the coupler between different solvers.
vis_options (gs.options.VisOptions) – The options configuring the visualization system (scene.visualizer). Visualizer controls both the interactive viewer and the cameras.
viewer_options (gs.options.ViewerOptions) – The options configuring the viewer (scene.visualizer.viewer).
renderer (gs.renderers.RendererOptions) – The renderer options used by camera for rendering images. This doesn’t affect the behavior of the interactive viewer.
show_viewer (bool) – Whether to show the interactive viewer. Set it to False if you only need headless rendering.
show_FPS (bool) – Whether to show the FPS in the terminal.
options (SceneOptions) – Every option above as one object, which is how a scene holds them. It is given alone, and passing another scene’s options here creates a scene from what that scene was created with.

destroy()[source]#

add_entity(morph: Morph | Iterable[Morph], material: None = None, surface: Surface | None = None, visualize_contact: bool = False, vis_mode: str | None = None, name: str | None = None) → RigidEntity[source]#

add_entity(morph: Morph | Iterable[Morph], material: Material[EntityT] = None, surface: Surface | None = None, visualize_contact: bool = False, vis_mode: str | None = None, name: str | None = None) → EntityT

Add an entity to the scene.

Parameters:

morph (gs.morphs.Morph | list[gs.morphs.Morph]) – The morph of the entity. If a list of morphs is provided, the entity will be heterogeneous (rigid only, single-link entities only). Each parallel environment will simulate a different geometry variant from the list.
material (gs.materials.Material | None, optional) – The material of the entity. If None, use gs.materials.Rigid().
surface (gs.surfaces.Surface | None, optional) – The surface of the entity. If None, use gs.surfaces.Default().
visualize_contact (bool) – Whether to visualize contact forces applied to this entity as arrows in the viewer and rendered images. Note that this will not be displayed in images rendered by camera using the RayTracer renderer.
vis_mode (str | None, optional) – The visualization mode of the entity. This is a handy shortcut for setting surface.vis_mode without explicitly creating a surface object.
name (str | None, optional) – User-specified name for the entity. If not provided, an auto-generated name will be assigned based on the morph type and entity UID (e.g., “box_a1b2c3d4”). Must be unique within the scene.

Returns:

entity – The created entity.

Return type:

genesis.Entity

add_stage(morph: USD, material: Material | None = None, surface: Surface | None = None, visualize_contact: bool = False, vis_mode: Literal['visual', 'collision'] = 'visual')[source]#

Add a stage to the scene.

Parameters:

morph (gs.morphs.USD) – The stage to add to the scene.
material (gs.materials.Material | None, optional) – The material of the stage. If None, use gs.materials.Rigid() for all morphs.
surface (gs.surfaces.Surface | None, optional) – The surface of the stage. If None, use gs.surfaces.Default() for all morphs.
visualize_contact (bool) – Whether to visualize contact forces applied to this stage as arrows in the viewer and rendered images. Note that this will not be displayed in images rendered by camera using the RayTracer renderer.
vis_mode (str | None, optional) – The visualization mode of the stage. This is a handy shortcut for setting surface.vis_mode without explicitly creating a surface object.

Returns:

entities – The created entities.

Return type:

List[genesis.Entity]

Add a mesh light to the scene. Only supported by RayTracer.

Parameters:

morph (gs.morphs.Morph) – The morph of the light. Must be an instance of gs.morphs.Primitive or gs.morphs.Mesh.
color (tuple of float, shape (3,)) – The color of the light, specified as (r, g, b).
intensity (float) – The intensity of the light.
revert_dir (bool) – Whether to revert the direction of the light. If True, the light will be emitted towards the mesh’s inside.
double_sided (bool) – Whether to emit light from both sides of surface.
cutoff (float) – The cutoff angle of the light in degrees. Range: [0.0, 180.0].

add_light(pos: ArrayLike | None, dir: ArrayLike | None, color: ArrayLike | None = (1.0, 1.0, 1.0), intensity: float = 1.0, directional: bool = False, castshadow: bool = True, cutoff: float = 45.0, attenuation: float = 0.0)[source]#

Add a light to the scene for batch renderer.

Parameters:

pos (tuple of float, shape (3,)) – The position of the light, specified as (x, y, z).
dir (tuple of float, shape (3,)) – The direction of the light, specified as (x, y, z).
color (tuple of float, shape (3,)) – The color of the light, specified as (r, g, b).
intensity (float) – The intensity of the light.
directional (bool) – Whether the light is directional.
castshadow (bool) – Whether the light casts shadows.
cutoff (float) – The cutoff angle of the light in degrees. Range: (0.0, 90.0).
attenuation (float) – The attenuation factor of the light. Light intensity will attenuate by distance with (1 / (1 + attenuation * distance ^ 2))

add_sensor(sensor_options: SensorOptions[SensorT]) → SensorT[source]#

Add a sensor to the scene.

Sensors extract information from the scene without modifying the physics simulation.

Parameters:: sensor_options (SensorOptions) – The options for the sensor.

read_sensors(envs_idx=None) → dict[type[Sensor], torch.Tensor][source]#

Read every sensor in the scene as a tensor per sensor class.

Always returns a fresh tensor independent of the internal sensor storage; the caller is free to mutate the result.

Parameters:: envs_idx (array-like | int | slice | None) – Environment selection. Defaults to all environments.
Returns:: For each sensor class present in the scene, a tensor of shape (B, [history,] class_cache_size).
Return type:: dict[Type[Sensor], torch.Tensor]

add_recorder(data_func: Callable, rec_options: RecorderOptions) → Recorder[source]#

Automatically read and process data. See RecorderOptions for more details.

Data from data_func is automatically read and processed using the recorder at the frequency rec_options.hz (or every step if not specified) as the scene is stepped. Recording starts with the build and every recorder stops with ‘stop_recording’.

Parameters:

data_func (Callable) – A function with no arguments that returns the data to be recorded.
rec_options (RecorderOptions) – The options for the recording.

Returns:

recorder – The created recorder object.

Return type:

Recorder

start_recording(rec_options: TrajectoryFile) → Recorder[source]#

Record the state of the scene at every step to a trajectory file, which ‘load_trajectory’ opens to seek and replay.

Recording starts with the build and stops with ‘stop_recording’. See ‘TrajectoryFile’ for what a frame holds and how the file is written.

Parameters:: rec_options (TrajectoryFile) – The file to write and the mode to record in.
Returns:: recorder – The created recorder object.
Return type:: Recorder

add_camera(model='pinhole', res=(320, 320), pos=(0.5, 2.5, 3.5), lookat=(0.5, 0.5, 0.5), up=(0.0, 0.0, 1.0), fov=30, aperture=2.0, focus_dist=None, GUI=False, spp=256, denoise=None, near=0.1, far=20.0, env_idx=None, debug=False)[source]#

Add a camera to the scene.

The camera model can be either ‘pinhole’, ‘thinlens’ or ‘fisheye’: - The ‘pinhole’ model is a simple camera model that captures light rays from a single point in space. - The ‘thinlens’ model is a more complex camera model that simulates a lens with a finite aperture size,

allowing for depth of field effects. It is only supported by the Raytracer.

The ‘fisheye’ model is a camera model that simulates a fisheye lens, allowing for wide-angle views. It is only supported by the BatchRenderer.

Warning

When ‘pinhole’ is used, the aperture and focal_len parameters are ignored.

Parameters:

model (str) – Specifies the camera model. Options are ‘pinhole’ or ‘thinlens’.
res (tuple of int, shape (2,)) – The resolution of the camera, specified as a tuple (width, height).
pos (tuple of float, shape (3,)) – The position of the camera in the scene, specified as (x, y, z).
lookat (tuple of float, shape (3,)) – The point in the scene that the camera is looking at, specified as (x, y, z).
up (tuple of float, shape (3,)) – The up vector of the camera, defining its orientation, specified as (x, y, z).
fov (float) – The vertical field of view of the camera in degrees.
aperture (float) – The aperture size of the camera, controlling depth of field.
focus_dist (float | None) – The focus distance of the camera. If None, it will be auto-computed using pos and lookat.
GUI (bool) – Whether to display the camera’s rendered image in a separate GUI window.
spp (int, optional) – Samples per pixel. Only available when using RayTracer renderer. Defaults to 256.
denoise (bool) – Whether to denoise the camera’s rendered image. Only available when using the RayTracer renderer. Defaults to True on Linux, otherwise False. If OptiX denoiser is not available in your platform, consider enabling the OIDN denoiser option when building the RayTracer.
near (float) – Distance from camera center to near plane in meters. Only available when using rasterizer in Rasterizer and BatchRender renderer. Defaults to 0.1.
far (float) – Distance from camera center to far plane in meters. Only available when using rasterizer in Rasterizer and BatchRender renderer. Defaults to 20.0.
env_idx (int, optional) – The specific environment index to bind to the camera. This option must be specified if and only if a non-batched renderer is being used. If provided, only this environment will be taken into account when following a rigid entity via ‘follow_entity’ and when being attached to some rigid link via ‘attach’. Note that this option is unrelated to which environment is being rendering on the scene. Default to None for batched renderers (ie BatchRender), ‘rendered_envs_idx[0]’ otherwise (ie Raytracer or Rasterizer).
debug (bool) – Whether to use the debug camera. It enables to create cameras that can used to monitor / debug the simulation without being part of the “sensors”. Their output is rendered by the usual simple Rasterizer systematically, no matter if BatchRender and RayTracer is enabled. This way, it is possible to record the simulation with arbitrary resolution and camera pose, without interfering with what robots can perceive from their environment. Defaults to False.

Returns:

camera – The created camera object.

Return type:

genesis.Camera

add_emitter(material: Material, max_particles=20000, surface: Surface | None = None)[source]#

Add a fluid emitter to the scene.

Parameters:

material (gs.materials.Material) – The material of the fluid to be emitted. Must be an instance of gs.materials.MPM.Base, gs.materials.SPH.Base, gs.materials.PBD.Particle or gs.materials.PBD.Liquid.
max_particles (int) – The maximum number of particles that can be emitted by the emitter. Particles will be recycled once this limit is reached.
surface (gs.surfaces.Surface | None, optional) – The surface of the emitter. If None, use gs.surfaces.Default(color=(0.6, 0.8, 1.0, 1.0)).

Returns:

emitter – The created emitter object.

Return type:

genesis.Emitter

add_force_field(force_field: ForceField)[source]#

Add a force field to the scene.

Parameters:: force_field (gs.force_fields.ForceField) – The force field to add to the scene.
Returns:: force_field – The added force field.
Return type:: gs.force_fields.ForceField

build(n_envs=0, env_spacing=(0.0, 0.0), n_envs_per_row: int | None = None, center_envs_at_origin=True)[source]#

Builds the scene once all entities have been added. This operation is required before running the simulation.

Parameters:

n_envs (int) – Number of parallel environments to create. If n_envs is 0, the scene will not have a batching dimension. When greater than 0, the first dimension of all the input and returned states will be the batch dimension.
env_spacing (tuple of float, shape (2,)) – The spacing between adjacent environments in the scene. This is for visualization purposes only and does not change simulation-related poses.
n_envs_per_row (int) – The number of environments per row for visualization. If None, it will be set to sqrt(n_envs).
center_envs_at_origin (bool) – Whether to put the center of all the environments at the origin (for visualization only).

reset(state: SimState | None = None, envs_idx=None)[source]#

Resets the scene to its initial state.

Parameters:

state (SimState | None) – The state to reset the scene to. If None, the scene will be reset to its initial state. If this is given, the scene’s registerered initial state will be updated to this state.
envs_idx (None | array_like, optional) – The indices of the environments. If None, all environments will be considered. Defaults to None.

backward(loss: Tensor, *args, **kwargs)[source]#

Differentiates loss through the recorded rollout and restores the pre-backward physics state.

Unrolling the gradient tape rewinds the physics state to step 0, so this method snapshots the current state first, runs the backward pass, and restores the snapshot afterwards. The scene then sits at the same physics state as before the call, with gradients populated and forward / backward re-armed, ready to continue the rollout or to be reset. The registered initial state (reset() with no argument) is preserved.

Parameters:: loss (torch.Tensor) – Scalar loss to differentiate. Extra positional and keyword arguments (e.g. gradient, retain_graph) are forwarded to torch.autograd.backward.
Returns:: snapshot – The physics state the scene was restored to.
Return type:: SimState

get_state()[source]#

Returns the current state of the scene.

Returns:: state – The state of the scene at the current time step.
Return type:: genesis.SimState

register_pre_step_callback(callback)[source]#: Register a callback invoked at the start of each step(), on the stepping thread. A callback may run deferred work there and veto the advance of that step by returning True. The scene calls them opaquely; use this to drive a scene from an external controller without coupling the scene to it.

step(update_visualizer=True, refresh_visualizer=True)[source]#: Runs a simulation step forward in time.

stop_recording()[source]#

draw_debug_line(start, end, radius=0.002, color=(1.0, 0.0, 0.0, 0.5))[source]#

Draws a line in the scene for visualization.

Parameters:

start (array_like, shape (3,)) – The starting point of the line.
end (array_like, shape (3,)) – The ending point of the line.
radius (float, optional) – The radius of the line (represented as a cylinder)
color (array_like, shape (4,), optional) – The color of the line in RGBA format.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_arrow(pos, vec=(0, 0, 1), radius=0.01, color=(1.0, 0.0, 0.0, 0.5))[source]#

Draws an arrow in the scene for visualization.

Parameters:

pos (array_like, shape (3,)) – The starting position of the arrow.
vec (array_like, shape (3,), optional) – The vector of the arrow.
radius (float, optional) – The radius of the arrow body (represented as a cylinder).
color (array_like, shape (4,), optional) – The color of the arrow in RGBA format.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_frame(T, axis_length=1.0, origin_size=0.015, axis_radius=0.01, color=None)[source]#

Draws a 3-axis coordinate frame in the scene for visualization.

Parameters:

T (array_like, shape (4, 4)) – The transformation matrix of the frame.
axis_length (float, optional) – The length of the axes.
origin_size (float, optional) – The size of the origin point (represented as a sphere).
axis_radius (float, optional) – The radius of the axes (represented as cylinders).
color (array_like, shape (4,), optional) – Uniform RGBA color override for the entire frame. If None, uses standard RGB axis coloring.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_frames(Ts, axis_length=1.0, origin_size=0.015, axis_radius=0.01, color=None)[source]#

Draws 3-axis coordinate frames in the scene for visualization.

Parameters:

Ts (array_like, shape (n, 4, 4)) – The transformation matrices of frames.
axis_length (float, optional) – The length of the axes.
origin_size (float, optional) – The size of the origin point (represented as a sphere).
axis_radius (float, optional) – The radius of the axes (represented as cylinders).
color (array_like, shape (4,), optional) – Uniform RGBA color override for the entire frame. If None, uses standard RGB axis coloring.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_mesh(mesh, pos=array([0., 0., 0.]), T=None)[source]#

Draws a mesh in the scene for visualization.

Parameters:

mesh (trimesh.Trimesh) – The mesh to be drawn.
pos (array_like, shape (3,), optional) – The position of the mesh in the scene.
T (array_like, shape (4, 4) | None, optional) – The transformation matrix of the mesh. If None, the mesh will be drawn at the position specified by pos. Otherwise, T has a higher priority than pos.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_sphere(pos, radius=0.01, color=(1.0, 0.0, 0.0, 0.5))[source]#

Draws a sphere in the scene for visualization.

Parameters:

pos (array_like, shape (3,)) – The center position of the sphere.
radius (float, optional) – radius of the sphere.
color (array_like, shape (4,), optional) – The color of the sphere in RGBA format.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_spheres(poss, radius=0.01, color=(1.0, 0.0, 0.0, 0.5))[source]#

Draws multiple spheres in the scene for visualization.

Parameters:

poss (array_like, shape (N, 3)) – The positions of the spheres.
radius (float, optional) – The radius of the spheres.
color (array_like, shape (4,), optional) – The color of the spheres in RGBA format.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_box(bounds, color=(1.0, 0.0, 0.0, 1.0), wireframe=True, wireframe_radius=0.0015)[source]#

Draws a box in the scene for visualization.

Parameters:

bounds (array_like, shape (2, 3)) – The bounds of the box, specified as [[min_x, min_y, min_z], [max_x, max_y, max_z]].
color (array_like, shape (4,), optional) – The color of the box in RGBA format.
wireframe (bool, optional) – Whether to draw the box as a wireframe.
wireframe_radius (float, optional) – The radius of the wireframe lines.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_points(poss, colors=(1.0, 0.0, 0.0, 0.5))[source]#

Draws points in the scene for visualization.

Parameters:

poss (array_like, shape (N, 3)) – The positions of the points.
colors (array_like, shape (4,), optional) – The color of the points in RGBA format.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_frustum(camera, color=(1.0, 1.0, 1.0, 0.3))[source]#

Draws a camera frustum in the scene for visualization.

Parameters:

camera (Camera) – The camera object whose frustum will be visualized. Works for any camera including sensor cameras.
color (array_like, shape (4,), optional) – The color of the frustum in RGBA format.

Returns:

node – The created debug object.

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_trajectory(poss, radius=0.002, color=(1.0, 0.5, 0.0, 0.8))[source]#

Draws a trajectory as a series of connected lines in the scene for visualization.

Parameters:

poss (array_like, shape (N, 3)) – The positions of the trajectory points.
radius (float, optional) – The radius of the trajectory lines.
color (array_like, shape (4,), optional) – The color of the trajectory in RGBA format.

Returns:

node – The created debug object (a single merged mesh of all segments).

Return type:

genesis.ext.pyrender.mesh.Mesh

draw_debug_path(qposs, entity, link_idx=-1, density=0.3, frame_scaling=1.0)[source]#

Draws a planned joint trajectory in the scene for visualization.

Parameters:

qposs (array_like, shape (N, M)) – The joint positions of the planned points. N is the number of configurations (i.e., trajectory points). M is the number of degrees of freedom for the entity (i.e., joint dimensions).
entity (gs.engine.entities.RigidEntity) – The rigid entity whose forward kinematics are used to compute the trajectory path.
link_idx (int, optional) – The link id of the rigid entity to visualize. Defeault is -1.
density (float, optional) – Controls the sampling density of the trajectory points to visualize. Default is 0.3.
frame_scaling (float, optional) – Scaling factor for the visualization frames’ size. Affects the length and thickness of the debug frames. Default is 1.0.

Returns:

node – The created debug object representing the visualized trajectory.

Return type:

genesis.ext.pyrender.mesh.Mesh

Notes

The function uses forward kinematics (FK) to convert joint positions to Cartesian space and render debug frames. The density parameter reduces FK computational load by sampling fewer points, with 1.0 representing the whole trajectory.

render_all_cameras(rgb=True, depth=False, segmentation=False, colorize_seg=False, normal=False, antialiasing=False, force_render=False)[source]#

Render the scene for all cameras using the batch renderer.

Parameters:

rgb (bool, optional) – Whether to render the rgb image.
depth (bool, optional) – Whether to render the depth image.
segmentation (bool, optional) – Whether to render the segmentation image.
normal (bool, optional) – Whether to render the normal image.
antialiasing (bool, optional) – Whether to apply anti-aliasing.
force_render (bool, optional) – Whether to force render the scene.
Returns – A tuple of tensors of shape (n_envs, H, W, 3) if rgb is not None, otherwise a list of tensors of shape (n_envs, H, W) if depth is not None. If n_envs == 0, the first dimension of the tensor is squeezed.

update_debug_objects(objs, poses)[source]#

Updates the poses of debug objects previously created by draw_debug_* methods.

Parameters:

objs (tuple of genesis.ext.pyrender.mesh.Mesh) – The debug objects to update, i.e. visualizer nodes returned by draw_debug_* methods. Currently only individual sphere, frame, mesh, and arrow objects (returned by draw_debug_sphere, draw_debug_frame, draw_debug_mesh, and draw_debug_arrow respectively) are supported.
poses (tuple of array_like, each of shape (4, 4)) – The new transformation matrices for each debug object.

clear_debug_object(obj)[source]#: Clears the specified debug object from the scene.

clear_debug_objects()[source]#: Clears all the debug objects in the scene.

get_time(envs_idx=None)[source]#

Get the simulated time of each environment, in seconds.

Environments are stepped and reset independently, so each one carries its own simulated time. The number of scene.step() calls is a separate scalar, Simulator.cur_step_global.

Parameters:: envs_idx (None | array_like, optional) – The indices of the environments. If None, all environments are returned. Defaults to None.
Returns:: time – The simulated time of each environment.
Return type:: torch.Tensor, shape (n_envs,) or scalar

export(path: str | PathLike) → None[source]#

Write a portable copy of this scene to a file that anyone can open.

What is written is what the scene was authored from and what its build resolved, so the file stands on its own: opening it reads no mesh, no model file and no texture from disk, and creates only the options, descriptions and meshes Genesis declares. The file is therefore self-contained enough to attach to a bug report.

A scene opened from a file stands at the configuration its entities were given rather than where the simulation had run to, so the simulated state has to be reproduced by stepping it again. Adding an entity resolves its description, so a scene is exported before it is built as readily as after.

Only a rigid or a kinematic entity carries a description. A scene holding anything that alters the simulation raises, naming it: an emitter and a force field. Everything else a description leaves out is written without, with a warning naming it: a camera, a sensor, a callback Genesis calls at every step, a texture read from an HDR or EXR file, and the visual vertices an entity was given at runtime. A recorder neither simulates nor draws, so it is left out without a word.

Parameters:: path (str or os.PathLike) – Where to write the file.

Create the scene a file holds, as written by ‘Scene.export’.

The file names what it holds rather than carrying code to run, and Genesis creates only the options, descriptions and meshes it declares, so a scene from a stranger is safe to open. The geometry travels in the file, so it opens on a machine holding none of the assets the scene was authored from.

Parameters:

path (str, os.PathLike or binary file) – The file to read.
show_viewer (bool, optional) – Whether to open an interactive viewer on the scene. Defaults to False.
viewer_options (ViewerOptions, optional) – Viewer options replacing the recorded ones. If None, the recorded ones stand. Defaults to None.
vis_options (VisOptions, optional) – Visualizer options replacing the recorded ones. If None, the recorded ones stand. Defaults to None.
renderer (RendererOptions, optional) – Renderer replacing the recorded one. If None, the recorded one stands. Defaults to None.

Returns:

scene – The scene the file describes, holding every entity it was authored with and waiting to be built.

Return type:

Scene

save_checkpoint(path: str | PathLike) → None[source]#

Write the whole state of this scene to a file, for ‘load_checkpoint’ to open a copy standing where it stands.

The file holds the scene as ‘export’ writes it and every array of the simulation, scratch included, so the exact state of a failing run is kept for inspection. It is a trajectory file of one frame (see ‘TrajectoryFile’), and ‘load_trajectory’ opens it as such.

Parameters:: path (str or os.PathLike) – The ‘.gstraj’ file to write.

classmethod load_checkpoint(path: str | PathLike, show_viewer: bool = False, viewer_options: ViewerOptions | None = None, vis_options: VisOptions | None = None, renderer: RendererOptions | None = None) → Scene[source]#

Create and build the scene a checkpoint file holds, standing in the final state the file records.

The file is one written by ‘save_checkpoint’ or by recording a ‘TrajectoryFile’ to its end. The viewer, visualizer and renderer options may be replaced (see ‘load’).

Parameters:

path (str or os.PathLike) – The file to read.
show_viewer (bool, optional) – Whether to open an interactive viewer on the scene. Defaults to False.
viewer_options (ViewerOptions, optional) – Viewer options replacing the recorded ones. Defaults to None.
vis_options (VisOptions, optional) – Visualizer options replacing the recorded ones. Defaults to None.
renderer (RendererOptions, optional) – Renderer replacing the recorded one. Defaults to None.

Returns:

scene – The built scene, in the recorded state.

Return type:

Scene

classmethod load_trajectory(path: str | PathLike, show_viewer: bool = False, viewer_options: ViewerOptions | None = None, vis_options: VisOptions | None = None, renderer: RendererOptions | None = None) → Trajectory[source]#

Open a recorded trajectory in the scene it was recorded from, created and built here, to seek and replay.

The file is one written by recording a ‘TrajectoryFile’. The viewer, visualizer and renderer options may be replaced (see ‘load’).

Parameters:

path (str or os.PathLike) – The file to read.
show_viewer (bool, optional) – Whether to open an interactive viewer on the scene. Defaults to False.
viewer_options (ViewerOptions, optional) – Viewer options replacing the recorded ones. Defaults to None.
vis_options (VisOptions, optional) – Visualizer options replacing the recorded ones. Defaults to None.
renderer (RendererOptions, optional) – Renderer replacing the recorded one. Defaults to None.

Returns:

trajectory – The trajectory, holding the built scene as ‘Trajectory.scene’.

Return type:

Trajectory

property uid#: The unique ID of the scene.

property dt#: The time duration for each simulation step.

property substeps#: The number of substeps per simulation step.

property requires_grad#: Whether the scene is in differentiable mode.

property is_built: bool#: Whether the scene has been built.

property show_FPS#: Whether to print the frames per second (FPS) in the terminal.

property viewer#: The viewer object for the scene.

property visualizer#: The visualizer object for the scene.

property sim#: The scene’s top-level simulator.

property solvers#: All the solvers managed by the scene’s simulator.

property active_solvers#: All the active solvers managed by the scene’s simulator.

property entities: list[genesis.engine.entities.base_entity.Entity]#: All the entities in the scene.

property entity_names: tuple[str, ...]#

Get the names of all entities in the scene.

Returns:: Tuple of entity names in order of creation.
Return type:: tuple[str, …]

property desc: SceneDescription#

its options and the description of each entity it holds.

It suffices to recreate the scene without any asset file. Each entity’s description stands here by reference, so what an attachment changes is visible. What the build allocates is left out, so this describes the authored scene rather than the state it has simulated to.

Type:: The description this scene is created from

get_entity(name: str | None = None, *, uid: str | None = None) → Entity[source]#

Get an entity by name or UID. Raises an exception if not found.

Parameters:

name (str, optional) – The exact name of the entity to find.
uid (str, optional) – The short UID (7-character) of the entity to find.

Returns:

The matching entity.

Return type:

Entity

property emitters#: All the emitters in the scene.

property tool_solver#: The scene’s tool_solver, managing all the ToolEntity in the scene.

property rigid_solver#: The scene’s rigid_solver, managing all the RigidEntity in the scene.

property kinematic_solver#: The scene’s kinematic_solver, managing all the kinematic (visualization-only) entities in the scene.

property mpm_solver#: The scene’s mpm_solver, managing all the MPMEntity in the scene.

property sph_solver#: The scene’s sph_solver, managing all the SPHEntity in the scene.

property fem_solver#: The scene’s fem_solver, managing all the FEMEntity in the scene.

property pbd_solver#: The scene’s pbd_solver, managing all the PBDEntity in the scene.

property segmentation_idx_dict#

Returns a dictionary mapping segmentation indices to scene entities.

In the segmentation map: - Index 0 corresponds to the background (-1). - Indices > 0 correspond to scene elements, which may be represented as:

entity_id

(entity_id, link_id)

(entity_id, link_id, geom_id)

depending on the material type and the configured segmentation level.

Scene options#

class genesis.options.scene.SceneOptions(*, sim: genesis.options.solvers.SimOptions = <factory>, tool: genesis.options.solvers.ToolOptions = <factory>, rigid: genesis.options.solvers.RigidOptions = <factory>, kinematic: genesis.options.solvers.KinematicOptions = <factory>, mpm: genesis.options.solvers.MPMOptions = <factory>, sph: genesis.options.solvers.SPHOptions = <factory>, fem: genesis.options.solvers.FEMOptions = <factory>, sf: genesis.options.solvers.SFOptions = <factory>, pbd: genesis.options.solvers.PBDOptions = <factory>, coupler: genesis.options.solvers.BaseCouplerOptions = <factory>, vis: genesis.options.vis.VisOptions = <factory>, viewer: genesis.options.vis.ViewerOptions = <factory>, profiling: genesis.options.profiling.ProfilingOptions = <factory>, renderer: genesis.options.renderers.RendererOptions = <factory>) → None[source]#

Every option a scene is created with, as one object.

Each field bears the name of the ‘Scene’ argument that carries it, without the ‘_options’ suffix. Each states its own default and falls back to it when given None, so a scene names an option only to override it, and every field holds one once the options exist.

Every option inherits from the simulation options the quantities it declares and leaves unset, which in practice is the solvers, since no other option shares a field with them. That resolution happens here, so every consumer reads the resolved value.

Profiling options#

class genesis.options.profiling.ProfilingOptions(*, show_FPS: bool = True, FPS_tracker_alpha: float = 0.95) → None[source]#

Profiling options

Parameters:

show_FPS (bool) – Whether to show the frame rate each step. Default true
FPS_tracker_alpha (float) – Exponential decay momentum for FPS moving average

Scene#

Scene options#

Profiling options#

This Page