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 |
|---|---|---|
|
Resting temperature of the material |
°C |
|
Thermal conductivity |
W/(m·K) |
|
Mass density |
kg/m³ |
|
Specific heat capacity |
J/(kg·K) |
|
Radiative emissivity, |
— |
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_temperaturedefaults to 21 °C.Convection.
convection_coefficientis 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 itsbase_temperature, exchanging no heat. Set it toTrueto evolve the temperature of every link that has thermal properties; the per-link values are then available on thelink_temperaturesattribute.Heat generation. Pass
heat_generation(a per-cell array matchinggrid_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.