newton.viewer.ViewerFile#

class newton.viewer.ViewerFile(output_path, auto_save=True, save_interval=100, max_history_size=None)[source]#

Bases: ViewerBase

File-based viewer backend for Newton physics simulations.

This backend records simulation data to JSON or binary files using the same ViewerBase API as other viewers. It captures model structure and state data during simulation for later replay or analysis.

Format is determined by file extension: - .json: Human-readable JSON format - .bin: Binary CBOR2 format (more efficient)

__init__(output_path, auto_save=True, save_interval=100, max_history_size=None)#

Initialize the File viewer backend for Newton physics simulations.

Parameters:

  • output_path (str) – Path to the output file (.json or .bin)

  • auto_save (bool) – If True, automatically save periodically during recording

  • save_interval (int) – Number of frames between auto-saves (when auto_save=True)

  • max_history_size (int | None) – Maximum number of states to keep in memory. If None, uses unlimited history. If set, keeps only the last N states.

apply_forces(state)#

File viewer does not apply interactive forces.

Parameters:

state (State) – Current simulation state.

close()#

Save final recording and cleanup.

end_frame()#

No frame rendering needed for file viewer.

get_frame_count()#

Return the number of frames in the loaded or recorded session.

Returns:

Number of frames available for playback.

Return type:

int

has_model()#

Return whether the loaded recording contains model data.

Returns:

True when model data is available for playback.

Return type:

bool

load_model(model)#

Restore a Model from the loaded recording.

Must be called after load_recording(). The given model is populated with the recorded model structure (bodies, shapes, etc.).

Parameters:

model (Model) – A Newton Model instance to populate.

load_recording(file_path=None, verbose=False)#

Load a previously recorded file for playback.

After loading, use load_model() and load_state() to restore the model and state at a given frame.

Parameters:

  • file_path (str | None) – Optional override for the file path. If omitted, uses the output_path from construction.

  • verbose (bool) – If True, print status output after loading.

load_state(state, frame_id)#

Restore State to a specific frame from the loaded recording.

Must be called after load_recording(). The given state is updated with the state snapshot at frame_id.

Parameters:

  • state (State) – A Newton State instance to populate.

  • frame_id (int) – Frame index in [0, get_frame_count()).

log_array(name, array)#

File viewer does not visualize generic arrays.

Parameters:

  • name (str) – Unique path/name for the array signal.

  • array (wp.array(dtype=Any) | nparray) – Array data to visualize.

log_instances(name, mesh, xforms, scales, colors, materials, hidden=False)#

File viewer does not render instances.

Parameters:

  • name (str) – Unique path/name for the instance batch.

  • mesh (str) – Name of the base mesh.

  • xforms (wp.array(dtype=wp.transform) | None) – Optional per-instance transforms.

  • scales (wp.array(dtype=wp.vec3) | None) – Optional per-instance scales.

  • colors (wp.array(dtype=wp.vec3) | None) – Optional per-instance colors.

  • materials (wp.array(dtype=wp.vec4) | None) – Optional per-instance material parameters.

  • hidden (bool) – Whether the instance batch is hidden.

log_lines(name, starts, ends, colors, width=0.01, hidden=False)#

File viewer does not render line primitives.

Parameters:

  • name (str) – Unique path/name for the line batch.

  • starts (wp.array(dtype=wp.vec3) | None) – Optional line start points.

  • ends (wp.array(dtype=wp.vec3) | None) – Optional line end points.

  • colors (wp.array(dtype=wp.vec3) | wp.array(dtype=wp.float32) | tuple[float, float, float] | list[float] | None) – Optional per-line colors or a shared RGB triplet.

  • width (float) – Line width hint.

  • hidden (bool) – Whether the line batch is hidden.

log_mesh(name, points, indices, normals=None, uvs=None, texture=None, hidden=False, backface_culling=True)#

File viewer does not render meshes.

Parameters:

  • name (str) – Unique path/name for the mesh.

  • points (wp.array(dtype=wp.vec3)) – Mesh vertex positions.

  • indices (wp.array(dtype=wp.int32) | wp.array(dtype=wp.uint32)) – Mesh triangle indices.

  • normals (wp.array(dtype=wp.vec3) | None) – Optional vertex normals.

  • uvs (wp.array(dtype=wp.vec2) | None) – Optional UV coordinates.

  • texture (np.ndarray | str | None) – Optional texture path/URL or image array.

  • hidden (bool) – Whether the mesh is hidden.

  • backface_culling (bool) – Whether back-face culling is enabled.

log_points(name, points, radii=None, colors=None, hidden=False)#

File viewer does not render point primitives.

Parameters:

  • name (str) – Unique path/name for the point batch.

  • points (wp.array(dtype=wp.vec3) | None) – Optional point positions.

  • radii (wp.array(dtype=wp.float32) | float | None) – Optional per-point radii or a shared radius.

  • colors (wp.array(dtype=wp.vec3) | wp.array(dtype=wp.float32) | tuple[float, float, float] | list[float] | None) – Optional per-point colors or a shared RGB triplet.

  • hidden (bool) – Whether the point batch is hidden.

log_scalar(name, value)#

File viewer does not visualize scalar signals.

Parameters:

  • name (str) – Unique path/name for the scalar signal.

  • value (int | float | bool | number) – Scalar value to visualize.

log_state(state)#

Record a state snapshot in addition to the base viewer processing.

Parameters:

state (State) – Current simulation state to record.

playback(state, frame_id)#

Restore a state snapshot from history into a State object.

Parameters:

  • state (State) – Destination state object to populate.

  • frame_id (int) – Frame index to load from history.

playback_model(model)#

Populate a Model instance from loaded recording data.

Parameters:

model (Model) – Destination model object to populate.

record(state)#

Record a snapshot of the provided simulation state.

Parameters:

state (State) – State to snapshot into the recording history.

record_model(model)#

Record a reference to the simulation model for later serialization.

Parameters:

model (Model) – Model to keep for serialization.

save_recording(file_path=None, verbose=False)#

Save the recorded data to file.

Parameters:

  • file_path (str | None) – Optional override for the output path. If omitted, uses the output_path from construction.

  • verbose (bool) – If True, print status output on success/failure.

set_model(model, max_worlds=None)#

Override set_model to record the model when it is set.

Parameters:

  • model (Model | None) – Model to bind to this viewer.

  • max_worlds (int | None) – Optional cap on rendered worlds.