FDSVismap Module

VisMap

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

class fdsvismap.FDSVisMap.RayCastingCache[source]

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_cells_flat_idx: ndarray[tuple[Any, ...], dtype[int32]]

ray_start_idx: ndarray[tuple[Any, ...], dtype[int64]]

class fdsvismap.FDSVisMap.VisMap[source]

Bases: object

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

One instance holds the smoke field, the obstructions, all safety signs and all routes of egress. A sign has a position, one viewing direction and a contrast factor, its visibility map does not depend on any route and is computed only once (add_sign()). A route is a polyline of waypoints together with the signs that guide along it, which do not have to lie on it (add_route()). From that follow the maps of a route and its coverage, the share of its length from which a sign is visible (get_route_coverage()).

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.
visual_objects (list[tuple[float, float, float, float, bool]]) – Rectangles added with add_visual_obstruction() and add_visual_hole(), as (x1, x2, y1, y2, obstructed). They are applied again whenever the obstruction array is rebuilt.
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, in ascending order. Initialized as an empty array.
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.
all_sign_dict (dict[int or str, Sign]) – Dictionary of all signs by their ID. Initialized as an empty dict.
all_route_dict (dict[int or str, Route]) – Dictionary of all routes by their ID. Initialized as an empty dict.
all_sign_distance_array_dict (dicts[np.ndarray]) – Dictionary of distance arrays between each sign and all cells. Initialized as an empty list.
all_sign_non_concealed_cells_array_dict (dict[np.ndarray]) – Dictionary of arrays indicating non-concealed cells for each sign. Initialized as an empty list.
all_sign_angle_array_dict (dict[np.ndarray]) – Dictionary of arrays representing the cosine of the angle of view for each sign. Initialized as an empty list.
all_time_all_sign_vismap_list (list[list[np.ndarray]]) – List of visibility maps for all signs at all times. Initialized as an empty list.
all_sign_non_concealed_cells_xy_idx_dict (dict[tuple[np.ndarray, np.ndarray]]) – Dictionary of indices of non-concealed cells for each sign. Initialized as an empty list.
all_sign_ray_casting_cache_dict (dict[int, RayCastingCache]) – Dictionary storing pre-computed ray casting data (flat indices of the cells along all rays, start index and cell count of each ray) for each sign. 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.
background_extent (tuple[float, float, float, float] or None) – Position of the background image as (x_min, x_max, y_min, y_max). If None, the image covers the simulation domain.
style (MapStyle) – Colors and opacities of all plots of this instance.
all_time_sign_agg_vismap_list (list[np.ndarray]) – List of sign-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, extent: Tuple[float, float, float, float] | None = None) → None[source]

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.
extent (tuple[float, float, float, float], optional) – Position of the image edges in global FDS coordinates as (x_min, x_max, y_min, y_max). The image may extend beyond the simulation domain. If None, the image covers exactly the simulation domain.

Raises:

ValueError – If the extent is not ordered as (x_min, x_max, y_min, y_max).

Add a route of egress as a polyline of waypoints, together with the signs that guide along it.

The route does not have to pass the signs, it is enough to see them. A sign may belong to several routes, its visibility map is computed only once.

Parameters:

route_id (int or str) – ID of the route, a number or a name such as "B2".
waypoints (array_like) – Waypoints of the route as (x, y) pairs in global FDS coordinates, the first one is the starting point.
signs (list[int or str], optional) – IDs of the signs that belong to the route. If None, all signs added so far belong to it.

Raises:

ValueError – If the route has less than two waypoints or a sign is unknown.

add_sign(sign_id: int | str, x: float, y: float, c: float, alpha: float | None | Literal['omni']) → None[source]

Add a safety sign, whose visibility is evaluated independently of the routes it belongs to.

A sign has exactly one viewing direction, given in the global coordinate system. A sign that two routes approach from different sides is added twice, once per viewing direction.

