handybeam.samplers

Module handybeam.samplers.rectilinear_sampler

File: rectilinear_sampler.py

Holds the class handybeam.samplers.rectilinear_sampler.RectilinearSampler

Original contributor: Salvador Catsis

class handybeam.samplers.rectilinear_sampler.RectilinearSampler(parent=None, normal_vector=array([0., 0., 1.]), parallel_vector=array([0., 1., 0.]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin_x=0.2, grid_extent_around_origin_y=0.2, local_work_size=(1, 1, 1), align_grid_size_to_gpu=64)[source]

Takes the specification for a rectilinear sampling grid, creates a grid of points, and then enables sampling the acoustic field at these points.

__init__(parent=None, normal_vector=array([0., 0., 1.]), parallel_vector=array([0., 1., 0.]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin_x=0.2, grid_extent_around_origin_y=0.2, local_work_size=(1, 1, 1), align_grid_size_to_gpu=64)[source]

Initialises an instance of the RectilinearSampler class.

Parameters:
  • parent (handybeam.world.World) – This is an instance of the handybeam world class.
  • normal_vector (numpy array) – This is the vector normal to the desired sampling grid.
  • parallel_vector (numpy array) – This is a vector parallel to the desired sampling grid.
  • origin (numpy array) – This is a vector specifying the origin of the sampling grid.
  • grid_spacing_per_wavelength (float) – This specifies the grid spacing as a fraction of the medium wavelength.
  • grid_spacing_per_m (float) – This specifies the grid spacing in meters.
  • grid_extent_around_origin_x (float) – This specifies the distance between the origin of the sampling grid and the edge along the x-axis.
  • grid_extent_around_origin_y (float) – This specifies the distance between the origin of the sampling grid and the edge along the y-axis.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
  • align_grid_size_to_gpu (int) – if set to true, the precise sampling density will be adjusted so that the count of pixels is a multiply of 256. This increases overall throughput of the GPU
__repr__()[source]

links to self.__str__()

__str__()[source]

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
extent

extent as for use in imshow(extent=this.extent)

Returns:a tuple suitable to give to imshow
find_rect_grid_area()[source]

This method finds the area of the requested sampling grid.

generate_propagation_parameters()[source]

This method finds the parameters to pass to the opencl kernel to correctly define the sampling grid.

print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False, local_work_size=None)[source]

Calls the rect_propagator to propagate the acoustic field to the desired sampling points.

Parameters:
  • print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
  • local_work_size (tuple or None) – Tuple e.g. (1,1,1) - set to use that work unit size. Note that correct setting require in-depth understanding of the GPU properties. Do not change away from (1,1,1) unless you know what You are doing.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(world=None, sampler=None, filename=None, figsize=[15, 10], dpi=150)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.

class handybeam.samplers.abstract_sampler.AbstractSampler(parent=None)[source]

Defines the common attributes of each sampler class.

__init__(parent=None)[source]

Initialises an instance of the AbstractSampler class.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
__repr__()

part of RememberInstanceCreationInfo. Overrides the regular __repr__(), and adds the creation name to the existing object’s __repr__()

__str__

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
set_parent(parent)[source]

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')[source]

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)[source]

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)[source]

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(world=None, sampler=None, filename=None, figsize=[15, 10], dpi=150)[source]

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
class handybeam.samplers.clist_sampler.ClistSampler(parent=None, local_work_size=(128, 1, 1))[source]

This is the general sampling grid class. It takes a list of sampling points and samples the acoustic field at these points.

__init__(parent=None, local_work_size=(128, 1, 1))[source]

This method intialises an instance of the ClistSampler class.

Parameters:
  • parent (handybeam_core.world.World) – This is an instance of the handybeam world class.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
__repr__()[source]

links to __str__()

__str__()[source]
Returns:a formatted string representing some fun fucts about this instance …
_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
add_sampling_points(x_list, y_list, z_list)[source]

This method adds the requested sampling points to the sampler object.

Parameters:
  • x_list (numpy array) – This is an array containing the x-coordinates of the requested sampling points.
  • y_list (numpy array) – This is an array containing the y-coordinates of the requested sampling points.
  • z_list (numpy array) – This is an array containing the z-coordinates of the requested sampling points.
clear_data()[source]

This method clears the data assigned to the object.

find_clist_grid_volume()[source]

This method finds the volume of the requested sampling grid.

print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False)[source]

This method calls the clist_propagator to propagate the acoustic field to the desired sampling points.

