GeneralSOS

GeneralSOS SOFA convention

Since R2023b

Description

The GeneralFIR object stores SOFA data following the GeneralSOS convention. This convention is a general representation of data in second-order section (SOS) filter form. It stores data for general purposes.

Use sofaread and sofawrite to read and write SOFA files with this convention.

Creation

Create a GeneralSOS object using sofaconvention.

s = sofaconvention("GeneralSOS");

Properties

expand all

Data

`Numerator` — Numerator coefficients of filters
`zeros(1,1,1,3)` (default) | M-by-R-by-N-by-3 array

Numerator coefficients of the SOS filters, specified as a real-valued M-by-R-by-N-by-3 array, where M is the number of measurements, R is the number of receivers, and N is the number of filter sections.

`Denominator` — Denominator coefficients of filters
`zeros(1,1,1,3)` (default) | M-by-R-by-N-by-3 array

Denominator coefficients of the SOS filters, specified as a real-valued M-by-R-by-N-by-3 array, where M is the number of measurements, R is the number of receivers, and N is the number of filter sections.

`Delay` — Broadband delay
`[0 0]` (default) | 1-by-R matrix | M-by-R matrix

Broadband delay in samples, specified as a 1-by-R or M-by-R matrix, where M is the number of measurements and R is the number of receivers.

`SamplingRate` — Sampling rate (Hz)
48000 (default) | positive scalar

Sampling rate of the data in hertz, specified as a positive scalar.

`SamplingRateUnits` — Sampling rate units
`"hertz"`

This property is read-only.

Sampling rate units, returned as a string.

`DataType` — Type of data
`"SOS"`

This property is read-only.

Type of data in the file, returned as a string.

Listener

`ListenerPosition` — Listener position
`[0 0 0]` (default) | 1-by-3 matrix | M-by-3 matrix

Listener position in Cartesian or spherical coordinates, specified as a 1-by-3 or M-by-3 matrix, where M is the number of measurements.

For more information, see Spatial Data Representations.

`ListenerPositionType` — Listener position type
`"cartesian"` (default) | `"spherical"`

Listener position type, specified as "cartesian" or "spherical".

`ListenerPositionUnits` — Listener position units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Listener position units, returned as "meter" if ListenerPositionType is "cartesian" or "degree, degree, meter" if ListenerPositionType is "spherical".

`ListenerView` — Listener view direction
`[1 0 0]` (default) | 1-by-3 matrix | M-by-3 matrix

Listener view direction, specified as a 1-by-3 or M-by-3 matrix, where M is the number of measurements. This property defines the direction of the positive x-axis of the local listener coordinate system.

`ListenerViewType` — Listener view type
`"cartesian"` (default) | `"spherical"`

Listener view type, specified as "cartesian" or "spherical".

`ListenerViewUnits` — Listener view units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Listener view units, returned as "meter" if ListenerViewType is "cartesian" or "degree, degree, meter" if ListenerViewType is "spherical".

`ListenerUp` — Listener up direction
`[0 0 1]` (default) | 1-by-3 matrix | M-by-3 matrix

Listener up direction, specified as a 1-by-3 or M-by-3 matrix, where M is the number of measurements. This property defines the direction of the positive z-axis of the local listener coordinate system.

`ListenerShortName` — Listener short name
`""` (default) | string

Listener short name, specified as a string. This property defines the ID of the subject from the database.

`ListenerDescription` — Listener description
`""` (default) | string

Listener description, specified as a string.

Receiver

`ReceiverPosition` — Receiver positions
`[0 0 0]` (default) | 1-by-3 matrix | R-by-3 matrix | R-by-3-by-M array

Receiver positions in Cartesian coordinates, spherical coordinates, or spherical harmonics, specified as a 1-by-3 matrix, R-by-3 matrix, or R-by-3-by-M array, where M is the number of measurements. If ReceiverPositionType is "cartesian" or "spherical", R is the number of receivers. If ReceiverPositionType is "spherical harmonics", R is the number of spherical-harmonic coefficients.

For more information, see Spatial Data Representations.

