sofar 1.2.1__py3-none-any.whl

sofar/sofa_conventions/write_verification_rules.py

@@ -0,0 +1,356 @@
+"""
+Write rules for validating SOFA files to json files.
+
+Writes the following json files:
+rules.json
+    Rules for verifying SOFA conventions and files
+unit_aliases.json
+    Allowed aliases for the standard units
+
+For a more detailed information about the json files refer to _readme.txt
+"""
+# %%
+import json
+import os
+from sofar.utils import _get_conventions
+
+# deprecations
+# NOTE: no further specific tests are enforced for deprecated conventions,
+#       i.e., there are no entries in `rules` for them.
+deprecations = {
+    "GLOBAL:SOFAConventions": {
+        "GeneralFIRE":"GenerelFIR-E",
+        "MultiSpeakerBRIR": "SingleRoomMIMOSRIR",
+        "MusicalInstrumentDirectivityTF": "FreeFieldDirectivityTF",
+        "SimpleBRIR": "SingleRoomSRIR",
+        "SingleRoomDRIR": "SingleRoomSRIR",
+        "SimpleFreeFieldDirectivityTF": "FreeFieldDirectivityTF",
+        "SimpleFreeFieldSOS": "SimpleFreeFieldHRSOS",
+        "SimpleFreeFieldTF": "SimpleFreeFieldHRTF",
+        "SingleTrackedAudio":
+            "AnnotatedEmitterAudio or AnnotatedReceiverAudio",
+    },
+}
+
+# definition of valid coordinate systems. Not defined explicitly in AES69 but
+# dozens of mentions of the following:
+coords_min = ["cartesian", "spherical"]
+coords_full = coords_min + ["spherical harmonics"]
+
+# definition of units acordings to AES69 Table 7
+units_min = ["metre", "degree, degree, metre"]
+units_full = units_min + [units_min[1]]
+
+# allowed alternative versions of units
+# NOTE: AES69 allows multi-unit strings to be separated by comma, comma plus
+#       space and space (AES69 Section 4.7.8). This means that the unit
+#       "cubic metre" will be tested as a multi unit string and is thus also
+#       split in the aliases. A separate test for verifying that "cubic" is
+#       followed be "metre" must be performed.
+unit_aliases = {
+    "metre": "metre",
+    "metres": "metre",
+    "meter": "metre",
+    "meters": "metre",
+    "cubic": "cubic",
+    "degree": "degree",
+    "degrees": "degree",
+    "second": "second",
+    "seconds": "second",
+}
+# possible values for restricted dimensions in the API
+# Dimensions for spherical harmonics (considering orders up to 100) according
+# to AES69 Eq. (5) and (6)
+sh_dimension = ([(N+1)**2 for N in range(100)],
+                "(N+1)**2 where N is the spherical harmonics order")
+# Dimensions for SOS (considering up to 100 sections) according to AES69
+# Appendix C.5.2
+sos_dimension = ([6 * (N + 1) for N in range(100)],
+                 "an integer multiple of 6 greater 0")
+
+# verification rules
+rules = {
+    # Global --------------------------------------------------------------
+    # Check value of GLOBAL_DataType (AES69 Annex C)
+    # (FIRE and TFE are legacy data types from SOFA version 1.0)
+    "GLOBAL:DataType": {
+        "value": ["Audio", "FIR", "FIR-E", "FIRE", "TF", "TF-E", "SOS"],
+        "specific":  {
+            "Audio": {
+                "Data.SamplingRate": None,
+                "Data.SamplingRate:Units": ["hertz"]},
+            "FIR": {
+                "Data.IR": None,
+                "Data.Delay": None,
+                "Data.SamplingRate": None,
+                "Data.SamplingRate:Units": ["hertz"]},
+            "FIR-E": {
+                "Data.IR": None,
+                "Data.Delay": None,
+                "Data.SamplingRate": None,
+                "Data.SamplingRate:Units": ["hertz"]},
+            "FIRE": {
+                "Data.IR": None,
+                "Data.Delay": None,
+                "Data.SamplingRate": None,
+                "Data.SamplingRate:Units": ["hertz"]},
+            "TF": {
+                "Data.Real": None,
+                "Data.Imag": None,
+                "N": None,
+                "N:Units": ["hertz"]},
+            "TF-E": {
+                "Data.Real": None,
+                "Data.Imag": None,
+                "N": None,
+                "N:Units": ["hertz"]},
+            "TFE": {
+                "Data.Real": None,
+                "Data.Imag": None,
+                "N": None,
+                "N:Units": ["hertz"]},
+            "SOS": {
+                "Data.SOS": None,
+                "Data.Delay": None,
+                "Data.SamplingRate": None,
+                "Data.SamplingRate:Units": ["hertz"],
+                # Checking the dimension of N if having SOS data
+                # (assuming up to 100 second order sections)
+                "_dimensions": {
+                    "N": {
+                        "value": sos_dimension[0],
+                        "value_str": sos_dimension[1]},
+                }}}},
+    # Specified in AES69 Section 4.7.7 and Table 6
+    "GLOBAL:RoomType": {
+        "value": ["free field", "reverberant", "shoebox", "dae"],
+        "specific": {
+            "reverberant": {
+                "GLOBAL:RoomDescription": None},
+            "shoebox": {
+                "RoomCornerA": None,
+                "RoomCornerB": None},
+            "dae": {
+                "GLOBAL:RoomGeometry": None}}},
+    # Specified in AES69 Annex D
+    "GLOBAL:SOFAConventions": {
+        "value": _get_conventions(return_type="name"),
+        "specific": {
+            "AnnotatedEmitterAudio": {
+                "Data.Emitter": None},
+            "AnnotatedReceiverAudio": {
+                "Data.Receiver": None},
+            "GeneralFIR": {
+                "GLOBAL:DataType": ["FIR"]},
+            "GeneralFIR-E": {
+                "GLOBAL:DataType": ["FIR-E"]},
+            "GeneralTF": {
+                "GLOBAL:DataType": ["TF"]},
+            "GeneralTF-E": {
+                "GLOBAL:DataType": ["TF-E"]},
+            "SimpleFreeFieldHRIR": {
+                "GLOBAL:DataType": ["FIR"],
+                "GLOBAL:RoomType": ["free field"],
+                "EmitterPosition:Type": coords_min,
+                "_dimensions": {
+                    "E": {
+                        "value": [1],
+                        "value_str": "1"}}},
+            "SimpleFreeFieldHRTF": {
+                "GLOBAL:DataType": ["TF"],
+                "GLOBAL:RoomType": ["free field"],
+                "EmitterPosition:Type": coords_min,
+                "_dimensions": {
+                    "E": {
+                        "value": [1],
+                        "value_str": "1"}}},
+            "SimpleFreeFieldHRSOS": {
+                "GLOBAL:DataType": ["SOS"],
+                "GLOBAL:RoomType": ["free field"],
+                "EmitterPosition:Type": coords_min,
+                "_dimensions": {
+                    "E": {
+                        "value": [1],
+                        "value_str": "1"}}},
+            "FreeFieldHRIR": {
+                "GLOBAL:DataType": ["FIR-E"],
+                "GLOBAL:RoomType": ["free field"]},
+            "FreeFieldHRTF": {
+                "GLOBAL:DataType": ["TF-E"],
+                "GLOBAL:RoomType": ["free field"]},
+            "SimpleHeadphoneIR": {
+                "GLOBAL:DataType": ["FIR"]},
+            "SingleRoomSRIR": {
+                "GLOBAL:DataType": ["FIR"]},
+            "SingleRoomMIMOSRIR": {
+                "GLOBAL:DataType": ["FIR-E"]},
+            "FreeFieldDirectivityTF": {
+                "GLOBAL:DataType": ["TF"]}}},
+    # check NLongName (AES69 Tables C.3 and C.4)
+    "N:LongName": {
+        "value": ["frequency"]},
+    # Listener ------------------------------------------------------------
+    # Possible values and dependencies are specified in
+    # AES69 Section 4.7.3
+    # ---------------------------------------------------------------------
+    # Check values and consistency of if ListenerPosition Type and Unit
+    "ListenerPosition:Type": {
+        "value": coords_min,
+        "specific": {
+            coords_min[0]: {
+                "ListenerPosition:Units": [units_min[0]]},
+            coords_min[1]: {
+                "ListenerPosition:Units": [units_min[1]]},
+        }},
+    # Check if dependencies of ListenerView are contained
+    "ListenerView": {
+        "value": None,
+        "general": ["ListenerView:Type", "ListenerView:Units"]},
+    # Check values and consistency of if ListenerView Type and Unit
+    "ListenerView:Type": {
+        "value": coords_min,
+        "specific": {
+            coords_min[0]: {
+                "ListenerView:Units": [units_min[0]]},
+            coords_min[1]: {
+                "ListenerView:Units": [units_min[1]]},
+        }},
+    # Check if dependencies of ListenerUp are contained
+    "ListenerUp": {
+        "value": None,
+        "general": ["ListenerView"]},
+    # Receiver ------------------------------------------------------------
+    # Possible values and dependencies are specified in
+    # AES69 Section 4.7.4
+    # ---------------------------------------------------------------------
+    # Check values and consistency of if ReceiverPosition Type and Unit
+    "ReceiverPosition:Type": {
+        "value": coords_full,
+        "specific": {
+            coords_full[0]: {
+                "ReceiverPosition:Units": [units_full[0]]},
+            coords_full[1]: {
+                "ReceiverPosition:Units": [units_full[1]]},
+            coords_full[2]: {
+                "ReceiverPosition:Units": [units_full[2]],
+                "_dimensions": {
+                    # Check dimension R if using spherical harmonics for the
+                    # receiver (assuming SH orders < 100)
+                    "R": {
+                        "value": sh_dimension[0],
+                        "value_str": sh_dimension[1]}}},
+        }},
+    # Check if dependencies of ReceiverView are contained
+    "ReceiverView": {
+        "value": None,
+        "general": ["ReceiverView:Type", "ReceiverView:Units"]},
+    # Check values and consistency of if ReceiverView Type and Unit
+    "ReceiverView:Type": {
+        "value": coords_min,
+        "specific": {
+            coords_min[0]: {
+                "ReceiverView:Units": [units_min[0]]},
+            coords_min[1]: {
+                "ReceiverView:Units": [units_min[1]]},
+            }},
+    # Check if dependencies of ReceiverUp are contained
+    "ReceiverUp": {
+        "value": None,
+        "general": ["ReceiverView"]},
+    # Source --------------------------------------------------------------
+    # Possible values and dependencies are specified in
+    # AES69 Section 4.7.5
+    # ---------------------------------------------------------------------
+    # Check values and consistency of if SourcePosition Type and Unit
+    "SourcePosition:Type": {
+        "value": coords_min,
+        "specific": {
+            coords_min[0]: {
+                "SourcePosition:Units": [units_min[0]]},
+            coords_min[1]: {
+                "SourcePosition:Units": [units_min[1]]},
+            }},
+    # Check if dependencies of SourceView are contained
+    "SourceView": {
+        "value": None,
+        "general": ["SourceView:Type", "SourceView:Units"]},
+    # Check values and consistency of if SourceView Type and Unit
+    "SourceView:Type": {
+        "value": coords_min,
+        "specific": {
+            coords_min[0]: {
+                "SourceView:Units": [units_min[0]]},
+            coords_min[1]: {
+                "SourceView:Units": [units_min[1]]},
+            }},
+    # Check if dependencies of SourceUp are contained
+    "SourceUp": {
+        "value": None,
+        "general": ["SourceView"]},
+    # Emitter -------------------------------------------------------------
+    # Possible values and dependencies are specified in
+    # AES69 Section 4.7.6
+    # ---------------------------------------------------------------------
+    # Check values and consistency of if EmitterPosition Type and Unit
+    "EmitterPosition:Type": {
+        "value": coords_full,
+        "specific": {
+            coords_full[0]: {
+                "EmitterPosition:Units": [units_full[0]]},
+            coords_full[1]: {
+                "EmitterPosition:Units": [units_full[1]]},
+            coords_full[2]: {
+                "EmitterPosition:Units": [units_full[2]],
+                "_dimensions": {
+                    # Check dimension R if using spherical harmonics for the
+                    # receiver (assuming SH orders < 100)
+                    "E": {
+                        "value": sh_dimension[0],
+                        "value_str": sh_dimension[1]}}},
+        }},
+    # Check if dependencies of EmitterView are contained
+    "EmitterView": {
+        "value": None,
+        "general": ["EmitterView:Type", "EmitterView:Units"]},
+    # Check values and consistency of if EmitterView Type and Unit
+    "EmitterView:Type": {
+        "value": coords_min,
+        "specific": {
+            coords_min[0]: {
+                "EmitterView:Units": [units_min[0]]},
+            coords_min[1]: {
+                "EmitterView:Units": [units_min[1]]},
+            }},
+    # Check if dependencies of EmitterUp are contained
+    "EmitterUp": {
+        "value": None,
+        "general": ["EmitterView"]},
+    # Check if dependencies of EmitterDescriptions are contained (specified in
+    # 5.3, D.12.5, D.13.5, D.14.5, D15.5)
+    "EmitterDescriptions": {
+        "value": None,
+        "general": ["GLOBAL:EmitterDescription"]},
+    # Room ----------------------------------------------------------------
+    # Possible values and dependencies are specified in
+    # AES69 Section 4.7.7
+    # ---------------------------------------------------------------------
+    "RoomVolume": {
+        "value": None,
+        "general": ["RoomVolume:Units"]},
+    "RoomTemperature": {
+        "value": None,
+        "general": ["RoomTemperature:Units"]},
+    "RoomVolume:Units": {
+        "value": ["cubic metre"]},
+    "RoomTemperature:Units": {
+        "value": ["kelvin"]},
+}
+
+# write to json files
+for content, name in zip([rules, unit_aliases, deprecations],
+                         ["rules", "unit_aliases", "deprecations"]):
+
+    json_file = os.path.join(
+        os.path.dirname(__file__), "rules", name + '.json')
+    with open(json_file, 'w') as file:
+        json.dump(content, file, indent=4)

