Geometry Module

Additional dependencies

To use the soundevent.geometry module you need to install some additional dependencies. Make sure you have them installed by running the following command:

pip install "soundevent[geometry]"

or, if you are using uv

uv add "soundevent[geometry]"

The soundevent.geometry module provides a comprehensive set of tools for handling the spatial and temporal aspects of sound events. It is organised into several components:

• Matching: Tools for pairing sets of geometries.
• Affinity: Functions to calculate similarity scores (e.g., IoU) between geometries.
• Operations: Core geometric manipulations (shifting, scaling, buffering) and queries.
• Features: Extraction of geometric properties.
• Conversion: Utilities to convert between soundevent geometries and shapely objects.
• Visualisation: Helpers for rendering geometries.

Matching

soundevent.geometry.match

Algorithms for matching geometries.

This module provides tools to match two sets of geometries (e.g., predicted sound events vs. ground truth annotations) based on their similarity or "affinity".

The matching process generally involves three steps:

1. Affinity Computation: Calculating a score (like IoU) between every pair of source and target geometries.
2. Selection: Choosing which pairs constitute a "match" based on a strategy (Optimal vs. Greedy).
3. Thresholding: Discarding matches that have a score below a certain value.

Main Functions

• match_geometries_optimal: Finds the global best set of matches using the Hungarian algorithm.
• match_geometries_greedy: Matches geometries sequentially in the order they appear. This is faster but order-dependent.

Both functions yield tuples of (source_index, target_index, score).

Functions:

Name	Description
match_geometries_greedy	Match geometries using a greedy strategy.
match_geometries_optimal	Match geometries to maximize total affinity.
select_greedy_matches	Select matches greedily based on the row order.
select_optimal_matches	Find the optimal assignment that maximizes the total affinity score.

Attributes

Functions

match_geometries_greedy(source, target, affinity=None, affinity_threshold=0, strict=False)

Match geometries using a greedy strategy.

Parameters:

Name	Type	Description	Default
source	Sequence[Geometry]	The list of source geometries.	required
target	Sequence[Geometry]	The list of target geometries.	required
affinity	ndarray | AffinityFn | None	How to compute the affinity score between geometries. Can be a function or a pre-computed matrix. If None, defaults to geometric IoU.	None
affinity_threshold	float	The minimum score required to consider a match valid.	0
strict	bool	Determines the matching behavior when the best target is already taken: - If False (default), the algorithm finds the next best available target (best available match). - If True, the source is left unmatched (best match or nothing).	False

Yields:

Name	Type	Description
source_index	int or None	The index of the geometry in the source list. Is None if a target geometry remains unmatched.
target_index	int or None	The index of the geometry in the target list. Is None if a source geometry remains unmatched.
score	float	The affinity score between the matched geometries. Returns 0.0 for unmatched items.

Notes

This function iterates through the source list in order. For each geometry, it picks the available target with the highest affinity. Once a target is matched, it cannot be used again.

Because this is done sequentially, the order of the input list matters. A geometry early in the list might match a target that would have been a better match for a geometry later in the list.

match_geometries_optimal(source, target, affinity=None, affinity_threshold=0)

Match geometries to maximize total affinity.

Parameters:

Name	Type	Description	Default
source	Sequence[Geometry]	The list of source geometries.	required
target	Sequence[Geometry]	The list of target geometries.	required
affinity	ndarray | AffinityFn | None	How to compute the affinity score between geometries. Can be a function taking two geometries and returning a float, or a pre-computed affinity matrix. If None, defaults to geometric IoU.	None
affinity_threshold	float	The minimum score required to consider a match valid. Pairs with a score below this will be returned as unmatched. Defaults to 0.	0

Yields:

Name	Type	Description
source_index	int or None	The index of the geometry in the source list. Is None if a target geometry remains unmatched.
target_index	int or None	The index of the geometry in the target list. Is None if a source geometry remains unmatched.
score	float	The affinity score between the matched geometries. Returns 0.0 for unmatched items.

Notes

This function solves the linear assignment problem. It finds the unique set of pairings that maximizes the sum of affinity scores for the entire group. This is computationally more expensive than greedy matching but ensures the best global result.

select_greedy_matches(affinity_matrix, strict=False, threshold=0)

Select matches greedily based on the row order.

Parameters:

Name	Type	Description	Default
affinity_matrix	ndarray	A 2D array of scores where rows represent sources and columns represent targets.	required
strict	bool	Determines the matching behavior when the best column is already taken: - If False (default), the algorithm finds the next best available column (best available match). - If True, the row is left unmatched (best match or nothing).	False
threshold	float	The lower bound for a valid match. Matches with affinity less than or equal to this value are discarded. Defaults to 0 (discarding zero-affinity matches).	0

Yields:

Name	Type	Description
row_index	int or None	The row index. If None, this indicates a leftover column that was not matched.
col_index	int or None	The column index. If None, this indicates a row that could not be matched.
affinity_score	float	The affinity score between the matched rows and columns. Returns 0 for unmatched items.

Notes

This algorithm iterates over rows 0 to N. Because matches are consumed greedily, the order of the rows in the input matrix affects the outcome.

select_optimal_matches(affinity_matrix, threshold=0)

Find the optimal assignment that maximizes the total affinity score.

Parameters:

Name	Type	Description	Default
affinity_matrix	ndarray	A 2D array where M[i, j] represents the score/affinity between row i and column j.	required

Yields:

Name	Type	Description
row_index	int or None	The row index (source).
col_index	int or None	The column index (target).
affinity_score	float	The affinity score between the matched rows and columns. Returns 0 for unmatched items.

Notes

This functions uses the Jonker-Volgenant algorithm via SciPy's [linear_sum_assignment][scipy.optimize.linear_sum_assignment].

Affinity & Similarity

soundevent.geometry.affinity

Measures of affinity between geometries.

Functions:

Name	Description
compute_bbox_iou	Compute the IoU of the bounding boxes of two geometries.
compute_frequency_iou	Compute the IoU of the frequency extents of two geometries.
compute_geometric_iou	Compute the IoU of two geometries.
compute_spectral_closeness	Compute the proximity of two geometries in frequency.
compute_temporal_closeness	Compute the proximity of two geometries in time.
compute_temporal_iou	Compute the IoU of the temporal extents of two geometries.

Attributes:

Name	Type	Description
AffinityFn		Type for functions that compute similarity scores between geometries.

Attributes

AffinityFn = Callable[[data.Geometry, data.Geometry], float] module-attribute

Type for functions that compute similarity scores between geometries.

Functions

compute_bbox_iou(geometry1, geometry2)

Compute the IoU of the bounding boxes of two geometries.

Parameters:

Name	Type	Description	Default
geometry1	Geometry	The first geometry object.	required
geometry2	Geometry	The second geometry object.	required

Returns:

Type	Description
float	The IoU score, a value between 0.0 and 1.0.

Notes

This function compares the bounding boxes of the geometries, not the exact shapes. For example, if you compare two diagonal lines that cross each other, their exact overlap might be small, but their bounding boxes might overlap significantly. This makes this function a fast, "coarse" filter for similarity. If you want to compute the true geometric IoU, use the compute_geometric_iou function.

Unlike compute_bbox_area, the IoU is a ratio and therefore scale-invariant. Stretching the frequency or temporal axis does not change the ratio of overlap. Hence, no scaling is required before computing the IoU.

compute_frequency_iou(geometry1, geometry2)

Compute the IoU of the frequency extents of two geometries.

Parameters:

Name	Type	Description	Default
geometry1	Geometry	The first geometry object.	required
geometry2	Geometry	The second geometry object.	required

Returns:

Type	Description
float	The IoU score, a value between 0.0 and 1.0.

Notes

This function projects the geometries onto the frequency axis and computes the Intersection over Union of the resulting frequency intervals (bandwidths).

This metric ignores the time component completely. Two events with the same pitch range will have a score of 1.0, even if they occur at completely different times in the recording.

compute_geometric_iou(geometry1, geometry2)

Compute the IoU of two geometries.

This function calculates the geometric similarity between two geometries, which is a measure of how much they overlap. The affinity is computed as the Intersection over Union (IoU).

IoU is a standard metric for comparing the similarity between two shapes. It is calculated as the ratio of the area of the overlap between the two geometries to the area of their combined shape.

\[ \text{IoU} = \frac{\text{Area of Overlap}}{\text{Area of Union}} \]

An IoU of 1 means the geometries are identical, while an IoU of 0 means they do not overlap at all.

Parameters:

Name	Type	Description	Default
geometry1	Geometry	The first geometry to be compared.	required
geometry2	Geometry	The second geometry to be compared.	required

Returns:

Name	Type	Description
affinity	float	The Intersection over Union (IoU) score, a value between 0 and 1 indicating the degree of overlap.

Examples:

