1. tomotok.geometry package

Contains functions and classes required for geometry matrix computation using single line of sight approximation.

• Functions computing contributions of nodes to gmat

• reconstruction grid definition

• line of sight generators for artificial diagnostics

• gmat handler prototype

class tomotok.geometry.Grid

Bases: object

Base class for describing reconstruction grid. Should be subclassed for specific grid types.

Only toroidally symmetric grids are supported. The grid is defined in the r-z plane and extended in toroidal direction by symmetry.

Attributes:

size

Total number of nodes in the grid.

faces: ndarray

vertices: ndarray

property size: int

Total number of nodes in the grid.

Returns:

int

total number of nodes in the grid

class tomotok.geometry.RegularGrid(nr: int, nz: int, rlims: Tuple[float, float], zlims: Tuple[float, float])

Bases: Grid

Rectangular grid of regularly spaced rectangles with the same size

Describes rectangular reconstruction grid consisting of regularly spaced toroidally symmetric nodes that have rectangular projection to reconstruction plane.

Attributes:

nrint

number of nodes along r (radial) axis

nzint

number of nodes along z (vertical) axis

nodes_numint

total number of nodes

rmin, rmaxfloat

limits of r axis

zmin, zmaxfloat

limits of z axis

rlims, zlimsTuple[float, float]

grid limits along respective axis

dr, dzfloat

dimension of node in r or z axis

r_border, z_bordernumpy.ndarray

arrays containing r resp. z coordinates of node borders

r_center, z_centernumpy.ndarray

arrays containing r resp. z coordinates of node centers

volumesnumpy.ndarray

Volumes of individual voxels assuming toroidal symmetry.

Methods

corners([mask])	Creates an array with r, z coordinates of node corners.
inside_corners(r, z)	Counts how many corners of each node are inside given polygon.
is_inside(r, z[, method])	Selects nodes with centers inside given polygon.
is_inside_all(r, z)	Selects nodes with all corners inside given polygon.
is_inside_any(r, z)	Selects nodes with at least one corner inside given polygon.
is_inside_center(r, z)	Selects nodes with centers inside given polygon.

property vertices: ndarray

property faces: ndarray

property volumes: ndarray

Volumes of individual voxels assuming toroidal symmetry.

Returns:

numpy.ndarray

matrix with volume values for each node with shape (nz, nr)

property centre: Tuple[float, float]

Returns the mean of rmin, rmax and zmin, zmax

property extent: Tuple[float, float, float, float]

Grid extent in format for use in matplotlib

Returns:

tuple of floats

rmin, rmax, zmin, zmax

property size: int

Total number of nodes in the grid.

Returns:

int

total number of nodes in the grid

property shape: Tuple[float, float]

property center_mesh: ndarray

property border_mesh: ndarray

property rlims: Tuple[float, float]

property zlims: Tuple[float, float]

is_inside(r: ndarray, z: ndarray, method: str = 'center') → ndarray

Selects nodes with centers inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinates of polygon points

methodstr, optional

method for selecting nodes, by default ‘center’, other options are ‘any’ and ‘all’

Returns:

numpy.ndarray

Mask matrix for pixgrid with True values for nodes inside polygon

inside_corners(r: ndarray, z: ndarray) → ndarray

Counts how many corners of each node are inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinates of polygon points

Returns:

numpy.ndarray

