Main Content

FreeFieldDirectivityTF

FreeFieldDirectivityTF SOFA convention

Since R2023b

expand all in page

    Description

    The FreeFieldDirectivityTF object stores SOFA data following the FreeFieldDirectivityTF convention. This convention stores directivities of acoustic sources (for example, instruments, loudspeakers, singers, and talkers) in the frequency domain for single or multiple measurements (for example, musical notes or playing styles). It considers musical notes as a parameter directly addressing musical instruments and singers. The measurements are performed in the free field with a single source that is surrounded by receivers. The measured data is represented as complex frequency-domain transfer functions (TF).

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

    Creation

    Create a FreeFieldDirectivityTF object using sofaconvention.

    s = sofaconvention("FreeFieldDirectivityTF");

    Properties

    expand all

    Data

    Measurements in frequency response form, specified as a complex M-by-R-by-N array, where M is the number of measurements, R is the number of receivers, and N is the frequency response length.

    Frequency vector, in hertz, corresponding to the frequency response, specified as a vector.

    This property is read-only.

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

    Listener

    Listener position in Cartesian, spherical, or spherical harmonics 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.

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

    This property is read-only.

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

    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.

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

    This property is read-only.

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

    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.

    Receiver

    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.

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

    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".

    Source

    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.

    Description of the spatial reference of the source position, specified as a string (for example, "The bell" for a trumpet or "On the front plate between the low- and mid/high-frequency unit" for a loudspeaker). This property provides a reference across different sources.

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

    This property is read-only.

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

    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.

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

    This property is read-only.

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

    Description of the spatial reference of the source view, specified as a string (for example, "Viewing direction of the bell" for a trumpet or "Perpendicular to the front plate" for a loudspeaker). This property provides a reference across different sources.

    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.

    Description of the spatial reference of the source up direction, specified as a string (for example, "Along the keys, keys up" for a trumpet or "Perpendicular to the top plate" for a loudspeaker). This property provides a reference across different sources.

    Source manufacturer, specified as a string.

    Description of the acoustic source, specified as a string (for example, "Violin", "Singer", or "2-way loudspeaker").

    Source tuning frequency, in hertz, to which the musical instrument is tuned corresponding to the note A4 (MIDI note number 64), specified as a numeric scalar.

    Emitter

    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.

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

    This property is read-only.

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

    General emitter description, specified as a string.

    Descriptions of each emitter, specified as an M-by-1 or E-by-1 string array or M-by-1 or E-by-1 cell array of character strings, where M is the number of measurements and E is the number of emitters.

    Room

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

    Metadata

    Description of musician, such as position or behavior, specified as a string (for example, "artificial excitation by R2D2").

    This property is read-only.

    Name of the SOFA convention, returned as a string.

    Name of the database that this data belongs to, specified as a 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.

    This property is read-only.

    Name of the API that created or edited the SOFA file, returned as a 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.

    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 containing a succinct description of the file contents, specified as a string.

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

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

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

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

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

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

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

    Published or web-based references that describe the data or the methods used to produce the data, specified as a 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.

    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.

    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

    writeWrite SOFA file
    validateValidate SOFA data

    Examples

    collapse all

    Open Live Script

    Create a SOFA template object following the FreeFieldDirectivityTF convention.

    s = sofaconvention("FreeFieldDirectivityTF");

    Generate mock frequency response data to store in the file. Initialize the FrequencyResponse property to store 512-point frequency responses for 25 measurements of a single receiver. Use freqz to get the complex frequency responses from random Butterworth filters.

    M = 25;
R = 1;
N = 512;
s.FrequencyResponse = complex(zeros(M,R,N));
fs = 44100;

for m = 1:M
    [b,a] = butter(5,rand);
    [h,f] = freqz(b,a,N,fs);
    s.FrequencyResponse(m,1,:) = h;
end

s.FrequencyVector = f;

    Save the data to a SOFA file.

    sofawrite("mockFreqResponseData.sofa",s);

    More About

    expand all

    Version History

    Introduced in R2023b

    See Also

    | |

    External Websites