>>> from soundevent.geometry import compute_geometric_iou
>>> geometry1 = data.BoundingBox(coordinates=[0.4, 2000, 0.6, 8000])
>>> geometry2 = data.BoundingBox(coordinates=[0.5, 5000, 0.7, 6000])
>>> affinity = compute_geometric_iou(geometry1, geometry2)
>>> print(round(affinity, 3))
0.077

compute_spectral_closeness(geometry1, geometry2, ratio=0, max_distance=1000)

Compute the proximity of two geometries in frequency.

Parameters:

Name	Type	Description	Default
geometry1	Geometry	The first geometry object.	required
geometry2	Geometry	The second geometry object.	required
ratio	float	The relative frequency point to compare (0.0 to 1.0). Defaults to 0 (compares lowest frequencies). Use 0.5 to compare center frequencies.	0
max_distance	float	The maximum frequency distance (in Hertz) allowed for a non-zero score. Defaults to 1000 Hz.	1000

Returns:

Type	Description
float	A closeness score between 0.0 and 1.0. * 1.0: The frequency points are identical. * 0.0: The distance is greater than or equal to max_distance. * 0.0 < x < 1.0: Linearly decays as distance increases.

Notes

This function measures the absolute distance between the specific frequency points derived from the ratio. The score decays linearly from 1 to 0 as the distance grows from 0 to max_distance.

compute_temporal_closeness(geometry1, geometry2, ratio=0, max_distance=0.1)

Compute the proximity of two geometries in time.

Parameters:

Name	Type	Description	Default
geometry1	Geometry	The first geometry object.	required
geometry2	Geometry	The second geometry object.	required
ratio	float	The relative time point to compare (0.0 to 1.0). Defaults to 0 (compares start times). Use 0.5 to compare temporal centers.	0
max_distance	float	The maximum time distance (in seconds) allowed for a non-zero score. Defaults to 0.1.	0.1

Returns:

Type	Description
float	A closeness score between 0.0 and 1.0. * 1.0: The time points are identical. * 0.0: The distance is greater than or equal to max_distance. * 0.0 < x < 1.0: Linearly decays as distance increases.

Notes

This function measures the absolute distance between the specific time points derived from the ratio. The score decays linearly from 1 to 0 as the distance grows from 0 to max_distance.

compute_temporal_iou(geometry1, geometry2)

Compute the IoU of the temporal extents of two geometries.

Parameters:

Name	Type	Description	Default
geometry1	Geometry	The first geometry object.	required
geometry2	Geometry	The second geometry object.	required

Returns:

Type	Description
float	The IoU score, a value between 0.0 and 1.0.

Notes

This function projects the geometries onto the time axis and computes the Intersection over Union of the resulting time intervals.

This metric ignores the frequency content completely. Two events occurring at the exact same time will have a score of 1.0, even if one is low frequency and the other is high frequency.

Geometric Operations

soundevent.geometry.operations

Functions that handle SoundEvent geometries.

Functions:

Name	Description
buffer_geometry	Buffer a geometry.
compute_bbox_area	Compute the area of a bounding box.
compute_bounds	Compute the bounds of a geometry.
compute_interval_overlap	Compute the length of the overlap between two intervals.
compute_interval_width	Compute the width of an interval.
get_geometry_point	Calculate the coordinates of a specific point within a geometry.
get_point_in_frequency	Compute a specific frequency point relative to the geometry's bandwidth.
get_point_in_time	Compute a specific time point relative to the geometry's duration.
group_sound_events	Group sound events into sequences based on a pairwise comparison.
have_frequency_overlap	Check if two geometries have frequency overlap.
have_temporal_overlap	Check if two geometries have temporal overlap.
intervals_overlap	Check if two intervals overlap.
is_in_clip	Check if a geometry lies within a clip, considering a minimum overlap.
rasterize	Rasterize geometric objects into an xarray DataArray.
scale_geometry	Scale a geometry by a given time and frequency factor.
shift_geometry

Attributes

Positions = Literal['bottom-left', 'bottom-right', 'top-left', 'top-right', 'center-left', 'center-right', 'top-center', 'bottom-center', 'center', 'centroid', 'point_on_surface'] module-attribute

Value = float | int module-attribute

Classes

Functions

buffer_bounding_box_geometry(geometry, time_buffer=0, freq_buffer=0)

Buffer a BoundingBox geometry.

Parameters:

Name	Type	Description	Default
geometry	BoundingBox	The geometry to buffer.	required
time_buffer	Time	The time buffer to apply to the geometry, in seconds. Defaults to 0.	0
freq_buffer	Frequency	The frequency buffer to apply to the geometry, in Hz. Defaults to 0.	0

