Proposal 0.4: Difference between revisions

From Sofaconventions
Jump to navigation Jump to search
← Older edit
Content deleted Content added
Closing 0.4
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
'''Only changes compared to the last version are listed here!!!'''
'''Only changes compared to the last version are listed here!!!'''


'''Please discuss the proposal by using the "Discussion" function of Wiki.'''


⚫
== Mandatory metadata ==


We propose the following metadata to be mandatory for '''all''' SOFA conventions. Following rules must be fulfilled:
⚫
== Fix mandatory metadata ==
* Mandatory because without this metadata '''any''' conventions will fail

The metadata mandatory in all SOFA conventions have not been fixed yet. We propose to have the following metadata mandatory in all SOFA conventions:
* Or, mandatory because users might forget it, resulting in inconsistencies for '''all''' conventions




Line 45: Line 45:
|GLOBAL_Title|||||||||| A succinct description of what is in the dataset
|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
|GLOBAL_References|||||||| || Published or web-based references that describe the data or methods used to produce it
to produce it
|-
|-
|GLOBAL_Comment|||||||| ||
|GLOBAL_Comment|||||||| ||
|-
|-
|GLOBAL_DatabaseTimeCreated|| || |||| || will be updated when saving and not existing or empty
|GLOBAL_TimeCreated|| || |||| || will be updated when saving and not existing or empty
|-
|-
|GLOBAL_DatabaseTimeModified|| || |||||| will be updated each time when saving
|GLOBAL_TimeModified|| || |||||| will be updated each time when saving
|-
|-
|ListenerPosition|| [1 0 0] ||||IC, MC|| double ||
|ListenerPosition|| [1 0 0] ||||IC, MC|| double ||
Line 99: Line 98:
'''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.
'''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 ==
=== Versioning of SOFA and conventions ===


Three version types:
Three version types:
Line 106: Line 106:
* APIVersion: clearly separated from the rest.
* APIVersion: clearly separated from the rest.


== Can datatypes change within conventions? ==
=== Allow various DataTypes within a single SOFAConventions? ===
If yes, any application would have either to implement all possible datatypes or to check if the supported datatype is given within the conventions.


* Fixed DataType:
Thus, no, until we will have so many conventions with only the datatype changing that we decide to change this decision.
** 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:
⚫
== Fix the coordinate systems ==
** 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 naming of the units ==


⚫
=== Fix the coordinate systems within conventions? ===
⚫
== Include strings as variables ==
Until now, Conventions support just a single coordinate system per variable and each application must use conversion functions if required.


== Clarify the role of dimension variables ==
=== Naming of the units ===
lowercase, the rest is not clarified yet.


⚫
=== Include strings as variables ===
⚫
== New datatype: IIRBiquad ==

=== 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 ===


{| border="1"
{| border="1"
Line 144: Line 155:
|}
|}


== New datatype: ComplexSpectrum ==
=== New: TF ===

Useful to describe a transfer function by a sparse number of frequencies. The guys from BEM simulations like it.


{| border="1"
{| border="1"
Line 167: Line 180:
Note that the dimensional variable N is mandatory, must be of dimension N, and must provide the frequency values.
Note that the dimensional variable N is mandatory, must be of dimension N, and must provide the frequency values.


== Update of datatype FIR ==
=== 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.
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.
Line 186: Line 199:
|Data.SamplingRate_Units||hertz|| || ||
|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.

Latest revision as of 14:36, 20 August 2013

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
  • 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.
Retrieved from "https://www.sofaconventions.org/mediawiki/index.php?title=Proposal_0.4&oldid=1687"