itaVA.m.proto 13.5 KB
Newer Older
1
classdef itaVA < handle
2 3
    %ITAVA Remote network interface to VA (Virtual Acoustics), the real-time 
    %auralization software made by ITA.
4 5 6
    %
    %   This class realizes a remote connection to a VA real-time
    %   auralization server and implements the full VA core interface
7 8 9 10 11
    %   in Matlab. You can connect to to the server
    %   and control all of its features to perform real-time
    %   auralization, including live tracking if available.
    %   In order to get understand to the concepts behind VA
    %   please refer to the VA documentation or have a look at the example scripts.
12
    %
13
    %   See also: itaVA_example_simple, itaVA_example_tracked_sound_receiver,
14 15 16
    %   itaVA_example_generic_path_renderer, itaVA_example_random_numbers
    %
    %   Quick usage:
17 18 19 20
    %
    %   - Create an interface and connect to the server running on the
    %     same computer (localhost)
    %
21 22
    %     va = itaVA;
    %     va.connect;
23 24
    %
    %     If no error occurs, you can then use the interface to work with
25
    %     the VA server.
26
    %
27
    %     Now, you can call other methods. For instance create a sound
28 29
    %     source:
    %
Dipl.-Ing. Jonas Stienen's avatar
Fix  
Dipl.-Ing. Jonas Stienen committed
30
    %     sourceID = va.create_sound_source( 'My Matlab virtual sound source' )
31 32 33 34 35 36 37 38 39 40
    %
    %     When everything is done, do not forget to close the connection.
    %     You can call disconnect on the instance or simply clear it:
    %
    %     clear va
    %
    %
    
    properties(Hidden = true, Access = private)
        handle = int32(0); % Connection handle
41
                
42 43 44 45 46
        % Connection defaults
        DEFAULT_SERVER_PORT = 12340;
    end
    
    methods(Static)
47 48 49
        
        function [ ok ] = check_for_mex_file()
            % Checks if VAMatlab executable can be found.
50
            if ~exist( 'VAMatlab', 'file' )
51 52 53
                disp( 'Matlab binding for VA not complete (missing VAMatlab executable).' )
                
                % file dialog
54
                itaVA_setup()
55
                
56 57
                % Re-check
                ok = exist( 'VAMatlab', 'file' ) > 0;
58 59 60 61 62
            else
                ok = true;
            end
        end
        
63
        function [version] = get_version()
64 65 66 67 68 69 70 71 72
            % Return the version of the VA Matlab interface
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	version  [string]  Version string
73 74 75 76 77
            
            if ~itaVA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

78
            version = VAMatlab('get_version');
79 80
        end
        
81
         function [] = set_verbose_mode(mode)
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
            % Sets the verbose level of the VA Matlab interface
            %
            % Parameters:
            %
            % 	mode  [string]   Verbose mode ('quiet'|'normal')
            %
            % Return values:
            %
            % 	None
            %
            % Remarks:
            %
            % - If you do not want any messages from the extension
            %   set the verbose mode to 'quiet'
            %
97 98 99 100 101
            
            if ~itaVA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

102
            VAMatlab('set_verbose_mode', mode);
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
        end
    end

    methods
        function this = itaVA(addressstring)
            % Initialization constructor. Initiiates a new connection.
            %
            % Parameters:
            %
            % 	addressstring  [string]   Hostname or IP address and port of the
            %                             server string (name:port), optional
            %
            % Return values:
            %
            % 	None
            %
            % Remarks:
            %
            % - You can leave the argument 'address' undefined, in order
            %   to create an clear, unconnected instance and connect to
            %   a server later using the method 'connect'
            % - Example: core = itaVA;
            %            core = itaVA('localhost:12340');
            %
            
128
            if ~itaVA.check_for_mex_file()
129 130 131
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end
        
132 133 134 135 136 137 138 139 140 141
            if (nargin > 0)
                this.connect(addressstring)
            end
        end
        
        function delete(this)
            % Destructor. Automatically disconnects an existing connection.
            this.disconnect
        end 
       
142
        function [connected] = is_connected(this)
143
            % Returns if a connection to a server is established
