biophysics - User contributions [en]

EXP programs

2026-09-29T07:53:04Z

Lof: /* Introduction */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including RZ6 systems, LED controllers, motors, and head movement systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration.

The programs are based on the EXP_framework, which is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

The [https://gitlab.science.ru.nl/marcw/biofysica/-/blob/master/experiment/EXP_programs/EXP_programs_user_manual.docx?ref_type=heads EXP_programs_use_manual.docx] can be downloaded from gitlab.

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These classes are templates for lab-specific classes which are used for building a lab-specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*An experiment file (.exp) specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each constructor.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-09-29T07:50:48Z

Lof: /* Introduction */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including RZ6 systems, LED controllers, motors, and head movement systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration.

The programs are based on the EXP_framework, which is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

A manual (EXP_programs_use_manual.docx) can be downloaded from gitlab.

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These classes are templates for lab-specific classes which are used for building a lab-specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*An experiment file (.exp) specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each constructor.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-09-29T07:48:10Z

Lof: /* Lab program example */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including RZ6 systems, LED controllers, motors, and head movement systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration.

The programs are based on the EXP_framework, which is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These classes are templates for lab-specific classes which are used for building a lab-specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*An experiment file (.exp) specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each constructor.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-09-29T07:46:53Z

Lof: /* EXP framework */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including RZ6 systems, LED controllers, motors, and head movement systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration.

The programs are based on the EXP_framework, which is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These classes are templates for lab-specific classes which are used for building a lab-specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*An experiment file (.exp) specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-09-29T07:44:14Z

Lof: /* EXP framework */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including RZ6 systems, LED controllers, motors, and head movement systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration.

The programs are based on the EXP_framework, which is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main objects in the EXP framework are:

environment
hardwareSystem
experiment
recordingsHandler
experimentPlayer
guiHandler
gui

*These objects are derived from EXP_ classes which are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*An experiment file (.exp) specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-09-29T07:42:07Z

Lof: /* EXP framework */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including RZ6 systems, LED controllers, motors, and head movement systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration.

The programs are based on the EXP_framework, which is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main objects in the EXP framework are:

environment
hardwareSystem
experiment
recordingsHandler
experimentPlayer
guiHandler
gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

Units in Matlab

2026-09-16T10:57:15Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
energy = power * time
x = sin(angle)
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
energy_kWh = power_kW * time_h
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:55:54Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
energy = power * time
x = sin(angle)
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
energy = 1000 * energy_kWh * hour
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:55:27Z

Lof: /* SI units */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
energy = power * time
x = sin(angle)
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
energy = 1000 * hour * energy_kWh
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:54:07Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
x = sin(angle)
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
energy = 1000 * hour * energy_kWh
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:53:48Z

Lof: /* SI units */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
x = sin(angle)
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
energy = 1000 * hour * energy_kWh
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:53:03Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
energy = 1000 * hour * energy_kWh
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:52:26Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
energy_kWh = 1000 * hour * energy
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:51:01Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
power_kW = 1000 * power
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:50:32Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
power_kW =
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:49:14Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
presure_psi = force_pnd / area_sqi
speed_kmh = distance_km / time_h
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:47:49Z

Lof: /* SI units */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
speed_kmh = distance_km / time_h
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:47:35Z

Lof: /* SI units */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
speed = distance / time
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
speed_kmh = distance_km / time_h
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:46:26Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
speed_kmh = distance_km / time_h
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

Units in Matlab

2026-09-16T10:46:16Z

Lof: /* Programming rules */

__TOC__
==Introduction==
When working with quantities we often have to know what the units are in which the quantities are expressed. There are several ways to use variables with units in a program.

Space probes have crashed on Mars due to invalid assumptions about units for some variables. So how can we avoid this type of disasters? We have to make it as simple and explicit as possible. But most importantly we have to have rules and stick to it!

==SI units==

In science we have the '''primary''' SI-units of the Franse Système international d'unités:

<pre>
Meter (m) - Unit of length
Kilogram (kg) - Unit of mass
Second (s) - Unit of time
Ampere (A) - Unit of electric current
Kelvin (K) - Unit of temperature
Mole (mol) - Unit of amount of substance
Candela (cd) - Unit of luminous intensity
</pre>

Combinations of these units are considered '''derived''' SI-units. These are units like m/s and units that can be expressed in terms of SI-units but have their own name, like: Newton (kg.m/s²) or Pascal (N/m²).

SI-units with prefixes like ''millisecond'' or ''centimeter'' are '''not''' considered primary or derived SI-units.

''Primary'' and ''derived'' SI-units will be here defined as '''basic SI-units'''. Units with prefixes do not fall under this definition.

Some common derived SI-units are:
<pre>
Joule (energy)
Coulomb (electric charge)
Voltage (electric potential)
Ohm (electric resistance)
Farad (electric capacitance)
Tesla (magnetic field strength)
Newton (force)
Watt (power)
Pascal (pressure)
</pre>

By using basic SI-units formulae can be expressed in their simplest form.
Examples:
<pre>
pressure = force / area
power = potential * current
</pre>

==Programming rules==
Primary rules:
* Use basic SI-units as much as possible.
* Use of basic SI-units is implicit: variables like ''someLength, someTime, someVolume'' are assumed in SI-units.
* Variables in non-basic SI-units like ''nanometer, millisecond'' or ''liter'' should have explicit '''suffixes''' like ''someLength_nm, someTime_ms or someVolume_liter''.
* Use of radians for angles is implicit. When using degrees use the suffix "_deg".

Secondary rules:
* If an input interface has non-basic units, convert them to basic SI-units as soon as possible after you read them from the interface.
* If an output interface needs non-basic units, convert them from basic SI-units as late as possible before outputting them.
* If you need to deviate from the primary rules make it explicit with comments.

examples:
speed_kmh = distance_km / time_h
x = sin(2*pi*angle_deg/360)

summary:
<pre>
Basic SI-units: implicit (preferred)
Other units : explicit by using suffixes
</pre>

EXP programs

2026-09-16T10:40:54Z

Lof: /* Introduction */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including RZ6 systems, LED controllers, motors, and head movement systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration.

The programs are based on the EXP_framework, which is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-09-16T10:34:26Z

Lof: /* Introduction */

==Introduction==

The EXP program software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

Experimental Software

2026-09-16T10:33:50Z

Lof: /* EXP programs */

==Biofysica toolbox==
*The [[Biofysica toolbox]] is the software repository on Gitlab for the Biophysics group.

==EXP programs==
*[[EXP programs]] are MATLAB programs for each biophysics lab with a Tucker Davis RZ6 device. The programs can be used for a variety of sound and vision experiments.

==BIOX==
*[[BIOX]] (BIOphysics eXperiment software) is a MATLAB software interface for the RZ6 multi I/O processor.

==Matrixtest==
*[[Matrixtest]] is MATLAB software for testing word recognition under different circumstances.

EXP programs

2026-08-31T08:30:05Z

Lof: /* EXP framework */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays real time information during the experiment.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:28:52Z

Lof: /* EXP framework */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in Matlab in the Object Oriented Programming (OOP) paradigm.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:28:26Z

Lof: /* EXP framework */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of about 150 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:28:11Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework. The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:27:33Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework (about 150 files). The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:25:48Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework (about 150 files). The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/ gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:25:36Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework (about 150 files). The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/||gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:25:23Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework (about 150 files). The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/|gitlab]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:25:06Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework (about 150 files). The code is part of the biophysics toolbox on [https://gitlab.science.ru.nl/]

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:23:24Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework (about 150 files).

The following programs are available:
TL_Program for the test lab
PL_Program for the auditory perception lab (patient lab)
EG_Program for the EEG/NIRS lab
RA_Program for the auditory persuit lab (robot arm)
VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:20:09Z

Lof: /* Introduction */

==Introduction==

The software is designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program has its own version of the program, but most of the code is shared in the form of the EXP_framework (about 150 files).

The following programs are available:
*TL_Program for the test lab
*PL_Program for the auditory perception lab (patient lab)
*EG_Program for the EEG/NIRS lab
*RA_Program for the auditory persuit lab (robot arm)
*VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-31T08:15:34Z

Lof: /* Introduction */

==Introduction==

This resource contains the MATLAB source code for a modular system named EXP_programs, developed by Ruurd Lof for the DCN at Radboud University. The software is specifically designed to control biophysical experiments in various specialized environments, such as the Patient Lab, the Robot Arm Lab, and the NIRS/EEG facilities. The code defines an extensive structure of classes and functions for managing hardware, including LED controllers, sound cards, motors, and head-coil calibration systems. Additionally, the script incorporates logic for adaptive algorithms, stimulus generation, and the handling of real-time experimental data via various protocols. Detailed specifications for audiological equipment and loudspeakers are integrated directly into the code to ensure accurate calibration. Collectively, the system forms a robust framework for the automation and synchronization of scientific research into human perception and motor control.

The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program is created by defining a gui and a few sub classes of certain classes in the EXP framework.

The following programs are available:
*TL_Program for the test lab
*PL_Program for the auditory perception lab (patient lab)
*EG_Program for the EEG/NIRS lab
*RA_Program for the auditory persuit lab (robot arm)
*VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

Coordinate systems

2026-08-28T12:44:05Z

Lof: /* consistency check */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

*When azimuth_deg + elevation_deg < 90° the circles have two intersections.
*When azimuth_deg + elevation_deg = 90° the circles have one intersection.
*When azimuth_deg + elevation_deg > 90° the circles have zero intersections.

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>
Where radius is the distance to the center and H, V and F are the horizontal, vertical and frontal distances in cartesian coordinates.

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:43:50Z

Lof: /* consistency check */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

When azimuth_deg + elevation_deg < 90° the circles have two intersections.
When azimuth_deg + elevation_deg = 90° the circles have one intersection.
When azimuth_deg + elevation_deg > 90° the circles have zero intersections.

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>
Where radius is the distance to the center and H, V and F are the horizontal, vertical and frontal distances in cartesian coordinates.

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:43:24Z

Lof: /* consistency check */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

When azimuth_deg + elevation_deg < 90° the circles have two intersections.
When azimuth_deg + elevation_deg = 90° the circles have one intersection.
When azimuth_deg + elevation_deg > 90° the circles have zero intersections.

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>
Where radius is the distance to the center and H, V and F are the horizontal, vertical and frontal distances in cartesian coordinates.

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:40:50Z

Lof: /* Transforming double polar to HVF coordinates */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>
Where radius is the distance to the center and H, V and F are the horizontal, vertical and frontal distances in cartesian coordinates.

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:40:35Z

Lof: /* Transforming Cartesian to double polar coordinates */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>
Where radius is the distance to the center.

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:39:51Z

Lof: /* Transforming Cartesian to double polar coordinates */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>
Where radius is the distance to the center.

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>
Where H, V and F are the horizontal, vertical and frontal distances in cartesian coordinates.

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:38:41Z

Lof: /* Transforming double polar to HVF coordinates */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>
Where radius is the distance to the center.

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:37:30Z

Lof: /* azimuth */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then
<pre>
Azimuth = arcsin(d_FV/R).
</pre>
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:36:27Z

Lof: /* elevation */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then Azimuth = arcsin(d_FV/R).
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, then Elevation = arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:36:15Z

Lof: /* azimuth */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, then Azimuth = arcsin(d_FV/R).
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, the Elevation is specified by arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:29:59Z

Lof: /* elevation */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, the Azimuth is specified by arcsin(d_FV/R).
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* If d_RF is the distance to the plane and R is the distance to a point from the center, the Elevation is specified by arcsin(d_RF/R).
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

Coordinate systems

2026-08-28T12:29:37Z

Lof: /* azimuth */

==Introduction==
In the three dimensions of our world you can define different coordinate systems. In our auditory labs a subject is placed with his head in the center of the speaker setup (a sphere or semi-circle). We define the coordinate systems in this situation with respect to the default position of the head of the subject.

Normally we are interested in the direction of a stimulus and we define the directions with the angles azimuth and elevation in a double polar coordinate system. This system is a non-conventional coordinate system that is not often used beyond auditory experiments.

*Coordinates in 3 dimensions are normally described by triples e.g. [X, Y, Z] or [phi, theta, r].
*Coordinates systems are defined with respect to the default gaze position in the experiment.
*When stimulus positions are specified, the coordinates are expressed in double polar coordinates.
*Our EMF head tracking system uses three orthogonal axis: Horizontal, Frontal, Vertical. We refer to them as H, F and V.
*For a fixed Cartesian coordinate system in the lab we will adopt the coordinate system "HFV".
*Other fixed coordinate systems in the lab are Double Polar and Spherical coordinates.
*When we want to use a Cartesian coordinate system relative to the head we will adopt the medical coordinate system "RAS".
*Equipment with IMU's can have use different definitions for Cartesian coordinates and we will refer to X, Y and Z for data in coordinates defined by a device which has yet to be converted to HFV or RAS coordinates.
*Our Gitkab\biofysica toolbox has classes and transformation functions for HFV, RAS, Double Polar and Spherical coordinate systems.
*The use of coordinate systems and transformations between coordinates systems should be made explicit in all documentation and programs.

The Spherical Coordinate System is more standard and is widely used. When your are interested in the Spherical coordinate system you have to ask Wikipedia or other sources.

==Cartesian coordinates in the lab==
For the lab we use the "HFV" coordinate system:

*H stands for Horizontal and is positive to the right.
*F stands for Frontal and is positive in the forward direction.
*V stands for Vertical and is positive in the upward direction.

The orientation of H, F van V are defined by the default position (looking straight ahead) of the subject (tested person) sitting on the experimental chair in the lab. The [0, 0, 0] position is right between the test persons ears.

In terms of unit vectors: V = H x F

==Medical Cartesian coordinates==
For a body (or head) a medical notation is often adopted:

<pre>
left (L)
right (R)
anterior (A)
posterior (P)
superior (S)
inferior (I)
</pre>

For describing the position of the head of a person we will adopt the 'RAS'-convention:

<pre>
R-axis: from left (-R) to right (+R)
A-axis: from back (-A) to front (+A)
S-axis: from bottom (-S) to top (+S)
</pre>

The origin in this system is chosen again right between the ears.

In terms of unit vectors: S = R x A

==Double Polar coordinates==
The double polar coordinates are fixed in the lab. The coordinates are called azimuth , elevation and radius. The azimuth defines a semi-circle parallel to the FV-plane. The elevation defines a circle parallel to the RF-plane. The intersection of the azimuth circle and the elevation circle is the target point. Since there are two intersections (most of the time), the hemisphere of the intersection has to be specified in order to resolve the ambiguity (see left picture).
Often only elevation and azimuth is given, assuming the target is in the forward hemisphere and the radius is not relevant.

[[file:Double_Polar.png|double polar coordinates]]

*pictures: Azimuth and elevation determine two perpendicular circles.
===azimuth===
* Azimuth is the angle with the FV-plane.
* If d_FV is the distance to the plane and R is the distance to a point from the center, the Azimuth is specified by arcsin(d_FV/R).
* pi/2 <= azimuth <= pi/2 (or -90° <= azimuth <= 90°)

===elevation===
* Elevation is the angle with the RF-plane
* pi/2 <= elevation<= pi/2 (or -90° <= elevation <= 90°)

===radius===
* Radius is the distance from the origin to a target point.
* In our lab experiment the radius is not important and can be set to 1.

===hemisphere===
[[file:Two_intersecting_rings.png|two intersecting rings]]
*Pictures: The stars mark the intersections of the circles. When the circles touch (only one intersection) the target lies in the HV-plane.

* Hemisphere is +1 for a point in the forward hemisphere.
* Hemisphere is 0 for a point in the HV-plane (F=0).
* Hemisphere is -1 for a point in the backward hemisphere.

===consistency check===
There is a constraint on azimuth and elevation:
<pre>
azimuth + elevation <= pi (or azimuth_deg + elevation_deg <= 90°)
</pre>

===Transforming double polar to HVF coordinates===
<pre>
H = radius * sin(azimuth)
V = radius * sin(elevation)
F = hemisphere * sqrt(radius^2 - H^2 - V^2)
</pre>

===Transforming Cartesian to double polar coordinates===
In the origin we have by definition azimuth = 0 and elevation = 0.

<pre>
radius = norm([H, V, F])
azimuth = arcsin(H/radius)
elevation = arcsin(V/radius)
hemisphere = sign(F);
</pre>

==Matlab==
===Angles===
Standard trigonometry functions in Matlab use radians as unit for angles. Inside your programs it is advised to use only radians in the code and convert to degrees when presenting values for angles on screen, or in an output file. When reading from screen or input file you should convert degrees to radians at the first assignment.
*When variables use degrees they should have the suffix '''_deg''' in the name.
*It is recommended to use the matlab conversion functions between radians and degrees:
<pre>
angle = deg2rad(angle_deg)
angle_deg = rad2deg(angle)
</pre>

===Trigonometric functions===
Matlab has all kind of standard trigonometric functions working with radians or with degrees. When degrees are used it is recommendable to add the suffix "_deg" to your angle variables.

Standard trigonometric functions using radians:
<pre>
x = sin(angle)
x = cos(angle)
x = tan(angle)
angle = asin(x)
angle = acos(x)
angle = atan(x)
angle = atan2(y, x)
</pre>

Standard trigoniometric functions using degrees:
<pre>
x = sind(angle_deg)
x = cosd(angle_deg)
x = tand(angle_deg)
angle_deg = asind(x)
angle_deg = acosd(x)
angle_deg = atand(x)
angle_deg = atan2d(y, x)
</pre>

===Coordinate system representations===
In the Gitlab in biofysica\utilities\coordinates\RAS_DP_SPH there are classes for the coordinates
<pre>
coordinates_HVF.m
coordinates_HVF_withID.m
coordinates_RAS.m
coordinates_DP.m
coordinates_DP_withID.m
coordinates_SPH.m
coordinates_SPH_withID.m
</pre>
The classes with suffix "_withID" are meant for relating coordinates to IDs of Leds or Speakers.

'''HVF coordinates''' are the coordinates fixed in the lab.
It has the following fields:
- ID (optional)
- right or H (in meters)
- up or V (in meters)
- forward or F (in meters)
In our auditory experiments the default position is the reference orientation and the origin is taken between the ears of the subject.

'''RAS coordinates''' is the standard for coordinates relative to the head orientation.
It has the following fields:
- right or R(in meters)
- anterior or A (in meters)
- superior or S(in meters)

'''Double Polar coordinates'''
- ID (optional)
- azimuth (in radians)
- elevation (in radians)
- radius (in meters)
- hemisphere (+1, 0 or -1: stands for forward, in between or backward hemisphere)

'''Spherical coordinates'''
- ID (optional)
- azimuth (in radians: 0 to 2pi positive X-axis is 0)
- elevation (in radians: -pi to pi positive Y-axis is 0)
- radius (in meters)

Example code:
<pre>
right = 0.5; % in meters
anterior = 0.5; % in meters
superior = 0.5; % in meters

% create a stimulus position in RAS:
stimulusPos_RAS = coordinates_RAS(right, anterior, superior);

% transform the stimulus position from RAS to double polar:
stimulusPos_DP = transform_RAS2DP(stimulusPos_RAS);
</pre>

===Coordinate transformations===

====Lab coordinates: DP <==> HVF====
The biofysica repository has the following transformation functions:

and conversion functions between coordinates:
<pre>
transform_HVF2DP
transform_DP2HVF
transform_device2RAS
</pre>

They all have a single input parameter in the form of a struct or table and a single output parameter in the form of a table. Angles are always in radians.
* HVF2DP_withNetCalibrationFile (Field coil reading to Double Polar)
The HVF2DP has an extra parameter NetCalibrationFile, that should contains the filename of the latest calibration.

====Device ==> RAS====
In order to transform device XYZ-coordinates to RAS-coordinates you have to specify a 3x3 transformation matrix.

E.g. If the X-saxis is pointing to Superior, the Y-axis to Right and the Z-axis pointing to Anterior you get the following transformation matrix:
<pre>
XYZ2RASdefinition = [0, 1, 0;
0, 0 ,1;
1, 0, 0];
</pre>

With the defined transformation matrix you can use the transform function:

<pre>
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, XYZ2RASdefinition)
</pre>

