The scene functions provide utilities to change a particular scene (represented by a SimState object) in a variety of ways, including adding a thruster, adding revolute or fixed joints, or adding shapes.

Creating a Scene

To create a scene, you can use the following code block

static_sim_params = StaticSimParams()
sim_params = SimParams()
engine = PhysicsEngine(static_sim_params)

# Create scene
sim_state = create_empty_sim(static_sim_params, floor_offset=0.0)

Editing a Scene

While you can edit a scene manually by changing the parameters, we recommend using the functions provided in jax2d.scene to edit a state.

Environment Size

Note, if the environment state has the maximum number of a certain entity type (e.g. polygons) and you try to add another one, it will result in a no-op.

add_circle_to_scene 

add_circle_to_scene(sim_state, static_sim_params, position, radius, rotation=0.0, velocity=jnp.zeros(2), angular_velocity=0.0, density=1.0, friction=1.0, restitution=0.0, fixated=False)

Adds a circle to the scene, with the properties specified by the given parameters.

Parameters:
  • sim_state (SimState) –
  • static_sim_params (StaticSimParams) –
  • position (ndarray) –

    Position of the center in world space

  • radius (float) –

    Radius of the circle

  • rotation (float, default: 0.0 ) –

    Rotation. Defaults to 0.0.

  • velocity (ndarray, default: zeros(2) ) –

    Initial velocity. Defaults to jnp.zeros(2).

  • angular_velocity (float, default: 0.0 ) –

    Initial angular velocity. Defaults to 0.0.

  • density (float, default: 1.0 ) –

    Shape's density. Defaults to 1.0.

  • friction (float, default: 1.0 ) –

    Friction coefficient. Defaults to 1.0.

  • restitution (float, default: 0.0 ) –

    How 'bouncy' the shape is, 0.0 is not bouncy at all and 1.0 is very bouncy. Restitution is calculated by multiplying the restitution values of two colliding shapes, so both have to have values > 0 to bounce. Defaults to 0.0.

  • fixated (bool, default: False ) –

    If true, the shape has infinite mass, meaning that it will not move and acts as a fixed shape. Defaults to False.
Returns:
  • tuple[SimState, tuple[int, int]] –

    tuple[SimState, tuple[int, int]]: (new_sim_state, (circle_index, global_index)): The two indices we return are: (a) the index of the newly-added circle in the state.circle array, and (b) the global index, in the range [0, num_shapes), where polygons are first, then circles.

add_fixed_joint_to_scene 

add_fixed_joint_to_scene(sim_state, static_sim_params, a_index, b_index, a_relative_pos, b_relative_pos)

Adds a fixed joint to a scene, where a fixed joint does not allow the relative rotation between the two objects to change.

Parameters:
  • sim_state (SimState) –
  • static_sim_params (StaticSimParams) –
  • a_index (int) –

    Global object index in range [0, num_shapes)

  • b_index (int) –

    Global object index in range [0, num_shapes)

  • a_relative_pos (ndarray) –

    The joint's position relative to the center of mass of object a_index.

  • b_relative_pos (ndarray) –

    The joint's position relative to the center of mass of object b_index.
Returns:
  • tuple[SimState, int] –

    tuple[SimState, int]: (new_sim_state, joint_index)

add_polygon_to_scene 

add_polygon_to_scene(sim_state, static_sim_params, position, vertices, n_vertices, rotation=0.0, velocity=jnp.zeros(2), angular_velocity=0.0, density=1.0, friction=1.0, restitution=0.0, fixated=False)

Adds a polygon to the scene.

Parameters:
  • sim_state (SimState) –
  • static_sim_params (StaticSimParams) –
  • position (ndarray) –

    Position of the center of the polygon in world space.

  • vertices (ndarray) –

    A list of vertices, which has shape (n_vertices, 2). The ordering of these vertices is important, and has to be clockwise, starting from the top-left vertex.

  • n_vertices (int) –

    How many vertices are in the polygon.

  • rotation (float, default: 0.0 ) –

    Rotation. Defaults to 0.0.

  • velocity (ndarray, default: zeros(2) ) –

    Initial velocity. Defaults to jnp.zeros(2).

  • angular_velocity (float, default: 0.0 ) –

    Initial angular velocity. Defaults to 0.0.

  • density (float, default: 1.0 ) –

    Shape's density. Defaults to 1.0.

  • friction (float, default: 1.0 ) –

    Friction coefficient. Defaults to 1.0.

  • restitution (float, default: 0.0 ) –

    How 'bouncy' the shape is, 0.0 is not bouncy at all and 1.0 is very bouncy. Restitution is calculated by multiplying the restitution values of two colliding shapes, so both have to have values > 0 to bounce. Defaults to 0.0.

  • fixated (bool, default: False ) –

    If true, the shape has infinite mass, meaning that it will not move and acts as a fixed shape. Defaults to False.
