Skip to main content

Source Directivities

The following documentation is presented as Python code running inside a Jupyter Notebook. To run it yourself you can copy/type each individual cell or directly download the full notebook, including all required files.
Download Jupyter Notebook

The SDK includes a number of directive sources that can be accessed through the source_directivity_library and users can also upload their own source directivities to the source_directivity_library by supplying a .clf file to define the directivity.

In this tutorial we'll show examples of how the source directivity library can be used and how a source direcivity is imported.

First off, let's initialize the SDK

from pathlib import Path
# Our working directory for tsdk files.
# Defaults to your home directory /tmp/tsdk, feel free to change it to what you like.
base_dir = Path.home() / "tmp" / "tsdk"
base_dir.mkdir(parents=True, exist_ok=True)

from treble_tsdk.tsdk import TSDK
from treble_tsdk import tsdk_namespace as treble
from treble_tsdk import display_data as dd

tsdk = TSDK()

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 "Public" is False then it is uploaded by your organization):
dd.as_table(source_directivities)

Query using filters​

There are a few possible ways to filter the query:

  1. Category and sub category
  2. Manufacturer
  3. Name
  4. Organization

Below are examples for each of these filters, but it is also possible to use multiple filters at once.

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.

Available values for SourceDirectivityCategory are the following:

  • amplified
  • natural
  • other (empty in the source directivity library that comes built-in with Treble)
directivity = tsdk.source_directivity_library.query(
    category=treble.SourceDirectivityCategory.amplified,
)

If querying by sub category:​

If we select the SourceDirectivityCategory value amplified we should choose any of these values from the sub category enum SourceDirectivityAmplified:

  • full_range
  • line_array
  • portable
  • installation
  • ceiling
  • en_54
  • studio_and_broadcast_monitor
  • subwoofers
  • cinema_speakers
amplified_directivities = tsdk.source_directivity_library.query(
    category=treble.SourceDirectivityCategory.amplified,
    sub_category=treble.SourceDirectivityAmplified.line_array,
)
line_array_directivity = amplified_directivities[0]

If we select the SourceDirectivityCategory value natural we should choose any of these values from the sub category enum SourceDirectivityNatural:

  • speech
  • instrument
  • other

The source directivity library contains only one directivity in the category natural, which is the directivity for speech. Therefore the sub categories instrument and other are empty in the public source directivity library, but directivities can be uploaded using these categories (see instructions on uploading a directivity below)

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

If we select the SourceDirectivityCategory value other we should choose any of these values from the sub category enum SourceDirectivityOther:

  • test_sources
  • noise_sources
  • other

Note that there are no source directivities in the source directivity library with the category other, but directivities can be uploaded using this category (see instructions on uploading a directivity below).

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]

It is possible to get a list of all available manufacturers if needed:

manufacturers = tsdk.source_directivity_library.get_manufacturers()
dd.as_table(manufacturers)

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="8020"
)
dd.as_table(source_directivities_by_name)

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.

When uploading a source directiviy you specify a name and category (amplified, natural or other) for the source directivity and the path to the .clf file, with a few more optional parameters as shown below. The function returns a SourceDirectivityObj that can then be used to define a directive source in a simulation.

The file undergoes processing, during which the directivity pattern and on axis response are extracted. Once this process is complete, your new source directivity can be used in simulations and it will be accessible in the source directivity library.

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
)

INFO:

Sometimes data is missing from the CLF file, for example the source definition for a certain octave band or the on axis response is not measured in full bandwidth. Treble will fill in the missing data by extrapolating the existing data. This is highlighted in the octave band values, where extrapolated values are colored orange.

Creating a directive source using the source directivity library​

You can either use a source directivity you have uploaded or any other directivity in the library. Here we will query the speech directivity by name (filtering by SourceDirectivityCategory.natural also works like in the example above) and use it to define a directive speech source.

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

After finding the directivity we define a SourceProperties object, supplying the directivity as well as certain azimuth and elevation angles.

source_properties = treble.SourceProperties(
    azimuth_angle=90.0,
    elevation_angle=10.0,
    source_directivity=speech_directivity # here we use the directivity queried above
)

Now we can create a Source object with the source type directive and the source properties we just created. This source can then be used when defining a simulation definition.

source_type = treble.SourceType.directive
source = treble.Source(
    x=1, 
    y=1,
    z=1.5, 
    source_type=source_type, 
    label="Source_1", 
    source_properties=source_properties
)