An example is definition_EyeSeeCamSci_XYZ2RAS.m which defines the transformation matrix for the EyeSeeCamSci.

====Built in Matlab functions for rotating Cartesian triples====
For rotations of Cartesian coordinates Matlab uses a 3x3 matrix working on the XYZ column vector.
For rotations around an axis there are functions that create these 3x3 matrices. It is important to know if the rotation axis is defined with respect to the room or with respect to a rotating device like a head tracker.

<pre>
In the biofysica toolbox you have the functions Rx, Ry and Rz. These functions generate rotation matrices.
Mx = Rx(angle1)
My = Ry(angle2)
Mz = Rz(angle3)

In case the rotations are small (say smaller than 1 degree) the order is not important:
M = Mx * My * Mz

When the rotation is done in multiple small steps you have:
M(i) = Mx(i) * My(i) * Mz(i)

And for the total rotation you have two situations depending on the coordinate system in which Mx, My and Mz are defined.

rotations in the device coordinates: M_total(i) = M(i) * M_total(i-1)
rotations in the room coordinates: M_total(i) = M_total(i-1) * M(i)

--------------------------------------------------------------------------------------
if you have the Aerospace Toolbox you can use rotx, roty and rotz (angles in degrees)
Mx = rotx(angle1_deg)
My = roty(angle2_deg)
Mz = rotz(angle3_deg)
--------------------------------------------------------------------------------------

