Visualization utilities

The cromosim.visu module provides two persistent renderers for microscopic simulations. They share the same simulation layers (people, contacts, paths, sensors, actual velocities and desired velocities) while using different graphics backends.

Matplotlib renderer

class cromosim.visu.matplotlibVisualization(domain, figure_id=None, axis=None, cmap='winter', figsize=None, velocity_reference=1.5, velocity_arrow_length=0.5)

Bases: _VisualizationDataMixin

2-D Matplotlib renderer for a Cromosim domain.

Parameters:

domaincromosim.domain.Domain

Computational domain to display.

figure_idint, optional

Matplotlib figure identifier.

axissequence of float, optional

Display limits [xmin, xmax, ymin, ymax]. By default the domain limits are used.

cmapstr, default=”winter”

Colormap used for real pedestrians.

figsizetuple of float, optional

Matplotlib figure size in inches.

velocity_referencefloat, default=1.5

Reference velocity used to define a fixed arrow scale. A vector with this norm is displayed with length velocity_arrow_length.

velocity_arrow_lengthfloat, default=0.5

Displayed length, in domain coordinates, of a velocity vector whose norm is velocity_reference. The same scale is used for U and Vd and remains constant throughout the simulation.

Methods

close()	Close the Matplotlib figure.
process_events()	Process GUI events without recreating the figure.
show()	Show the figure without blocking the simulation loop.
update(*, people[, contacts, ...])	Update one Matplotlib frame without rebuilding the figure.

Notes

The background image and axes are created only once. Pedestrian positions, contacts, trajectories, velocity vectors and sensor lines are subsequently updated in place whenever possible.

close()

Close the Matplotlib figure.

process_events()

Process GUI events without recreating the figure.

show()

Show the figure without blocking the simulation loop.

update(*, people, contacts=[], virtual_people=None, sensors=None, time=None, plot_people=True, plot_contacts=True, plot_velocities=False, plot_desired_velocities=False, plot_paths=False, plot_sensors=False, color_scalar_values=None, color_scalar_name='r', color_minmax=None, color_cmap='winter', show_scalar_bar=False, contacts_line_width=1.0, paths_line_width=0.5, sensors_line_width=1.0, savefig=False, filename=None, dpi=150)

Update one Matplotlib frame without rebuilding the figure.

Parameters mirror the PyVista visualization layer flags. Only artists whose topology changes are recreated; otherwise their underlying data are updated in place.

A renderer is created once and then updated at every visualization step. This avoids rebuilding the whole Matplotlib figure during the simulation.

from cromosim.visu import matplotlibVisualization

visu = matplotlibVisualization(
    domain,
    cmap="viridis",
    velocity_reference=1.0,
    velocity_arrow_length=1.5,
)

visu.update(
    people=people,
    contacts=contacts,
    sensors=sensors,
    time=t,
    plot_people=True,
    plot_contacts=True,
    plot_velocities=True,
    plot_desired_velocities=True,
    plot_paths=True,
    plot_sensors=True,
)

Fixed velocity-arrow scale

Both renderers use the same fixed conversion from a physical velocity to an arrow length. If velocity_reference is \(v_{ref}\) and velocity_arrow_length is \(L_{ref}\), a velocity vector \(v\) is displayed with length

\[L(v) = \frac{L_{ref}}{v_{ref}}\,\lVert v \rVert.\]

Consequently, the scale does not depend on the current frame or on the largest velocity present in that frame. Actual velocities U and desired velocities Vd therefore remain directly comparable throughout a simulation.

PyVista renderer

class cromosim.visu.pyvistaVisualization(domain, image_path, pixel_size, movie_path=None, fps=20, window_size=(1000, 800), movie_macro_block_size=1, velocity_reference=1.5, velocity_arrow_length=0.5)

Bases: _VisualizationDataMixin

Display a Cromosim microscopic simulation with PyVista.

Parameters:

image_pathstr or path-like

Path to the background image representing the domain.

pixel_sizefloat

Physical size represented by one image pixel.

movie_pathstr or path-like, optional

Output movie path. When provided, rendered frames can be written with update() by setting write_frame=True.

fpsint, default=20

Movie frame rate.

window_sizetuple of int, default=(1000, 800)

PyVista window size in pixels.

velocity_referencefloat, default=1.5

Reference velocity used to define a fixed arrow scale. A vector with this norm is displayed with length velocity_arrow_length.

velocity_arrow_lengthfloat, default=0.5

Displayed length, in domain coordinates, of a velocity vector whose norm is velocity_reference. The same scale is used for U and Vd and remains constant throughout the simulation.

Methods

close()	Close the PyVista plotter and its movie writer, if any.
process_events()	Process pending events for the interactive PyVista window.
show()	Open the interactive PyVista window without blocking execution.
update([xyrv, people, contacts, ...])	Update all visible layers of the PyVista scene.