Parameters:

sign_id (int or str) – ID of the sign, a number or a name such as "NA-NO".
x (float) – x-coordinate of the sign referring to global FDS coordinates.
y (float) – y-coordinate of the sign referring to global FDS coordinates.
c (float) – Contrast factor of the sign according to Jin.
alpha (float or None or str) – Orientation angle of the sign according to global FDS coordinates, measured clockwise from the positive y-axis. "omni" or None for a sign that is visible from all directions.

add_visual_hole(x1: float, x2: float, y1: float, y2: float) → None[source]

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[source]

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_route_dict: Dict[RouteId, Route]

all_sign_angle_array_dict: Dict[SignId, FloatArray | int]

all_sign_dict: Dict[SignId, Sign]

all_sign_distance_array_dict: Dict[SignId, FloatArray]

all_sign_non_concealed_cells_array_dict: Dict[SignId, BoolArray | int]

all_sign_non_concealed_cells_xy_idx_dict: Dict[SignId, Tuple[IntArray, IntArray]]

all_sign_ray_casting_cache_dict: Dict[SignId, RayCastingCache]

all_time_all_sign_vismap_list: List[List[BoolArray]]

all_time_sign_agg_vismap_list: List[BoolArray]

all_x_coords: FloatArray

all_y_coords: FloatArray

background_extent: Tuple[float, float, float, float] | None

background_image: np.ndarray

build_help_arrays(obstructions: bool, view_angle: bool, aa: bool, progress: bool = False) → None[source]

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 sign.
aa (bool, optional) – Flag indicating whether antialiasing should be used in the calculation of line-of-sight paths, affecting the smoothness of boundaries.
progress (bool, optional) – Flag indicating whether a progress bar over the signs is shown. Default is False.

build_obstructions_array() → None[source]

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.

The rectangles of add_visual_obstruction() and add_visual_hole() are applied again afterwards, in the order in which they were added, so that a rebuild does not drop them.

cell_size: Tuple[float, float]

compute_all(t_max: float | None = None, view_angle: bool = True, obstructions: bool = True, aa: bool = True, progress: bool = False) → None[source]

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

The results of previous calls are replaced. Messages about the progress are sent to the logger fdsvismap.FDSVisMap (level INFO per time point, DEBUG per sign), e.g. shown by logging.basicConfig(level=logging.INFO).

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 sign 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.
progress (bool) – Determines if progress bars are shown while the signs are prepared and the vismaps are computed. Default is False.

Raises:

ValueError – If no time points are set, or none of them is up to t_max.

extent: np.ndarray

fds_grid_shape: Tuple[int, int] | None

fds_slc_height: float

fds_time_points: FloatArray

get_agg_vismap(time: float, route_id: int | str | None = None) → ndarray[tuple[Any, ...], dtype[bool]][source]

Get the boolean visibility map at a point in time, aggregated over the signs of a route or over all signs.

A cell is True if at least one of the signs is visible from it.

Parameters:

time (float) – Timestep for which to calculate the visibility map.
route_id (int or str, optional) – ID of the route whose signs are aggregated. If None, all signs are aggregated.

Raises:

ValueError – If time exceeds the maximum time computed by compute_all() or there is no route with this ID.

Returns:

Aggregated boolean visibility map of the shape (ny, nx).

Return type:

np.ndarray

get_aset_map(max_time: float | None = None, route_id: int | str | None = None) → ndarray[tuple[Any, ...], dtype[float64]][source]

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

The times are kept as floats, as get_route_aset() does, so that time points with decimals are neither truncated nor confused with the maximum time.

Parameters:

max_time (float, optional) – The maximum time to consider. If None, the maximum time computed by compute_all() is used.
route_id (int or str, optional) – ID of the route whose signs are considered. If None, all signs are considered.

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_sign(x: float, y: float, sign_id: int | str) → float[source]