You can perform a rotation by applying the rotation matrix to a column vector (point = [1;0;0])
newPoint = M * point;
</pre>

====Older biofysica functions====
N.B. These are not recommended for new code.

Here are some earlier functions that are using different conventions:
<pre>
varargout = azel2cart(AZ,EL,R)
azel = cart2azel(x,y,z)
azel = xyz2azel(x,y,z)
[PostRotAZ,PostRotEL] = rotate2d(azimuth,elevation,Beta)
[X,Y,Z] = pitch(X,Y,Z,Angle)
[X,Y,Z] = yaw(X,Y,Z,Angle)

N.B. all angles are in degrees
</pre>

===Stimulus position lookup tables===
Setups with different speaker and led positions have a lookup table for the stimulus positions in the form of an excel file. The excel file should have a sheet with the name 'DP' for data in double polar coordinates. The sheet should have five columns with the headers 'ID', 'azimuth', 'elevation', 'radius', 'hemisphere'.
<pre>
stimulusPos = readtable(fname, 'sheet', 'DP');
</pre>
The function 'readtable' outputs a table with the named column headers that are accessable in the same way as fields of a struct.

<pre>
ID = stimulusPos.ID;
azimuth = stimulusPos.azimuth;
etc....
</pre>

==Head tracking==

===Field coil head tracking===
Field coil head tracking is a method for movement detection. A pickup coil mounted on the head of the subject is picking up modulated magnetic fields. Three lock-in amplifiers splits the signal from the head coil into three components, horizontal, vertical and frontal. These components are measured as voltages.

