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.

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.

has_model()#

Return True if the loaded recording contains model data (for playback).

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 – 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 – A Newton State instance to populate.

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

log_array(name, array)#

File viewer doesn’t log arrays visually, so this is a no-op.

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

File viewer doesn’t render instances, so this is a no-op.

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

File viewer doesn’t render lines, so this is a no-op.

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

File viewer doesn’t render meshes, so this is a no-op.

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

File viewer doesn’t render points, so this is a no-op.

log_scalar(name, value)#

File viewer doesn’t log scalars visually, so this is a no-op.

log_state(state)#

Override log_state to record the state in addition to standard processing.

playback(state, frame_id)#

Restore a state snapshot from history into a State object.

playback_model(model)#

Populate a Model instance from loaded recording data.

record(state)#

Record a snapshot of the provided simulation state.

record_model(model)#

Record a reference to the simulation model for later 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’s set.