Radiosity after Kang#

This module contains the implementation of the radiosity algorithm after Kang (2002). It was used to simulate sound propagation in street canyons, where the walls are assumed to be diffusely reflecting. The limitations of the implementation are - it is not optimized for speed - it does not support other patches then parallel or perpendicular relationships - it only supports rectangular patches

This was extended in the sparrowpy.DirectionalRadiosityKang class, which additionally supports directional reflections for surfaces in terms of BRDFs.

References:

Jian Kang, “Sound propagation in street canyons: Comparison between diffusely and geometrically reflecting boundaries,” The Journal of the Acoustical Society of America, vol. 107, no. 3, pp. 1394-1404, Mar. 2000, doi: 10.1121/1.428580.

class sparrowpy.RadiosityKang(walls, patch_size, max_order_k, ir_length_s, speed_of_sound=346.18, sampling_rate=1000, absorption=0.1, source=None)[source]#

Radiosity object simulation.

Methods:

`energy_at_receiver`(receiver[, max_order_k, ...])	Return the energetic impulse response at the receiver.
`from_dict`(input_dict)	Create an object from a dictionary.
`from_read`(filename)	Read the object to a far file.
`run`(source)	Execute the radiosity algorithm.
`to_dict`()	Convert this object to dictionary.
`write`(filename[, compress])	Write the object to a far file.

Attributes:

`ir_length_s`
`max_order_k`
`patch_list`
`patch_size`
`sampling_rate`
`speed_of_sound`

energy_at_receiver(receiver, max_order_k=None, ignore_direct=False)[source]#: Return the energetic impulse response at the receiver.

classmethod from_dict(input_dict: dict)[source]#: Create an object from a dictionary. Used for read write.

classmethod from_read(filename)[source]#: Read the object to a far file.

ir_length_s: float#

max_order_k: int#

patch_list: list[PatchesKang]#

patch_size: float#

run(source)[source]#: Execute the radiosity algorithm.

sampling_rate: int#

speed_of_sound: float#

to_dict() → dict[source]#: Convert this object to dictionary. Used for read write.

write(filename, compress=True)[source]#: Write the object to a far file.

class sparrowpy.PatchesKang(polygon, max_size, other_wall_ids, wall_id, scattering=1, absorption=0.1, sound_attenuation_factor=0, E_matrix=None)[source]#

Class representing patches of a polygon.

Attributes:

`E_matrix`
`E_n_samples`
`E_sampling_rate`
`absorption`
`area`	Return the area in m^2 of the polygon.
`center`	Return the center coordinates of the polygon.
`form_factors`
`max_size`
`n_bins`
`n_points`	Return the number of points of the polygon.
`normal`	Return the normal vector of the polygon.
`other_wall_ids`
`patches`
`pts`
`scattering`
`size`	Return the size in (lxmxn) of the polygon.
`sound_attenuation_factor`
`up_vector`
`wall_id`

Methods:

`calculate_energy_exchange`(patches_list, ...)	Calculate the energy exchange for a given order.
`calculate_form_factor`(patches_list)	Calculate the form factors between patches.
`energy_at_receiver`(max_order, receiver, ...)	Calculate the energy at the receiver.
`from_dict`(input_dict)	Create an object from a dictionary.
`get_form_factor`(patches_list, ...)	Return form factor.
`init_energy_exchange`(max_order_k, ...)	Initialize the energy exchange Matrix with source energy.
`intersection`(origin, direction)	Return a intersection point with a ray and the polygon.
`on_surface`(point)	Return if a point is on the surface of the polygon.
`plot`([ax, color])	Plot the patches.
`plot_point`([ax, color])	Plot the polygon points.
`plot_view_up`([ax])	Plot the view and up vector of the polygon.
`to_dict`()	Convert this object to dictionary.

E_matrix: ndarray#

E_n_samples: int#

E_sampling_rate: int#

absorption: ndarray#

property area: ndarray#: Return the area in m^2 of the polygon. supports all convex polygons and some concave polygons.

calculate_energy_exchange(patches_list, current_order_k, speed_of_sound, E_sampling_rate)[source]#

Calculate the energy exchange for a given order.

It implements formula 18 and save the result in self.E_matrix.

Parameters:

patches_list (list[Patches]) – list of all patches
current_order_k (int) – Order k
speed_of_sound (int, optional) – speed of sound in m/s.
E_sampling_rate (int, optional) – Sampling rate of histogram.

calculate_form_factor(patches_list) → None[source]#

Calculate the form factors between patches.

Parameters:

patches_list (list of patches) – List of patches.
M (float, optional) – Air attenuation factor in Np/m, by default 0
alpha (float, optional) – absorption coefficient of wall, by default 0.1

property center: ndarray#: Return the center coordinates of the polygon.