`ReceiverPositionType` — Receiver position type
`"cartesian"` (default) | `"spherical"` | `"spherical harmonics"`

Receiver position type, specified as "cartesian", "spherical", or "spherical harmonics".

`ReceiverPositionUnits` — Receiver position units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Receiver position units, returned as "meter" if ReceiverPositionType is "cartesian" or "spherical harmonics". If ReceiverPositionType is "spherical", the units are returned as "degree, degree, meter".

`ReceiverView` — Receiver view direction
`[1 0 0]` (default) | R-by-3 matrix | R-by-3-by-M array

Receiver view direction, specified as an R-by-3 matrix or R-by-3-by-M array, where M is the number of measurements and R is the number of receivers. This property defines the direction of the positive x-axis of the local receiver coordinate system.

`ReceiverViewType` — Receiver view type
`"cartesian"` (default) | `"spherical"`

Receiver view type, specified as "cartesian" or "spherical".

`ReceiverViewUnits` — Receiver view units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Receiver view units, returned as "meter" if ReceiverViewType is "cartesian" or "degree, degree, meter" if ReceiverViewType is "spherical".

`ReceiverUp` — Receiver up direction
`[0 0 1]` (default) | R-by-3 matrix | R-by-3-by-M array

Receiver up direction, specified as an R-by-3 matrix or R-by-3-by-M array, where M is the number of measurements and R is the number of receivers. This property defines the direction of the positive z-axis of the local receiver coordinate system.

`ReceiverShortName` — Receiver short name
`""` (default) | string

Receiver short name, specified as a string.

`ReceiverDescription` — Receiver description
`""` (default) | string

Receiver description, specified as a string.

Source

`SourcePosition` — Source position
`[0 0 1]` (default) | 1-by-3 matrix | M-by-3 matrix

Source position in Cartesian or spherical coordinates, specified as a 1-by-3 or M-by-3 matrix, where M is the number of measurements.

For more information, see Spatial Data Representations.

`SourcePositionType` — Source position type
`"spherical"` (default) | `"cartesian"`

Source position type, specified as "cartesian" or "spherical".

`SourcePositionUnits` — Source position units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Receiver position units, returned as "meter" if SourcePositionType is "cartesian" or "degree, degree, meter" if SourcePositionType is "spherical".

`SourceView` — Source view direction
`[1 0 0]` (default) | 1-by-3 matrix | M-by-3 matrix

Source view direction, specified as a 1-by-3 or M-by-3 matrix, where M is the number of measurements. This property defines the direction of the positive x-axis of the local source coordinate system.

`SourceViewType` — Source view type
`"cartesian"` (default) | `"spherical"`

Source view type, specified as "cartesian" or "spherical".

`SourceViewUnits` — Source view units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Source view units, returned as "meter" if SourceViewType is "cartesian" or "degree, degree, meter" if SourceViewType is "spherical".

`SourceUp` — Source up direction
`[0 0 1]` (default) | 1-by-3 matrix | M-by-3 matrix

Source up direction, specified as a 1-by-3 or M-by-3 matrix, where M is the number of measurements. This property defines the direction of the positive z-axis of the local source coordinate system.

`SourceShortName` — Source short name
`""` (default) | string

Source short name, specified as a string.

`SourceDescription` — Source description
`""` (default) | string

Source description, specified as a string.

Emitter

`EmitterPosition` — Emitter positions
`[0 0 0]` (default) | 1-by-3 matrix | E-by-3 matrix | E-by-3-by-M array

Emitter positions in Cartesian coordinates, spherical coordinates, or spherical harmonics, specified as a 1-by-3 matrix, E-by-3 matrix, or E-by-3-by-M array, where M is the number of measurements. If EmitterPositionType is "cartesian" or "spherical", E is the number of emitters. If EmitterPositionType is "spherical harmonics", E is the number of spherical-harmonic coefficients.

For more information, see Spatial Data Representations.

`EmitterPositionType` — Emitter position type
`"cartesian"` (default) | `"spherical"` | `"spherical harmonics"`

Emitter position type, specified as "cartesian", "spherical", or "spherical harmonics".

