Aufgrund eines Security Updates wird GitLab heute zwischen 14:30 und 15:00 Uhr kurzzeitig nicht zur Verfügung stehen. / Due to a security update GitLab will be temporarily unavailable between 2:30 and 3 today.

VA.m.proto 14.6 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 16
    %
    %   Quick usage:
17 18 19 20
    %
    %   - Create an interface and connect to the server running on the
    %     same computer (localhost)
    %
21
    %     va = VA;
22
    %     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
Fix  
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
                VA_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
            if ~VA.check_for_mex_file()
73 74 75
                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
            if ~VA.check_for_mex_file()
97 98 99
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

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

    methods
106
        function this = VA(addressstring)
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
            % 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'
123 124
            % - Example: core = VA;
            %            core = VA('localhost:12340');
125 126
            %
            
127
            if ~VA.check_for_mex_file()
128 129 130
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end
        
131 132 133 134 135 136 137 138 139 140
            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
141
        function [connected] = get_connected(this)
142
            % Returns if a connection to a server is established
Dipl.-Ing. Jonas Stienen's avatar
Fixes  
Dipl.-Ing. Jonas Stienen committed
143
           connected = VAMatlab('get_connected', this.handle);
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 183
        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
           
184
        function [state] = get_server_state(this)
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
            % 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; 
205
            state = VAMatlab('get_server_state', this.handle);
206
        end
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
		
		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
227
        
Dipl.-Ing. Jonas Stienen's avatar
Fix  
Dipl.-Ing. Jonas Stienen committed
228
        function connect_tracker( this, remote_ip, local_ip )
229 230
            % Connects to a local NatNet tracking server
            % 
231 232
            % The server will update a virtual sound receiver for real-time 
            % sound synthesis and the real world sound receiver position for
233 234 235
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
236
            % See also set_tracked_sound_receiver.
237 238 239 240 241 242 243 244 245 246 247 248
            %
            % 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

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

end