sofar/sofastream.py

@@ -0,0 +1,301 @@
+"""
+Read desired data from SOFA-file directly from disk without loading entire
+file into memory.
+"""
+from netCDF4 import Dataset
+import numpy as np
+
+
+class SofaStream():
+    """
+    Read desired data from SOFA-file directly from disk without loading entire
+    file into memory.
+
+    :class:`SofaStream` opens a SOFA-file and retrieves only the requested
+    data.
+
+    If you want to use all the data from a SOFA-file use :class:`Sofa`
+    class and :func:`read_sofa` function instead.
+
+    Parameters
+    ----------
+    filename : str
+        Full path to a SOFA-file
+
+    Returns
+    -------
+    sofa_stream : SofaStream
+        A SofaStream object which reads directly from the file.
+
+    Examples
+    --------
+    Get an attribute from a SOFA-file:
+
+        >>> import sofar as sf
+        >>> filename = "path/to/file.sofa"
+        >>> with sf.SofaStream(filename) as file:
+        >>>     data = file.GLOBAL_RoomType
+        >>>     print(data)
+        free field
+
+    Get a variable from a SOFA-file:
+
+        >>> with SofaStream(filename) as file:
+        >>>     data = file.Data_IR
+        >>>     print(data)
+        <class 'netCDF4._netCDF4.Variable'>
+        float64 Data.IR(M, R, N)
+        unlimited dimensions:
+        current shape = (11950, 2, 256)
+        filling on, default _FillValue of 9.969209968386869e+36 used
+
+    What is returned is a `netCDF-variable`. To access the values (in this
+    example the IRs) the variable needs to be sliced:
+
+        >>> with SofaStream(filename) as file:
+        >>>     data = file.Data_IR
+        >>>     # get all values
+        >>>     all_irs = data[:]
+        >>>     print(all_irs.shape)
+        (11950, 2, 256)
+        >>>     # get data from first channel
+        >>>     specific_irs = data[:,0,:]
+        >>>     print(specific_irs.shape)
+        (11950, 256)
+    """
+
+    def __init__(self, filename):
+        """Initialize a new SofaStream object (see documentation above)."""
+        self._filename = filename
+
+    def __enter__(self):
+        """
+        Executed when entering a ``with`` statement
+        (see documentation above).
+        """
+        self._file = Dataset(self._filename, mode="r")
+        return self
+
+    def __exit__(self, *args):
+        """
+        Executed when exiting a ``with`` statement
+        (see documentation above).
+        """
+        self._file.close()
+
+    def __getattr__(self, name):
+        """
+        Executed when accessing data within a with statement
+        (see documentation above).
+        """
+        # get netCDF4-attributes and -variable-keys from SOFA-file
+        dset_variables = np.array(list(self._file.variables.keys()))
+        dset_attributes = np.asarray(self._file.ncattrs())
+
+        # remove delimiter from passed sofar-attribute
+        name_netcdf = name.replace(
+            'GLOBAL_', '').replace('Data_', 'Data.')
+
+        # Handle variable-attributes (e.g. '_Units' and '_Type')
+        var_attr = None
+        if "_" in name_netcdf:
+            name_netcdf, var_attr = name_netcdf.split('_')
+
+        # get value if passed attribute points to a netCDF4-variable
+        if name_netcdf in dset_variables:
+            # get variable from SOFA-file
+            self._data = self._file.variables[name_netcdf]
+            if var_attr is not None:
+                self._data = getattr(self._data, var_attr)
+
+        # get value if passed attribute points to a netCDF4-attribute
+        elif name_netcdf in dset_attributes:
+            # get attribute value from SOFA-file
+            self._data = self._file.getncattr(name_netcdf)
+
+        else:
+            raise AttributeError(f"{name} is not contained in SOFA-file")
+
+        return self._data
+
+    @property
+    def list_dimensions(self):
+        """
+        Print the dimensions of the SOFA-file.
+
+        See :py:func:`~SofaStream.inspect` to see the shapes of the data inside
+        the SOFA-file and :py:func:`~SofaStream.get_dimension` to get the
+        size/value of a specific dimensions as integer number.
+
+        The SOFA standard defines the following dimensions that are used
+        to define the shape of the data entries:
+
+        M
+            number of measurements
+        N
+            number of samples, frequencies, SOS coefficients
+            (depending on GLOBAL_DataType)
+        R
+            Number of receivers or SH coefficients
+            (depending on ReceiverPosition_Type)
+        E
+            Number of emitters or SH coefficients
+            (depending on EmitterPosition_Type)
+        S
+            Maximum length of a string in a string array
+        C
+            Size of the coordinate dimension. This is always three.
+        I
+            Single dimension. This is always one.
+
+        """
+        dim = self._file.dimensions
+
+        # get verbose description for dimesion N
+        if self._file.getncattr('DataType').startswith("FIR"):
+            N_verbose = "samples"
+        elif self._file.getncattr('DataType').startswith("TF"):
+            N_verbose = "frequencies"
+        elif self._file.getncattr('DataType').startswith("SOS"):
+            N_verbose = "SOS coefficients"
+
+        # get verbose description for dimensions R and E
+        R_verbose = (
+            "receiver spherical harmonics coefficients"
+            if 'harmonic'
+            in self._file.variables['ReceiverPosition'].getncattr('Type')
+            else "receiver"
+            )
+        E_verbose = (
+            "emitter spherical harmonics coefficients"
+            if 'harmonic'
+            in self._file.variables['EmitterPosition'].getncattr('Type')
+            else "emitter"
+            )
+
+        dimensions = {
+            "M": "measurements",
+            "N": N_verbose,
+            "R": R_verbose,
+            "E": E_verbose,
+            "S": "maximum string length",
+            "C": "coordinate dimensions, fixed",
+            "I": "single dimension, fixed"}
+
+        info_str = ""
+        for key, value in dim.items():
+            value = value.size
+            dim_info = dimensions[key] if key in dimensions \
+                else "custom dimension"
+
+            info_str += f"{key} = {value} {dim_info}" + '\n'
+
+        print(info_str)
+
+    def get_dimension(self, dimension):
+        """
+        Get size of a SOFA dimension.
+
+        SOFA dimensions specify the shape of the data contained in a SOFA-file.
+        For a list of all dimensions see :py:func:`~list_dimensions`, for more
+        information about the data contained in a SOFA-file use
+        :py:func:`~inspect`.
+
+        Parameters
+        ----------
+        dimension : str
+            The dimension as a string, e.g., ``'N'``.
+
+        Returns
+        -------
+        size : int
+            the size of the queried dimension.
+        """
+
+        # get dimensons from SOFA-file
+        dims = self._file.dimensions
+
+        if dimension not in dims.keys():
+            raise ValueError((
+                f"{dimension} is not a valid dimension. "
+                "See Sofa.list_dimensions for a list of valid dimensions."))
+
+        return dims[dimension].size
+
+    def inspect(self, file=None):
+        """
+        Get information about the data inside a SOFA-file.
+
+        Prints the values of all attributes and variables with six or less
+        entries and the shapes and type of all numeric and string variables.
+        When printing the values of arrays, single dimensions are discarded for
+        easy of display, i.e., an array of shape (1, 3, 2) will be displayed as
+        an array of shape (3, 2).
+
+        Parameters
+        ----------
+        file : str
+            Full path of a file under which the information is to be stored in
+            plain text. The default ``None`` only print the information to the
+            console.
+        """
+
+        # Header of inspect-print
+        info_str = (
+            f"{self._file.getncattr('SOFAConventions')} "
+            f"{self._file.getncattr('SOFAConventionsVersion')} "
+            f"(SOFA version {self._file.getncattr('Version')})\n")
+        info_str += "-" * len(info_str) + "\n"
+
+        # information for attributes
+        for attr in self._file.ncattrs():
+
+            value = self._file.getncattr(attr)
+            sofar_attr = f"GLOBAL_{attr}"
+            info_str += sofar_attr + ' : ' + str(value) + '\n'
+
+        # information for variables
+        for key in self._file.variables.keys():
+            # get values, shape and dimensions
+            data = self._file[key]
+            shape = data.shape
+            dimensions = data.dimensions
+
+            # add variable name to info-string
+            info_str += key.replace('.', '_') + ' : '
+
+            # pad shape if required (trailing single dimensions are
+            # discarded following the numpy default)
+            while len(shape) < len(dimensions):
+                shape += (1, )
+
+            # add value for scalars
+            if data.size == 1:
+                info_str += str(data[:][0]) + '\n'
+
+            # Handle multidimensional data
+            else:
+                # make verbose shape, e.g., '(M=100, R=2, N=128, '
+                shape_verbose = "("
+                for s, d in zip(shape, dimensions):
+                    shape_verbose += f"{d}={s}, "
+
+                # add shape information
+                info_str += shape_verbose[:-2] + ")\n"
+                # add value information if not too much
+                if data.size < 7:
+                    info_str += "  " + \
+                        str(np.squeeze(data[:])).replace("\n", "\n  ") + "\n"
+
+            # Add variable-attributes to info string (e.g. 'Type' or 'Units)
+            for att_ in list(self._file[key].ncattrs()):
+                info_str += (key.replace('.', '_') + f'_{att_} : '
+                             + getattr(data, att_) + '\n')
+
+        # write to text file
+        if file is not None:
+            with open(file, 'w') as f_id:
+                f_id.write(info_str + "\n")
+
+        # print to console
+        print(info_str)