Classes used to build the computational domain

Destination class used to build a destination

class cromosim.domain.Destination(name, colors, excluded_colors=[], desired_velocity_from_color=[], fmm_speed=None, velocity_scale=1, next_destination_choice=None, next_destination=None, next_domain=None, next_destination_weights=None, next_transit_box_xshift=None, next_transit_box_yshift=None, next_transit_box=None)

Bases: object

Represent a target used to guide pedestrians through a domain.

A destination may correspond to a door, a staircase, another floor, or any other target encoded in the domain image. Desired velocities are obtained from a fast-marching travel-time field and may optionally be overridden on pixels of specified colors.

Examples

See cromosim/examples/domain/domain_room.py, cromosim/examples/domain/domain_stadium.py, cromosim/examples/domain/domain_shibuya_crossing.py and cromosim/examples/domain/domain_from_json.py.

Domain class used to build the computational domain

class cromosim.domain.Domain(name='Domain', background='White', pixel_size=1.0, xmin=0.0, width=100, ymin=0.0, height=100, wall_colors=[[0, 0, 0]], npzfile=None)

Bases: object

Represent a two-dimensional computational domain.

A domain is defined by a raster image (or a white image created in memory), its physical pixel size, wall colors, and a set of destinations. Matplotlib shapes may be drawn onto the raster before the domain is built.

The class computes wall-distance fields and destination travel-time fields with a fast-marching method. Their gradients are then used to obtain wall normals and pedestrian desired-velocity directions.

Attributes:

namestr

Domain name.

pixel_sizefloat

Physical size of one image pixel.

width, heightint

Image dimensions in pixels.

xmin, yminfloat

Physical coordinates of the lower-left corner.

xmax, ymaxfloat

Physical coordinates of the upper-right corner.

X, Ynumpy.ndarray

Mesh-grid arrays containing pixel-center coordinates.

imagePIL.Image.Image or numpy.ndarray

Domain image. After build_domain(), it is stored as a NumPy array with the vertical axis flipped so that the origin is at the lower left.

image_red, image_green, image_bluenumpy.ndarray

RGB channels created by build_domain().

wall_colorslist

RGB colors used to identify wall pixels.

wall_masknumpy.ndarray or None

Mask of wall pixels.

wall_idtuple or None

Indices of wall pixels.

wall_distancenumpy.ndarray or None

Distance to the nearest wall.

wall_grad_X, wall_grad_Ynumpy.ndarray or None

Components of the normalized wall-distance gradient.

destinationsdict or None

Destinations registered in the domain.

Methods

add_destination(dest)	Compute and register the fields associated with a destination.
add_shape(shape[, outline_color, fill_color])	Draw a Matplotlib shape onto the domain image.
build_domain()	Finalize the raster representation and compute wall geometry.
compute_wall_distance()	Compute the distance to walls and its normalized gradient.
people_desired_velocity(xyr, people_dest[, ...])	Evaluate desired velocities for a collection of pedestrians.
people_target_distance(xyr, people_dest[, ...])	Evaluate the distance to each pedestrian's current destination.
people_wall_distance(xyr[, II, JJ])	Evaluate the distance from each pedestrian boundary to the nearest wall.
plot([id, title, savefig, filename, dpi])	Plot the computational domain.
plot_desired_velocity(destination_name[, ...])	Plot a destination travel-time field and its desired-velocity directions.
plot_wall_dist([step, scale, scale_units, ...])	Plot the wall-distance field and its gradient.
save(outfile)	Save the domain state to a NumPy .npz archive.

Examples

See cromosim/examples/domain/domain_room.py, cromosim/examples/domain/domain_stadium.py, cromosim/examples/domain/domain_shibuya_crossing.py and cromosim/examples/domain/domain_from_json.py.

add_destination(dest)

Compute and register the fields associated with a destination.

A fast-marching travel-time field is computed outside the destination’s excluded colors. The negative normalized gradient defines the desired velocity direction. Explicit color-based velocity overrides are applied before normalization.

Parameters:

destDestination

Destination to add to the domain.

