Proposal 0.4
Only changes compared to the last version are listed here!!!
Mandatory metadata
We propose the following metadata to be mandatory for all SOFA conventions. Following rules must be fulfilled:
- Mandatory because without this metadata any conventions will fail
- Or, mandatory because users might forget it, resulting in inconsistencies for all conventions
Name | Default | Read-Only | Dimensions | Type | Comment |
---|---|---|---|---|---|
GLOBAL_Conventions | SOFA | r | |||
GLOBAL_Version | r | Insert the actual SOFA version here | |||
GLOBAL_SOFAConventions | Insert the name of the actual SOFA Conventions here | ||||
GLOBAL_SOFAConventionsVersion | Insert the actual SOFA convention version here | ||||
GLOBAL_APIName | Insert the API Name here | ||||
GLOBAL_APIVersion | Insert the API Version here | ||||
GLOBAL_AuthorContact | |||||
GLOBAL_License | No license provided, ask the author for permission | ||||
GLOBAL_Organization | |||||
GLOBAL_RoomType | free field | ||||
GLOBAL_DataType | FIR | Insert the name of the actual datatype here | |||
GLOBAL_History | |||||
GLOBAL_Source | The method of production of the original data. If it was model-generated, source should name the model and its version, as specifically as could be useful. If it is observational, source should characterize it. | ||||
GLOBAL_Title | A succinct description of what is in the dataset | ||||
GLOBAL_References | Published or web-based references that describe the data or methods used to produce it | ||||
GLOBAL_Comment | |||||
GLOBAL_TimeCreated | will be updated when saving and not existing or empty | ||||
GLOBAL_TimeModified | will be updated each time when saving | ||||
ListenerPosition | [1 0 0] | IC, MC | double | ||
ListenerPosition_Type | cartesian | ||||
ListenerPosition_Units | meter | ||||
ReceiverPosition | [0 -0.09 0; 0 0.09 0] | rCI, rCM | double | ||
ReceiverPosition_Type | cartesian | ||||
ReceiverPosition_Units | meter | ||||
SourcePosition | [0 0 0] | IC, MC | double | ||
SourcePosition_Type | cartesian | ||||
SourcePosition_Units | meter | ||||
EmitterPosition | [0 0 0] | eCI, eCM | double | ||
EmitterPosition_Type | cartesian | ||||
EmitterPosition_Units | meter |
Note: we consider the Data as mandatory, thus, Data must be provided according the corresponding DataType. If DataType is default (="FIR") then Data for the datatype "FIR" must be provided.
Legend:
- Name: the name of the metadata
- An underscore (_): the metadata is an attribute
- GLOBAL_: the metadata is a global attribute
- X_Y: the metadata is an attribute Y of the variable X
- No underscore: the metadata is a variable
- An underscore (_): the metadata is an attribute
- Default: default value for the metadata
- An asterisk (*): special handling required, mentioned in the column Comment
- Flags:
- r: read-only, must be the default value and must not be changed
- Dimensions: dimensions of the metadata (see SOFA specifications for more explanations)
- lower case: the variable size in that dimension determines the dimension size in the file
- upper case: variable must be of that dimension (or one of these dimensions)
- Type: type of the data, i.e., double, string, etc. Empty if attribute
Dimensional variables (coordinate variables): At the moment, we consider the dimension variables (or coordinate variables) as not mandatory, i.e., optional. Depending on the datatype and conventions, some of them might be mandatory, though. We suggest the type "double" for the dimensional variables.
Various issues
Versioning of SOFA and conventions
Three version types:
- Version: defines the version of the general SOFA specs
- ConventionsVersion: defines the version of the particular SOFA conventions. Could be merged with Version, but then, when we change something a Conventions, each time the version for the general SOFA specs would need to be increased. Not clear how to proceed. Maybe the AES standardization process will clarify. Until then: no merging, to be on the safe side.
- APIVersion: clearly separated from the rest.
Allow various DataTypes within a single SOFAConventions?
- Fixed DataType:
- Pro: very simple for applications: they just have to check the conventions and the data type is known.
- Con: separate conventions for each DataType required even though the measurement setup might have not changed.
- Arbitrary DataType allowed:
- Pro: less conventions, we will have conventions which do not consider the datatype.
- Con: Each application has either to provide all datatypes and branch while processing between the different algorithms, or to check both Conventions and DataType on loading.
At the moment we have 1 stable and 2 proposed SOFA Conventions. This number is rather low, thus we wait until we'll have more conventions and then decide if we want to allow to separate DataType from SOFAConventions.
Fix the coordinate systems within conventions?
Until now, Conventions support just a single coordinate system per variable and each application must use conversion functions if required.
Naming of the units
lowercase, the rest is not clarified yet.
Include strings as variables
Role of dimension variables
At the moment, we consider the dimension variables (or coordinate variables) as not mandatory, i.e., optional. Depending on the datatype and conventions, some of them might be mandatory, though. We suggest the type "double" for the dimensional variables. If provided, use also attributes to describe the LongName and Units.
DataType
New: IIRBiquad
Name | Default | Dimensions | Comment |
---|---|---|---|
Data.G | 1 | MR | broadband linear gain |
Data.B1 | MRN | nominator coefficient B1 | |
Data.B2 | MRN | nominator coefficient B2 | |
Data.A1 | MRN | denominator coefficient A1 | |
Data.A2 | MRN | denominator coefficient A2 | |
Data.Delay | 0 | MR | broadband delay |
Data.SamplingRate | 48000 | I | Sampling rate of the filter coefficients and the delay |
Data.SamplingRate_Units | hertz |
New: TF
Useful to describe a transfer function by a sparse number of frequencies. The guys from BEM simulations like it.
Name | Default | Dimensions | Type | Comment |
---|---|---|---|---|
Data.Real | 1 | mRn | double | real part of the complex spectrum |
Data.Imag | 0 | MRN | double | imaginary part of the complex spectrum |
N | 0 | N | double | frequency values |
N_LongName | frequency | |||
N_Units | hertz |
Note that the dimensional variable N is mandatory, must be of dimension N, and must provide the frequency values.
Update: FIR
The standard committee agreed that the broadband delay should be provided in any case. Thus, we propose to add a new field, Delay to the FIR type.
Name | Default | Dimensions | Type | Comment |
---|---|---|---|---|
Data.IR | 1 | mRn | double | impulse responses |
Data.Delay | 0 | IR, MR | double | broadband delay |
Data.SamplingRate | 48000 | I | double | Sampling rate of the IRs and the delay |
Data.SamplingRate_Units | hertz |
RoomType
We propose the following RoomTypes. Note that any other RoomType than freefield means that reverberation is expected to be in the data.
freefield
- Meaning: Data measured under assumed freefield conditions.
- Usage: Used for the most of the HRTF databases.
- Parameters:
- RoomDescription: optional, narrative description of the anechoic chamber used.
reverberant
- Meaning: don't know, don't care
- Usage: Default value.
- Parameters:
- RoomDescription: optional, narrative description of the room
shoebox
- Meaning: Rectangular room for which the size is known. Can be used as a first-order approximation of the room.
- Usage: BRIRs from Oldenburg measured in Office II are using that RoomType.
- Parameters:
- RoomCornerA: mandatory, [C], defines the first room corner. Provide Type and Units as well.
- RoomCornerB: mandatory, [C], defines the second room corner. Provide Type and Units as well.
- RoomDescription: optional, narrative description of the room.
link
- Meaning: Quantitative room description is provided in a separate file. This RoomType was "DAE" in previous SOFA versions, but I think that "link" is more general.
- Usage: Not used yet.
- Parameters:
- GLOBAL_RoomLink: mandatory, provides a link to the file. More details must be defined on the first appearance of usage.
- RoomDescription: optional, narrative description of the room.