itaVA.m.proto 14 KB
Newer Older
1
classdef itaVA < handle
2
    %ITAVA Remote network interface to VA (Virtual Acoustics), the real-time 
3 4 5
    %auralization framework.
	%
	% Find the VA applications, documentation and examples here: http://www.virtualacoustics.org
6 7 8
    %
    %   This class realizes a remote connection to a VA real-time
    %   auralization server and implements the full VA core interface
9 10
    %   in Matlab. You can connect to to the server
    %   and control all of its features to perform real-time
11
    %   auralization, including integrated live tracking if an OptiTrack tracker is at hand.
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 25
    %     If the connection is established, you can start controlling VA via the interface.
    %	  For instance create an move a sound source:
26
    %
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
27
    %     sourceID = va.create_sound_source( 'My Matlab virtual sound source' )
28
	%	  va.set_sound_source_position( sourceID, [ 0 0 0 ] );
29 30 31 32 33 34 35 36 37 38
    %
    %     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
39
                
40 41 42 43 44
        % Connection defaults
        DEFAULT_SERVER_PORT = 12340;
    end
    
    methods(Static)
45 46 47
        
        function [ ok ] = check_for_mex_file()
            % Checks if VAMatlab executable can be found.
48
            if ~exist( 'VAMatlab', 'file' )
49 50 51
                disp( 'Matlab binding for VA not complete (missing VAMatlab executable).' )
                
                % file dialog
52
                itaVA_setup()
53
                
54 55
                % Re-check
                ok = exist( 'VAMatlab', 'file' ) > 0;
56 57 58 59 60
            else
                ok = true;
            end
        end
        
61
        function [version] = get_version()
62 63 64 65 66 67 68 69 70
            % Return the version of the VA Matlab interface
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	version  [string]  Version string
71 72 73 74 75
            
            if ~itaVA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

76
            version = VAMatlab('get_version');
77 78
        end
        
79
         function [] = set_verbose_mode(mode)
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
            % 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'
            %
95 96 97 98 99
            
            if ~itaVA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

100
            VAMatlab('set_verbose_mode', mode);
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
        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');
            %
            
126
            if ~itaVA.check_for_mex_file()
127 128 129
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end
        
130 131 132 133 134 135 136 137 138 139
            if (nargin > 0)
                this.connect(addressstring)
            end
        end
        
        function delete(this)
            % Destructor. Automatically disconnects an existing connection.
            this.disconnect
        end 
       
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
140
        function [connected] = get_connected(this)
141
            % Returns if a connection to a server is established
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
142
           connected = VAMatlab('get_connected', this.handle);
143 144 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
        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
           
183
        function [state] = get_server_state(this)
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
            % 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; 
204
            state = VAMatlab('get_server_state', this.handle);
205 206
        end
        
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
207
        function connect_tracker( this, remote_ip, local_ip )
208 209
            % Connects to a local NatNet tracking server
            % 
210 211
            % The server will update a virtual sound receiver for real-time 
            % sound synthesis and the real world sound receiver position for
212 213 214
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
215
            % See also set_tracked_sound_receiver.
216 217 218 219 220 221 222 223 224 225 226 227
            %
            % 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

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

end