VA.m.proto 14.7 KB
Newer Older
1 2
classdef VA < handle
    %VA 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 14
    %   See also: VA_example_simple, VA_example_tracked_sound_receiver,
    %   VA_example_generic_path_renderer, VA_example_random_numbers
15
    %   VA_example_generic_path_renderer, VA_example_random_numbers
16 17
    %
    %   Quick usage:
18 19 20 21
    %
    %   - Create an interface and connect to the server running on the
    %     same computer (localhost)
    %
22
    %     va = VA;
23
    %     va.connect;
24
    %
25 26
    %     If the connection is established, you can start controlling VA via the interface.
    %	  For instance create an move a sound source:
27
    %
Dipl.-Ing. Jonas Stienen's avatar
Fix  
Dipl.-Ing. Jonas Stienen committed
28
    %     sourceID = va.create_sound_source( 'My Matlab virtual sound source' )
29
	%	  va.set_sound_source_position( sourceID, [ 0 0 0 ] );
30 31 32 33 34 35 36 37 38 39
    %
    %     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
40
                
41 42 43 44 45
        % Connection defaults
        DEFAULT_SERVER_PORT = 12340;
    end
    
    methods(Static)
46 47 48
        
        function [ ok ] = check_for_mex_file()
            % Checks if VAMatlab executable can be found.
49
            if ~exist( 'VAMatlab', 'file' )
50
                disp( 'Matlab binding for VA not found, starting VA setup routine' )
51 52
                
                % file dialog
53
                VA_setup()
54
                
55 56
                % Re-check
                ok = exist( 'VAMatlab', 'file' ) > 0;
57 58 59 60 61
            else
                ok = true;
            end
        end
        
62
        function [version] = get_version()
63 64 65 66 67 68 69 70 71
            % Return the version of the VA Matlab interface
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	version  [string]  Version string
72
            
73
            if ~VA.check_for_mex_file()
74 75 76
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

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

101
            VAMatlab('set_verbose_mode', mode);
102
        end
103
		
104 105 106
    end

    methods
107
        function this = VA(addressstring)
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123
            % 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'
124 125
            % - Example: core = VA;
            %            core = VA('localhost:12340');
126 127
            %
            
128
            if ~VA.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 
       
Dipl.-Ing. Jonas Stienen's avatar
Fixes  
Dipl.-Ing. Jonas Stienen committed
142
        function [connected] = get_connected(this)
143
            % Returns if a connection to a server is established
Dipl.-Ing. Jonas Stienen's avatar
Fixes  
Dipl.-Ing. Jonas Stienen committed
144
           connected = VAMatlab('get_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
        end
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
		
		function shutdown_server(this)
            % Attempts to shut down the remote server
            %
            % Server shutdown may be prohibited by the server configuration.
			% Shutting donw the server from client side is meant for cases
			% when the server is called by a script to run e.g. a simulation
			% while the rendering output is recorded. The export is triggered
			% when the core is finalized (or shut down).
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	None
            %
			VAMatlab( 'call_module', this.handle, 'VACore', struct( 'shutdown', true ) );
		end
228
        
Dipl.-Ing. Jonas Stienen's avatar
Fix  
Dipl.-Ing. Jonas Stienen committed
229
        function connect_tracker( this, remote_ip, local_ip )
230 231
            % Connects to a local NatNet tracking server
            % 
232 233
            % The server will update a virtual sound receiver for real-time 
            % sound synthesis and the real world sound receiver position for
234 235 236
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
237
            % See also set_tracked_sound_receiver.
238 239 240 241 242 243 244 245 246 247 248 249
            %
            % 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

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

end