Returns:

Name	Type	Description
geometry	BoundingBox	The buffered geometry.

buffer_geometry(geometry, time_buffer=0, freq_buffer=0, **kwargs)

Buffer a geometry.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry to buffer.	required
time_buffer	Time	The time buffer to apply to the geometry, in seconds. Defaults to 0.	0
freq_buffer	Frequency	The frequency buffer to apply to the geometry, in Hz. Defaults to 0.	0
**kwargs	Any	Additional keyword arguments to pass to the Shapely buffer function.	{}

Returns:

Name	Type	Description
geometry	Geometry	The buffered geometry.

Raises:

Type	Description
NotImplementedError	If the geometry type is not supported.
ValueError	If the time buffer or the frequency buffer is negative.

buffer_interval(geometry, time_buffer=0)

Buffer a TimeInterval geometry.

Parameters:

Name	Type	Description	Default
geometry	TimeInterval	The geometry to buffer.	required
time_buffer	Time	The time buffer to apply to the geometry, in seconds. Defaults to 0.	0

Returns:

Name	Type	Description
geometry	TimeInterval	The buffered geometry.

buffer_shapely_geometry(geometry, time_buffer=0, freq_buffer=0, **kwargs)

Buffer a shapely geometry.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry to buffer.	required
time_buffer	Time	The time buffer to apply to the geometry, in seconds. Defaults to 0.	0
freq_buffer	Frequency	The frequency buffer to apply to the geometry, in Hz. Defaults to 0.	0

Returns:

Name	Type	Description
geometry	Geometry	The buffered geometry.

buffer_timestamp(geometry, time_buffer=0)

Buffer a TimeStamp geometry.

Parameters:

Name	Type	Description	Default
geometry	TimeStamp	The geometry to buffer.	required
time_buffer	Time	The time buffer to apply to the geometry, in seconds. Defaults to 0.	0

Returns:

Name	Type	Description
geometry	TimeInterval	The buffered geometry.

compute_bbox_area(bbox)

Compute the area of a bounding box.

Parameters:

Name	Type	Description	Default
bbox	tuple[float, float, float, float]	The bounding box coordinates. The expected format is a tuple of four floats: (start_time, low_freq, end_time, high_freq).	required

Returns:

Type	Description
float	The computed area of the bounding box (duration × bandwidth).

Notes

Because time and frequency usually have different units (e.g., seconds vs. Hertz), the calculated "area" mixes these dimensions.

In practice, frequency values (often in the thousands) are much larger than time values (often small floats). This means the frequency dimension usually dominates the area calculation. To ensure both dimensions contribute equally, it is recommended to use the scale_geometry function to balance the coordinates before computing the area.

compute_bounds(geometry)

Compute the bounds of a geometry.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry to compute the bounds of.	required

Returns:

Name	Type	Description
bounds	tuple[float, float, float, float]	The bounds of the geometry. The bounds are returned in the following order: start_time, low_freq, end_time, high_freq.

compute_interval_overlap(interval1, interval2)

Compute the length of the overlap between two intervals.

Parameters:

Name	Type	Description	Default
interval1	tuple[float, float]	The first interval, as a tuple (start, stop).	required
interval2	tuple[float, float]	The second interval, as a tuple (start, stop).	required

Returns:

Type	Description
float	The length of the overlap between the two intervals. If there is no overlap, the function returns 0.0.

Raises:

Type	Description
ValueError	If intervals are not well-formed, i.e. start is greater than stop.

Examples:

>>> compute_interval_overlap((0, 2), (1, 3))
1.0
>>> compute_interval_overlap((0, 1), (1, 2))
0.0
>>> compute_interval_overlap((0, 1), (2, 3))
0.0

compute_interval_width(interval)

Compute the width of an interval.

Parameters:

Name	Type	Description	Default
interval	tuple[float, float]	The interval to compute the width of. The expected format is a tuple of two floats: (start, end).	required

Returns:

Type	Description
float	The computed width of the interval.

Notes

If the start time is greater than the end time, the function swaps the start and end times before computing the width.

get_geometry_point(geometry, position='bottom-left')

Calculate the coordinates of a specific point within a geometry.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry object for which to calculate the point coordinates.	required
position	Positions	The specific point within the geometry to calculate coordinates for. Defaults to 'bottom-left'.	'bottom-left'

Returns:

Type	Description
Tuple[float, float]	The coordinates of the specified point within the geometry.

Raises:

Type	Description
ValueError	If an invalid point is specified.

Notes

The following positions are supported:

• 'bottom-left': The point defined by the start time and lowest frequency of the geometry.
• 'bottom-right': The point defined by the end time and lowest frequency of the geometry.
• 'top-left': The point defined by the start time and highest frequency of the geometry.
• 'top-right': The point defined by the end time and highest frequency of the geometry.
• 'center-left': The point defined by the middle time and lowest frequency of the geometry.
• 'center-right': The point defined by the middle time and highest frequency of the geometry.
• 'top-center': The point defined by the end time and middle frequency of the geometry.
• 'bottom-center': The point defined by the start time and middle frequency of the geometry.
• 'center': The point defined by the middle time and middle frequency of the geometry.
• 'centroid': The centroid of the geometry. Computed using the shapely library.
• 'point_on_surface': A point on the surface of the geometry. Computed using the shapely library.

For all positions except 'centroid' and 'point_on_surface', the time and frequency values are calculated by first computing the bounds of the geometry and then determining the appropriate values based on the specified point type.

get_point_in_frequency(geometry, ratio=0)

Compute a specific frequency point relative to the geometry's bandwidth.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry object.	required
ratio	float	The relative position within the frequency interval (0.0 to 1.0). Defaults to 0.	0

Returns:

Type	Description
float	The calculated frequency in Hertz.

Raises:

Type	Description
ValueError	If the ratio is not between 0 and 1.

Notes

This function projects the geometry onto the frequency axis (finding the bounding box) and selects a point based on the provided ratio using linear interpolation:

freq = low_freq + ratio * (high_freq - low_freq)

Common Ratios

• 0.0: Returns the lowest frequency component.
• 0.5: Returns the center frequency (midpoint).
• 1.0: Returns the highest frequency component.

get_point_in_time(geometry, ratio=0)

Compute a specific time point relative to the geometry's duration.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry object.	required
ratio	float	The relative position within the time interval (0.0 to 1.0). Defaults to 0.	0

Returns:

Type	Description
float	The calculated timestamp in seconds.

Raises:

Type	Description
ValueError	If the ratio is not between 0 and 1.

Notes

This function projects the geometry onto the time axis (finding the bounding box) and selects a point based on the provided ratio using linear interpolation:

time = start_time + ratio * (end_time - start_time)

Common Ratios

• 0.0: Returns the start time (onset) of the event.
• 0.5: Returns the temporal center (midpoint) of the event.
• 1.0: Returns the end time (offset) of the event.

group_sound_events(sound_events, comparison_fn)

Group sound events into sequences based on a pairwise comparison.

This function takes a sequence of data.SoundEvent objects and a comparison function. It applies the comparison function to all pairs of sound events to determine their similarity. Sound events that are deemed similar are grouped together into data.Sequence objects.

The comparison function should take two data.SoundEvent objects as input and return True if they are considered similar, and False otherwise.

Parameters:

Name	Type	Description	Default
sound_events	Sequence[SoundEvent]	A sequence of data.SoundEvent objects to be grouped.	required
comparison_fn	Callable[[SoundEvent, SoundEvent], bool]	A function that compares two data.SoundEvent objects and returns True if they should be grouped together, False otherwise.	required

Returns:

Type	Description
list[Sequence]	A list of data.Sequence objects, where each sequence contains a group of similar sound events.

Notes

This function groups sound events based on transitive similarity. While it uses pairwise comparisons, the final groups (sequences) can include sound events that aren't directly similar according to your comparison_fn. Think of it like a chain: sound event A is similar to B, B is similar to C, but A might not be similar to C directly. They all end up in the same group because of their connections through B. Technically, this works by finding the connected components in a graph where the sound events are nodes, and the edges represent similarity based on your comparison_fn.

Examples:

>>> from soundevent import data
>>> from pathlib import Path
>>> recording = data.Recording(
...     path=Path("example.wav"),
...     duration=60,
...     samplerate=44100,
...     channels=1,
... )
>>> sound_events = [
...     data.SoundEvent(
...         geometry=data.BoundingBox(coordinates=[0, 1000, 1, 2000]),
...         recording=recording,
...     ),
...     data.SoundEvent(
...         geometry=data.BoundingBox(coordinates=[0.8, 800, 1.2, 1600]),
...         recording=recording,
...     ),
...     data.SoundEvent(
...         geometry=data.BoundingBox(coordinates=[8, 900, 9.3, 1500]),
...         recording=recording,
...     ),
... ]
>>> # Define a comparison function based on temporal overlap
>>> def compare_sound_events(se1, se2):
...     return have_temporal_overlap(
...         se1.geometry, se2.geometry, min_absolute_overlap=0.5
...     )
>>> # Group sound events with the comparison function
>>> sequences = group_sound_events(sound_events, compare_sound_events)