add_shape(shape, outline_color=[0, 0, 0], fill_color=[255, 255, 255])

Draw a Matplotlib shape onto the domain image.

Supported shapes are Line2D, Circle, Ellipse, Rectangle, and Polygon.

Parameters:

shapematplotlib artist

Shape to draw.

outline_colorsequence of int, optional

RGB outline color.

fill_colorsequence of int, optional

RGB fill color. It is ignored for Line2D objects.

build_domain()

Finalize the raster representation and compute wall geometry.

The current image is saved to "<domain name>_domain.png", converted to a NumPy array with a lower-left origin, and split into RGB channels. Wall pixels are then identified and the wall-distance field is computed.

compute_wall_distance()

Compute the distance to walls and its normalized gradient.

The distance field is evaluated with a fast-marching method using the wall pixels as the zero level set.

people_desired_velocity(xyr, people_dest, II=None, JJ=None)

Evaluate desired velocities for a collection of pedestrians.

Parameters:

xyrnumpy.ndarray

Array with at least four columns [x, y, radius, speed].

people_destarray-like of str

Destination name associated with each pedestrian.

II, JJnumpy.ndarray or None, optional

Precomputed row and column indices in the domain grid.

Returns:

II, JJnumpy.ndarray

Row and column indices used for interpolation by pixel lookup.

Vdnumpy.ndarray

Desired velocities, with shape (n_people, 2).

people_target_distance(xyr, people_dest, II=None, JJ=None)

Evaluate the distance to each pedestrian’s current destination.

Parameters:

xyrnumpy.ndarray

Array containing at least [x, y, radius] for each pedestrian.

people_destarray-like of str

Destination name associated with each pedestrian.

II, JJnumpy.ndarray or None, optional

Precomputed row and column indices in the domain grid.

Returns:

II, JJnumpy.ndarray

Row and column grid indices.

Dnumpy.ndarray

Destination distance minus pedestrian radius.

people_wall_distance(xyr, II=None, JJ=None)

Evaluate the distance from each pedestrian boundary to the nearest wall.

Parameters:

xyrnumpy.ndarray

Array containing at least [x, y, radius] for each pedestrian.

II, JJnumpy.ndarray or None, optional

Precomputed row and column indices in the domain grid.

Returns:

II, JJnumpy.ndarray

Row and column grid indices.

Dnumpy.ndarray

Wall distance minus pedestrian radius.

plot(id=1, title='', savefig=False, filename='fig.png', dpi=150)

Plot the computational domain.

Parameters:

idint, optional

Matplotlib figure number.

titlestr, optional

Figure title.

savefigbool, optional

Save the figure when True.

filenamestr, optional

Output image filename.

dpiint, optional

Resolution of the saved figure.

plot_desired_velocity(destination_name, step=10, scale=10, scale_units='inches', id=1, title='', savefig=False, filename='fig.png', dpi=150)

Plot a destination travel-time field and its desired-velocity directions.

Parameters:

destination_namestr

Name of the destination to display.

stepint, optional

Plot one velocity arrow every step pixels.

scalefloat, optional

Matplotlib quiver scale.

scale_unitsstr, optional

Matplotlib quiver scale units.

idint, optional

Matplotlib figure number.

titlestr, optional

Figure title.

savefigbool, optional

Save the figure when True.

filenamestr, optional

Output image filename.

dpiint, optional

Resolution of the saved figure.

plot_wall_dist(step=10, scale=10, scale_units='inches', id=1, title='', savefig=False, filename='fig.png', dpi=150)

Plot the wall-distance field and its gradient.

Parameters:

stepint, optional

Plot one gradient arrow every step pixels.

scalefloat, optional

Matplotlib quiver scale.

scale_unitsstr, optional

Matplotlib quiver scale units.

idint, optional

Matplotlib figure number.

titlestr, optional

Figure title.

savefigbool, optional

Save the figure when True.

filenamestr, optional

Output image filename.

dpiint, optional

Resolution of the saved figure.

save(outfile)

Save the domain state to a NumPy .npz archive.

Parameters:

outfilestr or path-like

Output filename. NumPy appends .npz when appropriate.