Main Content

SimpleFreeFieldHRIR

SimpleFreeFieldHRIR SOFA convention

Since R2023b

expand all in page

    Description

    The SimpleFreeFieldHRIR object stores SOFA data following the SimpleFreeFieldHRIR convention. This convention describes a spatially discrete free-field head-related transfer function (HRTF) measurement for a single subject (a single human listener or a mannequin head device). The measurements are made in the free field with a single excitation source assuming an omnidirectional loudspeaker. There are two receivers representing the ears of the subject. The measured HRTFs are represented as head-related impulse responses (HRIR).

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

    Creation

    Create a SimpleFreeFieldHRIR object using sofaconvention.

    s = sofaconvention("SimpleFreeFieldHRIR");

    Properties

    expand all

    Data

    Head-related impulse responses in FIR form, specified as a real-valued M-by-R-by-N array, where M is the number of measurements, R is the number of receivers, and N is the impulse response length. The number of receivers is typically equal to 2 in this convention.

    Delay of each impulse response 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. The number of receivers is typically equal to 2 in this convention.

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

    This property is read-only.

    Sampling rate units, returned as a string.

    This property is read-only.

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

    Listener

    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.

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

    This property is read-only.

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

    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.

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

    Receiver

    Receiver positions in Cartesian or spherical coordinates, specified as a 2-by-3 matrix or 2-by-3-by-M array, where M is the number of measurements and 2 represents the number of receivers. The default value assumes the head has a radius of 0.09 meters.

    For more information, see Spatial Data Representations.

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

    This property is read-only.

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

    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.

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

    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.

    Emitter

    Emitter position in Cartesian or spherical coordinates, specified as a 1-by-3 matrix or 1-by-3-by-M array, where M is the number of measurements and 1 represents the number of emitters.

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

    Metadata

    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
    interpolateHRTF3-D head-related transfer function (HRTF) interpolation
    findMeasurementsFind measurements in specified plane
    plotGeometryPlot measurements geometry
    freqzHRTF frequency response
    impzHead-related impulse response
    spectrumHRTF power spectrum
    interauralTimeDifferenceInteraural time difference
    interauralLevelDifferenceInteraural level difference
    directivityFrequency directivity
    energyTimeCurveCompute energy-time curve

    Examples

    collapse all

    Open Live Script

    Create a SOFA template object following the SimpleFreeFieldHRIR convention.

    s = sofaconvention("SimpleFreeFieldHRIR");

    Generate mock impulse response data to store in the file. Set the number of measurements M to two and set the impulse response length N to 1024. The number of receivers R is two, corresponding to two ears. Use the fir1 function to create arbitrary FIR filters for the impulse response measurements.

    M = 2;
N = 1024;
R = 2;

IR = zeros(M,R,N);
IR(1,:,:) = [fir1(N-1,0.1);fir1(N-1,.2)];
IR(2,:,:) = [fir1(N-1,0.15);fir1(N-1,.25)];

    Store the measurements in the SOFA object.

    s.Numerator = IR;

    Set the ListenerView so the positive x-axis of the local listener coordinate system points up with a 45 degree elevation. Set the ReceiverPosition so the ears are 18 cm apart on the x-axis.

    s.ListenerViewType = "spherical";
s.ListenerView = [0 45 0];
s.ReceiverPosition = [0 0 0; 0 0.18 0];

    Modify the Title and Comment metadata properties.

    s.Title = "My SOFA File";
s.Comment = "This SOFA file contains mock FIR data.";

    Save the data to a SOFA file.

    sofawrite("myFile.sofa",s);
    Open Live Script

    Read in a SOFA file containing HRTF measurements.

    s = sofaread("ReferenceHRTF.sofa");

    Call plotGeometry to visualize the 3-D locations of the receiver and moving source from the measurements.

    figure
plotGeometry(s)

    Figure contains an axes object. The axes object with xlabel X (meters), ylabel Y (meters) contains 2 objects of type line. One or more of the lines displays its values using only markers These objects represent Source position, Receiver position.

    Use findMeasurements to get the indices of measurements in the median plane. Plot the 3-D geometry of the specified measurements.

    idx = findMeasurements(s,Plane="median");
figure
plotGeometry(s,MeasurementIndex=idx);

    Figure contains an axes object. The axes object with xlabel X (meters), ylabel Y (meters) contains 2 objects of type line. One or more of the lines displays its values using only markers These objects represent Source position, Receiver position.

    Use freqz to compute and visualize the frequency response of the first measurement for the first receiver.

    figure
freqz(s)

    Figure contains an axes object. The axes object with xlabel Frequency (Hz), ylabel Magnitude (dB) contains an object of type line. This object represents Measurement 1. Receiver 1.

    Use impz to compute and visualize the impulse response of the first measurement for the first receiver.

    figure
impz(s)

    Figure contains an axes object. The axes object with xlabel Time (s) contains an object of type line. This object represents Measurement 1. Receiver 1.

    Use spectrum to compute and visualize the power spectrum of the HRTF data in the horizontal plane at zero elevation for the first receiver.

    figure
spectrum(s)

    Figure contains an axes object. The axes object with title Horizontal Plane Spectrum. Receiver 1., xlabel Frequency (Hz), ylabel Azimuth (degrees) contains an object of type surface.

    Compute and visualize the interaural time difference of the HRTF data in the horizontal plane at zero elevation.

    figure
interauralTimeDifference(s)

    Figure contains an axes object. The axes object with title Horizontal Plane Interaural Time Difference, xlabel Azimuth (degrees), ylabel ITD (s) contains an object of type line.

    Compute and visualize the interaural level difference of the HRTF data in the horizontal plane.

    figure
interauralLevelDifference(s)

    Figure contains an axes object. The axes object with title Horizontal Plane Interaural Level Difference, xlabel Frequency (Hz), ylabel Azimuth (degrees) contains an object of type surface.

    Compute and visualize the directivity of the HRTF data at 750 Hz and 1500 Hz in the horizontal plane.

    figure
directivity(s,[750 1500])

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type line. These objects represent 750.000000 Hz, 1500.000000 Hz.

    Compute and visualize the energy-time curve of the HRTF data in the horizontal plane.

    figure
energyTimeCurve(s)

    Figure contains an axes object. The axes object with title Horizontal Plane Energy-Time Curve. Receiver 1., xlabel Time (s), ylabel Azimuth (degrees) contains an object of type surface.

    More About

    expand all

    Version History

    Introduced in R2023b

    See Also

    | |

    External Websites