Notes

The public class name is intentionally kept in French for backward compatibility with existing Cromosim scripts.

close()

Close the PyVista plotter and its movie writer, if any.

process_events()

Process pending events for the interactive PyVista window.

show()

Open the interactive PyVista window without blocking execution.

update(xyrv=None, *, people=None, contacts=[], virtual_people=None, sensors=None, time=None, plot_people=True, plot_contacts=True, plot_velocities=False, plot_desired_velocities=False, plot_paths=False, plot_sensors=False, color_scalar_values=None, color_scalar_name='r', color_minmax=None, color_cmap='viridis', show_scalar_bar=True, write_frame=True)

Update all visible layers of the PyVista scene.

Parameters:

xyrvarray-like, optional

Backward-compatible particle array of shape (N, 4). Prefer passing people when velocities or paths must be displayed.

peopledict, optional

Cromosim people dictionary. Expected fields include "xyrv", "U", "Vd" and "paths" as required by the selected plotting options.

contactsnumpy.ndarray, optional

Contact array i, j, dij, eij_x, eij_y.

virtual_peopledict, optional

Virtual population used at domain interfaces.

sensorssequence of dict, optional

Sensor definitions containing a "line" entry.

timefloat, optional

Simulation time displayed in the upper-left corner.

plot_people, plot_contacts, plot_velocities, plot_desired_velocities,

plot_paths, plot_sensorsbool

Enable the corresponding simulation layer. These flags mirror the Matplotlib options used by cromosim.micro.plot_people().

color_scalar_valuesarray-like, optional

Per-person scalar values used to color real pedestrians.

color_scalar_namestr, default=”r”

Name of the scalar field used for coloring.

color_minmaxtuple of float, optional

Minimum and maximum values of the color scale.

color_cmapstr, default=”viridis”

Colormap name.

show_scalar_barbool, default=True

Display a scalar bar for real pedestrians.

write_framebool, default=True

Write the rendered frame when movie recording is enabled.

The PyVista renderer accepts the same velocity scaling parameters. It can also record frames directly to a movie when movie_path is supplied.

Legacy plotting functions

The historical plotting helpers remain available for compatibility:

cromosim.visu.plot_people(ifig, dom, people, contacts, colors, time=-1, axis=None, virtual_people=None, plot_people=True, plot_contacts=True, plot_velocities=False, plot_desired_velocities=False, plot_paths=False, plot_sensors=False, vmin=None, vmax=None, sensors=None, savefig=False, filename='fig.png', dpi=150, cmap='winter')

Plot pedestrians, contacts, velocities, paths and sensors.

Parameters:

ifigint

Matplotlib figure number.

domDomain

Domain whose background image and geometry are displayed.

peopledict

Pedestrian data.

contactsnumpy.ndarray

Contact rows (i, j, dij, eij_x, eij_y).

colorsnumpy.ndarray

Scalar values used to color pedestrians.

timefloat, optional

Simulation time displayed in the figure title when non-negative.

axissequence of float or None, optional

Plot limits [xmin, xmax, ymin, ymax].

virtual_peopledict or None, optional

Optional virtual pedestrians drawn with partial transparency.

plot_peoplebool, optional

Draw pedestrians.

plot_contactsbool, optional

Draw active contacts.

plot_velocitiesbool, optional

Draw actual velocities.

plot_desired_velocitiesbool, optional

Draw desired velocities.

plot_pathsbool, optional

Draw stored pedestrian trajectories.

plot_sensorsbool, optional

Draw sensor line segments.

vmin, vmaxfloat or None, optional

Color limits for pedestrian scalar values.

sensorssequence of dict or None, optional

Sensor definitions.

savefigbool, optional

Save the figure when True.

filenamestr, optional

Output image filename.

dpiint, optional

Output resolution in dots per inch.

cmapstr, optional

Matplotlib colormap name.

Returns:

None

The function updates the selected Matplotlib figure in place.

cromosim.visu.plot_sensors(ifig, sensors, time, flux_timestep=1, savefig=False, filename='fig.png', dpi=150, cmap='winter')

Plot sensor crossing times and entry/exit fluxes.

Parameters:

ifigint

Matplotlib figure number.

sensorssequence of dict

Sensor records containing at least "name", "times" and "dir".

timefloat

Current simulation time in seconds.

flux_timestepfloat, optional

Width, in seconds, of bins used for entry and exit counts.

savefigbool, optional

Save the figure when True.

filenamestr, optional

Output image filename.

dpiint, optional

Output resolution in dots per inch.

cmapstr, optional

Matplotlib colormap name. Kept for API compatibility.

Returns:

None

The function updates the selected Matplotlib figure in place.