144
           connected = VAMatlab('is_connected', this.handle);
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
        end
        
        function connect(this, addressstring)
            % Connects to a server
            %
            % Parameters:
            %
            % 	addressstring  [string]   Hostname or IP address and port of the
            %                             server string (name:port), optional
            %
            % Return values:
            %
            % 	None
            %
            % Remarks:
            %
            % - An error occurs if the instance is already connected
            % - Example: core.connect('localhost:12340')
            %
            if this.handle~=0
				error('Already connected. Close the existing connection first.'); 
			end 
            
			if nargin == 2
				if isempty(addressstring) 
					error('Server address must not be empty.');
				end
			else
				addressstring = 'localhost';
			end
            
            this.handle = VAMatlab('connect', addressstring);
        end
        
        function disconnect(this)
            % Disconnects from a server
            VAMatlab('disconnect', this.handle)
            this.handle = int32(0);
        end
           
185
        function [state] = get_server_state(this)
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
            % Returns the state of the connected server
            %
            % Use this function to check whether the server is
            % running fine and does not have any problems.
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	state [integer-1x1] Server stat
            %
            % States:
            % 
            % - 0 = Connected, but server not configured. Failure.
            % - 1 = Connected and ready for usage.
            % - 2 = Connected, but server has failure.
            %
            if this.handle==0, error('Not connected.'); end; 
206
            state = VAMatlab('get_server_state', this.handle);
207 208
        end
        
Dipl.-Ing. Jonas Stienen's avatar
Fix  
Dipl.-Ing. Jonas Stienen committed
209
        function connect_tracker( this, remote_ip, local_ip )
210 211
            % Connects to a local NatNet tracking server
            % 
212 213
            % The server will update a virtual sound receiver for real-time 
            % sound synthesis and the real world sound receiver position for
214 215 216
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
217
            % See also set_tracked_sound_receiver.
218 219 220 221 222 223 224 225 226 227 228 229
            %
            % Parameters (optional):
            %
            % 	remote_ip [char]	Remote ip address
            % 	local_ip [char]		Local ip address
            %

			if( nargin == 1 )
				remote_ip = '127.0.0.1';
				local_ip = '127.0.0.1';
			end

230
            VAMatlab( 'connect_tracker', this.handle, remote_ip, local_ip );
231 232
        end
        
233
        function [connected] = get_tracker_connected( this )
234
            % Returns true, if tracker is connected
235
            connected = VAMatlab( 'get_tracker_connected', this.handle );
236 237
        end
        
238
        function disconnect_tracker( this )
239
            % Disconnects from the NatNet tracking server
240
            VAMatlab( 'disconnect_tracker', this.handle )
241 242
        end
        
243
		% -- Tracked sound receiver -- %
244
		
245 246
        function set_tracked_sound_receiver( this, sound_receiver_id )
            % Connects a VA sound receiver with the tracked sound receiver rigid body
247 248 249
            %
            % Parameters:
            %
250
            % 	sound_receiver_id  [integer-1x1]   VA sound receiver id
251
            %
252
            VAMatlab( 'set_tracked_sound_receiver', this.handle, sound_receiver_id );
Jonas Stienen's avatar
Jonas Stienen committed
253
        end
254
        
255
        function set_tracked_sound_receiver_head_rigid_body_index( this, index )
256
            % Sets the index of the rigid body to be tracked for sound receiver (default is 1)
257
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_index', this.handle, index )
258 259
        end
        
260 261 262 263 264 265
        function set_tracked_sound_receiver_torso_rigid_body_index( this, index )
            % Sets the index of the rigid body to be tracked for sound receiver's absolute torso orientation (default is 1)
            VAMatlab( 'set_tracked_sound_receiver_torso_rigid_body_index', this.handle, index )
        end
        
        function set_tracked_sound_receiver_head_rigid_body_translation( this, translation )
266
            % Sets the pivot point translation for the tracked sound receiver rigid body
267 268 269 270 271
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
272
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_translation', this.handle, translation )
273 274
        end
        
275
        function set_tracked_sound_receiver_head_rigid_body_rotation( this, rotation )
276
            % Sets the rotation of orientation for the tracked sound receiver rigid body
