From e90db5bca43a2d97b086cdfc5fa0215661b1365d Mon Sep 17 00:00:00 2001 From: "Dipl.-Ing. Jonas Stienen" <jst@akustik.rwth-aachen.de> Date: Wed, 16 May 2018 08:52:13 +0200 Subject: [PATCH] More documentation for DAFF class --- .../openDAFF/OpenDAFFv1.7/DAFF.m | 117 ++++++++++++------ 1 file changed, 82 insertions(+), 35 deletions(-) diff --git a/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m b/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m index c414137b..a95aef5f 100644 --- a/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m +++ b/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m @@ -1,77 +1,124 @@ classdef DAFF < handle + + % DAFF is a direction audio file format for virtual acoustics + % A daff file instance can be used to load a file in DAFF format and + % receiver metadata, proerties and directional audio content. + % + % The most important functions are + % + % load Open a DAFF file + % close Closes a DAFF file + % nearest_neighbour_record Receive content for a certain direction in spherical coordinates + % metadata Get DAFF metadata as struct + % properties Get DAFF properties as struct + % + properties (Access = protected) - daffhandle - view = 'object' + + daffhandle % The internal DAFF file handle + view = 'object' % The DAFF viewpoint (user/object or developer/data) + end + methods + function obj = DAFF( filepath ) - %% Create DAFF class and loads content from file - % filepath Path to DAFF file + % Creates a DAFF instance and loads content from file + % filepath Path to DAFF file if( nargin > 0 ) obj.open( filepath ) end end + function open( obj, filepath ) - %% Opens a DAFF file + % Opens a DAFF file obj.daffhandle = DAFFv17( 'open', filepath ); end + function close( obj ) - %% Closes the DAFF file + % Closes the DAFF file DAFFv17( 'close', obj.daffhandle ) end + function set_data_view( obj ) - %% Switches to data view (alpha, beta) + % Switches to data view (alpha, beta) obj.view = 'data'; end function set_object_view( obj ) - %% Switches to object / user view (elevation, azimuth) [default] + % Switches to object / user view (elevation, azimuth) [default] obj.view = 'object'; end - function metadata = get_metadata(obj) - %% Returns the metadata of an opened DAFF file - metadata = DAFFv17('getMetadata', obj.daffhandle); + function metadata = metadata(obj) + % Returns the metadata of an opened DAFF file + metadata = DAFFv17( 'getMetadata', obj.daffhandle ); end - function metadata = get_record_metadata( obj, index ) - %% Returns the record metadata of an opened DAFF file - metadata = DAFFv17('getRecordMetadata', obj.daffhandle, index); + function metadata = record_metadata( obj, index ) + % Returns the record metadata of an opened DAFF file + metadata = DAFFv17( 'getRecordMetadata', obj.daffhandle, index ); end - function props = get_properties( obj ) - %% Returns the properties of an opened DAFF file + function props = properties( obj ) + % Returns the properties of an opened DAFF file props = DAFFv17( 'getProperties', obj.daffhandle ); end - function coords = get_record_coords( obj, index ) - %% Returns the coordinates of a grid point + function coords = record_coords( obj, index ) + % Returns the coordinates of a grid point coords = DAFFv17( 'getRecordCoords', obj.daffhandle, obj.view, index ); end - function idx = get_nearest_neighbour_index( obj, azi_deg, ele_deg ) - %% Returns the data at the nearest neighbour grid point to the given direction + function idx = nearest_neighbour_index( obj, azi_deg, ele_deg ) + % Returns the data at the nearest neighbour grid point to the given direction + % Uses spherical coordinates azimuth and elevation in degree. + % + % azi_deg Azimuthal angle in degree + % ele_deg Elevation angle in degree + % idx = DAFFv17( 'getNearestNeighbourIndex', obj.daffhandle, obj.view, azi_deg, ele_deg ); end - function data = get_nearest_neighbour_record( obj, azi_deg, ele_deg ) - %% Returns the data at the nearest neighbour grid point to the given direction + function data = nearest_neighbour_record( obj, azi_deg, ele_deg ) + % Returns the data at the nearest neighbour grid point to the given direction + % Uses spherical coordinates azimuth and elevation in degree. + % + % azi_deg Azimuthal angle in degree + % ele_deg Elevation angle in degree + % data = DAFFv17( 'getNearestNeighbourRecord', obj.daffhandle, obj.view, azi_deg, ele_deg ); end - function rec = get_record_by_index( obj, idx ) - %% Returns the data at a grid of the given index + function rec = record_by_index( obj, idx ) + % Returns the data at a grid of the given index rec = DAFFv17( 'getRecordByIndex', obj.daffhandle, idx ); end - function data = get_cell_records( obj, azi_deg, ele_deg ) - %% Returns the data of all four records of the surrounding cell to the given direction + function data = cell_records( obj, azi_deg, ele_deg ) + % Returns the data of all four records of the surrounding cell to the given direction + % Uses spherical coordinates azimuth and elevation in degree. + % + % azi_deg Azimuthal angle in degree + % ele_deg Elevation angle in degree + % data = DAFFv17('getCellRecords', obj.daffhandle, obj.view, azi_deg, ele_deg ); end - function idx = get_cell( obj, azi_deg, ele_deg ) - %% Returns the data at the nearest neighbour grid point to the given direction + function idx = cell( obj, azi_deg, ele_deg ) + % Returns the data at the nearest neighbour grid point to the given direction + % Uses spherical coordinates azimuth and elevation in degree. + % + % azi_deg Azimuthal angle in degree + % ele_deg Elevation angle in degree + % idx = DAFFv17( 'getCell', obj.daffhandle, obj.view, azi_deg, ele_deg ); end + end + methods (Static) - function help() - %% Prints the help output of OpenDAFF - DAFFv17('help') + + function mex_help() + % Prints the help output of OpenDAFF extension (mex) + DAFFv17( 'help' ) end - function v = get_version() - %% Returns the OpenDAFF version - v = DAFFv17('getVersion'); + + function v = mex_version() + % Returns the OpenDAFF extension (mex) version + v = DAFFv17( 'getVersion' ); end - end + + end + end -- GitLab