FreeFieldDirectivityTF
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
Data
FrequencyResponse
— Frequency response
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.
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, 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.
ListenerPositionType
— Listener position type
"cartesian"
(default) | "spherical"
| "spherical harmonics"
Listener position type, specified as "cartesian"
,
"spherical"
, or "spherical harmonics"
.
ListenerPositionUnits
— Listener position units
"meter"
| "degree, degree, meter"
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"
.
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.
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
"spherical"
(default) | "cartesian"
| "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"
.
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.
SourcePositionReference
— Description of spatial reference of source
""
(default) | string
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.
SourcePositionType
— Source position type
"cartesian"
(default) | "spherical"
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"
.
SourceViewReference
— Description of spatial reference of source view
""
(default) | string
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.
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.
SourceUpReference
— Description of spatial reference of source up direction
""
(default) | string
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.
SourceManufacturer
— Source manufacturer
""
(default) | string
Source manufacturer, specified as a string.
SourceType
— Description of acoustic source
""
(default) | string
Description of the acoustic source, specified as a string (for example,
"Violin"
, "Singer"
, or "2-way
loudspeaker"
).
SourceTuningFrequency
— Source tuning frequency (hertz)
0
(default) | numeric scalar
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
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"
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"
.
EmitterDescription
— General emitter description
""
(default) | string
General emitter description, specified as a string.
EmitterDescriptions
— Descriptions of each emitter
empty array (default) | M-by-1 string array | E-by-1 string array | M-by-1 cell array of character strings | E-by-1 cell array of character strings
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
RoomType
— Room type
"free field"
(default) | string
Type of room used to perform the measurements, specified as a string.
Metadata
Musician
— Description of musician
""
(default) | string
Description of musician, such as position or behavior, specified as a string (for
example, "artificial excitation by R2D2"
).
SOFAConventions
— Name of SOFA convention
"FreeFieldDirectivityTF"
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.1"
(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.
Examples
Create FreeFieldDirectivityTF SOFA File
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
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)2.
Version History
Introduced in R2023b
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)