The convention for head tracking directions (H,V,F) are related to gaze in the following way:
<pre>
Horizontal: H = positive signal when looking right
Vertical: V = positive signal when looking up
Frontal: F = positive signal when looking forward
</pre>

In Gitlab (biofysica\utilities\coordinates\HVF_RAS_DP_SPH\HVF field calibration) there is a function 'convert_HVFfieldValues2DP_withNetCalibration.m' that uses a netcalibration file in order to transform the (H,V,F)-voltages into double polar coordinates.

===Head tracker with IMU===
Each head tracker with an IMU has its own XYZ coordinate system. In order to transform this to RAS coordinates we have to use a device specific transformation matrix. In the biofysica toolbox there is a function for each device (definition_XYZ2RAS_<devicename>) that generates a struct with a description of the definition for the XYZ2RAS transformation and a transformation matrix. This struct can be readily used as the input for the function transform_XYZ2RAS.

Here is an example of a transformation of XYZ coordinates to RAS coordinates of a head tracking device:
<pre>
%get X, Y and Z from the device (X, Y and Z can be column arrays)
X = get_X_fromTheDevice;
Y = get_Y_fromTheDevice;
Z = get_Z_fromTheDevice;

% create a XYZcoordinates object
XYZcoordinates = coordinates_XYZ(X,Y,Z);