Parameters:print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(world=None, sampler=None, filename=None, figsize=[15, 10], dpi=150)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
class handybeam.samplers.hexagonal_sampler.HexagonalSampler(parent=None, normal_vector=array([0, 0, 1]), parallel_vector=array([0, 1, 0]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin=0.2, local_work_size=(1, 1, 1))[source]

This is the hexagonal sampling grid class. It takes the specification for a hexagonal sampling array and then samples the acoustic field at these points.

__init__(parent=None, normal_vector=array([0, 0, 1]), parallel_vector=array([0, 1, 0]), origin=array([0., 0., 0.2]), grid_spacing_per_wavelength=0.2, grid_spacing_per_m=None, grid_extent_around_origin=0.2, local_work_size=(1, 1, 1))[source]

This method intialises an instance of the HexagonalSampler class.

Parameters:
  • parent (handybeam.world.World) – This is an instance of the handybeam world class.
  • normal_vector (numpy array) – This is the vector normal to the desired sampling grid.
  • parallel_vector (numpy array) – This is a vector parallel to the desired sampling grid.
  • origin (numpy array) – This is a vector specifying the origin of the sampling grid.
  • grid_spacing_per_wavelength (float) – This specifies the grid spacing as a fraction of the medium wavelength.
  • grid_spacing_per_m (float) – This specifies the grid spacing in meters.
  • grid_extent_around_origin (float) – This specifies the distance between the origin of the sampling grid and the edge.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
__repr__()

part of RememberInstanceCreationInfo. Overrides the regular __repr__(), and adds the creation name to the existing object’s __repr__()

__str__

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
find_hex_grid_area()[source]

This method finds the area of the requested sampling grid.

generate_propagation_parameters()[source]

This method finds the parameters to pass to the opencl kernel to correctly define the sampling grid.

print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False)[source]

This method calls the hex_propagator to propagate the acoustic field to the desired sampling points.

Parameters:print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(world=None, sampler=None, filename=None, figsize=[15, 10], dpi=150)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.

Module handybeam.samplers.lambert_sampler

File: lambert_sampler.py

Holds the class handybeam.samplers.lambert_sampler.LambertSampler

Original contributor: Salvador Catsis

class handybeam.samplers.lambert_sampler.LambertSampler(parent=None, origin=array([0, 0, 0]), required_resolution=0.012, radius=0.05, local_work_size=(1, 1, 1))[source]

This is the lambert sampling grid class. It takes the specification for a lambert sampling array and then samples the acoustic field at these points.

__init__(parent=None, origin=array([0, 0, 0]), required_resolution=0.012, radius=0.05, local_work_size=(1, 1, 1))[source]

This method intialises an instance of the LambertSampler class.

Parameters:
  • parent (handybeam.world.World) – This is an instance of the handybeam world class.
  • origin (numpy array) – This is a vector specifying the origin of the sampling grid.
  • required_resolution (float) – This specifies the resolution of the lambert sampling grid, it changes the number of sampling points.
  • radius (float) – This specifies radius of the hemispherical sampling grid.
  • local_work_size (tuple) – This sets the local work size for the GPU, not recommended to change unless the user has experience with OpenCL and pyopencl.
__repr__()

part of RememberInstanceCreationInfo. Overrides the regular __repr__(), and adds the creation name to the existing object’s __repr__()

__str__

Return str(self).

_check_existence_after_creation()

Helper function for RememberInstanceCreationInfo

Returns:raises an error if the object’s data is not found
print_debug_creation_info()

helper method of RememberInstanceCreationInfo

Returns:prints the debug data
propagate(print_performance_feedback=False)[source]

This method calls the lamb_propagator to propagate the acoustic field to the desired sampling points.

Parameters:print_performance_feedback (boolean) – Boolean value determining whether or not to output the GPU performance.
set_parent(parent)

Sets the parent of this instance if one has not been provided.

Parameters:parent (handybeam.world.World) – This is an instance of the handybeam world class.
visualise_3D(threshold=50, colour_map='cubehelix')

show a 3D volume visualisation using VisPy

:param world : handybeam.world.World
the world from which to take the data
Parameters:
  • sampler – handybeam.samplers.abstract_sampler the sampler from which to take the data
  • threshold – threshold of visibility for volume visualisation
  • colour_map – colour map for volume visualisation
Returns:

creates the figure, and shows it.

visualise_all_in_one(filename=None)

visualises the amplitude and phase of the pressure field and the transducers.

Parameters:
  • world (handybeam.world.World) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid(filename=None)

This method visualises the location of the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.
visualise_sampling_grid_and_array(world=None, sampler=None, filename=None, figsize=[15, 10], dpi=150)

visualises the location of the sampling grid points and the transducers.

Parameters:
  • world (handybeam_core.world) – An instance of the handybeam.world class.
  • sampler (handybeam.sampler) – An instance of one of the handybeam sampler classes.
  • filename (string) – This string indicates the location in which the visualisation image should be stored.
  • figsize (tuple) – This tuple sets the size of the figure used to display the visualisation image.
  • dpi (int) – This int sets the resolution of the visualisation image.

Back to Welcome

Licence (documentation): Creative Commons CC BY-NC-SA 4.0

Licence (source code): Apache 2.0

EU logo

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 737087.


This project has received funding from Ultrahaptics.

Ultrahaptics logo