Temperature grid#

The TemperatureGrid sensor overlays a 3D voxel grid on one rigid link and reports the temperature of every cell, in degrees Celsius. Genesis World discretizes the link’s local bounding box into an (nx, ny, nz) grid and evolves each cell’s temperature from contact conduction, radiation, convection, and optional per-cell heat generation. Use it to observe how a surface heats or cools as other bodies touch it.

The complete script is examples/sensors/temperature_grid.py, an interactive scene in which a hot pusher and dropped objects heat a sensorized platform.

Minimal example#

A temperature sensor attaches to one link of a rigid entity. entity_idx selects the entity and link_idx_local the link within it; grid_size sets the resolution as (nx, ny, nz).

temperature_sensor = scene.add_sensor(
    gs.sensors.TemperatureGrid(
        entity_idx=platform.idx,
        link_idx_local=0,
        grid_size=(10, 10, 1),  # (nx, ny, nz) voxels over the link's local bounding box
        properties_dict=properties_dict,
        ambient_temperature=22.0,  # degC
        convection_coefficient=0.0,  # W/(m2*K); 0.0 disables surface cooling
        draw_debug=True,
        debug_temperature_range=(0.0, 80.0),  # degC mapped to the blue->red debug colors
    )
)

scene.build()

After the scene is built, read() returns the current temperature field:

data = temperature_sensor.read()  # shape ([n_envs,] nx, ny, nz), in degC
t_min, t_max = float(data.min()), float(data.max())

The [n_envs,] axis is present only when the scene is built with multiple environments; a single-environment scene returns a plain (nx, ny, nz) tensor.

Material properties#

Heat only flows between links that carry thermal properties. Supply these through properties_dict, which maps a global rigid-link index to a TemperatureProperties entry. Key -1 is the default applied to any link not listed explicitly; omit it and contacts with unlisted links transfer no heat at all.

properties_dict = {
    -1: gs.sensors.TemperatureProperties(  # default for unlisted links
        base_temperature=-40.0,
        conductivity=200.0,
        density=2000.0,
        specific_heat=1.0,
        emissivity=0.85,
    ),
    platform.base_link_idx: gs.sensors.TemperatureProperties(
        base_temperature=22.0,  # room temperature
        conductivity=100.0,
        density=1000.0,
        specific_heat=0.2,
        emissivity=0.4,
    ),
    pusher.base_link_idx: gs.sensors.TemperatureProperties(
        base_temperature=200.0,  # hot
        conductivity=1000.0,
        density=2000.0,
        specific_heat=1.0,
        emissivity=0.8,
    ),
}

Each field has a fixed unit:

Field

Meaning

Unit

base_temperature

Resting temperature of the material

°C

conductivity

Thermal conductivity

W/(m·K)

density

Mass density

kg/m³

specific_heat

Specific heat capacity

J/(kg·K)

emissivity

Radiative emissivity, 0–1

—

properties_dict, ambient_temperature, and convection_coefficient are shared across every temperature sensor in the scene: Genesis World merges the dictionaries, and the last ambient and convection values set win.

Behavior and guarantees#

  • Frame and layout. The grid sits in the link’s local frame and spans its bounding box, so it moves and rotates with the link. Cell (0, 0, 0) is the corner of the bounding box; grid_size=(10, 10, 1) is a single-layer 10×10 sheet, useful for a flat surface like the platform above.

  • Units. All temperatures are in degrees Celsius, on input (base_temperature, ambient_temperature) and on output (read()). ambient_temperature defaults to 21 °C.

  • Convection. convection_coefficient is the surface cooling coefficient h in W/(m²·K) and defaults to 1.0. Set it to 0.0 to disable convective cooling, as the example does.

  • Unlisted links. With simulate_all_link_temperatures=False (the default), every link other than the sensor’s own stays adiabatic at its base_temperature, exchanging no heat. Set it to True to evolve the temperature of every link that has thermal properties; the per-link values are then available on the link_temperatures attribute.

  • Heat generation. Pass heat_generation (a per-cell array matching grid_size, in W/m²) to inject heat into specific cells, for example to model a heating element embedded in the link.

Tip

draw_debug=True colors each cell in the viewer from blue (cool) to red (hot), mapped across debug_temperature_range in °C. It is a visualization aid only and does not affect the values read() returns.

See also#

  • Sensors: the sensor pipeline, batched reads, and history.

  • Recording data: saving sensor data alongside the simulation.