Visualization

---

Bases: ABC

Abstract base class representing a visualization engine.

The visualization engine is responsible for rendering the graph and agents, handling simulation updates, processing human inputs, and managing the overall visualization lifecycle.

add_artist(name, artist) abstractmethod

Add a custom artist or object to the visualization.

This method adds a custom artist or object to the visualization, allowing for additional elements to be displayed alongside the graph and agents. The artist can be used to render custom shapes, text, images, or other visual components within the visualization.

Parameters:

Name	Type	Description	Default
name	str	The unique name identifier for the custom artist.	required
artist	IArtist	The artist object representing the custom visualization element.	required

human_input(agent_name, state) abstractmethod

Process input from a human player or user.

This method handles input data provided by a human user, allowing for interactive control or modification of the visualization. It can be used to receive commands, adjust settings, or influence the simulation based on user actions.

Parameters:

Name	Type	Description	Default
agent_name	str	The unique name of the agent.	required
state	Dict[str, Any]	A dictionary containing the current state of the system or the input data from the user. Expected keys may include: - command (str): The command issued by the user. - parameters (Dict[str, Any]): Additional parameters related to the command. - Other state-related information as needed.	required

Returns:

Name	Type	Description
int	int	The target node id selected by the user.

Raises:

Type	Description
ValueError	If the input state contains invalid or unsupported commands.
KeyError	If required keys are missing from the state dictionary.
TypeError	If the types of the provided input data do not match expected types.

remove_artist(name) abstractmethod

Remove a custom artist or object from the visualization.

This method removes a custom artist or object from the visualization, effectively hiding or deleting the element from the display.

Parameters:

Name	Type	Description	Default
name	str	The unique name identifier of the custom artist to remove.	required

render_circle(x, y, radius, color, perform_culling_test) abstractmethod

Render a circle shape at the specified position with the given radius and color.

Parameters:

Name	Type	Description	Default
x	float	The x-coordinate of the circle's center.	required
y	float	The y-coordinate of the circle's center.	required
radius	float	The radius of the circle.	required
color	Tuple[Union[int, float], Union[int, float], Union[int, float]]	The color of the circle in RGB format.	required
perform_culling_test	bool	Whether to perform culling.	required

render_layer(layer_id) abstractmethod

Render the specified layer of the visualization.

Parameters:

Name	Type	Description	Default
layer_id	int	The layer number to render.	required

render_line(start_x, start_y, end_x, end_y, color, width, is_aa, perform_culling_test) abstractmethod

Render a line segment between two points with the specified color and width.

Parameters:

Name	Type	Description	Default
start_x	float	The x-coordinate of the starting point.	required
start_y	float	The y-coordinate of the starting point.	required
end_x	float	The x-coordinate of the ending point.	required
end_y	float	The y-coordinate of the ending point.	required
color	Tuple[Union[int, float], Union[int, float], Union[int, float]]	The color of the line in RGB format.	required
width	int	The width of the line in pixels. Only non-antialiasing lines supports width.	required
is_aa	bool	Whether to use antialiasing for smoother rendering.	required
perform_culling_test	bool	Whether to perform culling.	required

render_linestring(points, color, width, closed, is_aa, perform_culling_test) abstractmethod

Render a series of connected line segments between multiple points.

Parameters:

Name	Type	Description	Default
points	list[Tuple[float, float]]	A list of (x, y) coordinate tuples defining the line segments.	required
color	Tuple[Union[int, float], Union[int, float], Union[int, float]]	The color of the lines in RGB format.	required
width	int	The width of the lines in pixels. Only non-antialiasing lines supports width.	required
closed	bool	Whether the line segments form a closed shape.	required
is_aa	bool	Whether to use antialiasing for smoother rendering.	required
perform_culling_test	bool	Whether to perform culling.	required

render_polygon(points, color, width, perform_culling_test) abstractmethod

Render a polygon shape or outline defined by a list of vertices with the specified color and width.

Parameters:

Name	Type	Description	Default
points	list[Tuple[float, float]]	A list of (x, y) coordinate tuples defining the polygon vertices.	required
color	Tuple[Union[int, float], Union[int, float], Union[int, float]]	The color of the polygon in RGB format.	required
width	int	The width of the polygon outline in pixels. If equal to 0, the polygon is filled.	required
perform_culling_test	bool	Whether to perform culling.	required

render_rectangle(x, y, width, height, color, perform_culling_test) abstractmethod

Render a rectangle shape at the specified position with the given dimensions and color.

Parameters:

Name	Type	Description	Default
x	float	The x-coordinate of the rectangle's center.	required
y	float	The y-coordinate of the rectangle's center.	required
width	float	The width of the rectangle.	required
height	float	The height of the rectangle.	required
color	Tuple[Union[int, float], Union[int, float], Union[int, float]]	The color of the rectangle in RGB format.	required
perform_culling_test	bool	Whether to perform culling.	required

render_text(text, x, y, color, perform_culling_test) abstractmethod

Render text at the specified position with the given content and color.

Parameters:

Name	Type	Description	Default
text	str	The text content to display.	required
x	float	The x-coordinate of the text's center position.	required
y	float	The y-coordinate of the text's center position.	required
color	Tuple[Union[int, float], Union[int, float], Union[int, float]]	The color of the text in RGB format.	required
perform_culling_test	bool	Whether to perform culling.	required

set_agent_visual(name, **kwargs) abstractmethod

Configure the visual representation of a specific agent.

This method sets up visual parameters for an individual agent, allowing customization of how the agent is displayed within the visualization.

Parameters:

Name	Type	Description	Default
name	str	The unique name identifier of the agent to configure.	required
**kwargs	Dict[str, Any]	Arbitrary keyword arguments representing visual settings. Possible keys include: - color (str): The color to represent the agent. - shape (str): The shape to use for the agent's representation. - size (float): The size of the agent in the visualization.	{}

set_graph_visual(**kwargs) abstractmethod

Configure the visual representation of the graph.

This method sets up visual parameters such as colors, sizes, layouts, and other graphical attributes for the entire graph. It allows customization of how the graph is displayed to the user.

Parameters:

Name	Type	Description	Default
**kwargs	Dict[str, Any]	Arbitrary keyword arguments representing visual settings. Possible keys include: - color_scheme (str): The color scheme to use for nodes and edges. - layout (str): The layout algorithm for positioning nodes. - node_size (float): The size of the graph nodes. - edge_width (float): The width of the graph edges. - Additional visual parameters as needed.	{}

Raises:

Type	Description
ValueError	If any of the provided visual settings are invalid.
TypeError	If the types of the provided settings do not match expected types.

set_sensor_visual(name, **kwargs) abstractmethod

Configure the visual representation of a specific sensor.

This method sets up visual parameters for an individual sensor, allowing customization of how the sensor is displayed within the visualization.

Parameters:

Name	Type	Description	Default
name	str	The unique name identifier of the sensor to configure.	required
**kwargs	Dict[str, Any]	Arbitrary keyword arguments representing visual settings. Possible keys include: - color (str): The color to represent the sensor. - shape (str): The shape to use for the sensor's representation. - size (float): The size of the sensor in the visualization.	{}

Raises:

Type	Description
KeyError	If the sensor with the specified name does not exist.
ValueError	If the sensor type is not supported for default visualization.

simulate() abstractmethod

Execute a simulation step to update the visualization.

This method advances the simulation by one step, updating the positions, states, and visual representations of the graph and agents. It should be called repeatedly within a loop to animate the visualization in real-time.

Raises:

Type	Description
RuntimeError	If the simulation cannot be advanced due to internal errors.
ValueError	If the simulation parameters are invalid or inconsistent.

terminate() abstractmethod

Terminate the visualization engine and clean up resources.

This method is called when the simulation or application is exiting. It should handle the graceful shutdown of the visualization engine, ensuring that all resources are properly released and that the display is correctly closed.

Raises:

Type	Description
RuntimeError	If the engine fails to terminate gracefully.
IOError	If there are issues during the cleanup process.