have_frequency_overlap(geom1, geom2, min_absolute_overlap=0, min_relative_overlap=None)

Check if two geometries have frequency overlap.

This function determines whether two geometry objects have any frequency overlap, optionally considering a minimum required overlap, either in absolute terms (Hz) or relative to the smaller frequency range of the two geometries.

Parameters:

Name	Type	Description	Default
geom1	Geometry	The first geometry object.	required
geom2	Geometry	The second geometry object.	required
min_absolute_overlap	float	The minimum required absolute overlap in Hz. Defaults to 0, meaning any positive overlap is sufficient (touching intervals are not considered overlapping).	0
min_relative_overlap	float	The minimum required relative overlap (between 0 and 1). Defaults to None.	None

Returns:

Type	Description
bool	True if the geometries overlap with the specified minimum overlap, False otherwise.

Raises:

Type	Description
ValueError	If both min_absolute_overlap (> 0) and min_relative_overlap are provided. If min_relative_overlap is not in the range [0, 1].

have_temporal_overlap(geom1, geom2, min_absolute_overlap=0, min_relative_overlap=None)

Check if two geometries have temporal overlap.

This function determines whether two geometry objects have any time overlap, optionally considering a minimum required overlap, either in absolute terms (seconds) or relative to the shorter duration of the two geometries.

Parameters:

Name	Type	Description	Default
geom1	Geometry	The first geometry object.	required
geom2	Geometry	The second geometry object.	required
min_absolute_overlap	float	The minimum required absolute overlap in seconds. Defaults to 0, meaning any positive overlap is sufficient (touching intervals are not considered overlapping).	0
min_relative_overlap	float	The minimum required relative overlap (between 0 and 1). Defaults to None.	None

Returns:

Type	Description
bool	True if the geometries overlap with the specified minimum overlap, False otherwise.

Raises:

Type	Description
ValueError	If both min_absolute_overlap (> 0) and min_relative_overlap are provided. If min_relative_overlap is not in the range [0, 1].

intervals_overlap(interval1, interval2, min_relative_overlap=None, min_absolute_overlap=0)

Check if two intervals overlap.

This function determines whether two intervals, represented as tuples of (start, stop) values, overlap. An overlap is considered to occur if the length of the intersection of the two intervals is strictly greater than a specified threshold.

By default, touching intervals are not considered overlapping.

Parameters:

Name	Type	Description	Default
interval1	tuple[float, float]	The first interval, as a tuple (start, stop).	required
interval2	tuple[float, float]	The second interval, as a tuple (start, stop).	required
min_absolute_overlap	float	The minimum required absolute overlap. The overlap must be strictly greater than this value. Defaults to 0.	0
min_relative_overlap	float	The minimum required relative overlap with respect to the shorter of the two intervals. The overlap must be strictly greater than the computed threshold. The value must be in the range [0, 1]. Defaults to None.	None

Returns:

Type	Description
bool	True if the intervals overlap with the specified minimum overlap, False otherwise.

Raises:

Type	Description
ValueError	If both min_absolute_overlap > 0 and min_relative_overlap are provided. If min_relative_overlap is not in the range [0, 1].

is_in_clip(geometry, clip, minimum_overlap=0)

Check if a geometry lies within a clip, considering a minimum overlap.

This function determines whether a given geometry falls within the time boundaries of a clip. It takes into account a minimum_overlap parameter, which specifies the minimum required temporal overlap (in seconds) between the geometry and the clip for the geometry to be considered inside the clip.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry object to be checked.	required
clip	Clip	The clip object to check against.	required
minimum_overlap	float	The minimum required overlap between the geometry and the clip in seconds. Defaults to 0, meaning any overlap is sufficient.	0

Returns:

Type	Description
bool	True if the geometry is within the clip with the specified minimum overlap, False otherwise.

Raises:

Type	Description
ValueError	If the minimum_overlap is negative.

Examples:

>>> from soundevent import data
>>> from pathlib import Path
>>> recording = data.Recording(
...     path=Path("example.wav"),
...     samplerate=44100,
...     duration=60,
...     channels=1,
... )
>>> geometry = data.BoundingBox(coordinates=[4, 600, 4.8, 1200])
>>> clip = data.Clip(start_time=0.0, end_time=5.0, recording=recording)
>>> is_in_clip(geometry, clip, minimum_overlap=0.5)
True

rasterize(geometries, array, values=1, fill=0, dtype=np.float32, xdim=Dimensions.time.value, ydim=Dimensions.frequency.value, all_touched=False)

Rasterize geometric objects into an xarray DataArray.

This function takes a list of geometric objects (geometries) and rasterizes them into a specified xr.DataArray. Each geometry can be associated with a value, which is used to fill the corresponding pixels in the rasterized array.

Parameters:

Name	Type	Description	Default
geometries	list[Geometry]	A list of Geometry objects to rasterize.	required
array	DataArray	The xarray DataArray into which the geometries will be rasterized.	required
values	Value | list[Value] | tuple[Value]	The values to fill the rasterized pixels for each geometry. If a single value is provided, it will be used for all geometries. If a list or tuple of values is provided, it must have the same length as the geometries list. Defaults to 1.	1
fill	float	The value to fill pixels not covered by any geometry. Defaults to 0.	0
dtype	DTypeLike	The data type of the output rasterized array. Defaults to np.float32.	float32
xdim	str	The name of the dimension representing the x-axis in the DataArray. Defaults to "time".	time.value
ydim	str	The name of the dimension representing the y-axis in the DataArray. Defaults to "frequency".	frequency.value
all_touched	bool	If True, all pixels touched by geometries will be filled, otherwise only pixels whose center point is within the geometry are filled. Defaults to False.	False

Returns:

Type	Description
DataArray	A new xarray DataArray containing the rasterized data, with the same coordinates and dimensions as the input array.

Raises:

Type	Description
ValueError	If the number of values does not match the number of geometries.

scale_geometry(geom, time=1, freq=1, time_anchor=0, freq_anchor=0)

Scale a geometry by a given time and frequency factor.

The scaling is performed with respect to an anchor point. The formula for scaling a value val is (val - anchor) * factor + anchor.

Parameters:

Name	Type	Description	Default
geom	Geometry	The geometry to scale.	required
time	float	The time factor to apply to the geometry. Defaults to 1.	1
freq	float	The frequency factor to apply to the geometry. Defaults to 1.	1
time_anchor	float	The time anchor to use for scaling, in seconds. Defaults to 0.	0
freq_anchor	float	The frequency anchor to use for scaling, in Hz. Defaults to 0.	0

Returns:

Type	Description
Geometry	The scaled geometry.

scale_value(val, factor=1, anchor=0)

shift_geometry(geom, time=0, freq=0)

Features

soundevent.geometry.features

Compute sound event features from geometries.

This module contains functions to compute sound event features from their geometries. These are simple yet useful features that provide a first glance of the sound event.

These features are directly computed from the geometry, and do not depend on the audio signal nor the spectrogram.

The computed features are:

• duration: The duration of the sound event, in seconds.
• low_freq: The lowest frequency of the sound event, in Hz.
• high_freq: The highest frequency of the sound event, in Hz.
• bandwidth: The bandwidth of the sound event, in Hz.
• num_segments: The number of segments of the sound event.

Some of these features are not applicable to all geometries, as they require information not present in the geometry. However the function compute_geometric_features will compute all the features that are applicable to the given geometry and return them in a list.

Examples:

To compute the features of a bounding box:

>>> from soundevent import data, terms
>>> geometry = data.BoundingBox(
...     coordinates=(0, 0, 1, 1000),
... )
>>> compute_geometric_features(geometry)
[Feature(term=Term(label='Media Duration'), value=1.0), Feature(term=Term(label='Lower frequency bound'), value=0.0), Feature(term=Term(label='Upper frequency bound'), value=1000.0), Feature(term=Term(label='Bandwidth'), value=1000.0)]

Functions:

Name	Description
compute_geometric_features	Compute features from a geometry.

Classes

Functions

compute_geometric_features(geometry)

Compute features from a geometry.

Some basic acoustic features can be computed from a geometry. This function computes these features and returns them as a list of features.

The following features are computed when possible:

• duration: The duration of the geometry.
• low_freq: The lowest frequency of the geometry.
• high_freq: The highest frequency of the geometry.
• bandwidth: The bandwidth of the geometry.
• num_segments: The number of segments in the geometry.