number of corners inside polygon for each node, shape (#z, #r)

is_inside_any(r: ndarray, z: ndarray) → ndarray

Selects nodes with at least one corner inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinate vectors of polygon

Returns:

numpy.ndarray

Mask matrix with True values for nodes with at least one corner inside polygon

is_inside_all(r: ndarray, z: ndarray) → ndarray

Selects nodes with all corners inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinate vectors of polygon

Returns:

numpy.ndarray

Mask matrix with True values for nodes with all corners inside polygon

is_inside_center(r: ndarray, z: ndarray) → ndarray

Selects nodes with centers inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinate vectors of polygon

Returns:

numpy.ndarray

Mask matrix with True values for nodes with centers inside polygon

corners(mask: ndarray | None = None) → ndarray

Creates an array with r, z coordinates of node corners.

Corners are in clockwise order starting from top left.

Parameters:

masknumpy.ndarray

2D bool matrix for selecting nodes, shape (#z, #r)

Returns:

numpy.ndarray

corner coordinates for each node in reconstruction plane, shape (#z, #r, 4, 2)

tomotok.geometry.calcam_sparse_line(pupil: ndarray, endpoints: ndarray, grid: RegularGrid, **kw) → csr_array

Wrapper for sparse line of sight computation for typical input from Calcam.

Parameters:

pupilnp.ndarray

(x, y, z) coordinates of pupil position

endpointsnp.ndarray

(#rows, #columns, 3) line of sight end point coordinates

gridtomotok.geometry.RegularGrid

reconstruction grid

**kwdict

additional parameters passed to sparse_line

See also

sparse_line

tomotok.geometry.dense_line(starts: ndarray, ends: ndarray, grid: RegularGrid, step: float = 0.001, rmin: float = 0) → ndarray

Computes geometry matrix using simple numerical integration algorithm.

Uses lines of sight start and end points in 3D Cartesian coordinates as input.

Parameters:

starts, endsndarray

Contains lines of sight start/end points, with shape (…, 3)

gridRegularGrid

Reconstruction grid

stepfloat, optional

Integration step, by default 1e-3

rminfloat, optional

Stops the lines of sight if they intersect cylinder with radius of rmin, by default 0

Returns:

ndarray

geometry matrix with shape (#lines, #nodes)

See also

sparse_line

tomotok.geometry.generate_sightlines(pinhole: tuple[float, float, float] = (0, 0, 0), num: int | tuple[int, int] = (10, 1), fov: float | tuple[float, float] = (45, 0), axis: tuple[float, float, float] = (1, 0, 0), length: float = 1.0) → tuple[ndarray, ndarray]

Creates sightlines starting at pinhole and ending at points with uniform distribution over a given field of view.

Parameters:

numint or (int,int), optional

number of generated chords (vertical, horizontal)

pinholetuple of three floats, optional

cartesian coordinates of pinhole

fovfloat, or tuple of two float, optional

vertical and horizontal field of view in degrees

axistuple of three floats, optional

direction of symmetry axis from pinhole to the center of the field of view

elongfloat, optional

elongation of the sightlines, a multiplier for the length of the direction vectors

Returns:

startpointsnumpy.ndarray

array with line of sight start points coordinates, shape (#los, 3)

endpointsnumpy.ndarray

array with line of sight end points coordinates, shape (#los, 3)

tomotok.geometry.load_dense_gmat(floc: str | Path) → tuple[ndarray, RegularGrid]

Loads hdf file and creates dense geometry matrix and RegularGrid class

Parameters:

flocstr or pathlib.Path

hdf file location

Returns:

gmatnp.ndarray

gridgeometry.RegularGrid

tomotok.geometry.load_sparse_gmat(floc: str | Path) → tuple[sparray, RegularGrid]

Loads hdf file and creates geometry matrix in sparse array format and RegularGrid class

Parameters:

flocstr or pathlib.Path

hdf file location

Returns:

gmatsparse.sparray

gridgeometry.RegularGrid

tomotok.geometry.save_dense_gmat(floc: str | Path, gmat: ndarray, grid: RegularGrid, attrs_dct: dict = None) → None

Saves geometry matrix together with description of the grid.

Currently suports only dense matrices and regular rectangular grids.

Parameters:

flocstr or pathlib.Path

file location

gmatnp.ndarray

with shape (#chanels, #nodes)

gridRegularGrid

class describing regular grid the gmat was computed for

attrs_dictdict, optional

additional attributes to be saved in hdf file

tomotok.geometry.save_sparse_gmat(floc: str | Path, gmat: sparray, grid: RegularGrid, attrs_dct: dict = None) → None

Saves geometry matrix together with description of the grid.

Currently supports only regular rectangular grids.

Parameters:

flocstr or pathlib.Path

file location

gmatsparse.sparray

with shape (#chanels, #nodes)

gridRegularGrid

class describing regular grid the gmat was computed for

attrs_dictdict, optional

additional attributes to be saved in hdf file

tomotok.geometry.sparse_line(starts: ndarray, ends: ndarray, grid: RegularGrid, step: float = 0.001, rmin: float = 0) → csr_array

Computes geometry matrix using simple numerical integration algorithm.

Uses lines of sight start and end points in 3D Cartesian coordinates as input. The line between start and end points is divided into small segments of length step, and the contribution of each segment to the reconstruction grid is computed using a 2D histogram.

A central column blocking the lines of sights can be included using the rmin parameter. The generated points are checked for intersection with a cylinder of radius rmin around the z-axis, and if any point is found inside the cylinder, only the points on the line of sight between the start point and the intersection point are used for the histogram.

Parameters:

starts, endsndarray

Contains lines of sight start/end points, with shape (…, 3)

gridRegularGrid

Reconstruction grid

stepfloat, optional

Integration step, by default 1e-3

rminfloat, optional

Stops the lines of sight if they intersect cylinder with radius of rmin, by default -1

Returns:

sparse.csr_array

geometry matrix with shape (#lines, #nodes)

1.1. Submodules

1.2. tomotok.geometry.generators module

Module with numeric generators of geometry matrix.

tomotok.geometry.generators.sparse_line_3d(rchord: ndarray, vchord: ndarray, grid: RegularGrid, ychord: ndarray | None = None, step: float = 0.001, rmin: float | None = None) → csr_matrix

Computes geometry matrix using simple numerical integration algorithm.

Assumes toroidally symmetric reconstruction nodes. Optimized version working with sparse matrices.

Deprecated since version 2.0: Use sparse_line() instead.

Parameters:

rchordarray-like

radial coordinates of chord start and end points

vchordarray-like

vertical coordinates of chord start and end points

gridRegularGrid

ychordarray_like, optional

if specified, 3D Cartesian coordinates are assumed and rchord represents coordinates of x axis

stepfloat, optional

Integration step in meters.

rminfloat, optional

Stop iteration if r is lower. Useful when chords may go through central column.

Returns:

sparse.csr_matrix

See also

sparse_line

tomotok.geometry.generators.calcam_sparse_line_3d(pupil: ndarray, dirs: ndarray, grid: RegularGrid, step: float = 0.001, rmin: float | None = None, elong: float = 1.0, steps: float | None = None) → csr_matrix

Computes geometry matrix from calcam input using sparse_line_3d algorithm.

Assumes that pupil and dirs coordinates are (x, y, z) = (horizontal, horizontal, vertical)

Deprecated since version 2.0: Use calcam_sparse_line() instead.

Parameters:

pupilnp.ndarray

(x, y, z) coordinates of pupil position

dirsnp.ndarray

(#rows, #columns, 3) line of sight direction vector coordinates

gridtomotok.geometry.RegularGrid

reconstruction grid

stepfloat, optional

Integration step in meters.

rminfloat, optional

cut lines of sight if they intersect cylinder with radius of rmin, by default 0.3

elongfloat, optional

multiplier for direction vectors elongation

Returns:

sparse.csr_matrix

See also

calcam_sparse_line

tomotok.geometry.generators.sparse_line(starts: ndarray, ends: ndarray, grid: RegularGrid, step: float = 0.001, rmin: float = 0) → csr_array

Computes geometry matrix using simple numerical integration algorithm.

Uses lines of sight start and end points in 3D Cartesian coordinates as input. The line between start and end points is divided into small segments of length step, and the contribution of each segment to the reconstruction grid is computed using a 2D histogram.

A central column blocking the lines of sights can be included using the rmin parameter. The generated points are checked for intersection with a cylinder of radius rmin around the z-axis, and if any point is found inside the cylinder, only the points on the line of sight between the start point and the intersection point are used for the histogram.

Parameters:

starts, endsndarray

Contains lines of sight start/end points, with shape (…, 3)

gridRegularGrid

Reconstruction grid

stepfloat, optional

Integration step, by default 1e-3

rminfloat, optional

Stops the lines of sight if they intersect cylinder with radius of rmin, by default -1

Returns:

sparse.csr_array

geometry matrix with shape (#lines, #nodes)

tomotok.geometry.generators.calcam_sparse_line(pupil: ndarray, endpoints: ndarray, grid: RegularGrid, **kw) → csr_array

Wrapper for sparse line of sight computation for typical input from Calcam.

Parameters:

pupilnp.ndarray

(x, y, z) coordinates of pupil position

endpointsnp.ndarray

(#rows, #columns, 3) line of sight end point coordinates

gridtomotok.geometry.RegularGrid

reconstruction grid

**kwdict

additional parameters passed to sparse_line

See also

sparse_line

tomotok.geometry.generators.dense_line(starts: ndarray, ends: ndarray, grid: RegularGrid, step: float = 0.001, rmin: float = 0) → ndarray

Computes geometry matrix using simple numerical integration algorithm.

Uses lines of sight start and end points in 3D Cartesian coordinates as input.

Parameters:

starts, endsndarray

Contains lines of sight start/end points, with shape (…, 3)

gridRegularGrid

Reconstruction grid

stepfloat, optional

Integration step, by default 1e-3

rminfloat, optional

Stops the lines of sight if they intersect cylinder with radius of rmin, by default 0

Returns:

ndarray

geometry matrix with shape (#lines, #nodes)

See also

sparse_line

1.3. tomotok.geometry.grids module

Contains classes describing reconstruction grids. Currently only regular rectangular grid is implemented, but the base class allows for easy implementation of other grid types.

class tomotok.geometry.grids.Grid

Bases: object

Base class for describing reconstruction grid. Should be subclassed for specific grid types.

Only toroidally symmetric grids are supported. The grid is defined in the r-z plane and extended in toroidal direction by symmetry.

Attributes:

size

Total number of nodes in the grid.

faces: ndarray

vertices: ndarray

property size: int

Total number of nodes in the grid.

Returns:

int

total number of nodes in the grid

class tomotok.geometry.grids.RegularGrid(nr: int, nz: int, rlims: Tuple[float, float], zlims: Tuple[float, float])

Bases: Grid

Rectangular grid of regularly spaced rectangles with the same size

Describes rectangular reconstruction grid consisting of regularly spaced toroidally symmetric nodes that have rectangular projection to reconstruction plane.

Attributes:

nrint

number of nodes along r (radial) axis

nzint

number of nodes along z (vertical) axis

nodes_numint

total number of nodes

rmin, rmaxfloat

limits of r axis

zmin, zmaxfloat

limits of z axis

rlims, zlimsTuple[float, float]

grid limits along respective axis

dr, dzfloat

dimension of node in r or z axis

r_border, z_bordernumpy.ndarray

arrays containing r resp. z coordinates of node borders

r_center, z_centernumpy.ndarray

arrays containing r resp. z coordinates of node centers

volumesnumpy.ndarray

Volumes of individual voxels assuming toroidal symmetry.

Methods

corners([mask])	Creates an array with r, z coordinates of node corners.
inside_corners(r, z)	Counts how many corners of each node are inside given polygon.
is_inside(r, z[, method])	Selects nodes with centers inside given polygon.
is_inside_all(r, z)	Selects nodes with all corners inside given polygon.
is_inside_any(r, z)	Selects nodes with at least one corner inside given polygon.
is_inside_center(r, z)	Selects nodes with centers inside given polygon.

property vertices: ndarray

property faces: ndarray

property volumes: ndarray

Volumes of individual voxels assuming toroidal symmetry.

Returns:

numpy.ndarray

matrix with volume values for each node with shape (nz, nr)

property centre: Tuple[float, float]

Returns the mean of rmin, rmax and zmin, zmax

property extent: Tuple[float, float, float, float]

Grid extent in format for use in matplotlib

Returns:

tuple of floats

rmin, rmax, zmin, zmax

property size: int

Total number of nodes in the grid.

Returns:

int

total number of nodes in the grid

property shape: Tuple[float, float]

property center_mesh: ndarray

property border_mesh: ndarray

property rlims: Tuple[float, float]

property zlims: Tuple[float, float]

is_inside(r: ndarray, z: ndarray, method: str = 'center') → ndarray

Selects nodes with centers inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinates of polygon points

methodstr, optional

method for selecting nodes, by default ‘center’, other options are ‘any’ and ‘all’

Returns:

numpy.ndarray

Mask matrix for pixgrid with True values for nodes inside polygon

inside_corners(r: ndarray, z: ndarray) → ndarray

Counts how many corners of each node are inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinates of polygon points

Returns:

numpy.ndarray

number of corners inside polygon for each node, shape (#z, #r)

is_inside_any(r: ndarray, z: ndarray) → ndarray

Selects nodes with at least one corner inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinate vectors of polygon

Returns:

numpy.ndarray

Mask matrix with True values for nodes with at least one corner inside polygon

is_inside_all(r: ndarray, z: ndarray) → ndarray

Selects nodes with all corners inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinate vectors of polygon

Returns:

numpy.ndarray

Mask matrix with True values for nodes with all corners inside polygon

is_inside_center(r: ndarray, z: ndarray) → ndarray

Selects nodes with centers inside given polygon.

Parameters:

r, znumpy.ndarray

Coordinate vectors of polygon

Returns:

numpy.ndarray

Mask matrix with True values for nodes with centers inside polygon

corners(mask: ndarray | None = None) → ndarray

Creates an array with r, z coordinates of node corners.

Corners are in clockwise order starting from top left.

Parameters:

masknumpy.ndarray

2D bool matrix for selecting nodes, shape (#z, #r)

Returns:

numpy.ndarray

corner coordinates for each node in reconstruction plane, shape (#z, #r, 4, 2)

1.4. tomotok.geometry.io module

Saving and loading functions for geometry matrices in sparse format using h5py module.

tomotok.geometry.io.save_sparse_gmat(floc: str | Path, gmat: sparray, grid: RegularGrid, attrs_dct: dict = None) → None

Saves geometry matrix together with description of the grid.

Currently supports only regular rectangular grids.

Parameters:

flocstr or pathlib.Path

file location

gmatsparse.sparray

with shape (#chanels, #nodes)

gridRegularGrid

class describing regular grid the gmat was computed for

attrs_dictdict, optional

additional attributes to be saved in hdf file

tomotok.geometry.io.load_sparse_gmat(floc: str | Path) → tuple[sparray, RegularGrid]

Loads hdf file and creates geometry matrix in sparse array format and RegularGrid class

Parameters:

flocstr or pathlib.Path

hdf file location

Returns:

gmatsparse.sparray

gridgeometry.RegularGrid

tomotok.geometry.io.save_dense_gmat(floc: str | Path, gmat: ndarray, grid: RegularGrid, attrs_dct: dict = None) → None

Saves geometry matrix together with description of the grid.

Currently suports only dense matrices and regular rectangular grids.

Parameters:

flocstr or pathlib.Path

file location

gmatnp.ndarray

with shape (#chanels, #nodes)

gridRegularGrid

class describing regular grid the gmat was computed for

attrs_dictdict, optional

additional attributes to be saved in hdf file

tomotok.geometry.io.load_dense_gmat(floc: str | Path) → tuple[ndarray, RegularGrid]

Loads hdf file and creates dense geometry matrix and RegularGrid class

Parameters:

flocstr or pathlib.Path

hdf file location

Returns:

gmatnp.ndarray

gridgeometry.RegularGrid

1.5. tomotok.geometry.sightlines module

Routines for generating line of sight start and end points.

tomotok.geometry.sightlines.generate_sightlines(pinhole: tuple[float, float, float] = (0, 0, 0), num: int | tuple[int, int] = (10, 1), fov: float | tuple[float, float] = (45, 0), axis: tuple[float, float, float] = (1, 0, 0), length: float = 1.0) → tuple[ndarray, ndarray]

Creates sightlines starting at pinhole and ending at points with uniform distribution over a given field of view.

Parameters:

numint or (int,int), optional

number of generated chords (vertical, horizontal)

pinholetuple of three floats, optional

cartesian coordinates of pinhole

fovfloat, or tuple of two float, optional

vertical and horizontal field of view in degrees

axistuple of three floats, optional

direction of symmetry axis from pinhole to the center of the field of view

elongfloat, optional

elongation of the sightlines, a multiplier for the length of the direction vectors

Returns:

startpointsnumpy.ndarray

array with line of sight start points coordinates, shape (#los, 3)

endpointsnumpy.ndarray

array with line of sight end points coordinates, shape (#los, 3)

tomotok.geometry.sightlines.generate_los(pinhole=(0, 0, 0), num=(10, 1), fov=(45, 0), axis=(1, 0, 0), length=1.0)

Creates line of sight endpoints with uniform distribution.

Deprecated since version 2.0: Use generate_sightlines instead

tomotok.geometry.sightlines.generate_directions(num: int | tuple[int, int] = (10, 1), fov: float | tuple[float, float] = (45, 0), axis: ArrayLike = (1, 0, 0), length=1.0) → ndarray

Creates direction vectors for lines of sight using camera like convention.

The first line of sight is top left, then the numbering follows a row, the last one is bottom right.

Parameters:

numint or (int,int), optional

number of generated chords (vertical, horizontal)

fovfloat, or tuple of two float, optional

vertical or (vertical, horizontal) field of view in degrees

axistuple of three floats, optional

direction of symmetry axis

lengthfloat, optional

line of sight length, by default 1

Returns:

dirsnumpy.ndarray

contains direction vectors cartesian coordinates, shape (#los, 3)

tomotok.geometry.sightlines.rot_v(points: ArrayLike, angle: float) → ndarray

Rotates given points in vertical direction, that is about horizontal y axis perpendicular to r/x.

Should be done before horizontal rotation.

Parameters:

pointsnumpy.ndarray

3D coordinates of points to be rotated with shape (#points, 3)

anglefloat

angle of rotation in radians

Returns:

numpy.ndarray

array of rotated points

tomotok.geometry.sightlines.rot_h(points: ArrayLike, angle: float) → ndarray

Rotates given points in horizontal direction, that is about vertical axis z.

Parameters:

pointsnumpy.ndarray

3D coordinates of points to be rotated with shape (#points, 3)

anglefloat

angle of rotation in radians

Returns:

numpy.ndarray

array of rotated points

tomotok.geometry.sightlines.save_los(loc: str | Path, startpoints: ndarray | list[ndarray], endpoints: ndarray | list[ndarray], detector_names: str | list[str] = None)

Saves line of sight start and end points to json file.

Parameters:

locstr or Path

location of los file for saving

startpoints, endpointslist of numpy.ndarray

list of arrays with start and end points coordinates, shape (#chords, 3)

detector_nameslist of str, optional

list of detector names, detector_# is used if not specified