Calculate the distance from the given x, y coordinates to a sign.

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.
sign_id (int or str) – The ID of the sign to which distance is measured.

Raises:

ValueError – If there is no sign with this ID.

Returns:

The distance to the sign from the specified location.

Return type:

float

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

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

The slice data of the FDS time steps closest to the time points (see set_time_points()) is read once and kept in memory. Other time steps are read from the FDS output on request, which takes longer for large simulations.

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[source]

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_route_aset(route_id: int | str, max_time: float | None = None) → ndarray[tuple[Any, ...], dtype[float64]][source]

Get for each point of a route the first time at which no sign of the route is visible from it any more.

Parameters:

route_id (int or str) – ID of the route.
max_time (float, optional) – The maximum time to consider. If None, the maximum time computed by compute_all() is used. Points from which a sign is visible up to this time get max_time.

Raises:

ValueError – If there is no route with this ID or max_time exceeds the maximum computed time.

Returns:

Array with one time per point of get_route_points().

Return type:

np.ndarray

get_route_coverage(route_id: int | str, time: float) → ndarray[tuple[Any, ...], dtype[bool]][source]

Get for each point of a route whether at least one sign of the route is visible from it at a point in time.

Parameters:

route_id (int or str) – ID of the route.
time (float) – Time point in seconds, rounded to the closest computed time point.

Raises:

ValueError – If there is no route with this ID or time exceeds the maximum computed time.

Returns:

Boolean array with one value per point of get_route_points().

Return type:

np.ndarray

get_route_points(route_id: int | str) → ndarray[tuple[Any, ...], dtype[float64]][source]

Get the points at which a route is evaluated, sampled along its polyline in the resolution of the grid.

Parameters:: route_id (int or str) – ID of the route.
Raises:: ValueError – If there is no route with this ID.
Returns:: Coordinates of the sampling points of the shape (m, 2).
Return type:: np.ndarray

get_sign_vismap(sign_id: int | str, time: float) → ndarray[tuple[Any, ...], dtype[bool]][source]

Generate the boolean vismap of a single sign at a given time, independently of any route.

Parameters:

sign_id (int or str) – ID of the sign 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 sign can be seen (True) from a specific cell or not (False).

Return type:

np.ndarray

get_time_agg_vismap(t_max: float | None = None, route_id: int | str | None = None) → ndarray[tuple[Any, ...], dtype[bool]][source]

Get the boolean visibility map aggregated over time and over the signs of a route or over all signs.

A cell is True if at least one of the signs is visible from it at every time point.

Parameters:

t_max (float, optional) – The maximum time to consider. If not specified, all time points computed by compute_all() are used, also if it was called with its own t_max.
route_id (int or str, optional) – ID of the route whose signs are aggregated. If None, all signs are aggregated.

Raises:

ValueError – If t_max exceeds the maximum time computed by compute_all() or there is no route with this ID.

Returns:

Time-aggregated boolean visibility map of the shape (ny, nx).

Return type:

np.ndarray

get_visibility_to_sign(time: float, x: float, y: float, sign_id: int | str) → float[source]

Calculate the visibility of a sign at the cell closest to the given x, y coordinates at a certain time.

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.
sign_id (int or str) – The ID of the sign to check visibility for.

Raises:

ValueError – If there is no sign with this ID.

Returns:

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

Return type:

float

max_vis: float

min_vis: float

num_edge_cells: int

obstructions_array: BoolArray

obstructions_collection: Sequence[Any]

plot_aset_map(max_time: float | None = None, plot_obstructions: bool = False, flip_y_axis: bool = True, ax: Axes | None = None, route_id: int | str | None = None, legend: bool = True) → Tuple[Figure, Axes][source]

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

The color scale style.aset_cmap runs from 0 to the maximum time. Cells from which no sign is visible at any time point up to the maximum time are drawn in style.never_visible. For a route, its polyline and its signs are drawn on the map.

Parameters:

max_time (float, 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.
ax (matplotlib.axes.Axes, optional) – Axes to plot into, e.g. a subplot. If None, a new figure is created.
route_id (int or str, optional) – ID of the route whose signs are considered. If None, all signs are considered.
legend (bool, optional) – Flag indicating whether a legend of the route is added. Default is True.

Raises:

ValueError – If there is no route with this ID.

Returns:

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

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

plot_map(map_array: ndarray, cmap: str | Colormap = 'viridis', ax: Axes | None = None, plot_obstructions: bool = False, flip_y_axis: bool = True, alpha: float | None = None, vmin: float | None = None, vmax: float | None = None, colorbar: bool = True, cbar_kwargs: Dict[str, Any] | None = None) → Tuple[Figure, Axes][source]

Plot a map of the simulation domain over the background image.

The axes show the simulation domain. A background image that extends beyond the domain is cut off, use ax.set_xlim and ax.set_ylim to show more of it. A new figure uses the compressed layout of matplotlib, so that legends next to the map fit into it.

Parameters:

map_array (np.ndarray) – Array of the shape (ny, nx), e.g. from get_aset_map() or get_agg_vismap(). Arrays of the shape (nx, ny) such as from get_extco_array_at_time() have to be transposed with .T.
cmap (str or matplotlib.colors.Colormap, optional) – Colormap of the map. Default is ‘viridis’.
ax (matplotlib.axes.Axes, optional) – Axes to plot into, e.g. a subplot. If None, a new figure is created.
plot_obstructions (bool, optional) – Flag indicating whether obstruction at the evaluation height should be plotted or not.
flip_y_axis (bool, optional) – Flag indicating whether y-axis should be flipped or not to have the origin at bottom left.
alpha (float, optional) – Opacity of the map over the background image. If None, style.map_alpha is used.
vmin (float, optional) – Lower limit of the color scale. If None, the minimum of the map is used.
vmax (float, optional) – Upper limit of the color scale. If None, the maximum of the map is used.
colorbar (bool, optional) – Flag indicating whether a colorbar is added. Default is True.
cbar_kwargs (dict, optional) – Keyword arguments for Figure.colorbar, e.g. label or pad. They override the defaults orientation="horizontal" and pad=0.15.

Raises:

RuntimeError – If no FDS data has been read.
ValueError – If the shape of the map does not match the grid.

Returns:

The figure and the axes of the plot.

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

plot_route_vismap(route_id: int | str, time: float, **kwargs: Any) → Tuple[Figure, Axes][source]

Plot the boolean vismap of the signs of a route at a time point together with its coverage.

See plot_vismap().

Parameters:

route_id (int or str) – ID of the route.
time (float) – Time point in seconds.
kwargs – Further keyword arguments of plot_vismap().

Returns:

The figure and the axes of the plot.

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

plot_routes(route_ids: Sequence[int | str] | None = None, ax: Axes | None = None, plot_obstructions: bool = False, flip_y_axis: bool = True, legend: bool = True) → Tuple[Figure, Axes][source]

Plot the routes and the signs over the background image, without any visibility map.

Every route is drawn as a dashed line in style.sign with its starting point, an arrow head at its end and its name along its longest section. The legend names the routes a sign belongs to. The plot shows the input of the evaluation and does not need compute_all().

Parameters:

route_ids (list[int or str], optional) – IDs of the routes to plot. If None, all routes and all signs are plotted, otherwise only the given routes and their signs.
ax (matplotlib.axes.Axes, optional) – Axes to plot into, e.g. a subplot. If None, a new figure is created.
plot_obstructions (bool, optional) – Flag indicating whether obstruction at the evaluation height should be plotted or not.
flip_y_axis (bool, optional) – Flag indicating whether y-axis should be flipped or not to have the origin at bottom left.
legend (bool, optional) – Flag indicating whether a legend of the signs is added. Default is True.

Raises:

RuntimeError – If no FDS data has been read.
ValueError – If there is no route with one of these IDs.

Returns:

The figure and the axes of the plot.

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

plot_sign_vismap(sign_id: int | str, time: float, **kwargs: Any) → Tuple[Figure, Axes][source]

Plot the boolean vismap of a single sign at a time point, see plot_vismap().

Parameters:

sign_id (int or str) – ID of the sign.
time (float) – Time point in seconds.
kwargs – Further keyword arguments of plot_vismap().

Returns:

The figure and the axes of the plot.

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

plot_time_agg_vismap(t_max: float | None = None, plot_obstructions: bool = False, flip_y_axis: bool = True, ax: Axes | None = None, legend: bool = True, route_id: int | str | None = None) → Tuple[Figure, Axes][source]

Create a plot visualizing the time-aggregated visibility map for the signs of a route or for all signs.

The map uses the colors style.visible and style.not_visible to distinguish whether any sign is visible or not from each cell at every time point, both are described by the legend. The route is drawn section by section in the colors of covered and uncovered sections, its signs are marked with their IDs. The contrast factor and the viewing angle of each sign are given in a legend to the right of the map.

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.
ax (matplotlib.axes.Axes, optional) – Axes to plot into, e.g. a subplot. If None, a new figure is created.
legend (bool, optional) – Flag indicating whether a legend is added. Default is True.
route_id (int or str, optional) – ID of the route to plot. If None, the map is aggregated over all signs and no route is drawn.

Raises:

ValueError – If there is no route with this ID.

Returns:

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

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

Plot the boolean vismap at a time point, either of one sign, of a route or aggregated over all signs.

The time is rounded to the closest time point computed by compute_all(). The plot shows the signs with their IDs. The legend to the right of the map is headed by the name of the route, describes the two colors of the map and lists the signs with their contrast factor and viewing angle. For a route, its polyline is drawn section by section in the colors of covered and uncovered sections.

Parameters:

time (float) – Time point in seconds.
sign_id (int or str, optional) – ID of the sign. If None, the vismap of the route or aggregated over all signs is plotted.
ax (matplotlib.axes.Axes, optional) – Axes to plot into, e.g. a subplot. If None, a new figure is created.
plot_obstructions (bool, optional) – Flag indicating whether obstruction at the evaluation height should be plotted or not.
flip_y_axis (bool, optional) – Flag indicating whether y-axis should be flipped or not to have the origin at bottom left.
legend (bool, optional) – Flag indicating whether a legend is added. Default is True.
route_id (int or str, optional) – ID of the route whose signs are aggregated and whose polyline is drawn. If None, all signs are aggregated.

Raises:

RuntimeError – If compute_all() has not been called.
ValueError – If time exceeds the maximum computed time, there is no sign or route with this ID or both a sign and a route are given.

Returns:

The figure and the axes of the plot.

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

quantity: str

read_fds_data(sim_dir: str, fds_slc_height: float = 2.0, fds_slc_id: str | None = None, fds_slc_index: int | None = None) → None[source]

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

If defined, the relevant slice file is read by index or ID, otherwise by quantity as the horizontal slice closest to the given height. The slice data itself is read on first access, see get_extco_array_at_time().

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.
fds_slc_index (int, optional) – Index of the slice in fdsreader.Simulation(sim_dir).slices, as listed in the error message. Selects slices without an ID. Default is None.

Raises:

ValueError – If no matching slice is found. The message lists the available slices.

set_grid(x_coords: Sequence[float], y_coords: Sequence[float], slc_height: float = 2.0) → None[source]

Define the sampling grid without reading an FDS simulation.

Visibility is a property of geometry and smoke, and only the smoke has to come from FDS. A scene that has walls and signs but no fire – a clear-air evacuation model, a unit test – still needs somewhere to evaluate, and this supplies it so the ray casting, view-angle and obstruction handling stay in this library rather than being approximated by every caller.

Pair with set_uniform_extco() for the extinction field and add_visual_obstruction() for the walls. Maps that were computed before are discarded, because they belong to the old grid.

Parameters:

x_coords – Cell-centre x coordinates, ascending.
y_coords – Cell-centre y coordinates, ascending.
slc_height – Height the scene is evaluated at, in metres. Only used to select obstructions by their z range.

Raises:

ValueError – If either coordinate array has fewer than two entries, since a cell size cannot be derived from one.

set_time_points(time_points: Sequence[float]) → None[source]

Set the times on which the simulation should be evaluated.

The time points are sorted in ascending order and duplicates are removed, because the aggregation over time relies on that order. Only the slice data of the FDS time steps closest to these time points is kept in memory.

Parameters:: time_points (list) – Time points in the simulation in seconds, in any order.

set_uniform_extco(extco: float = 0.0, time_points: Sequence[float] | None = None) → None[source]

Use one extinction coefficient everywhere instead of an FDS slice.

extco=0 is clear air, for which get_visibility_to_sign() returns max_vis wherever a sign is in line of sight and within the readable half-plane – the two terms that survive when there is no smoke. A non-zero value models a uniformly smoke-logged scene.

Parameters:

extco – Extinction coefficient in 1/m, applied at every cell.
time_points – Times the scene is defined at. Defaults to the times of set_time_points(), or to [0.0] if none are set; a static field is the same at every time, so one point suffices. Sets the evaluation times as well, so a synthetic scene does not also need set_time_points() before compute_all().

Raises:

ValueError – If extco is negative.

set_visibility_bounds(min_vis: float, max_vis: float) → None[source]

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

sign_is_visible(time: float, x: float, y: float, sign_id: int | str) → bool[source]

Determine if a sign is visible from the 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.
sign_id (int or str) – The ID of the sign to check visibility for.

Raises:

ValueError – If time exceeds the maximum time computed by compute_all() or there is no sign with this ID.

Returns:

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

Return type:

bool

slc: fds.Simulation.Slice | None

style: MapStyle

vismap_time_points: FloatArray

visual_objects: List[Tuple[float, float, float, float, 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[source]

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[source]

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

fdsvismap.helper_functions.get_ids_of_closest_values(values_array: ndarray[tuple[Any, ...], dtype[floating]], values: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[int64]][source]

Find the closest value in a sorted coordinate array for each of many values at once.

Parameters:

values_array (numpy.ndarray) – Array of values in ascending order, e.g. the cell coordinates of one axis.
values (numpy.ndarray) – The values to find the closest values to.

Returns:

The indices of the closest values in the array, one per given value.

Return type:

numpy.ndarray

fdsvismap.helper_functions.progress_bar(iterable: Iterable[T], show: bool, description: str) → Iterable[T][source]

Wrap an iterable in a tqdm progress bar, shown as a widget in Jupyter notebooks.

Parameters:

iterable (Iterable) – The iterable to be wrapped.
show (bool) – Flag indicating whether the progress bar is shown. If False, the iterable is returned unchanged.
description (str) – Description shown in front of the progress bar.

Returns:

The iterable, wrapped in a progress bar if requested.

Return type:

Iterable

Sign

Module defining the Sign data structure for fdsvismap.

class fdsvismap.Sign.Sign(x: float, y: float, c: float, alpha: float | None)[source]

Bases: object

A safety sign, the object whose visibility is evaluated.

A sign has exactly one viewing direction, given in the global coordinate system. It does not depend on the routes the sign belongs to.

Parameters:

x (float) – X coordinate of the sign referring to global FDS coordinates.
y (float) – Y coordinate of the sign referring to global FDS coordinates.
c (float) – Contrast factor of the sign according to Jin.
alpha (float or None) – Orientation angle of the sign according to global FDS coordinates, measured clockwise from the positive y-axis. None means that the sign is visible from all directions.

alpha: float | None

c: float

x: float

y: float

Route

Module defining the Route data structure for fdsvismap.

class fdsvismap.Route.Route(waypoints: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.float64]], signs: ~typing.List[str | int] = <factory>)[source]

Bases: object

A route of egress as a polyline of waypoints, together with the signs that guide along it.

The route does not have to pass the signs, it is enough to see them. Which signs belong to a route follows from the way the route runs, not from the order in which the signs were added.

Parameters:

waypoints (array_like) – Waypoints of the route as (x, y) pairs in global FDS coordinates, the first one is the starting point. They are stored as an array of the shape (n, 2).
signs (list[int or str]) – IDs of the signs that belong to the route.

Raises:

ValueError – If the waypoints are not pairs of coordinates or the route has less than two of them.

property length: float

Get the length of the route along its polyline.

Returns:: Length of the route in meters.
Return type:: float

sample(step: float) → ndarray[tuple[Any, ...], dtype[float64]][source]

Sample the polyline of the route at equidistant points.

The first sampling point is the starting point, the last one the end of the route. The actual distance between the points is at most step.

Parameters:: step (float) – Maximum distance between two sampling points in meters.
Raises:: ValueError – If the step is not positive.
Returns:: Coordinates of the sampling points of the shape (m, 2).
Return type:: np.ndarray

signs: List[str | int]

waypoints: ndarray[tuple[Any, ...], dtype[float64]]

MapStyle

class fdsvismap.MapStyle.MapStyle(not_visible: str = '#dcd9d2', visible: str = '#3f9e5a', sign: str = '#0a5f28', start_point_face: str = 'white', start_point_edge: str = 'black', route_covered: str = '#1b7a3c', route_uncovered: str = '#8f8a83', aset_cmap: str = 'viridis', never_visible: str = '#c6c9de', obstruction: str = '#5a5a5a', obstruction_alpha: float = 0.5, map_alpha: float = 0.7)[source]

Bases: object

Colors and opacities of the map plots of a VisMap.

Each VisMap holds its own instance as vis.style. Change single values, e.g. vis.style.visible = "#2e7d32", or assign a new MapStyle to change all plots of this VisMap. Colors are given in any format matplotlib accepts.

The default colors distinguish cells from which a sign is visible (green) from the others (light, neutral gray) by lightness and saturation, so they remain distinguishable with red-green color vision deficiency.

Parameters:

not_visible (str) – Color of cells from which no sign is visible.
visible (str) – Color of cells from which a sign is visible.
sign (str) – Color of the signs, drawn as a short bar across the viewing direction with an arrow in the viewing direction, and of the route through them.
start_point_face (str) – Fill color of the start point.
start_point_edge (str) – Edge color of the start point.
route_covered (str) – Color of the sections of a route from which a sign of the route is visible. Darker than visible, so that the route stays visible on the map.
route_uncovered (str) – Color of the sections of a route from which no sign of the route is visible. Darker than not_visible, so that the route stays visible on the map.
aset_cmap (str) – Colormap of the ASET map, scaled from 0 to the maximum time.
never_visible (str) – Color of cells in the ASET map from which no sign is visible at any time point. The default is separated from all colors of viridis, also with color vision deficiency.
obstruction (str) – Color of obstructions.
obstruction_alpha (float) – Opacity of obstructions.
map_alpha (float) – Opacity of the maps over the background image.

aset_cmap: str = 'viridis'

map_alpha: float = 0.7

never_visible: str = '#c6c9de'

not_visible: str = '#dcd9d2'

obstruction: str = '#5a5a5a'

obstruction_alpha: float = 0.5

route_covered: str = '#1b7a3c'

route_uncovered: str = '#8f8a83'

sign: str = '#0a5f28'

start_point_edge: str = 'black'

start_point_face: str = 'white'

visible: str = '#3f9e5a'