% transform to RAS coordinates
RAScoordinates = transform_XYZ2RAS(XYZcoordinates, definition_XYZ2RAS_devicename);

% this is what you get
R = RAScoordinates.right
A = RAScoordinates.anterior
S = RAScoordinates.superior
</pre>

==Conventions for expressing angles in text==
An angle is normally expressed in radians or degrees.

One radian corresponds to the angle for which the arc (s) on a circle equals the radius (r), thus 1 rad = s/r = 1. In the SI standard 1 rad = 1 per definition, so rad is dimensionless. Therefore it is not necessary to explicitly use it. Only when confusion is possible you should mention it as the unit behind a value.

The other convention for angles is the degree. The conversion between radians and degrees follows from the relation 360° = 2π rad. Note that the degree, with the symbol °, is not a unit of the SI. When expressing angles in degrees the use of the symbol ° is mandatory.

When using trigonometric formulae you have to be aware that by default these functions use radians. If you want to use constants expressed in degrees you have to use the degree symbol °. The following expression are equivalent:

<pre>
X and L in meters, angle in radians

X = L * sin(pi/2)

is equivalent to:

X = L * sin(90°)

and

angle = pi + arcsin(Y/L)

is equivalent to:

angle = 180° + arcsin(Y/L)
</pre>

EXP programs

