Commands

In this section, the available commands available for US simulations are documented. Please note that all paths are relative to the folder where the NFIL file is located.

Command add_geom

Description Adds the geometry from a NUR file to the simulation.

Arguments The add_geom commands accepts two arguments:

  • The path to the NUR file with the geometry to be added to the simulation.
  • The path to the MAT file that defines the affine transformation applied to the geometry.

Example:

add_geom car.nur car.mat

Command add_sound_source

Description Adds a new ultrasound source to the simulation.

Arguments This command accepts the following arguments, in order:

  • The path to the MAT file that defines the affine transformation applied to the source.
  • The amplitude of the ultrasound source.
  • The phase of the ultrasound source.
  • The frequency of operation of the DUS file given in the next argument, in kHz.
  • The DUS file that the defines the ultrasound pattern.

The later two arguments can be repeated if the user wants to specify DUS pattern files for different frequencies.

Examples:

add_sound_source source.mat 1.0 0.0 50.0 pattern.dus
add_sound_source source.mat 1.0 0.0 50.0 pattern50khz.dus 60.0 pattern60khz.dus

Command set_simulation_type

Description Sets the simulation type of the current US simulation. Note that some other commands will only work when the simulation is of a certain type.

Arguments This command only takes one argument the simulation type. The simulation type can either be "near" for Near Field simulations, "coupling" for coupling simulations or "doppler" for doppler simulations.

Examples:

set_simulation_type near
set_simulation_type coupling

Command set_frequency

Description Sets the frequency of the simulation.

Arguments This command only takes one argument the frequency in kHz.

Example:

set_frequency 50.0

Command set_freq_sweep

Description Sets a frequency sweep for the simulation.

Precondition The simulation type must not be Doppler.

Arguments This command takes the following arguments, in order:

  • The initial frequency of the simulation, in kHz.
  • The final frequency of the simulation, in kHz.
  • The number of frequency samples in the interval of frequencies.

Example:

set_freq_sweep 50.0 60.0 3

Command set_speed_sound

Description Sets the speed of sound of the simulation.

Arguments This command only takes one argument the speed of sound in m/s.

Example:

set_speed_sound 340.0

Command set_speed_sweep

Description Sets a sweep of speeds of sound for the simulation.

Precondition The simulation type must not be Doppler.

Arguments This command takes the following arguments, in order:

  • The initial speed of sound, in m/s.
  • The final speed of sound, in m/s.
  • The number of samples in the interval of speeds.

Example:

set_speed_sweep 340.0 350.0 3

Command set_bounces

Description Sets the number of effects per ray that will be calculated in the ray-tracing.

Arguments This command only takes one argument the number of desired effects.

Example:

set_bounces 2

Command set_effects

Description Sets the types of effects that will be taken into account when calculating rays in the ray-tracing. Note that direct and reflected rays are ALWAYS calculated.

Arguments This command takes the list of effects to be calculated, or "none" if the user does not want to calculate any effects other than direct and reflected. The available effects are "Tx" (transmission) and "Rf" (refraction).

Examples:

set_effects Tx Df
set_effects none

Command add_passive

Description Adds a new receiver to the simulation.

Precondition Simulation must be of type Coupling.

Arguments This command takes the following arguments:

  • Path to the MAT file that defines the position and orientation of the receiver.
  • Path to the DUS file that defines the ultrasound pattern of the receiver.
  • The effective area of the receiver, in m 2.

Example:

add_passive passive.mat passive.dus 0.01

Command set_doppler_freq_bin

Description Sets the Doppler frequency bin value.

Precondition Simulation must be of type Doppler.

Arguments This command takes only one argument the Doppler frequency bin, in Hz.

Example:

set_doppler_freq_bin 1.0

Command set_doppler_velocity_obj

Description Sets the doppler velocity for a geometry object.

Precondition Simulation must be of type Doppler.

Arguments This command takes the following arguments:

  • The name of the object. The name of an object is the name set to it before exporting to NUR.
  • The three components (X, Y, Z) of the vector that defines the velocity, in m/s.

Example:

set_doppler_velocity_obj car 26.0 0.0 0.0

Command set_doppler_rotation_obj

Description Sets the doppler rotation for a geometry object.

Precondition Simulation must be of type Doppler.

Arguments This command takes the following arguments:

  • The name of the object. The name of an object is the name set to it before exporting to NUR.
  • The three components (X, Y, Z) of the first point of the rotation axis.
  • The three components (X, Y, Z) of the second point of the rotation axis.
  • The rotation speed, in rad/s.

Example:

set_doppler_rotation_obj box 0.0 0.0 0.0 0.0 0.0 1.0 0.5

Command set_doppler_velocity_source

Description Sets the doppler velocity for an ultrasound source.

Precondition Simulation must be of type Doppler.

Arguments This command takes the following arguments:

  • The index (starting at 1) of the source the user wants to apply the velocity to. Indices are assigned sequentially to sources when they are created with the add_sound_source command.
  • The three components (X, Y, Z) of the vector that defines the velocity, in m/s.

Example:

