SimpleFreeFieldHRTF

SimpleFreeFieldHRTF SOFA convention

Since R2023b

Description

The SimpleFreeFieldHRTF object stores SOFA data following the SimpleFreeFieldHRTF 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 complex frequency-domain transfer functions (TF).

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

Creation

Create a SimpleFreeFieldHRTF object using sofaconvention.

s = sofaconvention("SimpleFreeFieldHRTF");

Properties

Data

FrequencyResponse — Frequency response

[0 0] (default) | M-by-R-by-N array

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

FrequencyVector — Frequency vector

1 (default) | vector

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

DataType — Type of data

"TF"

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.

Receiver

ReceiverPosition — Receiver positions

[0 0.09 0; 0 -0.09 0] (default) | 2-by-3 matrix | 2-by-3-by-M array

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.

ReceiverPositionType — Receiver position type

"cartesian" (default) | "spherical"

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

ReceiverPositionUnits — Receiver position units

"meter" | "degree, degree, meter"

This property is read-only.

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

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.

Emitter

EmitterPosition — Emitter position

[0 0 0] (default) | 1-by-3 matrix | 1-by-3-by-M array

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.

EmitterPositionType — Emitter position type

"cartesian" (default) | "spherical"

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

EmitterPositionUnits — Emitter position units

"meter" | "degree, degree, meter"

This property is read-only.

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

Metadata

SOFAConventions — Name of SOFA convention

"SimpleFreeFieldHRTF"

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
interpolateHRTF	3-D head-related transfer function (HRTF) interpolation
findMeasurements	Find measurements in specified plane
plotGeometry	Plot measurements geometry
freqz	HRTF frequency response
spectrum	HRTF power spectrum
interauralLevelDifference	Interaural level difference
directivity	Frequency directivity

Examples

Write Frequency Response Data to SOFA File

Create a SOFA template object following the SimpleFreeFieldHRTF convention to store measurement data as complex frequency responses.

s = sofaconvention("SimpleFreeFieldHRTF");

Load HRTF data containing impulse response measurements. Initialize the FrequencyResponse property to store 100 measurements in 512-point frequency responses.

load 'ReferenceHRTF.mat' hrtfData sourcePosition sampleRate
M = 100;
N = 512;
R = 2; % 2 ears

s.FrequencyResponse = complex(zeros(M,R,N));

For 100 of the measurements from the HRTF data, use freqz to get the complex frequency responses from the FIR filters and store them in the SOFA object.

for i = 1:M
    ear1FIR = squeeze(hrtfData(:,i,1));
    ear2FIR = squeeze(hrtfData(:,i,2));
    
    [h1,f] = freqz(ear1FIR,1,N,sampleRate);
    s.FrequencyResponse(i,1,:) = h1;
    h2 = freqz(ear2FIR,1,N,sampleRate);
    s.FrequencyResponse(i,2,:) = h2;
end

s.FrequencyVector = f;

Set the SourcePosition property to store the positional data, in spherical coordinates, corresponding to the selected measurements.

s.SourcePositionType = "spherical";
s.SourcePosition = sourcePosition(1:M,1:3);

Write the data to a SOFA file.

sofawrite("freqResponseData.sofa",s);

Read SOFA File with Frequency Response Data

Read in a SOFA file that follows the SimpleFreeFieldHRTF convention and contains measurements in frequency response form.

s = sofaread("freqResponseData.sofa");

Select the complex frequency response corresponding to the tenth measurement and the right ear.

measurementIdx = 10;
ear = 2;

freqResponse = squeeze(s.FrequencyResponse(measurementIdx,ear,:));

Plot the magnitude response in decibels.

plot(s.FrequencyVector,20*log10(abs(freqResponse)))
xlabel("Frequency (Hz)")
ylabel("Magnitude (dB)")

Visualize and Analyze Data in SimpleFreeFieldHRTF SOFA File

Read in a SOFA file containing HRTF measurements.

s = sofaread("exampleSimpleFreeFieldHRTF.sofa");

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

figure
plotGeometry(s)

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);

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

figure
freqz(s)

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

figure
spectrum(s)

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

figure
interauralLevelDifference(s)

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

figure
directivity(s,[750 1500])

More About

Spatial Data Representations

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

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.

Version History

Introduced in R2023b