energy_at_receiver(max_order, receiver, speed_of_sound, sampling_rate)[source]#

Calculate the energy at the receiver.

this is supposed to be from just one wall

Parameters:

max_order (_type_) – _description_
sound_source (_type_) – _description_
receiver (_type_) – _description_
speed_of_sound (float, optional) – _description_
sampling_rate (int, optional) – _description_

Returns:

_description_

Return type:

_type_

form_factors: ndarray#

classmethod from_dict(input_dict: dict)[source]#: Create an object from a dictionary. Used for read write.

get_form_factor(patches_list, source_path_id, receiver_wall_id, receiver_patch_id)[source]#

Return form factor.

Parameters:

patches_list (list of Patches) – patches list
source_path_id (int) – _description_
receiver_wall_id (int) – receiver wall id
receiver_patch_id (_type_) – _description_

Returns:

_description_

Return type:

_type_

init_energy_exchange(max_order_k, ir_length_s, source, sampling_rate, speed_of_sound)[source]#

Initialize the energy exchange Matrix with source energy.

It init the matrix self.E_matrix and add source energy after (6).

Parameters:

max_order_k (int) – max order of energy exchange iterations.
ir_length_s (float) – length of the impulse response in seconds.
source (SoundSource) – sound source with sound_power and position
sampling_rate (int, optional) – Sampling rate of impulse response.
speed_of_sound (float, optional) – speed of sound in m/s.

intersection(origin: ndarray, direction: ndarray) → ndarray#

Return a intersection point with a ray and the polygon.

Parameters:

origin (np.ndarray) – origin of the incoming wave
direction (np.ndarray) – direction of the incoming wave

Returns:

intersection point, if it hit, otherwise None

Return type:

np.ndarray

max_size: float#

n_bins: int#

property n_points: int#: Return the number of points of the polygon.

property normal: ndarray#: Return the normal vector of the polygon.

on_surface(point: ndarray) → bool#

Return if a point is on the surface of the polygon.

Returns True if the point is on the polygon’s surface and false otherwise.

other_wall_ids: list[int]#

patches: list[Polygon]#

plot(ax: Axes = None, color=None)[source]#: Plot the patches.

plot_point(ax: Axes = None, color=None)#: Plot the polygon points.

plot_view_up(ax: Axes = None)#: Plot the view and up vector of the polygon.

pts: ndarray#

scattering: ndarray#

property size: ndarray#: Return the size in (lxmxn) of the polygon.

sound_attenuation_factor: ndarray#

to_dict() → dict[source]#: Convert this object to dictionary. Used for read write.

up_vector: ndarray#

wall_id: int#

class sparrowpy.DirectionalRadiosityKang(polygon_list, patch_size, max_order_k, ir_length_s, sofa_path, speed_of_sound=346.18, sampling_rate=1000, source=None)[source]#

Radiosity object for directional scattering coefficients.

Methods:

`energy_at_receiver`(receiver[, order_k])	Return the energetic impulse response at the receiver.
`from_dict`(input_dict)	Create an object from a dictionary.
`from_read`(filename)	Read the object to a far file.
`run`(source)	Execute the radiosity algorithm.
`to_dict`()	Convert this object to dictionary.
`write`(filename[, compress])	Write the object to a far file.

energy_at_receiver(receiver, order_k=None)[source]#: Return the energetic impulse response at the receiver.

classmethod from_dict(input_dict: dict)[source]#: Create an object from a dictionary. Used for read write.

classmethod from_read(filename)[source]#: Read the object to a far file.

run(source)[source]#: Execute the radiosity algorithm.

to_dict() → dict[source]#: Convert this object to dictionary. Used for read write.

write(filename, compress=True)[source]#: Write the object to a far file.

class sparrowpy.PatchesDirectionalKang(polygon, max_size, other_wall_ids, wall_id, data, sources, receivers, absorption=None, sound_attenuation_factor=None, already_converted=False, E_matrix=None)[source]#

Class representing patches with directional scattering behaviour.

Attributes:

`E_matrix`
`E_n_samples`
`E_sampling_rate`
`absorption`
`area`	Return the area in m^2 of the polygon.
`center`	Return the center coordinates of the polygon.
`directivity_data`
`directivity_receivers`
`directivity_sources`
`form_factors`
`max_size`
`n_bins`
`n_points`	Return the number of points of the polygon.
`normal`	Return the normal vector of the polygon.
`other_wall_ids`
`patches`
`pts`
`scattering`
`size`	Return the size in (lxmxn) of the polygon.
`sound_attenuation_factor`
`up_vector`
`wall_id`

Methods:

`calculate_energy_exchange`(patches_list, ...)	Calculate the energy exchange for a given order.
`calculate_form_factor`(patches_list)	Calculate the form factors between patches.
`energy_at_receiver`(max_order, receiver, ...)	Calculate the energy at the receiver.
`from_dict`(input_dict)	Create an object from a dictionary.
`from_sofa`(polygon, max_size, other_wall_ids, ...)	Create object with directional data from sofa.
`get_form_factor`(patches_list, ...)	Return form factor.
`init_energy_exchange`(max_order_k, ...)	Initialize the energy exchange Matrix with source energy.
`intersection`(origin, direction)	Return a intersection point with a ray and the polygon.
`on_surface`(point)	Return if a point is on the surface of the polygon.
`plot`([ax, color])	Plot the patches.
`plot_point`([ax, color])	Plot the polygon points.
`plot_view_up`([ax])	Plot the view and up vector of the polygon.
`to_dict`()	Convert this object to dictionary.

E_matrix: ndarray#

E_n_samples: int#

E_sampling_rate: int#

absorption: ndarray#

property area: ndarray#: Return the area in m^2 of the polygon. supports all convex polygons and some concave polygons.

calculate_energy_exchange(patches_list, current_order_k, speed_of_sound, E_sampling_rate)[source]#

Calculate the energy exchange for a given order.

It implements formula 18 and save the result in self.E_matrix.

Parameters:

patches_list (list[Patches]) – list of all patches
current_order_k (int) – Order k
speed_of_sound (int, optional) – speed of sound in m/s.
E_sampling_rate (int, optional) – Sampling rate of histogram, e.g. 1000 Hz -> 1ms.

calculate_form_factor(patches_list) → None#

Calculate the form factors between patches.

Parameters:

patches_list (list of patches) – List of patches.
M (float, optional) – Air attenuation factor in Np/m, by default 0
alpha (float, optional) – absorption coefficient of wall, by default 0.1

property center: ndarray#: Return the center coordinates of the polygon.

directivity_data: ndarray#

directivity_receivers: Coordinates#

directivity_sources: Coordinates#

energy_at_receiver(max_order, receiver, speed_of_sound, sampling_rate)[source]#

Calculate the energy at the receiver.

this is supposed to be from just one wall

Parameters:

max_order (int) – max order of energy exchange iterations.
sound_source (SoundSource) – sound source with sound_power and position
receiver (Receiver) – receiver object with position.
speed_of_sound (float, optional) – Speed of sound in m/s.
sampling_rate (int, optional) – _description_, by default 1000

Returns:

_description_

Return type:

_type_

form_factors: ndarray#

classmethod from_dict(input_dict: dict)[source]#: Create an object from a dictionary. Used for read write.

classmethod from_sofa(polygon, max_size, other_wall_ids, wall_id, wall_directivity_path, absorption=None, sound_attenuation_factor=None)[source]#: Create object with directional data from sofa.

get_form_factor(patches_list, source_path_id, receiver_wall_id, receiver_patch_id)#

Return form factor.

Parameters:

patches_list (list of Patches) – patches list
source_path_id (int) – _description_
receiver_wall_id (int) – receiver wall id
receiver_patch_id (_type_) – _description_

Returns:

_description_

Return type:

_type_

init_energy_exchange(max_order_k, ir_length_s, source, sampling_rate, speed_of_sound)[source]#

Initialize the energy exchange Matrix with source energy.

Parameters:

max_order_k (int) – max order of energy exchange iterations.
ir_length_s (float) – length of the impulse response in seconds.
source (SoundSource) – Sound source with sound_power and position
sampling_rate (int) – Sample rate of histogram, by default 1000 -> 1ms
speed_of_sound (float,) – speed of sound in m/s.

intersection(origin: ndarray, direction: ndarray) → ndarray#

Return a intersection point with a ray and the polygon.

Parameters:

origin (np.ndarray) – origin of the incoming wave
direction (np.ndarray) – direction of the incoming wave

Returns:

intersection point, if it hit, otherwise None

Return type:

np.ndarray

max_size: float#

n_bins: int#

property n_points: int#: Return the number of points of the polygon.

property normal: ndarray#: Return the normal vector of the polygon.

on_surface(point: ndarray) → bool#

Return if a point is on the surface of the polygon.

Returns True if the point is on the polygon’s surface and false otherwise.

other_wall_ids: list[int]#

patches: list[Polygon]#

plot(ax: Axes = None, color=None)#: Plot the patches.

plot_point(ax: Axes = None, color=None)#: Plot the polygon points.

plot_view_up(ax: Axes = None)#: Plot the view and up vector of the polygon.

pts: ndarray#

scattering: ndarray#

property size: ndarray#: Return the size in (lxmxn) of the polygon.

sound_attenuation_factor: ndarray#

to_dict() → dict[source]#: Convert this object to dictionary. Used for read write.

up_vector: ndarray#

wall_id: int#