set_doppler_velocity_source 1 1.0 2.0 0.0

Command set_doppler_velocity_obs

Description Sets the doppler velocity for an observation point group.

Precondition Simulation must be of type Doppler.

Arguments This command takes the following arguments:

  • The index (starting at 1) of the observation point group the user wants to apply the velocity to. Indices are assigned sequentially to observation point groups when they are created.
  • The three components (X, Y, Z) of the vector that defines the velocity, in m/s.

Example:

set_doppler_velocity_obs 1 1.0 2.0 0.0

Command set_meshing_processors

Description Sets the number of processors that will be used for meshing.

Arguments This command only takes one argument the number of processors that will be used.

Example:

set_meshing_processors 4

Command set_executing_processors

Description Sets the number of processors that will be used for execution.

Arguments This command only takes one argument the number of processors that will be used.

Example:

set_executing_processors 4

Command set_processors

Description Sets the number of processors that will be used for meshing and execution. This command is a shortcut for setting the number of processors for both calculations without the need to call two commands.

Arguments This command only takes one argument the number of processors that will be used.

Example:

set_processors 4

Command add_point_observation

Description Adds an observation point to the simulation.

Precondition Simulation type must not be Coupling.

Arguments This command takes the following arguments:

  • Path to the DIS file that defines the translation applied to this observation point.
  • Coordinates (X, Y, Z) of the point. The result of applying the translation defined in the DIS file to this point will be the location of the observation point.

Example:

add_point_observation obs1.dis 2.0 1.0 0.0

Command add_cylinder_observation

Description Adds a cylinder (or cylindrical section) of observation points to the simulation.

Precondition Simulation type must not be Coupling.

Arguments This command takes the following arguments (all distances are expressed in meters):

  • Path to the DIS file that defines the translation applied to this group of observation points.
  • The coordinates (X, Y, Z) of the center of the cylinder's base.
  • The radius of the cylinder.
  • The number of points along the height of the cylinder.
  • The height of the cylinder.
  • The number of points along the circumference of the cylinder.
  • The initial angle of the cylindrical section, in degrees.
  • The final angle of the cylindrical section, in degrees.

Example:

add_cylinder_observation obs2.dis 0.0 0.0 0.0 2.0 11 20.0 10 0.0 180.0

Command add_line_observation

Description Adds a line of observation points.

Precondition Simulation type must not be Coupling.

Arguments This command takes the following arguments (all distances are given in meters):

  • The path to a MAT or DIS file defining an affine transformation or a translation, respectively.
  • The number of points of the line.
  • The coordinates (X, Y, Z) of the initial point of the line.
  • The coordinates (X, Y, Z) of the final point of the line.

Examples:

add_line_observation obs3.dis 21 10.0 0.0 0.0 20.0 0.0 0.0
add_line_observation obs3.mat 11 0.0 0.0 0.0 0.0 10.0 0.0

Command add_parallelogram_observation

Description Adds a parallelogram of observation points.

Precondition Simulation type must not be Coupling.

Arguments The command takes the following arguments (all distances are given in meters):

  • The path to a MAT or DIS file defining an affine transformation or a translation, respectively.
  • The coordinates (X, Y, Z) of three points defining the vertices of the parallelogram. The fourth point is calculated by using the other three points.
  • The number of points along the direction from the first to the second point.
  • The number of points along the direction from the second to the third point.

Example:

add_parallelogram_observation obs4.mat 2.0 2.0 0.0 0.0 0.0 0.0 4.0 0.0 0.0 11 11

Command add_plane_observation

Description Adds a plane of observation points to the simulation.

Precondition Simulation type must not be Coupling.

Arguments The command takes the following arguments (all distances are given in meters):

  • The path to a DIS path defining the translation applied to this group of observation points.
  • The constant coordinate of the plane (can either be "x", "y" or "z").
  • The value of the constant coordinate of the plane.
  • The initial value of the first non-constant coordinate of the plane.
  • The total size of the plane along its first non-constant coordinate.
  • The number of points along the first non-constant coordinate of the plane.
  • The initial value of the second non-constant coordinate of the plane.
  • The total size of the plane along its second non-constant coordinate.
  • The number of points along the second non-constant coordinate of the plane.

Example:

add_plane_observation obs5.dis y 2.0 1.0 5.0 5 2.0 6.0 5

Command add_sphere_observation

Description Adds a sphere of observation points to the simulation.

Precondition The simulation type must not be Coupling.

Arguments The command takes the following arguments (all distances are given in meters):

  • The path to the DIS file with the translation applied to this group of observation points.
  • The coordinates (X, Y, Z) of the center of the sphere.
  • The initial radius of the sphere.
  • The increment between two consecutive radius values.
  • The number of radius values.
  • The number of points along the theta direction.
  • The initial theta value, in degrees.
  • The final theta value, in degrees.
  • The number of points along the phi direction.
  • The initial phi value, in degrees.
  • The final phi value, in degrees.

Example:

add_sphere_observation obs6.dis 2.0 0.0 0.0 10.0 1.0 3 11 0.0 90.0 21 0.0 180.0