Skip to content

QuickStart

Jump to bottom
Ioseb Laghidze edited this page Nov 22, 2020 · 19 revisions

This quickstart guide introduces a few of the most important features of the API for both creating and loading SOFA files. More indepth explanations of the API will follow in the near future.

Table of Contents:

  1. Creating a new SOFA File
  2. Setting convention dimensions
  3. Viewing convention parameters
  4. Accessing parameter values
  5. Exporting a SOFA file
  6. Loading a SOFA file

Note: Upon reading this section, it is recommended to read about the Convention Templates for quickly generating the code structure for each convention.

1 - Creating a new SOFA File

The SOFASonix schema can be initialised as follows

from SOFASonix import SOFAFile

sofa = SOFAFile(convention, sofaConventionsVersion=False, version=False, load=False, verbose=True, **dims)

The parameters of the constructor are explained below

  • convention - The SOFA convention name (ie GeneralFIR). The case does not matter ('generalfir' is also acceptable).
  • sofaConventionsVersion - The "GLOBAL:SOFAConventionsVersion" of the convention (as defined in the global parameters of every SOFA conventnion). This is optional and defaults to the latest.
  • version - The "GLOBAL:Version" parameter of the convention. Optional and defaults to the latest
  • load - A boolean parameter used only when loading files to prevent overwriting the "GLOBAL:DateCreated" and "GLOBAL:DateModified" parameters. This is for internal use only, and can be safely ignored.
  • verbose - Whether to print informative messages when loading SOFAFiles (particularly setting/deleting parameters) or not. By default this is active and will print messages ie in cases where a dimension is set based on a parameter (see section 2.3). This can be switched off by setting to False to prevent message clutter when using the API as part of larger scripts.
  • dims - The explicit value for any SOFA dimension can be passed directly to the constructor (ie N = 1024, E = 2).

Note: The supplied version and sofaConventionsVersion must be compatible with the supported conventions along with the convention name. Should there be any issues, SOFASonix will raise an informative SOFAError such as shown below

[In]: sofa = SOFAFile("simplefreefieldhrir", 0.1, 0.5)

[Out]: SOFAError: Incompatible SOFAConventionsVersion (0.1) and spec version (0.5) supplied. The following pairs are available for 'SimpleFreeFieldHRIR':

- Version: 1.0, Spec Version: 1.0
- Version: 0.4, Spec Version: 0.6
- Version: 0.3, Spec Version: 0.5

2 - Setting convention dimensions

Dimension values of the convention are set using the following four methods:

  1. During Instantiation (as explained in section 1)
  2. Dot Notation
  3. Using setDim()
  4. Parameter-Defined

2.1 Dot notation

Dimensions can be assigned a value using the shorthand dot notation. The SOFASonix object can be followed with the dimension name (case-insensitive) which must be prefixed using an underscore:

# Set dimension E
sofa._e =2

# Set dimension N 
sofa._N = 1024

# Print dimensions
print(sofa._E)
print(sofa._N)

Only dimensions that are editable (ie not READ-ONLY with respect to the convention) can be changed.

2.2 setDim() and getDim()

Alternatively, the setDim() method can be used.

sofa.setDim("N", 1024)

To obtain dimension values, getDim() may also be used

print(sofa.getDim("n"))

Both setDim() and getDim() are case-insensitive with dimension letters.

2.3 Parameter-Defined

Certain parameters defined by AES69-2015 are assigned special privileges for defining certain dimensions. These parameter dimensions are represented by a lower-case letter in their dimensions definition. For instance, with respect to the GeneralFIR convention, the parameter "EmitterPosition" can have dimensions of either eCI or eCM. The lower-case e means that the size of the EmitterPosition array's first dimension should set the emitter dimension E.

SOFASonix accommodates for parameter-defined dimensions in all cases, and will print a message every time a dimension is set through a parameter-value.

NOTE: Parameter-definitions of dimensions have the highest priority at this stage.

3 - Viewing convention parameters

SOFASonix supports showing what convention parameters are part of the specific convention and version. This can be seen by running the view() command on an instantiated SOFAFile object.

sofa.view()

This shows the following columns in tabular form

  • Shorthand - The shorthand syntax for quickly editing/viewing the parameter value. Explained in the following section.
  • Type - The parameter type (A = Attribute, D = Double, S = String)
  • Value - Shows a preview of the value for parameter that is an attribute, and the array shape if the parameter is a double or string
  • RO - Shows the READ-ONLY state of the parameter, which is convention-specific according to SOFAConventions
  • M - Shows whether the parameter is mandatory or not
  • Dims - Shows the accepted dimensions of the parameter if it is a double or a string.

4 - Accessing parameter values

SOFASonix provides a shorthand and an explicit method for accessing convention parameters - editing or viewing their values.

4.1 Obtaining the value of a parameter

As part of the shorthand accessibility feature of SOFASonix, parameter values can be viewed using dot-notation followed by the shorthand name of the parameter (shorthand names are listed with the view() method of section 3 above). The shorthand names are effectively the SOFAConvention parameter names with ":" and "." replaced by "_". They are also case-insensitive.

# Accessing the Data.IR parameter
print(sofa.data_ir)

The more explicit approach for accessing parameters is using the getParam() method. This is not case-insensitive and must provide the parameter name exactly as specified in the convention on the SOFAConventions website ie

# Using the explicit approach
print(sofa.getParam("GLOBAL:Conventions")
print(sofa.getParam("Data.IR")

The shorthand notation is recommended for its ease of use.

4.2 Editing/assigning parameter values

Editing parameter values is similar to viewing the current values. The shorthand method:

sofa.global_authorcontact = '[email protected]'
sofa.data_ir = myarray

The explicit method

sofa.setParam("GLOBAL:AuthorContact", '[email protected]')

4.3 Validation

SOFASonix has a strict set of validation rules that reflect the structure and rules for each standard. For instance, parameters of type ('double') must have the correct dimensions before being accepted. Informative errors will be raised if parameter values are of incorrect format.

5 - Exporting a SOFA file

Once all parameters required by the convention are supplied, the export() method can be used to generate the SOFA file:

sofa.export("SOFAFILENAME")

This will generate a file SOFAFILENAME.sofa in the same directory. Note: the .sofa extension is appended automatically.

The export() will only be successful provided that data validation is passed. Should there be any issues, informative exceptions will be raised when export() is called.

6 - Loading a SOFA file

SOFA files may be loaded using the load() command.

loadsofa = SOFAFile.load("sofafile.sofa", verbose=True)

The load() function also supports custom parameters that may be added from third party APIs which are not part of the official convention. Messages will be printed in the console specifying which of these 'foreign parameters' has been imported (these may also be exported without any issues when saving a modified variant of the file). An optional verbose parameter can also be set here, which sets the verbose mode for the returned SOFAFile instance (see section 1).

Once the SOFA file has been loaded, the same methods/functions are applicable from sections 2-5.

loadsofa = SOFAFile.load("sofafile.sofa")

# View the convention parameters
loadsofa.view()

# Copy impulse response data
data = loadsofa.data_ir

# Edit parameters
loadsofa.global_comment = "This is a new description of the file"

# Re-export sofa file
loadsofa.export("sofafile_new")
Clone this wiki locally