Returns:
  • tuple[SimState, tuple[int, int]] –

    tuple[SimState, tuple[int, int]]: (new_sim_state, (polygon_index, global_index)): The two indices we return are: (a) the index of the newly-added polygon in the state.polygon array, and (b) the global index, in the range [0, num_shapes), where polygons are first, then circles.

add_rectangle_to_scene 

add_rectangle_to_scene(sim_state, static_sim_params, position, dimensions, rotation=0.0, velocity=jnp.zeros(2), angular_velocity=0.0, density=1.0, friction=1.0, restitution=0.0, fixated=False)

Adds a rectangle to the scene.

Parameters:
  • sim_state (SimState) –
  • static_sim_params (StaticSimParams) –
  • position (ndarray) –

    Position of the center of the rectangle in world space

  • dimensions (ndarray) –

    (width, height) of the rectangle

  • rotation (float, default: 0.0 ) –

    Rotation. Defaults to 0.0.

  • velocity (ndarray, default: zeros(2) ) –

    Initial velocity. Defaults to jnp.zeros(2).

  • angular_velocity (float, default: 0.0 ) –

    Initial angular velocity. Defaults to 0.0.

  • density (float, default: 1.0 ) –

    Shape's density. Defaults to 1.0.

  • friction (float, default: 1.0 ) –

    Friction coefficient. Defaults to 1.0.

  • restitution (float, default: 0.0 ) –

    How 'bouncy' the shape is, 0.0 is not bouncy at all and 1.0 is very bouncy. Restitution is calculated by multiplying the restitution values of two colliding shapes, so both have to have values > 0 to bounce. Defaults to 0.0.

  • fixated (bool, default: False ) –

    If true, the shape has infinite mass, meaning that it will not move and acts as a fixed shape. Defaults to False.
Returns:
  • tuple[SimState, tuple[int, int]] –

    tuple[SimState, tuple[int, int]]: (new_sim_state, (polygon_index, global_index)): The two indices we return are: (a) the index of the newly-added polygon in the state.polygon array, and (b) the global index, in the range [0, num_shapes), where polygons are first, then circles.

add_revolute_joint_to_scene 

add_revolute_joint_to_scene(sim_state, static_sim_params, a_index, b_index, a_relative_pos, b_relative_pos, motor_on=False, motor_speed=1.0, motor_power=1.0, has_joint_limits=False, min_rotation=-np.pi, max_rotation=np.pi)

Adds a revolute joint to the scene, connecting the two shapes given by a_index and b_index.

Parameters:
  • sim_state (SimState) –
  • static_sim_params (StaticSimParams) –
  • a_index (int) –

    Global object index in range [0, num_shapes)

  • b_index (int) –

    Global object index in range [0, num_shapes)

  • a_relative_pos (ndarray) –

    The joint's position relative to the center of mass of object a_index.

  • b_relative_pos (ndarray) –

    The joint's position relative to the center of mass of object b_index.

  • motor_on (bool, default: False ) –

    If this is true, the joint has a motor that can be activated by actions, applying a torque to these two objects. Defaults to False.

  • motor_speed (float, default: 1.0 ) –

    Only in use if motor_on is True, how fast can the motor rotate. Defaults to 1.0.

  • motor_power (float, default: 1.0 ) –

    Only in use if motor_on is True, the maximum torque the motor can apply. Defaults to 1.0.

  • has_joint_limits (bool, default: False ) –

    If true, then the joint has limits that it cannot exceed. Defaults to False.

  • min_rotation (float, default: -pi ) –

    Minimum joint limit. Defaults to -np.pi.

  • max_rotation (float, default: pi ) –

    Maximum joint limit. Defaults to np.pi.
Returns:
  • tuple[SimState, int] –

    tuple[SimState, int]: (new_sim_state, joint_index)

add_thruster_to_scene 

add_thruster_to_scene(sim_state, object_index, relative_position, rotation, power=1.0)

Adds a thruster to the object specified by object_index.

Parameters:
  • sim_state (SimState) –
  • object_index (int) –

    The global object index, i.e., in the range [0, num_objects), where polygons are first, then circles.

  • relative_position (ndarray) –

    Position of the thruster relative to the center of mass of the object.

  • rotation (float) –

    The rotation of the thruster, note that it is recommended to have the thruster always point in the direction of the center of mass of the object.

  • power (float, default: 1.0 ) –

    How strong the thruster is. Defaults to 1.0.
Returns:
  • tuple[SimState, int] –

    tuple[SimState, int]: (new_sim_state, thruster_index)