FDSVismap Module

VisMap

Module for creating visibility maps (VisMap) based on Fire Dynamics Simulator (FDS) data.

class fdsvismap.FDSVisMap.RayCastingCache

Bases: TypedDict

non_concealed_x_idx: ndarray[tuple[Any, ...], dtype[int64]]

non_concealed_y_idx: ndarray[tuple[Any, ...], dtype[int64]]

ray_cell_counts: ndarray[tuple[Any, ...], dtype[int64]]

ray_paths_x: list[ndarray[tuple[Any, ...], dtype[int64]]]

ray_paths_y: list[ndarray[tuple[Any, ...], dtype[int64]]]

class fdsvismap.FDSVisMap.VisMap

Bases: object

A class to build visibility maps (VisMap) based on Fire Dynamics Simulator (FDS) data.

Variables:

• obstructions_array – Array indicating obstructed cells in the FDS simulation. Initialized as None.

• fds_grid_shape (tuple[int, int] or None) – Shape of the FDS grid. Initialized as None.

• all_y_coords (np.ndarray or None) – y-coordinates of the FDS grid. Initialized as None.

• all_x_coords (np.ndarray or None) – x-coordinates of the FDS grid. Initialized as None.

• obstructions_collection (list or None # TODO: check) – Collection of obstruction data from FDS simulation. Initialized as None.

• vismap_time_points (np.ndarray or None) – Time points for which the visibility maps are created. Initialized as None.

• fds_time_points (np.ndarray or None) – Time points available in the FDS simulation data. Initialized as None.

• quantity (str) – Quantity of FDS slice file to be evaluated, specific to the type of data being visualized. Initialized to ‘ext_coef_C0.9H0.1’.

• slc (fds.Simulation.Slice or None) – Slice object for visibility calculations. Initialized as None.

• start_point (tuple[float, float] or None) – The starting point coordinates (x, y) for the route of egress. Initialized as None.

• all_wp_dict (dict[Waypoint]) – Dictionary of waypoints for the path. Initialized as an empty list.

• all_wp_distance_array_dict – Dictionary of distance arrays between each waypoint and all cells. Initialized as an empty list.

• all_wp_non_concealed_cells_array_dict (dict[np.ndarray]) – Dictionary of arrays indicating non-concealed cells for each waypoint. Initialized as an empty list.

• all_wp_angle_array_dict (dict[np.ndarray]) – Dictionary of arrays representing the cosine of the angle of view for each waypoint. Initialized as an empty list.

• all_time_all_wp_vismap_array_list (list[list[np.ndarray]]) – List of visibility maps for all waypoints at all times. Initialized as an empty list.

• all_wp_non_concealed_cells_xy_idx_dict (dict[tuple[np.ndarray, np.ndarray]]) – Dictionary of indices of non-concealed cells for each waypoint. Initialized as an empty list.

• all_wp_ray_casting_cache_dict (dict[int, RayCastingCache]) – Dictionary storing pre-computed ray casting data (line indices and cell counts) for each waypoint. Initialized as an empty dict.

• min_vis (float) – Minimum local visibility threshold to meet performance criteria. Initialized to 0.

• max_vis (float) – Maximum visibility threshold. Initialized to 30.

• fds_slc_height (float or None) – Height at which the FDS slice is evaluated. Initialized as None.

• background_image (ndarray or None # TODO: Type?) – Background image for the plot. Initialized as None.

• all_time_wp_agg_vismap_list (list[np.ndarray]) – List of waypoint-aggregated visibility maps for all time steps. Initialized as an empty list.

• num_edge_cells (int) – Number of edge cells considered for collision detection. Initialized to 1.

add_background_image(file: str) → None

Load and set a background image for future plots created within this visualization class.

Parameters:

file (str) – Path to the image file that will be used as the background.

add_visual_hole(x1: float, x2: float, y1: float, y2: float) → None

Remove obstructions from a specified rectangular area within the simulation grid.

This is valid for everything affected by the ray tracing algorithms.

Parameters:

• x1 (float) – The x-coordinate of the first corner of the rectangle.

• x2 (float) – The x-coordinate of the opposite corner of the rectangle.

• y1 (float) – The y-coordinate of the first corner of the rectangle.

• y2 (float) – The y-coordinate of the opposite corner of the rectangle.

add_visual_obstruction(x1: float, x2: float, y1: float, y2: float) → None

Add obstructions from a specified rectangular area to the simulation grid.

This is valid for everything affected by the ray tracing algorithms.

Parameters:

• x1 (float) – The x-coordinate of the first corner of the rectangle.

• x2 (float) – The x-coordinate of the opposite corner of the rectangle.

• y1 (float) – The y-coordinate of the first corner of the rectangle.

• y2 (float) – The y-coordinate of the opposite corner of the rectangle.

all_time_all_wp_vismap_array_list: List[List[BoolArray]]

all_time_wp_agg_vismap_list: List[BoolArray]

all_wp_angle_array_dict: Dict[int, FloatArray | int]

all_wp_dict: Dict[int, Waypoint]

all_wp_distance_array_dict: Dict[int, FloatArray]

all_wp_non_concealed_cells_array_dict: Dict[int, BoolArray | int]

all_wp_non_concealed_cells_xy_idx_dict: Dict[int, Tuple[IntArray, IntArray]]

all_wp_ray_casting_cache_dict: Dict[int, RayCastingCache]

all_x_coords: FloatArray

all_y_coords: FloatArray

background_image: np.ndarray

build_help_arrays(obstructions: bool, view_angle: bool, aa: bool) → None

Construct auxiliary arrays used for the comprehensive creation of visibility maps.

Note: If ‘collision’ is False, all cells are considered as non-concealed; if ‘view_angle’ is False, the angle is not factored into visibility calculations.

Parameters:

• obstructions (bool) – Flag indicating whether to consider cells being concealed by obstructions.

• view_angle (bool) – Flag indicating whether to consider view angles from each waypoint.

• aa (bool, optional) – Flag indicating whether antialiasing should be used in the calculation of line-of-sight paths, affecting the smoothness of boundaries.

build_obstructions_array() → None

Construct an obstruction array based on FDS simulation data.

Marks cells in the grid as obstructed based on the obstruction objects defined within the FDS simulation. It takes into account the height of the slice (fds_slc_height) to determine if an obstruction at a given location blocks visibility.

cell_size: Tuple[float, float]

compute_all(t_max: float | None = None, view_angle: bool = True, obstructions: bool = True, aa: bool = True) → None

Execute all required computations to generate aggregated visibility maps over all waypoints and time points.

Parameters:

• t_max (float, optional) – The maximum simulation time to compute up to. If not specified, all available time points are computed.

• view_angle (bool) – Determines if view angles should be considered in the visibility calculations, affecting how visibility is computed relative to the waypoint orientations. Default is True.

• obstructions (bool) – Determines if collisions (obstructions) should be considered, impacting whether certain paths are considered visible based on physical barriers. Default is True.

• aa (bool) – Determines if antialiasing should be applied when computing visibility lines, which can smooth the appearance of the visibility boundaries but might affect computational performance. Default is True.

create_aset_map_plot(max_time: float | None = None, plot_obstructions: bool = False, flip_y_axis: bool = True) → Tuple[Figure, Axes]

Create a plot visualizing the ASET map (Available Safe Egress Time) map indicating for each cell the first time any waypoint is not visible.

Parameters:

• max_time (int, optional) – The maximum time value to consider for the ASET calculations. If None, it defaults to the last time in the visibility data.

• plot_obstructions (bool, optional) – Flag indicating whether obstruction at the evaluation height should be plotted or not.

• flip_y_axis (bool, Default is True.) – Flag indicating whether y-axis should be flipped or not to have the origin at bottom left.

Returns:

A tuple containing the matplotlib figure and axes objects that display the ASET map.

Return type:

(matplotlib.figure.Figure, matplotlib.axes._subplots.AxesSubplot)

create_time_agg_wp_agg_vismap_plot(t_max: float | None = None, plot_obstructions: bool = False, flip_y_axis: bool = True) → Tuple[Figure, Axes]

Create a plot visualizing the time-aggregated visibility map for all waypoints.

The map uses a custom color map to distinguish whether any waypoint is visible (green) or not (red) from each cell. The plot also features the trajectory of movement from the start point through all waypoints, highlighted with annotations for each waypoint.

Parameters:

• t_max (float, optional) – The maximum time to consider. If not specified, all computed time points are used.

• plot_obstructions (bool, optional) – Flag indicating whether obstruction at the evaluation height should be plotted or not.

• flip_y_axis (bool, Default is True.) – Flag indicating whether y-axis should be flipped or not to have the origin at bottom left.

Returns:

A tuple containing the matplotlib figure and axes objects that display the aggregated visibility map.

Return type:

(matplotlib.figure.Figure, matplotlib.axes._subplots.AxesSubplot)

extent: np.ndarray

fds_grid_shape: Tuple[int, int] | None

fds_slc_height: float

fds_time_points: FloatArray

get_aset_map(max_time: float | None = None) → ndarray[tuple[Any, ...], dtype[int64]]

Generate a map indicating the earliest time at which each point becomes non-visible.

Parameters:

max_time (int, optional) – The maximum time to consider. If not specified, the last time in self.times is used.

Returns:

A 2D array where each cell represents the earliest time of non-visibility

for the corresponding point. Cells for points that never become non-visible are set to max_time. :rtype: np.ndarray

get_distance_to_wp(x: float, y: float, waypoint_id: int) → float

Calculate the distance from a specific cell closest to the given x, y coordinates to a designated waypoint.

Parameters:

• x (float) – The x-coordinate of the location from which to measure distance.

• y (float) – The y-coordinate of the location from which to measure distance.

• waypoint_id (int) – The ID of the waypoint to which distance is measured.

Returns:

The distance to the waypoint from the specified location.

Return type:

float

get_extco_array_at_time(time: float) → ndarray[tuple[Any, ...], dtype[float64]]

Get the array of extinction coefficients from the relevant slice file closest to the given time.

Parameters:

time (float) – Time point to be evaluated in seconds.

Returns:

Array of extinction coefficients at the specified time.

Return type:

np.ndarray

get_local_visibility(time: float, x: float, y: float, c: float) → float

Calculate the local visibility at a specific cell closest to the given x, y.

coordinates at a certain time based on local extinction coefficient values.

Parameters:

• time (float) – The simulation time at which to calculate the visibility.

• x (float) – The x-coordinate in the simulation grid where visibility is to be calculated.

• y (float) – The y-coordinate in the simulation grid where visibility is to be calculated.

• c (float) – Contrast factor for exit sign according to Jin

Returns:

The computed local visibility value at the given location and time.

Return type:

float

get_time_agg_wp_agg_vismap(t_max: float | None = None) → ndarray[tuple[Any, ...], dtype[bool]]

Get a time-aggregated and waypoint-aggregated boolean visibility map.

Parameters:

t_max (float, optional) – The maximum time to consider. If not specified, all computed time points are used. Must not exceed the value of t_max passed to compute_all().

Raises:

ValueError – If t_max exceeds the maximum time computed by compute_all().

Returns:

Time-aggregated and waypoint-aggregated boolean visibility map.

Return type:

BoolArray

get_visibility_to_wp(time: float, x: float, y: float, waypoint_id: int) → float

Calculate the visibility at a specific cell closest to the given x, y.

coordinates at a certain time relative to a specific waypoint.

Parameters:

• time (float) – The simulation time at which to calculate the visibility.

• x (float) – The x-coordinate in the simulation grid where visibility is to be calculated.

• y (float) – The y-coordinate in the simulation grid where visibility is to be calculated.

• waypoint_id (int) – The ID of the waypoint to check visibility for.

Returns:

The computed visibility value at the given location and time relative to a specific waypoint..

Return type:

float

get_vismap(waypoint_id: int, time: float) → ndarray[tuple[Any, ...], dtype[bool]]

Generate a boolean vismap for a specific waypoint at a given time.

Parameters:

• waypoint_id (int) – The index of the waypoint for which the visibility map is to be calculated.

• time (float) – The simulation time at which to evaluate visibility.

Returns:

Boolean vismap indicating whether the waypoint can be seen (True) from a specific cell or not (False).

Return type:

np.ndarray

get_wp_agg_vismap(time: float) → ndarray[tuple[Any, ...], dtype[bool]]

Get a waypoint aggregated bool type visibility map for a specific point in time.

Parameters:

time (float) – Timestep for which to calculate the visibility map.

Raises:

ValueError – If time exceeds the maximum time computed by compute_all().

Returns:

Waypoint aggregated bool type visibility map.

Return type:

np.ndarray

max_vis: float

min_vis: float

num_edge_cells: int

obstructions_array: BoolArray

obstructions_collection: Sequence[Any]

quantity: str

read_fds_data(sim_dir: str, fds_slc_height: float = 2.0, fds_slc_id: str | None = None) → None

Read FDS data and store relevant coordinates, shape of the meshgrid, slices and obstructions.

If defined, the relevant slice file is read by ID, otherwise by quantity and closest to given height.

Parameters:

• sim_dir (object) – Directory where FDS simulation data is stored

• fds_slc_id (str) – ID (name) of FDS slice file to be evaluated. Default is None.

• fds_slc_height (float, optional) – The height at which to evaluate visibility. Default is 2.

set_start_point(x: float, y: float) → None

Set the starting point for the route of egress.

Parameters:

• x (float) – x-coordinate of the starting point referring to global FDS coordinates.

• y (float) – y-coordinate of the starting point referring to global FDS coordinates.

set_time_points(time_points: Sequence[float]) → None

Set the times on which the simulation should be evaluated.

Parameters:

time_points (list) – List of time points in the simulation.

set_visibility_bounds(min_vis: float, max_vis: float) → None

Set a lower and upper bound for visibility as a performance criterion.

The lower bound is considered as a local minimum value. :param min_vis: float :type min_vis: Lower limit for local visibility to meet the performance criterion :param max_vis: float :type max_vis: Upper limit for local visibility to be considered

set_waypoint(waypoint_id: int, x: float, y: float, c: int, alpha: int) → None

Add a waypoint along the route of egress.

Parameters:

• waypoint_id (int) – ID of the waypoint to add to the route.

• x (float) – x-coordinate of the waypoint referring to global FDS coordinates.

• y (float) – y-coordinate of the waypoint referring to global FDS coordinates.

• c (int) – Contrast factor for exit sign according to Jin.

• alpha (int) – Orientation angle of the exit sign according to global FDS coordinates.

slc: fds.Simulation.Slice | None

start_point: Tuple[float, float]

vismap_time_points: FloatArray

wp_is_visible(time: float, x: float, y: float, waypoint_id: int) → bool

Determine if a waypoint is visible from a specific cell closest to the given x, y coordinates at a certain time.

Parameters:

• time (float) – The simulation time for which visibility is checked.

• x (float) – The x-coordinate of the location from which visibility is checked.

• y (float) – The y-coordinate of the location from which visibility is checked.

• waypoint_id (int) – The ID of the waypoint to check visibility for.

Raises:

ValueError – If time exceeds the maximum time computed by compute_all().

Returns:

A boolean value indicating whether the specified waypoint is visible from the given location and time.

Return type:

bool

Helper Functions

fdsvismap.helper_functions.count_cells_to_obstruction(line_x: ndarray[tuple[Any, ...], dtype[float64]], line_y: ndarray[tuple[Any, ...], dtype[float64]], obstruction: ndarray[tuple[Any, ...], dtype[float64]]) → int

Calculate the number of cells until the line intersects with an obstruction.

Parameters:

• line_x (np.ndarray) – 1D array of x-coordinates of the line.

• line_y (np.ndarray) – 1D array of y-coordinates of the line.

• obstruction – 2D array representing the obstruction.

Shape (n, 2) where n is the number of obstruction cells, each row containing [x, y] coordinates. :type obstruction: np.ndarray :return: The number of cells until the line intersects with the obstruction, or -1 if there’s no intersection. :rtype: int

fdsvismap.helper_functions.get_id_of_closest_value(values_array: ndarray[tuple[Any, ...], dtype[floating]], value: float) → int

Find the closest point in a given coordinate array to a given value.

Parameters:

• values_array (numpy.ndarray) – An array of values to which the closest value should be found.

• value (float) – The value to find the closest value to.

Returns:

The index of the closest value in an array to a given value.

Return type:

int

Waypoint

class fdsvismap.Waypoint.Waypoint(x: float, y: float, c: float, alpha: int)

Bases: object

A waypoint on the visibility map.

Parameters:

• x (float) – X coordinate of the waypoint referring to global FDS coordinates.

• x – X coordinate of the waypoint referring to global FDS coordinates.

• y (float) – Y coordinate of the waypoint referring to global FDS coordinates.

• c (int) – Contrast factor for exit sign according to JIN.

• alpha (int) – Orientation angle of the exit sign in the global coordinate system.

alpha: int

c: float

x: float

y: float