`EmitterPositionUnits` — Emitter position units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Emitter position units, returned as "meter" if EmitterPositionType is "cartesian" or "spherical harmonics". If EmitterPositionType is "spherical", the units are returned as "degree, degree, meter".

`EmitterView` — Emitter view direction
`[1 0 0]` (default) | E-by-3 matrix | E-by-3-by-M array

Emitter view direction, specified as an E-by-3 matrix or E-by-3-by-M array, where M is the number of measurements and E is the number of emitters. This property defines the direction of the positive x-axis of the local emitter coordinate system.

`EmitterViewType` — Emitter view type
`"cartesian"` (default) | `"spherical"`

Emitter view type, specified as "cartesian" or "spherical".

`EmitterViewUnits` — Emitter view units
`"meter"` | `"degree, degree, meter"`

This property is read-only.

Emitter view units, returned as "meter" if EmitterViewType is "cartesian" or "degree, degree, meter" if EmitterViewType is "spherical".

`EmitterUp` — Emitter up direction
`[0 0 1]` (default) | E-by-3 matrix | E-by-3-by-M array

Emitter up direction, specified as an E-by-3 matrix or E-by-3-by-M array, where M is the number of measurements and E is the number of emitters. This property defines the direction of the positive z-axis of the local emitter coordinate system.

`EmitterShortName` — Emitter short name
`""` (default) | string

Emitter short name, specified as a string.

`EmitterDescription` — Emitter description
`""` (default) | string

Emitter description, specified as a string.

Room

`RoomType` — Room type
`"free field"` (default) | string

Type of room used to perform the measurements, specified as a string.

Metadata

`SOFAConventions` — Name of SOFA convention
`"GeneralSOS"`

This property is read-only.

Name of the SOFA convention, returned as a string.

`DatabaseName` — Name of database
`""` (default) | string

Name of the database that this data belongs to, specified as a string.

`Version` — Version of specifications
`"2.1"` (default) | string

This property is read-only.

Version of the SOFA AES69 specifications, returned as a string of the format "x.y" where x is the version major and y is the version minor.

`APIName` — Name of API
`"Audio Toolbox"` (default) | string

This property is read-only.

Name of the API that created or edited the SOFA file, returned as a string.

`APIVersion` — Version of API
`"1.0"` (default) | string

This property is read-only.

Version of the API that created or edited the SOFA file, returned as a string of the format "x.y" or "x.y.z" where x is the version major and y and z are the version minors.

`SOFAConventionsVersion` — Version of convention set
`"1.0"` (default) | string

This property is read-only.

Version of the SOFA AES69 convention set, returned as a string of the format "x.y" where x is the version major and y is the version minor.

`Title` — Title
`""` (default) | string

Title containing a succinct description of the file contents, specified as a string.

`AuthorContact` — Contact information of author
`""` (default) | string

Contact information of the author (for example, an email address), specified as a string.

`Organization` — Name of organization
`""` (default) | string

Name of the organization of the author, specified as a string.

`License` — Legal license
`""` (default) | string

Legal license under which the data is provided, specified as a string.

`ApplicationName` — Name of application
`"Audio Toolbox"` (default) | string

Name of the application that created or edited the file, specified as a string.

`ApplicationVersion` — Version of application
`"3.0.0"` (default) | string

Version of the application that created or edited the file, specified as a string.

`Comment` — Comment
`""` (default) | string

Comment that can contain miscellaneous information about the data or methods used to produce the data, specified as a string.

`History` — History
`""` (default) | string

History defining the audio trail for modifications to the original data, specified as a string.

`References` — References
`""` (default) | string

Published or web-based references that describe the data or the methods used to produce the data, specified as a string.

`Origin` — Origin
`""` (default) | string

Origin, specified as a string representing the method used for creating the original data. In the case of model-generated data, the origin should name the model and its version. In the case of observed or measured data, the origin should characterize the data and, where possible, name the measurement method.

`DateCreated` — Date created
string

This property is read-only.

Date and time of the creation of the file, returned as a string in ISO 8601 format "YYYY-MM-DD hh:mm:ss". This property is set when a new file is created.

