Skip to main content

Directional Point Sources

The SDK provides directional point sources that utilizes an approximated directivity pattern for the wave-based solver.

A number of directive sources are included and can be accessed through the source_directivity_library. In addition, users can also upload their own source directivities to the source_directivity_library by supplying a .clf file to define the directivity.

Querying the source directivity library​

You can query the whole source directivity library which returns all directivites that come built-in with Treble as well as source directivities uploaded by your organization.

source_directivities = tsdk.source_directivity_library.query()
# Display the data in a table (if the column "Private" is True then it is uploaded by your organization):
dd.as_table(source_directivities)

There are a few possible ways to filter the query: by category and sub category, manufacturer, name and organization.

1. Query by category​

We can query the source directivity library by category and sub category, although both are optional.

The enum SourceDirectivityCategory is used for querying by category. If sub category is also used then we need to select a value from any of the category's sub category as listed below.

directivity = tsdk.source_directivity_library.query(
    category=treble.SourceDirectivityCategory.natural
)
dd.as_table(directivity)
If querying by sub category:​

For using sub categories the enum SourceDirectivityCategory is used with a sub category value. As an example, for a speech source, SourceDirectivityCategory.natural is used. Then the sub category is choosen with the enum SourceDirectivityNatural.speech.

natural_directivities = tsdk.source_directivity_library.query(
    category=treble.SourceDirectivityCategory.natural,
    sub_category=treble.SourceDirectivityNatural.speech,
)
speech_directivity = natural_directivities[0]

2. Query by manufacturer​

We can query the source directivity library by manufacturer which searches the library for a source directivity with a manufacturer value containing the given string. Note that it is not case sensitive.

jbl_directivities = tsdk.source_directivity_library.query(
    manufacturer="jbl"
)
dd.as_table(jbl_directivities)
jbl_directivity = jbl_directivities[0]

3. Query by name​

Querying the source directivity library by name works like querying by manufacturer, searching the library for a source directivity with a name containing the given string, not case sensitive.

source_directivities_by_name = tsdk.source_directivity_library.query(
    name="speech"
)

4. Filter by organization​

By using get_organization_directivities you get only the source directivities uploaded by your organization.

source_directivities = tsdk.source_directivity_library.get_organization_directivities()
dd.as_table(source_directivities) # Empty if you have not uploaded a source directivity

Plotting​

Source directivities can be visualized using two plotting functions.

The on axis SPL at 1 meter can be visualized using plot_spl_on_axis().

speaker = tsdk.source_directivity_library.query(name="8020")[0]
speaker.plot_spl_on_axis()

The directivity pattern can be visualized as a sound pressure 'balloon' using plot_directivity_pattern(). Note that the plot is interactive as you can change the frequency using the slider.

speaker.plot_directivity_pattern()

Source directivity upload​

The SDK offers the possibility to upload a source directiviy to the source_directivity_library by supplying a .clf file to define the directivity. Name and category has to be specified as well as the .clf file path.

my_source_directivity = tsdk.source_directivity_library.create_source_directivity(
    name="My source directivity",
    source_directivity_file_path="data/Genelec+Oy-8020.CF2",
    category=treble.SourceDirectivityCategory.amplified,
    sub_category=treble.SourceDirectivityAmplified.studio_and_broadcast_monitor, # Optional
    description="Uploaded by me", # Optional
    manufacturer="Genelec Oy", # Optional
    correct_ir_by_on_axis_spl_default= True # Optional, default True
)

Creating a directive source using the source directivity library​

To create a source to define a simulation, it is possible to use either an updloaded source directivity or any other directivity in the library as previously shown. To define a source as directive, a Source object is created with the source type treble.SourceType.directive. The directiviy is specified in the source properties with the queried directivity pattern.

directivities = tsdk.source_directivity_library.query(
    name="speech"
)
dd.as_table(directivities)
speech_directivity = directivities[0]

source_properties = treble.SourceProperties(
    azimuth_angle=0.0,
    elevation_angle=0.0,
    source_directivity=speech_directivity # here the directivity queried above is used
)
source = treble.Source(
    x=1,
    y=1,
    z=1.5,
    source_type=treble.SourceType.directive,
    label="Speech_source",
    source_properties=source_properties
)