-
Notifications
You must be signed in to change notification settings - Fork 4
Convention Templates
Ioseb Laghidze edited this page Jun 12, 2019
·
15 revisions
SOFASonix is packaged with a Template Generator for each convention supported by the API. The generated templates are python scripts that can be edited to quickly create SOFA files. Each template clarifies which parameters are mandatory for a given convention and version, alongside the required dimensions for Double or String variables.
The Templates folder of this repository contains generated templates for the latest versions of each convention (as of 01.06.19). However, templates for any convention version (GLOBAL:Version and GLOBAL:SOFAConventionsVersion) may be generated. The process for doing this is explained below.
Suppose it is of interest to generate three SOFA files for a custom third-party API. The conventions are "SimpleFreeFieldHRIR", "GeneralFIRE" and "MultiSpeakerBRIR". The third-party API supports the following versions for each of these conventions:
- SimpleFreeFieldHRIR - Version: 0.5, SOFAConventionsVersion: 0.3
- GeneralFIRE - Version: 0.6, SOFAConventionsVersion: 0.1
- MultiSpeakerBRIR - Version:0.6, SOFAConventionsVersion: 0.2
To generate a template for each of these configurations, the following script can be used
from SOFASonix import TemplateGenerator
TemplateGenerator("SimpleFreeFieldHRIR", sofaConventionsVersion=0.3, version=0.5)
TemplateGenerator("GeneralFIRE", sofaConventionsVersion=0.1, version=0.6)
TemplateGenerator("MultiSpeakerBRIR", sofaConventionsVersion=0.2, version=0.6, useNone=False)This will generate the following files in the directory the script above is run:
.
├── GeneralFIRE_0.6_0.1.py
├── MultiSpeakerBRIR_0.6_0.2.py
└── SimpleFreeFieldHRIR_0.5_0.3.py
The contents of each example file are displayed below for demonstration, with default dimension and parameter values where available. These files may be edited to insert the necessary information (whilst removing any non-mandatory options if desired using a value of None) and then run to generate the corresponding SOFA files using the SOFASonix API.
Note By default, the TemplateGenerator assigns a value of None to all non-mandatory parameters. This means they will be removed and hence not be included in the exported SOFA file. This default assignment is simply for convenience and can be disabled using the useNone=False argument, as seen with the MultiSpeakerBRIR case.
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright (c) 2018, I.Laghidze
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# * Neither the name of SOFASonix nor the names of its contributors
# may be used to endorse or promote products derived from this software
# without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# =============================================================================
#
# File: GeneralFIRE_0.6_0.1.py
# Project: SOFASonix
# Author: I.Laghidze
# License: BSD 3
#
# =============================================================================
from SOFASonix import SOFAFile
import numpy as np
"""
=============================== Initial Config ================================
"""
# Create SOFAFile object with the latest GeneralFIRE convention
sofa = SOFAFile("GeneralFIRE", sofaConventionsVersion=0.1, version=0.6)
# Set dimensions
sofa._M = 100
sofa._N = 1024
sofa._R = 2
sofa._E = 4
# View parameters of convention
sofa.view()
"""
=============================== Attributes ====================================
"""
# ----- Mandatory attributes -----
sofa.GLOBAL_AuthorContact = ""
sofa.GLOBAL_Comment = ""
sofa.GLOBAL_License = "No license provided, ask the author for permission"
sofa.GLOBAL_Organization = ""
sofa.GLOBAL_RoomType = "free field"
sofa.GLOBAL_DateCreated = "2019-06-07 19:38:06"
sofa.GLOBAL_DateModified = "2019-06-07 19:38:06"
sofa.GLOBAL_Title = ""
sofa.ListenerPosition_Type = "cartesian"
sofa.ListenerPosition_Units = "meter"
sofa.ReceiverPosition_Type = "cartesian"
sofa.ReceiverPosition_Units = "meter"
sofa.SourcePosition_Type = "spherical"
sofa.SourcePosition_Units = "degree, degree, meter"
sofa.EmitterPosition_Type = "cartesian"
sofa.EmitterPosition_Units = "meter"
sofa.Data_SamplingRate_Units = "hertz"
# ----- Non-Mandatory attributes -----
sofa.GLOBAL_ApplicationName = None
sofa.GLOBAL_ApplicationVersion = None
sofa.GLOBAL_History = None
sofa.GLOBAL_References = None
sofa.GLOBAL_Origin = None
"""
=============================== Double Variables ==============================
"""
# ----- Mandatory double variables -----
# Needs dimensions IC or MC
sofa.ListenerPosition = np.zeros(1)
# Needs dimensions rCI or rCM
sofa.ReceiverPosition = np.zeros(1)
# Needs dimensions IC or MC
sofa.SourcePosition = np.zeros(1)
# Needs dimensions eCI or eCM
sofa.EmitterPosition = np.zeros(1)
# Needs dimensions mREn
sofa.Data_IR = np.zeros(1)
# Needs dimensions I
sofa.Data_SamplingRate = np.zeros(1)
# Needs dimensions IRE or MRE
sofa.Data_Delay = np.zeros(1)
# ----- Non-mandatory double variables -----
"""
=============================== Export ========================================
"""
# Save file upon completion
sofa.export("filename")#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright (c) 2018, I.Laghidze
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# * Neither the name of SOFASonix nor the names of its contributors
# may be used to endorse or promote products derived from this software
# without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# =============================================================================
#
# File: MultiSpeakerBRIR_0.6_0.2.py
# Project: SOFASonix
# Author: I.Laghidze
# License: BSD 3
#
# =============================================================================
from SOFASonix import SOFAFile
import numpy as np
"""
=============================== Initial Config ================================
"""
# Create SOFAFile object with the latest MultiSpeakerBRIR convention
sofa = SOFAFile("MultiSpeakerBRIR", sofaConventionsVersion=0.2, version=0.6)
# Set dimensions
sofa._M = 100
sofa._N = 1024
sofa._R = 2
sofa._E = 4
# View parameters of convention
sofa.view()
"""
=============================== Attributes ====================================
"""
# ----- Mandatory attributes -----
sofa.GLOBAL_AuthorContact = ""
sofa.GLOBAL_Comment = ""
sofa.GLOBAL_License = "No license provided, ask the author for permission"
sofa.GLOBAL_Organization = ""
sofa.GLOBAL_RoomType = "reverberant"
sofa.GLOBAL_DateCreated = "2019-06-12 12:03:24"
sofa.GLOBAL_DateModified = "2019-06-12 12:03:24"
sofa.GLOBAL_Title = ""
sofa.GLOBAL_DatabaseName = ""
sofa.GLOBAL_ListenerShortName = ""
sofa.ListenerPosition_Type = "cartesian"
sofa.ListenerPosition_Units = "meter"
sofa.ListenerView_Type = "cartesian"
sofa.ListenerView_Units = "meter"
sofa.ReceiverPosition_Type = "cartesian"
sofa.ReceiverPosition_Units = "meter"
sofa.SourcePosition_Type = "spherical"
sofa.SourcePosition_Units = "degree, degree, meter"
sofa.EmitterPosition_Type = "cartesian"
sofa.EmitterPosition_Units = "meter"
sofa.Data_SamplingRate_Units = "hertz"
# ----- Non-Mandatory attributes -----
sofa.GLOBAL_ApplicationName = ""
sofa.GLOBAL_ApplicationVersion = ""
sofa.GLOBAL_History = ""
sofa.GLOBAL_References = ""
sofa.GLOBAL_Origin = ""
sofa.GLOBAL_RoomDescription = ""
sofa.EmitterView_Type = "cartesian"
sofa.EmitterView_Units = "meter"
"""
=============================== Double Variables ==============================
"""
# ----- Mandatory double variables -----
# Needs dimensions IC or MC
sofa.ListenerPosition = np.zeros(1)
# Needs dimensions IC or MC
sofa.ListenerUp = np.zeros(1)
# Needs dimensions IC or MC
sofa.ListenerView = np.zeros(1)
# Needs dimensions rCI or rCM
sofa.ReceiverPosition = np.zeros(1)
# Needs dimensions IC or MC
sofa.SourcePosition = np.zeros(1)
# Needs dimensions eCI or eCM
sofa.EmitterPosition = np.zeros(1)
# Needs dimensions mREn
sofa.Data_IR = np.zeros(1)
# Needs dimensions I
sofa.Data_SamplingRate = np.zeros(1)
# Needs dimensions IRE or MRE
sofa.Data_Delay = np.zeros(1)
# ----- Non-mandatory double variables -----
# Needs dimensions ECI or ECM
sofa.EmitterUp = np.zeros(1)
# Needs dimensions ECI or ECM
sofa.EmitterView = np.zeros(1)
"""
=============================== Export ========================================
"""
# Save file upon completion
sofa.export("filename")#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright (c) 2018, I.Laghidze
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# * Neither the name of SOFASonix nor the names of its contributors
# may be used to endorse or promote products derived from this software
# without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# =============================================================================
#
# File: SimpleFreeFieldHRIR_0.5_0.3.py
# Project: SOFASonix
# Author: I.Laghidze
# License: BSD 3
#
# =============================================================================
from SOFASonix import SOFAFile
import numpy as np
"""
=============================== Initial Config ================================
"""
# Create SOFAFile object with the latest SimpleFreeFieldHRIR convention
sofa = SOFAFile("SimpleFreeFieldHRIR", sofaConventionsVersion=0.3, version=0.5)
# Set dimensions
sofa._M = 100
sofa._N = 1024
# View parameters of convention
sofa.view()
"""
=============================== Attributes ====================================
"""
# ----- Mandatory attributes -----
sofa.GLOBAL_ApplicationName = ""
sofa.GLOBAL_ApplicationVersion = ""
sofa.GLOBAL_AuthorContact = ""
sofa.GLOBAL_Comment = ""
sofa.GLOBAL_History = ""
sofa.GLOBAL_License = "No license provided, ask the author for permission"
sofa.GLOBAL_Organization = ""
sofa.GLOBAL_References = ""
sofa.GLOBAL_RoomType = "free field"
sofa.GLOBAL_Source = ""
sofa.GLOBAL_TimeCreated = ""
sofa.GLOBAL_TimeModified = ""
sofa.GLOBAL_Title = ""
sofa.GLOBAL_DatabaseName = ""
sofa.GLOBAL_SubjectID = ""
sofa.ListenerPosition_Type = "cartesian"
sofa.ListenerPosition_Units = "meter"
sofa.ReceiverPosition_Type = "cartesian"
sofa.ReceiverPosition_Units = "meter"
sofa.SourcePosition_Type = "spherical"
sofa.SourcePosition_Units = "degree, degree, meter"
sofa.EmitterPosition_Type = "cartesian"
sofa.EmitterPosition_Units = "meter"
sofa.Data_SamplingRate_Units = "hertz"
# ----- Non-Mandatory attributes -----
"""
=============================== Double Variables ==============================
"""
# ----- Mandatory double variables -----
# Needs dimensions IC or MC
sofa.ListenerPosition = np.zeros(1)
# Needs dimensions IC or MC
sofa.ListenerUp = np.zeros(1)
# Needs dimensions IC or MC
sofa.ListenerView = np.zeros(1)
# Needs dimensions rCI or rCM
sofa.ReceiverPosition = np.zeros(1)
# Needs dimensions IC or MC
sofa.SourcePosition = np.zeros(1)
# Needs dimensions eCI or eCM
sofa.EmitterPosition = np.zeros(1)
# Needs dimensions mRn
sofa.Data_IR = np.zeros(1)
# Needs dimensions I
sofa.Data_SamplingRate = np.zeros(1)
# Needs dimensions IR or MR
sofa.Data_Delay = np.zeros(1)
# ----- Non-mandatory double variables -----
"""
=============================== Export ========================================
"""
# Save file upon completion
sofa.export("filename")