`DateModified` — Date modified
string

This property is read-only.

Date and time of the last file modification, returned as a string in ISO 8601 format "YYYY-MM-DD hh:mm:ss". This property is updated when a file is saved.

Object Functions

`write`	Write SOFA file
`validate`	Validate SOFA data

Examples

collapse all

Create GeneralSOS SOFA File

Open Live Script

Create a SOFA template object following the GeneralSOS convention to store measurement data as SOS filters.

s = sofaconvention("GeneralSOS");

Generate mock SOS data to store in the file. Use designVarSlopeFilter to create an SOS filter for one receiver in a single measurement.

M = 1;
N = 4;
R = 1;
s.Numerator = zeros(M,R,N,3);
s.Denominator = zeros(M,R,N,3);

[num,den] = designVarSlopeFilter(24,.2,Orientation="row");
s.Numerator(1,1,:,:) = num;
s.Denominator(1,1,:,:) = den;

Save the data to a SOFA file.

sofawrite("mockSOSData.sofa",s);

More About

expand all

Spatial Data Representations

In this SOFA convention, you can represent spatial data using Cartesian or spherical coordinate systems with spatially discrete representations. Alternatively, you can represent spatial data with a continuous representation using spherical harmonics.

Each spatial representation stores the position data in numerical triplets (for example, [0 0 0]).

Cartesian coordinates contain three orthogonal linear values in the format [x y z]. The units of the values are meters.
Spherical coordinates contain angular values for azimuth and elevation and a linear value for the radius in the format [azimuth elevation radius]. The azimuth angle, in degrees, must be in the range [0, 360). The elevation angle, in degrees, must be in the range [-90, 90]. The units of the linear radius are meters.
The spatially continuous representation uses the spatial frequency domain represented by a finite series of spherical harmonics. The position data stores the real-valued spherical-harmonic coefficients in Ambisonic Channel Number (ACN) order. For spherical harmonics, only the third element of the triplet is relevant.
The number of spherical-harmonic coefficients N defines the highest spherical-harmonic order L, where N=(L+1)².

Version History

Introduced in R2023b

GeneralSOS

Description

Creation

Properties

Data

Numerator — Numerator coefficients of filters zeros(1,1,1,3) (default) | M-by-R-by-N-by-3 array

Denominator — Denominator coefficients of filters zeros(1,1,1,3) (default) | M-by-R-by-N-by-3 array

Delay — Broadband delay [0 0] (default) | 1-by-R matrix | M-by-R matrix

SamplingRate — Sampling rate (Hz) 48000 (default) | positive scalar

SamplingRateUnits — Sampling rate units "hertz"

DataType — Type of data "SOS"

Listener

ListenerPosition — Listener position [0 0 0] (default) | 1-by-3 matrix | M-by-3 matrix

ListenerPositionType — Listener position type "cartesian" (default) | "spherical"

ListenerPositionUnits — Listener position units "meter" | "degree, degree, meter"

ListenerView — Listener view direction [1 0 0] (default) | 1-by-3 matrix | M-by-3 matrix

ListenerViewType — Listener view type "cartesian" (default) | "spherical"

ListenerViewUnits — Listener view units "meter" | "degree, degree, meter"

ListenerUp — Listener up direction [0 0 1] (default) | 1-by-3 matrix | M-by-3 matrix

ListenerShortName — Listener short name "" (default) | string

ListenerDescription — Listener description "" (default) | string

Receiver

ReceiverPosition — Receiver positions [0 0 0] (default) | 1-by-3 matrix | R-by-3 matrix | R-by-3-by-M array

ReceiverPositionType — Receiver position type "cartesian" (default) | "spherical" | "spherical harmonics"

ReceiverPositionUnits — Receiver position units "meter" | "degree, degree, meter"

ReceiverView — Receiver view direction [1 0 0] (default) | R-by-3 matrix | R-by-3-by-M array

ReceiverViewType — Receiver view type "cartesian" (default) | "spherical"

ReceiverViewUnits — Receiver view units "meter" | "degree, degree, meter"

