Skip to main content
Version: 0.2.5

3D Simulators — Overview

Cart-Pole — real-time 3D simulation

synapsys.viz.simview provides plug-and-play 3D simulation windows that combine real-time PyVista rendering and matplotlib telemetry in a single PySide6 interface — ready to accept any controller you design.

What you get in one line​

from synapsys.viz import CartPoleView
CartPoleView().run()

A complete window with:

  • 3D panel — real-time physics animation (PyVista + VTK)
  • Telemetry panel — 4 synchronized matplotlib charts (position, angle, control, phase portrait)
  • Control bar — hold-to-apply perturbation buttons, magnitude slider, pause/reset
  • Automatic LQR — if no controller is provided, the lib linearizes the simulator and designs an LQR internally
  • Global keyboard capture — A/D (perturbation), R (reset), Space (pause), Q (close)

Architecture​

SimulatorBase          ← synapsys.simulators
│  dynamics(), step(), linearize()
│
SimViewBase            ← synapsys.viz.simview._base  (QMainWindow)
│  • creates Qt window (3D + matplotlib splitter)
│  • QTimer loop → _on_tick()
│  • auto-LQR via linearize() + lqr()
│  • keyboard, perturbations, pause, reset
│  • _build_all() called in run()
│
├── CartPoleView        ← state: [x, ẋ, θ, θ̇]
├── PendulumView        ← state: [θ, θ̇]
└── MassSpringDamperView ← state: [q, q̇]  + setpoint tracking

Each subclass implements only what is specific to its physical system (3D scene, charts, HUD, LQR parameters). All Qt boilerplate is inherited from the base.

Available simulators​

ClassPhysical systemStateInputPerturbation
CartPoleViewCart + inverted pendulum[x, ẋ, θ, θ̇]Horizontal force on cart (N)◀/▶ horizontal force
PendulumViewSingle-link inverted pendulum[θ, θ̇]Joint torque (N·m)↺/↻ angular torque
MassSpringDamperViewMass-spring-damper[q, q̇]External force (N)◀/▶ force + setpoints 1/2/3

Standalone vs. library module​

ApproachLines of codeRequires Qt knowledge?
Standalone file viz3d_cartpole_qt.py~470 linesYes — layout, QTimer, splitter, canvas
CartPoleView().run()1 lineNo
CartPoleView(controller=my_net).run()1 line + your functionNo

The standalone files in examples/simulators/ remain available as a reference for anyone who wants to understand the internal implementation or build highly customized UIs beyond what the library provides.

Dependencies​

pip install synapsys[viz]
# or individually:
pip install pyside6 pyvistaqt matplotlib numpy

Note: pyvistaqt requires a VTK installation compatible with Qt. In headless environments (servers without a display), use pyvista with the offscreen backend.

Next steps​