2026-08-27T08:44:35Z

Lof: /* Lab program example */

==Introduction==

EXP programs are MATLAB programs for each auditory lab with an RZ6 DSP. The software is based on the EXP framework. The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The framework is a collection of classes and functions that are the basis for Lab programs. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program is created by defining a gui and a few sub classes of certain classes in the EXP framework.

The following programs are available:
*TL_Program for the test lab
*PL_Program for the auditory perception lab (patient lab)
*EG_Program for the EEG/NIRS lab
*RA_Program for the auditory persuit lab (robot arm)
*VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

environment = TL_environment;
hardware = TL_hardwareSystems(environment);
experiment = TL_experiment(environment, hardware);
recordings = TL_recordingsHandler(environment, experiment);
player = TL_experimentPlayer(hardware, recordings, experiment);
guiHandler = TL_guiHandler(player, environment, experiment, hardware);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-27T08:42:28Z

Lof: /* Lab program example */

==Introduction==

EXP programs are MATLAB programs for each auditory lab with an RZ6 DSP. The software is based on the EXP framework. The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The framework is a collection of classes and functions that are the basis for Lab programs. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program is created by defining a gui and a few sub classes of certain classes in the EXP framework.

The following programs are available:
*TL_Program for the test lab
*PL_Program for the auditory perception lab (patient lab)
*EG_Program for the EEG/NIRS lab
*RA_Program for the auditory persuit lab (robot arm)
*VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to each other.