ReceiverUp — Receiver up direction [0 0 1] (default) | R-by-3 matrix | R-by-3-by-M array

ReceiverShortName — Receiver short name "" (default) | string

ReceiverDescription — Receiver description "" (default) | string

Source

SourcePosition — Source position [0 0 1] (default) | 1-by-3 matrix | M-by-3 matrix

SourcePositionType — Source position type "spherical" (default) | "cartesian"

SourcePositionUnits — Source position units "meter" | "degree, degree, meter"

SourceView — Source view direction [1 0 0] (default) | 1-by-3 matrix | M-by-3 matrix

SourceViewType — Source view type "cartesian" (default) | "spherical"

SourceViewUnits — Source view units "meter" | "degree, degree, meter"

SourceUp — Source up direction [0 0 1] (default) | 1-by-3 matrix | M-by-3 matrix

SourceShortName — Source short name "" (default) | string

SourceDescription — Source description "" (default) | string

Emitter

EmitterPosition — Emitter positions [0 0 0] (default) | 1-by-3 matrix | E-by-3 matrix | E-by-3-by-M array

EmitterPositionType — Emitter position type "cartesian" (default) | "spherical" | "spherical harmonics"

EmitterPositionUnits — Emitter position units "meter" | "degree, degree, meter"

EmitterView — Emitter view direction [1 0 0] (default) | E-by-3 matrix | E-by-3-by-M array

EmitterViewType — Emitter view type "cartesian" (default) | "spherical"

EmitterViewUnits — Emitter view units "meter" | "degree, degree, meter"

EmitterUp — Emitter up direction [0 0 1] (default) | E-by-3 matrix | E-by-3-by-M array

EmitterShortName — Emitter short name "" (default) | string

EmitterDescription — Emitter description "" (default) | string

Room

RoomType — Room type "free field" (default) | string

Metadata

SOFAConventions — Name of SOFA convention "GeneralSOS"

DatabaseName — Name of database "" (default) | string

Version — Version of specifications "2.1" (default) | string

APIName — Name of API "Audio Toolbox" (default) | string

APIVersion — Version of API "1.0" (default) | string

SOFAConventionsVersion — Version of convention set "1.0" (default) | string

Title — Title "" (default) | string

AuthorContact — Contact information of author "" (default) | string

Organization — Name of organization "" (default) | string

License — Legal license "" (default) | string

ApplicationName — Name of application "Audio Toolbox" (default) | string

ApplicationVersion — Version of application "3.0.0" (default) | string

Comment — Comment "" (default) | string

History — History "" (default) | string

References — References "" (default) | string

Origin — Origin "" (default) | string

DateCreated — Date created string

DateModified — Date modified string

Object Functions

Examples

Create GeneralSOS SOFA File

More About

Spatial Data Representations

Version History

See Also

External Websites

`Numerator` — Numerator coefficients of filters
`zeros(1,1,1,3)` (default) | M-by-R-by-N-by-3 array

`Denominator` — Denominator coefficients of filters
`zeros(1,1,1,3)` (default) | M-by-R-by-N-by-3 array

`Delay` — Broadband delay
`[0 0]` (default) | 1-by-R matrix | M-by-R matrix

`SamplingRate` — Sampling rate (Hz)
48000 (default) | positive scalar

`SamplingRateUnits` — Sampling rate units
`"hertz"`

`DataType` — Type of data
`"SOS"`

`ListenerPosition` — Listener position
`[0 0 0]` (default) | 1-by-3 matrix | M-by-3 matrix

`ListenerPositionType` — Listener position type
`"cartesian"` (default) | `"spherical"`

`ListenerPositionUnits` — Listener position units
`"meter"` | `"degree, degree, meter"`

`ListenerView` — Listener view direction
`[1 0 0]` (default) | 1-by-3 matrix | M-by-3 matrix

`ListenerViewType` — Listener view type
`"cartesian"` (default) | `"spherical"`

`ListenerViewUnits` — Listener view units
`"meter"` | `"degree, degree, meter"`