277 278 279 280 281 282 283
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
284
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
285 286
        end
		
287
		% -- Tracked real-world sound receiver -- %
288
		
289 290
        function set_tracked_real_world_sound_receiver( this, sound_receiver_id )
            % Connects a VA real-world sound receiver with the tracked real-world rigid body
291 292 293
            %
            % Parameters:
            %
294
            % 	sound_receiver_id  [integer-1x1]   VA real-world sound receiver id
295
            %
296
            VAMatlab( 'set_tracked_real_world_sound_receiver', this.handle, sound_receiver_id );
297 298
        end
		
299
        function set_tracked_real_world_sound_receiver_head_rigid_body_index( this, index )
300 301
            % Sets the index of the rigid body to be tracked for real-world sound receiver (default is 1)
            VAMatlab( 'set_tracked_real_world_sound_receiver_rigid_body_index', this.handle, index )
Jonas Stienen's avatar
Jonas Stienen committed
302
        end
303 304 305 306 307
		
        function set_tracked_real_world_sound_receiver_torso_rigid_body_index( this, index )
            % Sets the index of the rigid body to be tracked for real-world sound receiver' torso (default is 1)
            VAMatlab( 'set_tracked_real_world_sound_receiver_torso_rigid_body_index', this.handle, index )
        end
Jonas Stienen's avatar
Jonas Stienen committed
308
        
309
        function set_tracked_real_world_sound_receiver_head_rigid_body_translation( this, translation )
310
            % Sets the pivot point translation for the tracked real-world sound receiver rigid body
Jonas Stienen's avatar
Jonas Stienen committed
311 312 313 314 315
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
316
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_translation', this.handle, translation )
Jonas Stienen's avatar
Jonas Stienen committed
317
        end
318
        
319
        function set_tracked_real_world_sound_receiver_head_rigid_body_rotation( this, rotation )
320
            % Sets the rotation of orientation for the tracked real-world sound receiver rigid body
Jonas Stienen's avatar
Jonas Stienen committed
321 322 323 324 325 326 327
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
328
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
Jonas Stienen's avatar
Jonas Stienen committed
329 330
        end
		        
331 332
		% -- Tracked source -- %
		
333
        function set_tracked_sound_source( this, source_id )
334 335 336 337
            % Connects a VA source with the tracked source rigid body
            %
            % Parameters:
            %
Jonas Stienen's avatar
Jonas Stienen committed
338
            % 	source_id  [integer-1x1]   VA source id
339
            %
340
            VAMatlab( 'set_tracked_sound_source', this.handle, source_id );
341
        end
342
		
343
        function set_tracked_source_rigid_body_index( this, index )
Jonas Stienen's avatar
Jonas Stienen committed
344
            % Sets the index of the rigid body to be tracked for source (default is 1)
345
            VAMatlab( 'set_tracked_source_rigid_body_index', this.handle, index )
Jonas Stienen's avatar
Jonas Stienen committed
346 347
        end
        
348
        function set_tracked_source_rigid_body_translation( this, translation )
Jonas Stienen's avatar
Jonas Stienen committed
349 350 351 352 353 354
            % Sets the pivot point translation for the tracked source rigid body
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
355
            VAMatlab( 'set_tracked_source_rigid_body_translation', this.handle, translation )
Jonas Stienen's avatar
Jonas Stienen committed
356 357
        end
        
358
        function set_tracked_source_rigid_body_rotation( this, rotation )
Jonas Stienen's avatar
Jonas Stienen committed
359 360 361 362 363 364 365 366
            % Sets the rotation of orientation for the tracked source rigid body
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
367
            VAMatlab( 'set_tracked_source_rigid_body_rotation', this.handle, rotation )
Jonas Stienen's avatar
Jonas Stienen committed
368 369
        end
		
370 371 372 373 374 375 376 377
        
        %% --= Functions =--
        
        ###STUBCODE###
        
        function display(this)
            % TODO: Define nice behaviour
%             if this.handle
378
%                 fprintf('Connection established to server ''%s''\n', this.get_server_address())
379 380 381 382 383 384 385 386
%             else
%                 fprintf('Not connected\n');
%             end
        end
        
    end

end