Depending on the geometry type, some features may not be computed. For example, a TimeStamp geometry does not have a bandwidth.

Parameters:

Name	Type	Description	Default
geometry	Geometry	The geometry to compute features from.	required

Returns:

Type	Description
List[Feature]	The computed features.

Raises:

Type	Description
NotImplementedError	If the geometry type is not supported.

Conversion

soundevent.geometry.conversion

Convert Geometry objects into shapely objects and vice versa.

Functions:

Name	Description
geometry_to_shapely	Convert a Geometry to a shapely geometry.
shapely_to_geometry	Convert a shapely geometry to a soundevent geometry.

Functions

bounding_box_to_shapely(geom)

Convert a BoundingBox to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	BoundingBox	The BoundingBox geometry to convert.	required

Returns:

Type	Description
Polygon	The converted shapely geometry.

geometry_to_shapely(geom)

geometry_to_shapely(
    geom: data.TimeStamp,
) -> shapely.LineString

geometry_to_shapely(
    geom: data.TimeInterval,
) -> shapely.Polygon

geometry_to_shapely(geom: data.Point) -> shapely.Point

geometry_to_shapely(
    geom: data.LineString,
) -> shapely.LineString

geometry_to_shapely(geom: data.Polygon) -> shapely.Polygon

geometry_to_shapely(
    geom: data.BoundingBox,
) -> shapely.Polygon

geometry_to_shapely(
    geom: data.MultiPoint,
) -> shapely.MultiPoint

geometry_to_shapely(
    geom: data.MultiLineString,
) -> shapely.MultiLineString

geometry_to_shapely(
    geom: data.MultiPolygon,
) -> shapely.MultiPolygon

Convert a Geometry to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	Geometry	The Geometry to convert.	required

Returns:

Type	Description
Geometry	The converted shapely geometry.

linestring_to_shapely(geom)

Convert a LineString to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	LineString	The LineString geometry to convert.	required

Returns:

Type	Description
LineString	The converted shapely geometry.

multilinestring_to_shapely(geom)

Convert a MultiLineString to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	MultiLineString	The MultiLineString geometry to convert.	required

Returns:

Type	Description
MultiLineString	The converted shapely geometry.

multipoint_to_shapely(geom)

Convert a MultiPoint to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	MultiPoint	The MultiPoint geometry to convert.	required

Returns:

Type	Description
MultiPoint	The converted shapely geometry.

multipolygon_to_shapely(geom)

Convert a MultiPolygon to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	MultiPolygon	The MultiPolygon geometry to convert.	required

Returns:

Type	Description
MultiPolygon	The converted shapely geometry.

point_to_shapely(geom)

Convert a Point to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	Point	The Point geometry to convert.	required

Returns:

Type	Description
Point	The converted shapely geometry.

polygon_to_shapely(geom)

Convert a Polygon to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	Polygon	The Polygon geometry to convert.	required

Returns:

Type	Description
Polygon	The converted shapely geometry.

shapely_to_geometry(geom)

Convert a shapely geometry to a soundevent geometry.

Parameters:

Name	Type	Description	Default
geom	Geometry	The shapely geometry to convert.	required

Returns:

Type	Description
Geometry	The converted soundevent geometry.

Raises:

Type	Description
NotImplementedError	If the geometry type is not supported.

time_interval_to_shapely(geom)

Convert a TimeInterval to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	TimeInterval	The TimeInterval geometry to convert.	required

Returns:

Type	Description
Geometry	The converted shapely geometry.

time_stamp_to_shapely(geom)

Convert a TimeStamp to a shapely geometry.

Parameters:

Name	Type	Description	Default
geom	TimeStamp	The TimeStamp geometry to convert.	required

Returns:

Type	Description
Geometry	The converted shapely geometry.

Visualisation

soundevent.geometry.html

HTML representation of geometries.

Functions:

Name	Description
geometry_to_html	Represent the geometry as HTML.
shapely_to_html	Represent the geometry as HTML.
timestamp_to_html	Represent the geometry as HTML.

Functions

geometry_to_html(geom)

Represent the geometry as HTML.

Parameters:

Name	Type	Description	Default
geom	Geometry	The geometry to represent as HTML.	required

Returns:

Type	Description
str	The HTML representation of the geometry.

shapely_to_html(geometry)

Represent the geometry as HTML.

Returns:

Type	Description
str	The HTML representation of the geometry.

timestamp_to_html(geom)

Represent the geometry as HTML.

Returns:

Type	Description
str	The HTML representation of the geometry.