`ListenerUp` — Listener up direction
`[0 0 1]` (default) | 1-by-3 matrix | M-by-3 matrix

`ListenerShortName` — Listener short name
`""` (default) | string

`ListenerDescription` — Listener description
`""` (default) | string

`ReceiverPosition` — Receiver positions
`[0 0 0]` (default) | 1-by-3 matrix | R-by-3 matrix | R-by-3-by-M array

`ReceiverPositionType` — Receiver position type
`"cartesian"` (default) | `"spherical"` | `"spherical harmonics"`

`ReceiverPositionUnits` — Receiver position units
`"meter"` | `"degree, degree, meter"`

`ReceiverView` — Receiver view direction
`[1 0 0]` (default) | R-by-3 matrix | R-by-3-by-M array

`ReceiverViewType` — Receiver view type
`"cartesian"` (default) | `"spherical"`

`ReceiverViewUnits` — Receiver view units
`"meter"` | `"degree, degree, meter"`

`ReceiverUp` — Receiver up direction
`[0 0 1]` (default) | R-by-3 matrix | R-by-3-by-M array

`ReceiverShortName` — Receiver short name
`""` (default) | string

`ReceiverDescription` — Receiver description
`""` (default) | string

`SourcePosition` — Source position
`[0 0 1]` (default) | 1-by-3 matrix | M-by-3 matrix

`SourcePositionType` — Source position type
`"spherical"` (default) | `"cartesian"`

`SourcePositionUnits` — Source position units
`"meter"` | `"degree, degree, meter"`

`SourceView` — Source view direction
`[1 0 0]` (default) | 1-by-3 matrix | M-by-3 matrix

`SourceViewType` — Source view type
`"cartesian"` (default) | `"spherical"`

`SourceViewUnits` — Source view units
`"meter"` | `"degree, degree, meter"`

`SourceUp` — Source up direction
`[0 0 1]` (default) | 1-by-3 matrix | M-by-3 matrix

`SourceShortName` — Source short name
`""` (default) | string

`SourceDescription` — Source description
`""` (default) | string

`EmitterPosition` — Emitter positions
`[0 0 0]` (default) | 1-by-3 matrix | E-by-3 matrix | E-by-3-by-M array

`EmitterPositionType` — Emitter position type
`"cartesian"` (default) | `"spherical"` | `"spherical harmonics"`

`EmitterPositionUnits` — Emitter position units
`"meter"` | `"degree, degree, meter"`

`EmitterView` — Emitter view direction
`[1 0 0]` (default) | E-by-3 matrix | E-by-3-by-M array

`EmitterViewType` — Emitter view type
`"cartesian"` (default) | `"spherical"`

`EmitterViewUnits` — Emitter view units
`"meter"` | `"degree, degree, meter"`

`EmitterUp` — Emitter up direction
`[0 0 1]` (default) | E-by-3 matrix | E-by-3-by-M array

`EmitterShortName` — Emitter short name
`""` (default) | string

`EmitterDescription` — Emitter description
`""` (default) | string

`RoomType` — Room type
`"free field"` (default) | string

`SOFAConventions` — Name of SOFA convention
`"GeneralSOS"`

`DatabaseName` — Name of database
`""` (default) | string

`Version` — Version of specifications
`"2.1"` (default) | string

`APIName` — Name of API
`"Audio Toolbox"` (default) | string

`APIVersion` — Version of API
`"1.0"` (default) | string

`SOFAConventionsVersion` — Version of convention set
`"1.0"` (default) | string

`Title` — Title
`""` (default) | string

`AuthorContact` — Contact information of author
`""` (default) | string

`Organization` — Name of organization
`""` (default) | string

`License` — Legal license
`""` (default) | string

`ApplicationName` — Name of application
`"Audio Toolbox"` (default) | string

`ApplicationVersion` — Version of application
`"3.0.0"` (default) | string

`Comment` — Comment
`""` (default) | string

`History` — History
`""` (default) | string

`References` — References
`""` (default) | string

`Origin` — Origin
`""` (default) | string

`DateCreated` — Date created
string

`DateModified` — Date modified
string