elec_load - Read ascii electrode file
Load an ascii electrode file and return
the electrode labels and coordinates. This
function can read and return Cartesian (x,y,z)
and/or spherical (theta,phi,r) coordinates.
The ascii file format is that of NeuroScan
3Dspace export files. Each row of the file
comprises an electrode label, an electrode
type code (see below), and the x,y,z
coordinates (cm). Each field is separated
by spaces. For example,
Fz 69 Xcm Ycm Zcm
Usage:
[elec,type,X,Y,Z,theta,phi,r] = elec_load(file,[coordinates],[xo],[yo],[zo],[N])
where:
file = 'path\filename' with row format:
'%s %d %f %f %f' = [elec_label, type, (X,Y,Z) or (theta,phi,r)]
N is how many electrodes to load (129 default).
(xo,yo,zo) are the origin {(0,0,0) default}.
coordinates is a string option for input data type:
'Cartesian' = cartesian in Neuroscan 3Dspace format (default);
format is ['label' type X Y Z].
As of 08/2003, it is better to use
elec_load_scan_3ddasc for Neuroscan 3Dspace
ascii export files (*.dat). Otherwise, try
this function.
'Spherical1' = spherical, theta and phi in degrees,
'Spherical2' = spherical, theta and phi in radians,
format is ['label' type theta phi r]
theta is counterclockwise rotation from +x in x-y plane (azimuth),
phi is elevation with respect to z-axis, r is radius in cm,
+ve x-axis from origin through T4 (right ear)
+ve y-axis from origin through Nasion (theta = 90degrees = pi/2 rads)
Result:
elec is an electrode label, as cellstr array (Nx1)
type is an electrode type, as uint8 (unsigned integer, Nx1),
(X,Y,Z) & (theta,phi,r) as double floating point (Nx1), with
theta and phi in radians. The origin is (0,0,0), unless forced
otherwise with the input arguments.
Notes:
i) Type is defined as follows (from Neuroscan 3Dspace ascii export):
Electrode Type
--------- ----
Nasion 110 (or 78)
Left 108 (or 76)
Right 114 (or 82)
electrodes 69
Centroid 99 (or 67; eg <0,0,0>)
Ref 120 (or 88)
Scalp Points 32
Open the 3Dspace ascii export (*.dat file) and check these type
values. If they are not consistent with the above, either hack
the code of this function or edit the type values in the ascii
file.
From the return values, the electrodes can be selected by:
index = find(type == 69); % or whatever the type is in your file
X = X(index); Y = Y(index); Z = Z(index); elec = elec(index);
ii) Conversion from spherical to Cartesian coordinates is:
x = r .* sin(phi) .* cos(theta);
y = r .* sin(phi) .* sin(theta);
z = r .* cos(phi);
Phi here is elevation with respect to z-axis. The matlab
function sph2cart uses elevation with respect to xy plane.
iii) Conversion from Cartesian to spherical coordinates is:
theta = atan2( y, x );
phi = atan2( sqrt( x.^2 + y.^2 ), z );
r = sqrt( x.^2 + y.^2 + z.^2);
Phi here is the elevation with respect to z-axis. The matlab
function cart2sph uses elevation with respect to xy plane.
Bugs:
For NeuroScan 3Dspace export files, reading beyond the electrode
points, into the scalp points (type 32), causes all fields to
shift one to the left. To avoid this error, include a short
string before each '32' in the electrode file or use the N
option to only read the electrode points.0001 function [elec,type,X,Y,Z,theta,phi,r] = elec_load(filename,coordinates,xo,yo,zo,N) 0002 0003 % elec_load - Read ascii electrode file 0004 % 0005 % Load an ascii electrode file and return 0006 % the electrode labels and coordinates. This 0007 % function can read and return Cartesian (x,y,z) 0008 % and/or spherical (theta,phi,r) coordinates. 0009 % 0010 % The ascii file format is that of NeuroScan 0011 % 3Dspace export files. Each row of the file 0012 % comprises an electrode label, an electrode 0013 % type code (see below), and the x,y,z 0014 % coordinates (cm). Each field is separated 0015 % by spaces. For example, 0016 % 0017 % Fz 69 Xcm Ycm Zcm 0018 % 0019 % Usage: 0020 % 0021 % [elec,type,X,Y,Z,theta,phi,r] = elec_load(file,[coordinates],[xo],[yo],[zo],[N]) 0022 % 0023 % where: 0024 % 0025 % file = 'path\filename' with row format: 0026 % 0027 % '%s %d %f %f %f' = [elec_label, type, (X,Y,Z) or (theta,phi,r)] 0028 % 0029 % N is how many electrodes to load (129 default). 0030 % (xo,yo,zo) are the origin {(0,0,0) default}. 0031 % 0032 % coordinates is a string option for input data type: 0033 % 'Cartesian' = cartesian in Neuroscan 3Dspace format (default); 0034 % format is ['label' type X Y Z]. 0035 % 0036 % As of 08/2003, it is better to use 0037 % elec_load_scan_3ddasc for Neuroscan 3Dspace 0038 % ascii export files (*.dat). Otherwise, try 0039 % this function. 0040 % 0041 % 'Spherical1' = spherical, theta and phi in degrees, 0042 % 'Spherical2' = spherical, theta and phi in radians, 0043 % format is ['label' type theta phi r] 0044 % 0045 % theta is counterclockwise rotation from +x in x-y plane (azimuth), 0046 % phi is elevation with respect to z-axis, r is radius in cm, 0047 % +ve x-axis from origin through T4 (right ear) 0048 % +ve y-axis from origin through Nasion (theta = 90degrees = pi/2 rads) 0049 % 0050 % Result: 0051 % 0052 % elec is an electrode label, as cellstr array (Nx1) 0053 % type is an electrode type, as uint8 (unsigned integer, Nx1), 0054 % (X,Y,Z) & (theta,phi,r) as double floating point (Nx1), with 0055 % theta and phi in radians. The origin is (0,0,0), unless forced 0056 % otherwise with the input arguments. 0057 % 0058 % Notes: 0059 % 0060 % i) Type is defined as follows (from Neuroscan 3Dspace ascii export): 0061 % 0062 % Electrode Type 0063 % --------- ---- 0064 % Nasion 110 (or 78) 0065 % Left 108 (or 76) 0066 % Right 114 (or 82) 0067 % electrodes 69 0068 % Centroid 99 (or 67; eg <0,0,0>) 0069 % Ref 120 (or 88) 0070 % Scalp Points 32 0071 % 0072 % Open the 3Dspace ascii export (*.dat file) and check these type 0073 % values. If they are not consistent with the above, either hack 0074 % the code of this function or edit the type values in the ascii 0075 % file. 0076 % 0077 % From the return values, the electrodes can be selected by: 0078 % index = find(type == 69); % or whatever the type is in your file 0079 % X = X(index); Y = Y(index); Z = Z(index); elec = elec(index); 0080 % 0081 % ii) Conversion from spherical to Cartesian coordinates is: 0082 % 0083 % x = r .* sin(phi) .* cos(theta); 0084 % y = r .* sin(phi) .* sin(theta); 0085 % z = r .* cos(phi); 0086 % 0087 % Phi here is elevation with respect to z-axis. The matlab 0088 % function sph2cart uses elevation with respect to xy plane. 0089 % 0090 % iii) Conversion from Cartesian to spherical coordinates is: 0091 % 0092 % theta = atan2( y, x ); 0093 % phi = atan2( sqrt( x.^2 + y.^2 ), z ); 0094 % r = sqrt( x.^2 + y.^2 + z.^2); 0095 % 0096 % Phi here is the elevation with respect to z-axis. The matlab 0097 % function cart2sph uses elevation with respect to xy plane. 0098 % 0099 % Bugs: 0100 % For NeuroScan 3Dspace export files, reading beyond the electrode 0101 % points, into the scalp points (type 32), causes all fields to 0102 % shift one to the left. To avoid this error, include a short 0103 % string before each '32' in the electrode file or use the N 0104 % option to only read the electrode points. 0105 % 0106 0107 % $Revision: 1.2 $ $Date: 2005/07/12 22:16:48 $ 0108 0109 % Licence: GNU GPL, no express or implied warranties 0110 % History: 08/1999, Darren.Weber_at_radiology.ucsf.edu 0111 % 08/2003, Darren.Weber_at_radiology.ucsf.edu 0112 % new version of 3Dspace exports different type numbers ;-) 0113 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0114 0115 if ~exist('N', 'var'), N = 129; 0116 elseif isempty(N), N = 129; 0117 end 0118 if ~exist('coordinates', 'var'), 0119 coordinates = 'Cartesian'; 0120 elseif isempty(coordinates), 0121 coordinates = 'Cartesian'; 0122 end 0123 if ~exist('xo', 'var'), xo = 0; 0124 elseif isempty(xo), xo = 0; 0125 end 0126 if ~exist('yo', 'var'), yo = 0; 0127 elseif isempty(xo), yo = 0; 0128 end 0129 if ~exist('zo', 'var'), zo = 0; 0130 elseif isempty(xo), zo = 0; 0131 end 0132 0133 tic; 0134 0135 [path,name,ext] = fileparts(filename); 0136 file = fullfile(path,[name ext]); 0137 0138 eegversion = '$Revision: 1.2 $'; 0139 fprintf('ELEC_LOAD [v %s]\n',eegversion(11:15)); 0140 fprintf('...loading ''%s'' electrodes from:\n\t%s\n', coordinates, file); 0141 0142 switch coordinates 0143 0144 case 'Cartesian' 0145 [elec,type,X,Y,Z] = textread(file,'%s %d %f %f %f', N); 0146 type = uint8(type); 0147 0148 fprintf('...converting from cm to meters.\n'); 0149 % Convert from Neuroscan 3Dspace coordinate 0150 % metric (cm) to meters. 0151 X = X ./ 100; Y = Y ./ 100; Z = Z ./ 100; 0152 0153 % If possible, adjust all coordinates so that origin is (0,0,0) 0154 index = find(type == 99); 0155 if ~isempty(index), 0156 xo = X(index); yo = Y(index); zo = Z(index); 0157 end 0158 fprintf('...centering origin at (0,0,0).\n'); 0159 X = X - xo; Y = Y - yo; Z = Z - zo; 0160 xo = X(index); yo = Y(index); zo = Z(index); 0161 0162 % Convert to spherical 0163 fprintf('...calculating spherical coordinates.\n'); 0164 theta = atan2( (Y-yo), (X-xo) ); 0165 phi = atan2( sqrt( (X-xo).^2 + (Y-yo).^2 ), (Z-zo) ); 0166 r = sqrt( (X-xo).^2 + (Y-yo).^2 + (Z-zo).^2); 0167 0168 case 'Spherical1' %degrees 0169 [elec,type,theta,phi,r] = textread(file,'%s %d %f %f %f', N); 0170 % convert theta and phi to radians 0171 theta = theta * (pi/180); phi = phi * (pi/180); 0172 [X, Y, Z] = elec_sph2cart(theta,phi,r,1); 0173 fprintf('...converting from cm to meters.\n'); 0174 X = X ./ 100; Y = Y ./ 100; Z = Z ./ 100; 0175 0176 case 'Spherical2' %radians 0177 [elec,type,theta,phi,r] = textread(file,'%s %d %f %f %f', N); 0178 [X, Y, Z] = elec_sph2cart(theta,phi,r,0); 0179 fprintf('...converting from cm to meters.\n'); 0180 X = X ./ 100; Y = Y ./ 100; Z = Z ./ 100; 0181 0182 otherwise 0183 doc elec_load; 0184 msg = sprintf('...invalid coordinate type: ''%s'', see ''help elec_load''\n', coordinates); 0185 error(msg); 0186 0187 end 0188 0189 fprintf('...loaded %d electrodes\n', size(elec,1)); 0190 0191 t = toc; fprintf('...done (%6.2f sec).\n\n',t); 0192 0193 return