programPar = TL_programParameters;
hardwareSystems = TL_hardwareSystems(programPar);
experiment = TL_experiment(programPar);
trialRecordings = TL_recordingsHandler(programPar, experiment, hardwareSystems);
player = TL_experimentPlayer(hardwareSystems, trialRecordings, programPar, experiment);
guiHandler = TL_guiHandler(player, programPar, experiment, hardwareSystems);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);

EXP programs

2026-08-27T08:41:29Z

Lof: /* EXP framework */

==Introduction==

EXP programs are MATLAB programs for each auditory lab with an RZ6 DSP. The software is based on the EXP framework. The EXP framework is a MATLAB toolbox developed by [[Ruurd Lof]]. The framework is a collection of classes and functions that are the basis for Lab programs. The toolbox is mainly programmed object oriented programming style. It is modular with respect to the hardware that can be used.

Each lab program is created by defining a gui and a few sub classes of certain classes in the EXP framework.

The following programs are available:
*TL_Program for the test lab
*PL_Program for the auditory perception lab (patient lab)
*EG_Program for the EEG/NIRS lab
*RA_Program for the auditory persuit lab (robot arm)
*VC_Program for the vestibular chair lab

==EXP framework==

The EXP framework consists of over 200 files and is written in the Object Oriented Programming (OOP) paradigm by Ruurd Lof.

The main classes in the EXP framework are:

EXP_environment
EXP_hardwareSystem
EXP_experiment
EXP_recordingsHandler
EXP_experimentPlayer
EXP_guiHandler
EXP_gui

*These EXP_ classes and a few others are the templates for building a lab specific program.

*All programs use the same GUI that is always responsive and displays sounds, sound locations, led locations and acquisition results for every trial.

*A .exp file specifies the whole experiment.

*The program outputs a .mat file for every trial (and block) with a struct called 'trialInfo'.

*There is no need for the experimenter to do any Matlab programming.

==Lab program example==

An example of a Lab program is the TestLabProgram. All programs have the same basic structure:

A few objects (TestLab classes are starting with TL_) are created in a fixed order and linked by passing references to the objects.

programPar = TL_programParameters;
hardwareSystems = TL_hardwareSystems(programPar);
experiment = TL_experiment(programPar);
trialRecordings = TL_recordingsHandler(programPar, experiment, hardwareSystems);
player = TL_experimentPlayer(hardwareSystems, trialRecordings, programPar, experiment);
guiHandler = TL_guiHandler(player, programPar, experiment, hardwareSystems);

At last a GUI is launched with a link to the guihandler object.

TL_Gui(guiHandler);